Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
import {
CommandId,
DEFAULT_PROVIDER_INTERACTION_MODE,
ThreadId,
type OrchestrationEvent,
ProviderInstanceId,
} from "@akeru/contracts";
import * as NodeServices from "@effect/platform-node/NodeServices";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Queue from "effect/Queue";
import * as Stream from "effect/Stream";
import { it as effectIt } from "@effect/vitest";
import { describe, expect, it } from "vite-plus/test";
import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
import * as RepositoryIdentityResolver from "../../project/RepositoryIdentityResolver.ts";
import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
import * as ThreadBackgroundLiveness from "../ThreadBackgroundLiveness.ts";
import * as ThreadPlanProgress from "../ThreadPlanProgress.ts";
import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
import {
OrchestrationProjectionPipeline,
type OrchestrationProjectionPipelineShape,
} from "../Services/ProjectionPipeline.ts";
import { finishMaintenance, tryBeginMaintenance } from "../../remote/updateGate.ts";
import {
now,
createOrchestrationSystem,
asProjectId,
asMessageId,
} from "./test-support/OrchestrationSystem.ts";
describe("OrchestrationEngine", () => {
it("holds turn starts from every surface while a server update is in progress", async () => {
const createdAt = now();
const system = await createOrchestrationSystem();
const { engine } = system;
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-maintenance-create"),
projectId: asProjectId("project-maintenance"),
title: "Project",
workspaceRoot: "/tmp/project-maintenance",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-maintenance-create"),
threadId: ThreadId.make("thread-maintenance"),
projectId: asProjectId("project-maintenance"),
title: "Thread",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
}),
);
const turnStart = {
type: "thread.turn.start" as const,
commandId: CommandId.make("cmd-turn-start-maintenance"),
threadId: ThreadId.make("thread-maintenance"),
message: {
messageId: asMessageId("msg-maintenance"),
role: "user" as const,
text: "hello",
attachments: [],
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required" as const,
createdAt,
};
expect(tryBeginMaintenance()).toBe(true);
try {
const sequenceBefore = await system.run(engine.latestSequence);
await expect(system.run(engine.dispatch(turnStart))).rejects.toThrow(/installing an update/);
expect(await system.run(engine.latestSequence)).toBe(sequenceBefore);
// Other commands keep flowing during maintenance.
await system.run(
engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-thread-maintenance-rename"),
threadId: ThreadId.make("thread-maintenance"),
title: "Renamed",
}),
);
} finally {
finishMaintenance();
}
// The blocked command left no rejection receipt, so a retry is admitted.
await system.run(engine.dispatch(turnStart));
const thread = (await system.readModel()).threads.find(
(entry) => entry.id === ThreadId.make("thread-maintenance"),
);
expect(thread?.messages.map((message) => message.id)).toContain(asMessageId("msg-maintenance"));
await system.dispose();
});
effectIt.effect("keeps a queued turn start admitted after its caller is interrupted", () =>
Effect.gen(function* () {
const workerReachedBlocker = yield* Deferred.make<void>();
const releaseBlocker = yield* Deferred.make<void>();
const blockingProjectionPipeline: OrchestrationProjectionPipelineShape = {
bootstrap: Effect.void,
projectEvent: (event) =>
event.commandId === CommandId.make("cmd-blocker")
? Deferred.succeed(workerReachedBlocker, undefined).pipe(
Effect.andThen(Deferred.await(releaseBlocker)),
)
: Effect.void,
projectEventDeferred: (event) =>
blockingProjectionPipeline.projectEvent(event).pipe(Effect.as(Effect.void)),
};
const engineLayer = OrchestrationEngineLive.pipe(
Layer.provide(OrchestrationProjectionSnapshotQueryLive),
Layer.provide(ThreadBackgroundLiveness.layer),
Layer.provide(ThreadPlanProgress.layer),
Layer.provide(Layer.succeed(OrchestrationProjectionPipeline, blockingProjectionPipeline)),
Layer.provide(OrchestrationEventStoreLive),
Layer.provide(OrchestrationCommandReceiptRepositoryLive),
Layer.provide(RepositoryIdentityResolver.layer),
Layer.provide(SqlitePersistenceMemory),
Layer.provide(NodeServices.layer),
);
yield* Effect.gen(function* () {
const engine = yield* OrchestrationEngineService;
const createdAt = now();
const threadId = ThreadId.make("thread-interrupted-start");
yield* engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-interrupted-start"),
projectId: asProjectId("project-interrupted-start"),
title: "Project",
workspaceRoot: "/tmp/project-interrupted-start",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
});
yield* engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-interrupted-start"),
threadId,
projectId: asProjectId("project-interrupted-start"),
title: "Thread",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
});
// Occupy the worker so the turn start waits in the queue.
const blocker = yield* engine
.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-blocker"),
threadId,
title: "Blocked",
})
.pipe(Effect.forkChild({ startImmediately: true }));
yield* Deferred.await(workerReachedBlocker);
const caller = yield* engine
.dispatch({
type: "thread.turn.start",
commandId: CommandId.make("cmd-turn-start-interrupted"),
threadId,
message: {
messageId: asMessageId("msg-interrupted"),
role: "user",
text: "hello",
attachments: [],
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
createdAt,
})
.pipe(Effect.forkChild({ startImmediately: true }));
yield* Fiber.interrupt(caller);
// The worker still owns the queued turn, so an update cannot begin.
expect(tryBeginMaintenance()).toBe(false);
yield* Deferred.succeed(releaseBlocker, undefined);
yield* Fiber.join(blocker);
// The queue is FIFO: once this returns, the turn start has committed.
yield* engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-after-interrupted-start"),
threadId,
title: "After",
});
const turnEvents = Array.from(yield* Stream.runCollect(engine.readEvents(0))).filter(
(event) => event.commandId === CommandId.make("cmd-turn-start-interrupted"),
);
expect(turnEvents.length).toBeGreaterThan(0);
expect(tryBeginMaintenance()).toBe(true);
finishMaintenance();
}).pipe(Effect.provide(engineLayer));
}),
);
it("archives and unarchives threads through orchestration commands", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-archive-create"),
projectId: asProjectId("project-archive"),
title: "Project Archive",
workspaceRoot: "/tmp/project-archive",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-archive-create"),
threadId: ThreadId.make("thread-archive"),
projectId: asProjectId("project-archive"),
title: "Archive me",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "full-access",
branch: null,
worktreePath: null,
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-thread-archive-title-regeneration"),
threadId: ThreadId.make("thread-archive"),
regenerateTitle: true,
}),
);
await system.run(
engine.dispatch({
type: "thread.archive",
commandId: CommandId.make("cmd-thread-archive"),
threadId: ThreadId.make("thread-archive"),
}),
);
expect(
(await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
?.archivedAt,
).not.toBeNull();
expect(
(await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
?.titleRegeneration,
).toBeNull();
await system.run(
engine.dispatch({
type: "thread.unarchive",
commandId: CommandId.make("cmd-thread-unarchive"),
threadId: ThreadId.make("thread-archive"),
}),
);
expect(
(await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
?.archivedAt,
).toBeNull();
expect(
(await system.readModel()).threads.find((thread) => thread.id === "thread-archive")
?.titleRegeneration,
).toBeNull();
await system.run(
engine.dispatch({
type: "thread.title.regeneration.complete",
commandId: CommandId.make("cmd-thread-archive-stale-title-completion"),
threadId: ThreadId.make("thread-archive"),
requestId: CommandId.make("cmd-thread-archive-title-regeneration"),
title: "Stale generated title",
}),
);
expect(
(await system.readModel()).threads.find((thread) => thread.id === "thread-archive")?.title,
).toBe("Archive me");
await system.dispose();
});
it("replays append-only events from sequence", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-replay-create"),
projectId: asProjectId("project-replay"),
title: "Replay Project",
workspaceRoot: "/tmp/project-replay",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-replay-create"),
threadId: ThreadId.make("thread-replay"),
projectId: asProjectId("project-replay"),
title: "replay",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.delete",
commandId: CommandId.make("cmd-thread-replay-delete"),
threadId: ThreadId.make("thread-replay"),
}),
);
const events = await system.run(
Stream.runCollect(engine.readEvents(0)).pipe(
Effect.map((chunk): OrchestrationEvent[] => Array.from(chunk)),
),
);
expect(events.map((event) => event.type)).toEqual([
"project.created",
"thread.created",
"thread.deleted",
]);
await system.dispose();
});
it("streams persisted domain events in order", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-stream-create"),
projectId: asProjectId("project-stream"),
title: "Stream Project",
workspaceRoot: "/tmp/project-stream",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
const eventTypes: string[] = [];
await system.run(
Effect.gen(function* () {
const eventQueue = yield* Queue.unbounded<OrchestrationEvent>();
yield* Effect.forkScoped(
Stream.take(engine.streamDomainEvents, 2).pipe(
Stream.runForEach((event) => Queue.offer(eventQueue, event).pipe(Effect.asVoid)),
),
);
yield* Effect.sleep("10 millis");
yield* engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-stream-thread-create"),
threadId: ThreadId.make("thread-stream"),
projectId: asProjectId("project-stream"),
title: "domain-stream",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
});
yield* engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-stream-thread-update"),
threadId: ThreadId.make("thread-stream"),
title: "domain-stream-updated",
});
eventTypes.push((yield* Queue.take(eventQueue)).type);
eventTypes.push((yield* Queue.take(eventQueue)).type);
}).pipe(Effect.scoped),
);
expect(eventTypes).toEqual(["thread.created", "thread.meta-updated"]);
await system.dispose();
});
it("does not regress a generated branch to a stale temporary worktree branch", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-branch-race-project-create"),
projectId: asProjectId("project-branch-race"),
title: "Branch Race Project",
workspaceRoot: "/tmp/project-branch-race",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-branch-race-thread-create"),
threadId: ThreadId.make("thread-branch-race"),
projectId: asProjectId("project-branch-race"),
title: "Branch Race Thread",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: "t3code/generated-branch-name",
worktreePath: "/tmp/project-branch-race-worktree",
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-stale-temporary-branch-sync"),
threadId: ThreadId.make("thread-branch-race"),
branch: "t3code/1234abcd",
expectedBranch: "t3code/1234abcd",
}),
);
const snapshot = await system.readModel();
expect(snapshot.threads[0]?.branch).toBe("t3code/generated-branch-name");
await system.dispose();
});
it("allows authoritative worktree bootstrap to assign a temporary branch", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-worktree-bootstrap-project-create"),
projectId: asProjectId("project-worktree-bootstrap"),
title: "Worktree Bootstrap Project",
workspaceRoot: "/tmp/project-worktree-bootstrap",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-worktree-bootstrap-thread-create"),
threadId: ThreadId.make("thread-worktree-bootstrap"),
projectId: asProjectId("project-worktree-bootstrap"),
title: "Worktree Bootstrap Thread",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: "main",
worktreePath: null,
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.meta.update",
commandId: CommandId.make("cmd-authoritative-worktree-bootstrap"),
threadId: ThreadId.make("thread-worktree-bootstrap"),
branch: "t3code/1234abcd",
worktreePath: "/tmp/project-worktree-bootstrap-worktree",
}),
);
const snapshot = await system.readModel();
expect(snapshot.threads[0]?.branch).toBe("t3code/1234abcd");
expect(snapshot.threads[0]?.worktreePath).toBe("/tmp/project-worktree-bootstrap-worktree");
await system.dispose();
});
it("fails command dispatch when command invariants are violated", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
await expect(
system.run(
engine.dispatch({
type: "thread.turn.start",
commandId: CommandId.make("cmd-invariant-missing-thread"),
threadId: ThreadId.make("thread-missing"),
message: {
messageId: asMessageId("msg-missing"),
role: "user",
text: "hello",
attachments: [],
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
createdAt: now(),
}),
),
).rejects.toThrow("Thread 'thread-missing' does not exist");
await system.dispose();
});
it("rejects duplicate thread creation", async () => {
const system = await createOrchestrationSystem();
const { engine } = system;
const createdAt = now();
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-project-duplicate-create"),
projectId: asProjectId("project-duplicate"),
title: "Duplicate Project",
workspaceRoot: "/tmp/project-duplicate",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
await system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-duplicate-1"),
threadId: ThreadId.make("thread-duplicate"),
projectId: asProjectId("project-duplicate"),
title: "duplicate",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
}),
);
await expect(
system.run(
engine.dispatch({
type: "thread.create",
commandId: CommandId.make("cmd-thread-duplicate-2"),
threadId: ThreadId.make("thread-duplicate"),
projectId: asProjectId("project-duplicate"),
title: "duplicate",
modelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
branch: null,
worktreePath: null,
createdAt,
}),
),
).rejects.toThrow("already exists");
await system.dispose();
});
it("stamps the dispatching client's origin onto persisted event metadata", async () => {
const createdAt = now();
const system = await createOrchestrationSystem();
const { engine } = system;
await system.run(
engine.dispatch(
{
type: "project.create",
commandId: CommandId.make("cmd-origin-project-create"),
projectId: asProjectId("project-origin"),
title: "Origin Project",
workspaceRoot: "/tmp/project-origin",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
},
{ origin: { surface: "mobile", appVersion: "1.2.3" } },
),
);
await system.run(
engine.dispatch({
type: "project.create",
commandId: CommandId.make("cmd-no-origin-project-create"),
projectId: asProjectId("project-no-origin"),
title: "No Origin Project",
workspaceRoot: "/tmp/project-no-origin",
defaultModelSelection: {
instanceId: ProviderInstanceId.make("codex"),
model: "gpt-5-codex",
},
createdAt,
}),
);
const events = await system.run(
Stream.runCollect(engine.readEvents(0)).pipe(Effect.map((chunk) => Array.from(chunk))),
);
const withOrigin = events.find((event) => event.commandId === "cmd-origin-project-create");
const withoutOrigin = events.find(
(event) => event.commandId === "cmd-no-origin-project-create",
);
expect(withOrigin?.metadata.origin).toEqual({ surface: "mobile", appVersion: "1.2.3" });
expect(withoutOrigin?.metadata.origin).toBeUndefined();
await system.dispose();
});
});