Skip to content

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.

feat(server): add subscription login and a Mastra Codex harness

Leo Orel2e44c7fa5f57
diff --git a/apps/server/package.json b/apps/server/package.json
index ca19f7085..a3bc45048 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -28,8 +28,14 @@
"@effect/platform-node-shared": "catalog:",
"@effect/sql-sqlite-bun": "catalog:",
"@ff-labs/fff-node": "0.9.4",
+ "@mastra/code-sdk": "1.5.1",
+ "@mastra/core": "1.63.0",
"@opencode-ai/sdk": "^1.3.15",
+ "@opencoredev/sandbox-sdk": "file:../../../sandbox-sdk/packages/sdk",
"@pierre/diffs": "catalog:",
+ "@upstash/box": "0.5.3",
+ "@vercel/sandbox": "^2.5.0",
+ "e2b": "^2.32.0",
"effect": "catalog:",
"msgpackr-extract": "3.0.4",
"node-pty": "^1.1.0",
diff --git a/apps/server/src/provider/AkeruAgentInstructions.ts b/apps/server/src/provider/AkeruAgentInstructions.ts
new file mode 100644
index 000000000..eaba879cd
--- /dev/null
+++ b/apps/server/src/provider/AkeruAgentInstructions.ts
@@ -0,0 +1,9 @@
+export const AKERU_AGENT_INSTRUCTIONS = [
+ "You are Akeru, a general-purpose assistant.",
+ "Help with conversation, research, writing, planning, operations, and technical work.",
+ "Do not assume that a request is a software-engineering task.",
+ "Use enabled plugin tools when they help with the request.",
+ "Use workspace tools only when the task requires file or command work.",
+ "When asked about available tools, describe only tools present in the current turn.",
+ "Do not claim that a tool ran unless its result is present in this turn.",
+].join("\n");
diff --git a/apps/server/src/provider/AkeruMastraHarness.test.ts b/apps/server/src/provider/AkeruMastraHarness.test.ts
new file mode 100644
index 000000000..13f835217
--- /dev/null
+++ b/apps/server/src/provider/AkeruMastraHarness.test.ts
@@ -0,0 +1,41 @@
+import { AuthStorage } from "@mastra/code-sdk/auth/storage";
+import type { ToolsInput } from "@mastra/core/agent";
+import { TOOL_NAME_OVERRIDES } from "@mastra/code-sdk/tool-names";
+import { RequestContext } from "@mastra/core/request-context";
+import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
+import { assert, describe, it } from "vite-plus/test";
+
+import { AKERU_AGENT_INSTRUCTIONS } from "./AkeruAgentInstructions.ts";
+import { resolveAkeruTools } from "./AkeruMastraHarness.ts";
+
+describe("AkeruMastraHarness", () => {
+ it("configures Akeru as a general-purpose assistant with plugin awareness", () => {
+ assert.include(AKERU_AGENT_INSTRUCTIONS, "general-purpose assistant");
+ assert.include(AKERU_AGENT_INSTRUCTIONS, "enabled plugin tools");
+ assert.include(AKERU_AGENT_INSTRUCTIONS, "Do not assume");
+ assert.notInclude(AKERU_AGENT_INSTRUCTIONS, "coding agent");
+ });
+
+ it("builds workspace and selected MCP tools from the controller resource", async () => {
+ const workspace = new Workspace({
+ filesystem: new LocalFilesystem({ basePath: process.cwd() }),
+ sandbox: new LocalSandbox({ workingDirectory: process.cwd() }),
+ tools: TOOL_NAME_OVERRIDES,
+ });
+ const requestContext = new RequestContext();
+ requestContext.setRaw("controller", {
+ resourceId: "thread-1",
+ session: { modelId: "openai/gpt-5.6-sol" },
+ });
+
+ const tools = await resolveAkeruTools(requestContext, {
+ authStorage: new AuthStorage("/tmp/akeru-unused-auth.json"),
+ getThreadWorkspace: (threadId) => (threadId === "thread-1" ? workspace : undefined),
+ getThreadTools: (threadId) =>
+ (threadId === "thread-1" ? { exa_search: {} } : {}) as ToolsInput,
+ });
+
+ assert.containsAllKeys(tools, ["view", "write_file", "execute_command", "exa_search"]);
+ await workspace.destroy();
+ });
+});
diff --git a/apps/server/src/provider/AkeruMastraHarness.ts b/apps/server/src/provider/AkeruMastraHarness.ts
new file mode 100644
index 000000000..75e6be077
--- /dev/null
+++ b/apps/server/src/provider/AkeruMastraHarness.ts
@@ -0,0 +1,131 @@
+import { AuthStorage } from "@mastra/code-sdk/auth/storage";
+import { openaiCodexProvider } from "@mastra/code-sdk/providers/openai-codex";
+import type { ToolsInput } from "@mastra/core/agent";
+import {
+ AgentController as MastraAgentController,
+ type Session,
+} from "@mastra/core/agent-controller";
+import { createCodingAgent } from "@mastra/core/coding-agent";
+import type { RequestContext } from "@mastra/core/request-context";
+import { createWorkspaceTools, type Workspace } from "@mastra/core/workspace";
+
+import { AKERU_AGENT_INSTRUCTIONS } from "./AkeruAgentInstructions.ts";
+
+const DEFAULT_MODEL_ID = "openai/gpt-5.6-sol";
+
+export interface AkeruMastraState {
+ readonly projectPath?: string;
+ readonly yolo?: boolean;
+}
+
+export type AkeruMastraSession = Session<AkeruMastraState>;
+
+export interface AkeruMastraHarnessOptions {
+ readonly authStorage: AuthStorage;
+ readonly getThreadTools: (threadId: string) => ToolsInput;
+ readonly getThreadWorkspace: (threadId: string) => Workspace | undefined;
+}
+
+export interface AkeruMastraHarness {
+ readonly controller: Pick<
+ MastraAgentController<AkeruMastraState>,
+ "init" | "createSession" | "deleteSession" | "destroy"
+ >;
+ readonly destroy: () => void;
+}
+
+function controllerContext(requestContext: RequestContext): Record<string, unknown> | undefined {
+ const value = requestContext.getRaw("controller");
+ return typeof value === "object" && value !== null
+ ? (value as Record<string, unknown>)
+ : undefined;
+}
+
+function controllerModelId(requestContext: RequestContext): string {
+ const value = controllerContext(requestContext);
+ if (!value || !("session" in value)) return DEFAULT_MODEL_ID;
+ const session = value.session;
+ if (typeof session !== "object" || session === null || !("modelId" in session)) {
+ return DEFAULT_MODEL_ID;
+ }
+ return typeof session.modelId === "string" ? session.modelId : DEFAULT_MODEL_ID;
+}
+
+function controllerResourceId(requestContext: RequestContext): string | undefined {
+ const value = controllerContext(requestContext)?.resourceId;
+ return typeof value === "string" ? value : undefined;
+}
+
+function codexModelName(modelId: string): string {
+ return modelId.startsWith("openai/") ? modelId.slice("openai/".length) : modelId;
+}
+
+export async function resolveAkeruTools(
+ requestContext: RequestContext,
+ options: AkeruMastraHarnessOptions,
+): Promise<ToolsInput> {
+ const threadId = controllerResourceId(requestContext);
+ if (!threadId) return {};
+ const workspace = options.getThreadWorkspace(threadId);
+ const workspaceTools = workspace
+ ? await createWorkspaceTools(workspace, {
+ requestContext: Object.fromEntries(requestContext.entries()),
+ workspace,
+ })
+ : {};
+ return { ...workspaceTools, ...options.getThreadTools(threadId) };
+}
+
+function toolCategory(toolName: string): "read" | "edit" | "execute" | "mcp" | "other" {
+ if (/read|view|grep|search|find|list|stat/i.test(toolName)) return "read";
+ if (/edit|write|delete|mkdir|move|rename/i.test(toolName)) return "edit";
+ if (/execute|command|shell|process|terminal/i.test(toolName)) return "execute";
+ if (/mcp/i.test(toolName)) return "mcp";
+ return "other";
+}
+
+export async function createAkeruMastraHarness(
+ options: AkeruMastraHarnessOptions,
+): Promise<AkeruMastraHarness> {
+ const agent = createCodingAgent({
+ id: "akeru-agent",
+ name: "Akeru",
+ instructions: AKERU_AGENT_INSTRUCTIONS,
+ model: ({ requestContext }) =>
+ openaiCodexProvider(codexModelName(controllerModelId(requestContext)), {
+ authStorage: options.authStorage,
+ }),
+ tools: ({ requestContext }) => resolveAkeruTools(requestContext, options),
+ workspace: undefined,
+ });
+
+ const controller = new MastraAgentController<AkeruMastraState>({
+ id: "akeru-codex",
+ agent,
+ modes: [
+ { id: "build", name: "Build", defaultModelId: DEFAULT_MODEL_ID },
+ {
+ id: "plan",
+ name: "Plan",
+ defaultModelId: DEFAULT_MODEL_ID,
+ instructions: "Inspect and explain. Do not change files or run mutating commands.",
+ },
+ ],
+ defaultModeId: "build",
+ disableBuiltinTools: [
+ "submit_plan",
+ "task_write",
+ "task_update",
+ "task_complete",
+ "task_check",
+ "subagent",
+ ],
+ toolCategoryResolver: toolCategory,
+ intervalHandlers: [],
+ });
+
+ return {
+ controller,
+ destroy: () => undefined,
+ };
+}
diff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.ts
index 0cf152239..e77a04bed 100644
--- a/apps/server/src/provider/Errors.ts
+++ b/apps/server/src/provider/Errors.ts
@@ -187,6 +187,33 @@ export class ProviderSessionDirectoryPersistenceError extends Schema.TaggedError
}
}
+export class AgentControllerUnsupportedEngineError extends Schema.TaggedErrorClass<AgentControllerUnsupportedEngineError>()(
+ "AgentControllerUnsupportedEngineError",
+ {
+ provider: Schema.String,
+ model: Schema.String,
+ detail: Schema.String,
+ cause: Schema.optional(Schema.Defect()),
+ },
+) {
+ override get message(): string {
+ return `AgentController cannot resolve engine '${this.provider}/${this.model}': ${this.detail}`;
+ }
+}
+
+export class AgentControllerRuntimeError extends Schema.TaggedErrorClass<AgentControllerRuntimeError>()(
+ "AgentControllerRuntimeError",
+ {
+ operation: Schema.String,
+ detail: Schema.String,
+ cause: Schema.optional(Schema.Defect()),
+ },
+) {
+ override get message(): string {
+ return `AgentController failed in ${this.operation}: ${this.detail}`;
+ }
+}
+
export type ProviderAdapterError =
| ProviderAdapterValidationError
| ProviderAdapterSessionNotFoundError
@@ -202,3 +229,8 @@ export type ProviderServiceError =
| ProviderSessionDirectoryPersistenceError
| ProviderAdapterError
| CheckpointServiceError;
+
+export type AgentControllerError =
+ | AgentControllerUnsupportedEngineError
+ | AgentControllerRuntimeError
+ | ProviderServiceError;
diff --git a/apps/server/src/provider/Layers/AgentController.test.ts b/apps/server/src/provider/Layers/AgentController.test.ts
new file mode 100644
index 000000000..5547f3958
--- /dev/null
+++ b/apps/server/src/provider/Layers/AgentController.test.ts
@@ -0,0 +1,720 @@
+// @effect-diagnostics globalDate:off nodeBuiltinImport:off preferSchemaOverJson:off
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import type { AgentControllerEvent, MastraDBMessage, Session } from "@mastra/core/agent-controller";
+import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
+import {
+ ApprovalRequestId,
+ McpServerId,
+ ProviderDriverKind,
+ ProviderInstanceId,
+ ThreadId,
+ TurnId,
+ type ProviderRuntimeEvent,
+ type ProviderSession,
+} from "@t3tools/contracts";
+import { it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
+import { assert, describe, expect, vi } from "vite-plus/test";
+
+import { ServerConfig } from "../../config.ts";
+import { AgentController } from "../Services/AgentController.ts";
+import { LegacyProviderBridge } from "../Services/LegacyProviderBridge.ts";
+import type { ProviderServiceShape } from "../Services/ProviderService.ts";
+import {
+ createAkeruMastraAuthStorage,
+ makeAgentControllerLive,
+ toMcpServerConfigs,
+ type AgentControllerLiveOptions,
+} from "./AgentController.ts";
+
+const codexThreadId = ThreadId.make("thread-mastra-codex");
+const claudeThreadId = ThreadId.make("thread-legacy-claude");
+const codexInstanceId = ProviderInstanceId.make("codex");
+const claudeInstanceId = ProviderInstanceId.make("claudeAgent");
+
+const codexSelection = {
+ instanceId: codexInstanceId,
+ model: "gpt-5.6-sol",
+};
+
+function makeProviderSession(
+ threadId: ThreadId,
+ provider: "codex" | "claudeAgent",
+): ProviderSession {
+ return {
+ provider: ProviderDriverKind.make(provider),
+ providerInstanceId: ProviderInstanceId.make(provider),
+ threadId,
+ status: "ready",
+ runtimeMode: "full-access",
+ model: provider === "codex" ? "gpt-5.6-sol" : "claude-fable-5",
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ };
+}
+
+function makeBridge() {
+ const startSession = vi.fn<ProviderServiceShape["startSession"]>((threadId, input) =>
+ Effect.succeed(
+ makeProviderSession(threadId, String(input.provider) === "codex" ? "codex" : "claudeAgent"),
+ ),
+ );
+ const sendTurn = vi.fn<ProviderServiceShape["sendTurn"]>((input) =>
+ Effect.succeed({ threadId: input.threadId, turnId: TurnId.make("legacy-turn") }),
+ );
+ const interruptTurn = vi.fn<ProviderServiceShape["interruptTurn"]>(() => Effect.void);
+ const respondToRequest = vi.fn<ProviderServiceShape["respondToRequest"]>(() => Effect.void);
+ const respondToUserInput = vi.fn<ProviderServiceShape["respondToUserInput"]>(() => Effect.void);
+ const stopSession = vi.fn<ProviderServiceShape["stopSession"]>(() => Effect.void);
+ const rollbackConversation = vi.fn<ProviderServiceShape["rollbackConversation"]>(
+ () => Effect.void,
+ );
+ const service: ProviderServiceShape = {
+ startSession,
+ sendTurn,
+ interruptTurn,
+ respondToRequest,
+ respondToUserInput,
+ stopSession,
+ rollbackConversation,
+ listSessions: () => Effect.succeed([]),
+ getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
+ getInstanceInfo: (instanceId) => {
+ const driverKind = ProviderDriverKind.make(String(instanceId));
+ return Effect.succeed({
+ instanceId,
+ driverKind,
+ displayName: undefined,
+ enabled: true,
+ continuationIdentity: {
+ driverKind,
+ continuationKey: `${driverKind}:instance:${instanceId}`,
+ },
+ });
+ },
+ uploadFeedback: (input) => Effect.succeed({ feedbackId: `feedback-${String(input.threadId)}` }),
+ streamEvents: Stream.empty,
+ };
+ return {
+ service,
+ startSession,
+ sendTurn,
+ interruptTurn,
+ respondToRequest,
+ respondToUserInput,
+ stopSession,
+ rollbackConversation,
+ };
+}
+
+function makeMastraHarness() {
+ const harnessOptions: Array<
+ Parameters<NonNullable<AgentControllerLiveOptions["makeMastraHarness"]>>[0]
+ > = [];
+ const listeners = new Set<(event: AgentControllerEvent) => void>();
+ let modeId = "build";
+ let modelId = "openai/gpt-5.6-sol";
+ let resolveSend: (() => void) | undefined;
+ const sendMessage = vi.fn(
+ () =>
+ new Promise<void>((resolve) => {
+ resolveSend = resolve;
+ }),
+ );
+ const session = {
+ state: { set: vi.fn(async () => undefined) },
+ mode: {
+ get: () => modeId,
+ switch: vi.fn(async ({ modeId: next }: { readonly modeId: string }) => {
+ modeId = next;
+ }),
+ },
+ model: {
+ get: () => modelId,
+ switch: vi.fn(async ({ modelId: next }: { readonly modelId: string }) => {
+ modelId = next;
+ }),
+ },
+ permissions: {
+ setForCategory: vi.fn(async () => undefined),
+ setForTool: vi.fn(async () => undefined),
+ },
+ subscribe: vi.fn((listener: (event: AgentControllerEvent) => void) => {
+ listeners.add(listener);
+ return () => listeners.delete(listener);
+ }),
+ sendMessage,
+ abort: vi.fn(),
+ respondToToolApproval: vi.fn(),
+ respondToToolSuspension: vi.fn(async () => undefined),
+ } as unknown as Session<Record<string, unknown>>;
+ const createSession = vi.fn(async () => session as never);
+ const deleteSession = vi.fn(async () => true);
+ const destroy = vi.fn(async () => undefined);
+ const factory: NonNullable<AgentControllerLiveOptions["makeMastraHarness"]> = async (options) => {
+ harnessOptions.push(options);
+ return {
+ controller: {
+ init: vi.fn(async () => undefined),
+ createSession,
+ deleteSession,
+ destroy,
+ },
+ destroy: vi.fn(),
+ };
+ };
+ const emit = (event: AgentControllerEvent) => {
+ for (const listener of listeners) listener(event);
+ };
+ return {
+ factory,
+ harnessOptions,
+ session,
+ createSession,
+ deleteSession,
+ sendMessage,
+ emit,
+ finishSend: () => resolveSend?.(),
+ };
+}
+
+function assistantMessage(text: string): MastraDBMessage {
+ return {
+ id: "assistant-message",
+ role: "assistant",
+ createdAt: new Date("2026-01-01T00:00:00.000Z"),
+ content: {
+ format: 2,
+ parts: [{ type: "text", text }],
+ },
+ threadId: String(codexThreadId),
+ resourceId: String(codexThreadId),
+ } as MastraDBMessage;
+}
+
+function makeLayer(
+ bridge: ProviderServiceShape,
+ factory: NonNullable<AgentControllerLiveOptions["makeMastraHarness"]>,
+ makeMcpManager?: NonNullable<AgentControllerLiveOptions["makeMcpManager"]>,
+ baseDir?: string,
+) {
+ return makeAgentControllerLive({
+ makeMastraHarness: factory,
+ ...(makeMcpManager ? { makeMcpManager } : {}),
+ }).pipe(
+ Layer.provide(
+ Layer.merge(
+ Layer.succeed(LegacyProviderBridge, bridge),
+ ServerConfig.layerTest(
+ process.cwd(),
+ baseDir ?? { prefix: "akeru-mastra-controller-test-" },
+ ).pipe(Layer.provide(NodeServices.layer)),
+ ),
+ ),
+ );
+}
+
+function provideController<A, E>(
+ effect: Effect.Effect<A, E, AgentController>,
+ bridge: ProviderServiceShape,
+ factory: NonNullable<AgentControllerLiveOptions["makeMastraHarness"]>,
+ makeMcpManager?: NonNullable<AgentControllerLiveOptions["makeMcpManager"]>,
+ baseDir?: string,
+) {
+ return effect.pipe(
+ Effect.provide(makeLayer(bridge, factory, makeMcpManager, baseDir)),
+ Effect.orDie,
+ );
+}
+
+function resolveCodex(controller: AgentController["Service"]) {
+ return controller.resolveEngine({
+ threadId: codexThreadId,
+ engine: { provider: "codex", model: "gpt-5.6-sol" },
+ fallback: codexSelection,
+ mode: "default",
+ });
+}
+
+describe("toMcpServerConfigs", () => {
+ it("converts only the bot's filtered MCP registrations for Mastra", () => {
+ expect(
+ toMcpServerConfigs([
+ {
+ id: McpServerId.make("builtin-exa"),
+ name: "Exa",
+ transport: "url",
+ url: "https://mcp.exa.ai/mcp",
+ enabled: true,
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ },
+ {
+ id: McpServerId.make("local-tools"),
+ name: "Local tools",
+ transport: "stdio",
+ command: "bunx",
+ args: ["local-tools"],
+ enabled: true,
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ },
+ ]),
+ ).toEqual({
+ "builtin-exa": { url: "https://mcp.exa.ai/mcp" },
+ "local-tools": { command: "bunx", args: ["local-tools"] },
+ });
+ });
+});
+
+describe("AgentControllerLive", () => {
+ it.effect("reads Akeru subscription credentials through Mastra AuthStorage", () =>
+ Effect.gen(function* () {
+ const config = yield* ServerConfig;
+ const authPath = NodePath.join(config.secretsDir, "subscription-auth.json");
+ yield* Effect.sync(() => {
+ NodeFS.mkdirSync(config.secretsDir, { recursive: true });
+ NodeFS.writeFileSync(
+ authPath,
+ JSON.stringify({
+ "openai-codex": {
+ type: "oauth",
+ access: "subscription-access",
+ refresh: "subscription-refresh",
+ expires: 4_102_444_800_000,
+ accountId: "account-123",
+ },
+ }),
+ );
+ });
+
+ const auth = createAkeruMastraAuthStorage(config.secretsDir);
+ assert.deepEqual(auth.get("openai-codex"), {
+ type: "oauth",
+ access: "subscription-access",
+ refresh: "subscription-refresh",
+ expires: 4_102_444_800_000,
+ accountId: "account-123",
+ });
+ }).pipe(
+ Effect.provide(
+ ServerConfig.layerTest(process.cwd(), { prefix: "akeru-mastra-auth-test-" }).pipe(
+ Layer.provide(NodeServices.layer),
+ ),
+ ),
+ ),
+ );
+
+ it.effect("passes Akeru subscription auth to the custom memory-free harness", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ return provideController(
+ Effect.gen(function* () {
+ yield* AgentController;
+ const options = mastra.harnessOptions[0];
+ assert.isDefined(options);
+ assert.isDefined(options.authStorage);
+ assert.notProperty(options, "memory");
+ }),
+ bridge.service,
+ mastra.factory,
+ );
+ });
+
+ it.effect("boots a real Mastra Code controller and creates a Codex session", () => {
+ const bridge = makeBridge();
+ const layer = makeAgentControllerLive().pipe(
+ Layer.provide(
+ Layer.merge(
+ Layer.succeed(LegacyProviderBridge, bridge.service),
+ ServerConfig.layerTest(process.cwd(), {
+ prefix: "akeru-mastra-real-controller-test-",
+ }).pipe(Layer.provide(NodeServices.layer)),
+ ),
+ ),
+ );
+
+ return Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ const session = yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ });
+
+ assert.equal(session.provider, "codex");
+ assert.equal(session.model, "gpt-5.6-sol");
+ yield* controller.stopSession({ threadId: codexThreadId });
+ expect(bridge.startSession).not.toHaveBeenCalled();
+ }).pipe(Effect.provide(layer), Effect.orDie);
+ });
+
+ it.effect("runs Codex turns through Mastra Session.sendMessage and normalizes events", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ const session = yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ });
+ assert.equal(session.provider, "codex");
+
+ const events: ProviderRuntimeEvent[] = [];
+ const eventsFiber = yield* controller.streamEvents.pipe(
+ Stream.runForEach((event) =>
+ Effect.sync(() => {
+ events.push(event);
+ }),
+ ),
+ Effect.forkChild({ startImmediately: true }),
+ );
+ yield* Effect.yieldNow;
+ yield* controller.sendTurn({ threadId: codexThreadId, input: "Reply once." });
+ mastra.emit({
+ type: "message_update",
+ message: assistantMessage("Mastra"),
+ } as AgentControllerEvent);
+ mastra.emit({
+ type: "message_end",
+ message: assistantMessage("Mastra answer"),
+ } as AgentControllerEvent);
+ mastra.emit({ type: "agent_end", reason: "complete" } as AgentControllerEvent);
+ mastra.finishSend();
+ yield* Effect.yieldNow;
+ yield* Effect.yieldNow;
+ yield* Fiber.interrupt(eventsFiber);
+
+ assert.deepEqual(
+ events.slice(0, 7).map((event) => event.type),
+ [
+ "turn.started",
+ "session.state.changed",
+ "item.started",
+ "content.delta",
+ "content.delta",
+ "item.completed",
+ "turn.completed",
+ ],
+ );
+ assert.equal(
+ events
+ .filter((event) => event.type === "content.delta")
+ .map((event) => event.payload.delta)
+ .join(""),
+ "Mastra answer",
+ );
+ expect(mastra.sendMessage).toHaveBeenCalledWith({ content: "Reply once." });
+ expect(bridge.startSession).not.toHaveBeenCalled();
+ expect(bridge.sendTurn).not.toHaveBeenCalled();
+ }),
+ bridge.service,
+ mastra.factory,
+ );
+ });
+
+ it.effect("keeps a suspended Mastra turn active until tool input resumes", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "approval-required",
+ });
+ yield* controller.sendTurn({ threadId: codexThreadId, input: "Ask for input." });
+ mastra.emit({
+ type: "tool_suspended",
+ toolCallId: "tool-input-1",
+ toolName: "ask_user",
+ args: {},
+ suspendPayload: {},
+ } as AgentControllerEvent);
+ mastra.emit({ type: "agent_end", reason: "suspended" } as AgentControllerEvent);
+ mastra.finishSend();
+ yield* Effect.yieldNow;
+
+ const [waiting] = yield* controller.listSessions();
+ assert.isDefined(waiting?.activeTurnId);
+
+ yield* controller.respondToUserInput({
+ threadId: codexThreadId,
+ requestId: ApprovalRequestId.make("tool-input-1"),
+ answers: { answer: "Continue" },
+ });
+ mastra.emit({ type: "agent_end", reason: "complete" } as AgentControllerEvent);
+
+ const [completed] = yield* controller.listSessions();
+ assert.isUndefined(completed?.activeTurnId);
+ expect(mastra.session.respondToToolSuspension).toHaveBeenCalledWith({
+ toolCallId: "tool-input-1",
+ resumeData: { answer: "Continue" },
+ });
+ }),
+ bridge.service,
+ mastra.factory,
+ );
+ });
+
+ it.effect("reads persisted image attachments for Mastra turns", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "akeru-mastra-image-"));
+ const attachmentsDir = NodePath.join(baseDir, "userdata", "attachments");
+ NodeFS.mkdirSync(attachmentsDir, { recursive: true });
+ NodeFS.writeFileSync(NodePath.join(attachmentsDir, "image-1.png"), "image");
+
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ });
+ yield* controller.sendTurn({
+ threadId: codexThreadId,
+ input: "Inspect this image.",
+ attachments: [
+ {
+ type: "image",
+ id: "image-1",
+ name: "screenshot.png",
+ mimeType: "image/png",
+ sizeBytes: 5,
+ },
+ ],
+ });
+
+ expect(mastra.sendMessage).toHaveBeenCalledWith({
+ content: `Inspect this image.\n\n[Attached image "screenshot.png" is saved at: ${NodePath.join(attachmentsDir, "image-1.png")}]`,
+ files: [
+ {
+ data: "aW1hZ2U=",
+ mediaType: "image/png",
+ filename: "screenshot.png",
+ },
+ ],
+ });
+ }).pipe(
+ Effect.ensuring(
+ Effect.sync(() => NodeFS.rmSync(baseDir, { recursive: true, force: true })),
+ ),
+ ),
+ bridge.service,
+ mastra.factory,
+ undefined,
+ baseDir,
+ );
+ });
+
+ it.effect("attaches the globally installed MCP servers selected for the bot", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ const mcpManager = {
+ init: vi.fn(async () => undefined),
+ disconnect: vi.fn(async () => undefined),
+ getTools: vi.fn(() => ({ exa_search: {} })),
+ };
+ const makeMcpManagerMock = vi.fn((_dataDir, _configDir, _servers) => mcpManager as never);
+ const makeMcpManager: NonNullable<AgentControllerLiveOptions["makeMcpManager"]> =
+ makeMcpManagerMock;
+ const exaServer = {
+ id: McpServerId.make("builtin-exa"),
+ name: "Exa",
+ transport: "url" as const,
+ url: "https://mcp.exa.ai/mcp",
+ enabled: true,
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ };
+
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ const session = yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ mcpServers: [exaServer],
+ });
+
+ assert.deepEqual(session.mcpServerIds, [exaServer.id]);
+ expect(makeMcpManagerMock).toHaveBeenCalledOnce();
+ expect(makeMcpManagerMock.mock.calls[0]?.[2]).toEqual({
+ "builtin-exa": { url: "https://mcp.exa.ai/mcp" },
+ });
+ expect(mcpManager.init).toHaveBeenCalledOnce();
+
+ yield* controller.stopSession({ threadId: codexThreadId });
+ expect(mcpManager.disconnect).toHaveBeenCalledOnce();
+ }),
+ bridge.service,
+ mastra.factory,
+ makeMcpManager,
+ );
+ });
+
+ it.effect("creates a remote Mastra workspace for the bot sandbox provider", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ const remote = new Workspace({
+ filesystem: new LocalFilesystem({ basePath: process.cwd() }),
+ sandbox: new LocalSandbox({ workingDirectory: process.cwd() }),
+ });
+ const makeRemoteWorkspace = vi.fn(async () => remote);
+ const layer = makeAgentControllerLive({
+ makeMastraHarness: mastra.factory,
+ makeRemoteWorkspace,
+ }).pipe(
+ Layer.provide(
+ Layer.merge(
+ Layer.succeed(LegacyProviderBridge, bridge.service),
+ ServerConfig.layerTest(process.cwd(), {
+ prefix: "akeru-mastra-remote-sandbox-test-",
+ }).pipe(Layer.provide(NodeServices.layer)),
+ ),
+ ),
+ );
+
+ return Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ cwd: process.cwd(),
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ botSandbox: "upstash",
+ });
+
+ expect(makeRemoteWorkspace).toHaveBeenCalledOnce();
+ expect(makeRemoteWorkspace).toHaveBeenCalledWith({
+ threadId: String(codexThreadId),
+ sandbox: "upstash",
+ });
+ expect(mastra.createSession.mock.calls[0]?.[0]).toMatchObject({ workspace: remote });
+ yield* controller.stopSession({ threadId: codexThreadId });
+ }).pipe(Effect.provide(layer), Effect.orDie);
+ });
+
+ it.effect("keeps Claude on the existing provider adapter", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* controller.resolveEngine({
+ threadId: claudeThreadId,
+ engine: { provider: "claudeAgent", model: "claude-fable-5" },
+ fallback: codexSelection,
+ mode: "plan",
+ });
+ yield* controller.startSession(claudeThreadId, {
+ threadId: claudeThreadId,
+ provider: ProviderDriverKind.make("claudeAgent"),
+ providerInstanceId: claudeInstanceId,
+ cwd: process.cwd(),
+ runtimeMode: "approval-required",
+ });
+ const result = yield* controller.sendTurn({
+ threadId: claudeThreadId,
+ input: "Use Claude.",
+ });
+
+ assert.equal(result.turnId, TurnId.make("legacy-turn"));
+ expect(bridge.startSession).toHaveBeenCalledOnce();
+ expect(bridge.sendTurn).toHaveBeenCalledOnce();
+ expect(mastra.createSession).not.toHaveBeenCalled();
+ expect(mastra.sendMessage).not.toHaveBeenCalled();
+ }),
+ bridge.service,
+ mastra.factory,
+ );
+ });
+
+ it.effect("stops a legacy session after resolving the thread to Codex", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ const legacySession = makeProviderSession(codexThreadId, "claudeAgent");
+ const service: ProviderServiceShape = {
+ ...bridge.service,
+ listSessions: () => Effect.succeed([legacySession]),
+ };
+
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* controller.resolveEngine({
+ threadId: codexThreadId,
+ engine: { provider: "claudeAgent", model: "claude-fable-5" },
+ fallback: codexSelection,
+ mode: "default",
+ });
+ yield* controller.resolveEngine({
+ threadId: codexThreadId,
+ engine: { provider: "codex", model: "gpt-5.6-sol" },
+ fallback: codexSelection,
+ mode: "default",
+ });
+ yield* controller.stopSession({ threadId: codexThreadId });
+
+ expect(bridge.stopSession).toHaveBeenCalledWith({ threadId: codexThreadId });
+ }),
+ service,
+ mastra.factory,
+ );
+ });
+
+ it.effect("does not fall back to the legacy Codex loop when its Mastra session is absent", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ const error = yield* controller
+ .sendTurn({ threadId: codexThreadId, input: "No legacy fallback." })
+ .pipe(Effect.flip);
+
+ assert.equal(error._tag, "AgentControllerRuntimeError");
+ expect(bridge.sendTurn).not.toHaveBeenCalled();
+ }),
+ bridge.service,
+ mastra.factory,
+ );
+ });
+});
diff --git a/apps/server/src/provider/Layers/AgentController.ts b/apps/server/src/provider/Layers/AgentController.ts
new file mode 100644
index 000000000..96f3c6ac1
--- /dev/null
+++ b/apps/server/src/provider/Layers/AgentController.ts
@@ -0,0 +1,928 @@
+// @effect-diagnostics globalDate:off globalConsole:off globalRandom:off nodeBuiltinImport:off
+import * as NodeCrypto from "node:crypto";
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { AuthStorage } from "@mastra/code-sdk/auth/storage";
+import {
+ createMcpManager,
+ type McpManager,
+ type McpServerConfig,
+} from "@mastra/code-sdk/mcp/index";
+import type {
+ AgentControllerEvent,
+ MastraDBMessage,
+ MastraMessagePart,
+} from "@mastra/core/agent-controller";
+import { Workspace } from "@mastra/core/workspace";
+import {
+ EventId,
+ ProviderDriverKind,
+ ProviderInstanceId,
+ RuntimeItemId,
+ RuntimeRequestId,
+ TurnId,
+ type McpServer,
+ type ModelSelection,
+ type ProviderApprovalDecision,
+ type ProviderRuntimeEvent,
+ type ProviderSession,
+ type RuntimeMode,
+ type ThreadId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PubSub from "effect/PubSub";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+
+import { resolveAttachmentPath } from "../../attachmentStore.ts";
+import { ServerConfig } from "../../config.ts";
+import {
+ createAkeruMastraHarness,
+ type AkeruMastraHarness,
+ type AkeruMastraHarnessOptions,
+ type AkeruMastraSession,
+} from "../AkeruMastraHarness.ts";
+import { createBotWorkspace, type CreateRemoteBotWorkspaceInput } from "../botWorkspace.ts";
+import { AgentControllerRuntimeError, AgentControllerUnsupportedEngineError } from "../Errors.ts";
+import { AgentController, type AgentControllerShape } from "../Services/AgentController.ts";
+import { LegacyProviderBridge } from "../Services/LegacyProviderBridge.ts";
+
+const DEFAULT_MODE_ID = "build";
+const PLAN_MODE_ID = "plan";
+type MastraSession = AkeruMastraSession;
+
+interface ResolvedEngine {
+ readonly modelSelection: ModelSelection;
+ readonly provider: ProviderDriverKind;
+ readonly providerInstanceId: ProviderInstanceId;
+ readonly mastraModelId: string;
+ readonly mode: "default" | "plan";
+}
+
+interface ActiveTurn {
+ readonly turnId: TurnId;
+ readonly assistantItemId: RuntimeItemId;
+ assistantLength: number;
+ assistantStarted: boolean;
+ assistantCompleted: boolean;
+ waiting: boolean;
+ finished: boolean;
+}
+
+interface ActiveSession {
+ readonly session: MastraSession;
+ readonly provider: ProviderDriverKind;
+ readonly providerInstanceId: ProviderInstanceId;
+ readonly cwd: string | undefined;
+ readonly createdAt: string;
+ readonly mcpServerIds: readonly McpServer["id"][];
+ runtimeMode: RuntimeMode;
+ model: string;
+ status: ProviderSession["status"];
+ activeTurn: ActiveTurn | null;
+ readonly toolNames: Map<string, string>;
+ readonly unsubscribe: () => void;
+}
+
+export interface AgentControllerLiveOptions {
+ readonly makeMastraHarness?: (options: AkeruMastraHarnessOptions) => Promise<AkeruMastraHarness>;
+ readonly makeMcpManager?: typeof createMcpManager;
+ readonly makeRemoteWorkspace?: (input: CreateRemoteBotWorkspaceInput) => Promise<Workspace>;
+}
+
+export function createAkeruMastraAuthStorage(secretsDir: string): AuthStorage {
+ return new AuthStorage(NodePath.join(secretsDir, "subscription-auth.json"));
+}
+
+function failureDetail(cause: unknown): string {
+ return cause instanceof Error ? cause.message : String(cause);
+}
+
+function nowIso(): string {
+ return new Date().toISOString();
+}
+
+function eventId(): EventId {
+ return EventId.make(`mastra-${NodeCrypto.randomUUID()}`);
+}
+
+function messageText(message: MastraDBMessage): string {
+ return message.content.parts
+ .filter(
+ (part): part is MastraMessagePart & { text: string } =>
+ part.type === "text" && typeof part.text === "string",
+ )
+ .map((part) => part.text)
+ .join("");
+}
+
+function mastraModeId(mode: "default" | "plan"): string {
+ return mode === "plan" ? PLAN_MODE_ID : DEFAULT_MODE_ID;
+}
+
+function mastraModelId(provider: ProviderDriverKind, model: string): string {
+ switch (String(provider)) {
+ case "codex":
+ return `openai/${model}`;
+ case "claudeAgent":
+ return `anthropic/${model}`;
+ case "grok":
+ return `xai/${model}`;
+ default:
+ return model.includes("/") ? model : `${provider}/${model}`;
+ }
+}
+
+export function toMcpServerConfigs(servers: readonly McpServer[]): Record<string, McpServerConfig> {
+ return Object.fromEntries(
+ servers.map((server) => [
+ String(server.id),
+ server.transport === "url"
+ ? { url: server.url }
+ : { command: server.command, ...(server.args ? { args: [...server.args] } : {}) },
+ ]),
+ );
+}
+
+function permissionPolicy(
+ runtimeMode: RuntimeMode,
+ category: "read" | "edit" | "execute" | "mcp" | "other",
+): "allow" | "ask" {
+ if (runtimeMode === "full-access" || runtimeMode === "auto") return "allow";
+ if (category === "read") return "allow";
+ if (runtimeMode === "auto-accept-edits" && category === "edit") return "allow";
+ return "ask";
+}
+
+function usesMastraCode(provider: ProviderDriverKind): boolean {
+ return String(provider) === "codex";
+}
+
+function itemType(
+ toolName: string,
+): "command_execution" | "file_change" | "mcp_tool_call" | "dynamic_tool_call" {
+ if (/execute|command|shell|terminal/i.test(toolName)) return "command_execution";
+ if (/edit|write|delete|mkdir|file/i.test(toolName)) return "file_change";
+ if (/mcp/i.test(toolName)) return "mcp_tool_call";
+ return "dynamic_tool_call";
+}
+
+const make = (options?: AgentControllerLiveOptions) =>
+ Effect.gen(function* () {
+ const config = yield* ServerConfig;
+ const legacyProviderBridge = yield* LegacyProviderBridge;
+ const mutationLock = yield* Semaphore.make(1);
+ const runtimeEvents = yield* PubSub.unbounded<ProviderRuntimeEvent>();
+ const resolvedByThread = new Map<string, ResolvedEngine>();
+ const sessions = new Map<string, ActiveSession>();
+
+ const runMastra = <A>(operation: string, run: () => Promise<A>) =>
+ Effect.tryPromise({
+ try: run,
+ catch: (cause) =>
+ new AgentControllerRuntimeError({
+ operation,
+ detail: failureDetail(cause),
+ cause,
+ }),
+ });
+
+ yield* Effect.sync(() => {
+ NodeFS.mkdirSync(config.stateDir, { recursive: true, mode: 0o700 });
+ });
+
+ const authStorage = createAkeruMastraAuthStorage(config.secretsDir);
+ const mcpManagers = new Map<string, McpManager>();
+ const workspaces = new Map<string, Workspace>();
+ const makeMastraHarness = options?.makeMastraHarness ?? createAkeruMastraHarness;
+ const bundle = yield* runMastra("construct", () =>
+ makeMastraHarness({
+ authStorage,
+ getThreadTools: (threadId) => mcpManagers.get(threadId)?.getTools() ?? {},
+ getThreadWorkspace: (threadId) => workspaces.get(threadId),
+ }),
+ );
+ yield* runMastra("init", () => bundle.controller.init());
+
+ const disconnectMcpManager = (key: string) => {
+ const manager = mcpManagers.get(key);
+ if (!manager) return Effect.void;
+ mcpManagers.delete(key);
+ return runMastra("mcp.disconnect", () => manager.disconnect()).pipe(
+ Effect.ignoreCause({ log: true }),
+ );
+ };
+
+ const disconnectWorkspace = (key: string) => {
+ const workspace = workspaces.get(key);
+ if (!workspace) return Effect.void;
+ workspaces.delete(key);
+ return runMastra("workspace.destroy", () => workspace.destroy()).pipe(
+ Effect.ignoreCause({ log: true }),
+ );
+ };
+
+ const publish = (event: ProviderRuntimeEvent) => {
+ PubSub.publishUnsafe(runtimeEvents, event);
+ };
+
+ const baseEvent = (
+ threadId: ThreadId,
+ active: Pick<ActiveSession, "provider" | "providerInstanceId">,
+ turnId?: TurnId,
+ ) => ({
+ eventId: eventId(),
+ provider: active.provider,
+ providerInstanceId: active.providerInstanceId,
+ threadId,
+ createdAt: nowIso(),
+ ...(turnId ? { turnId } : {}),
+ });
+
+ const publishSessionState = (
+ threadId: ThreadId,
+ active: ActiveSession,
+ state: "ready" | "running" | "waiting" | "stopped" | "error",
+ reason?: string,
+ ) => {
+ active.status =
+ state === "running"
+ ? "running"
+ : state === "error"
+ ? "error"
+ : state === "stopped"
+ ? "closed"
+ : "ready";
+ publish({
+ ...baseEvent(threadId, active, active.activeTurn?.turnId),
+ type: "session.state.changed",
+ payload: { state, ...(reason ? { reason } : {}) },
+ });
+ };
+
+ const finishTurn = (
+ threadId: ThreadId,
+ active: ActiveSession,
+ state: "completed" | "failed" | "interrupted",
+ errorMessage?: string,
+ ) => {
+ const turn = active.activeTurn;
+ if (!turn || turn.finished) return;
+ turn.finished = true;
+ if (turn.assistantStarted && !turn.assistantCompleted) {
+ turn.assistantCompleted = true;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: turn.assistantItemId,
+ type: "item.completed",
+ payload: { itemType: "assistant_message", status: "completed" },
+ });
+ }
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ type: "turn.completed",
+ payload: {
+ state,
+ ...(errorMessage ? { errorMessage } : {}),
+ },
+ });
+ active.activeTurn = null;
+ publishSessionState(threadId, active, "ready");
+ };
+
+ const publishAssistantText = (
+ threadId: ThreadId,
+ active: ActiveSession,
+ message: MastraDBMessage,
+ complete: boolean,
+ ) => {
+ if (message.role !== "assistant") return;
+ const turn = active.activeTurn;
+ if (!turn) return;
+ const text = messageText(message);
+ if (!turn.assistantStarted && text.length > 0) {
+ turn.assistantStarted = true;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: turn.assistantItemId,
+ type: "item.started",
+ payload: { itemType: "assistant_message", status: "inProgress" },
+ });
+ }
+ if (text.length > turn.assistantLength) {
+ const delta = text.slice(turn.assistantLength);
+ turn.assistantLength = text.length;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: turn.assistantItemId,
+ type: "content.delta",
+ payload: { streamKind: "assistant_text", delta },
+ });
+ }
+ if (complete && turn.assistantStarted && !turn.assistantCompleted) {
+ turn.assistantCompleted = true;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: turn.assistantItemId,
+ type: "item.completed",
+ payload: { itemType: "assistant_message", status: "completed" },
+ });
+ }
+ };
+
+ const handleControllerEvent = (
+ threadId: ThreadId,
+ active: ActiveSession,
+ event: AgentControllerEvent,
+ ) => {
+ const turn = active.activeTurn;
+ switch (event.type) {
+ case "message_update":
+ publishAssistantText(threadId, active, event.message, false);
+ return;
+ case "message_end":
+ publishAssistantText(threadId, active, event.message, true);
+ return;
+ case "tool_start": {
+ if (!turn) return;
+ active.toolNames.set(event.toolCallId, event.toolName);
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: RuntimeItemId.make(event.toolCallId),
+ type: "item.started",
+ payload: {
+ itemType: itemType(event.toolName),
+ status: "inProgress",
+ title: event.toolName,
+ data: { args: event.args },
+ },
+ });
+ return;
+ }
+ case "tool_update":
+ if (!turn) return;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: RuntimeItemId.make(event.toolCallId),
+ type: "item.updated",
+ payload: {
+ itemType: itemType(active.toolNames.get(event.toolCallId) ?? "tool"),
+ status: "inProgress",
+ data: { partialResult: event.partialResult },
+ },
+ });
+ return;
+ case "tool_end": {
+ if (!turn) return;
+ const toolName = active.toolNames.get(event.toolCallId) ?? "tool";
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ itemId: RuntimeItemId.make(event.toolCallId),
+ type: "item.completed",
+ payload: {
+ itemType: itemType(toolName),
+ status: event.isError ? "failed" : event.denied ? "declined" : "completed",
+ title: toolName,
+ data: { result: event.result },
+ },
+ });
+ return;
+ }
+ case "tool_approval_required":
+ if (!turn) return;
+ active.toolNames.set(event.toolCallId, event.toolName);
+ turn.waiting = true;
+ publishSessionState(threadId, active, "waiting");
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ requestId: RuntimeRequestId.make(event.toolCallId),
+ type: "request.opened",
+ payload: {
+ requestType: "dynamic_tool_call",
+ detail: `Allow ${event.toolName}?`,
+ args: event.args,
+ options: [
+ { decision: "accept", label: "Allow" },
+ { decision: "acceptForSession", label: "Allow for session" },
+ { decision: "decline", label: "Decline" },
+ ],
+ },
+ });
+ return;
+ case "tool_suspended":
+ if (!turn) return;
+ active.toolNames.set(event.toolCallId, event.toolName);
+ turn.waiting = true;
+ publishSessionState(threadId, active, "waiting");
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ requestId: RuntimeRequestId.make(event.toolCallId),
+ type: "user-input.requested",
+ payload: {
+ questions: [
+ {
+ id: event.toolCallId,
+ header: event.toolName,
+ question: `Input required for ${event.toolName}`,
+ options: [],
+ multiSelect: false,
+ },
+ ],
+ },
+ });
+ return;
+ case "usage_update":
+ if (!turn) return;
+ publish({
+ ...baseEvent(threadId, active, turn.turnId),
+ type: "thread.token-usage.updated",
+ payload: {
+ usage: {
+ usedTokens: Math.max(0, event.usage.totalTokens ?? 0),
+ inputTokens: Math.max(0, event.usage.promptTokens ?? 0),
+ outputTokens: Math.max(0, event.usage.completionTokens ?? 0),
+ reasoningOutputTokens: Math.max(0, event.usage.reasoningTokens ?? 0),
+ },
+ },
+ });
+ return;
+ case "error":
+ publish({
+ ...baseEvent(threadId, active, turn?.turnId),
+ type: "runtime.error",
+ payload: {
+ message: event.error.message || "Mastra agent failed.",
+ class: "provider_error",
+ },
+ });
+ finishTurn(threadId, active, "failed", event.error.message || "Mastra agent failed.");
+ return;
+ case "agent_end":
+ if (event.reason === "suspended") {
+ if (turn) turn.waiting = true;
+ publishSessionState(threadId, active, "waiting");
+ return;
+ }
+ finishTurn(
+ threadId,
+ active,
+ event.reason === "aborted"
+ ? "interrupted"
+ : event.reason === "error"
+ ? "failed"
+ : "completed",
+ );
+ return;
+ default:
+ return;
+ }
+ };
+
+ const inspectEngine: AgentControllerShape["inspectEngine"] = Effect.fn(
+ "AgentController.inspectEngine",
+ )(function* (modelSelection) {
+ const provider = String(modelSelection.instanceId);
+ const model = modelSelection.model;
+ const unavailable = (cause: unknown) =>
+ new AgentControllerUnsupportedEngineError({
+ provider,
+ model,
+ detail: `Provider instance '${provider}' is not available.`,
+ cause,
+ });
+ const routing = yield* legacyProviderBridge
+ .getInstanceInfo(modelSelection.instanceId)
+ .pipe(Effect.mapError(unavailable));
+ const capabilities = yield* legacyProviderBridge
+ .getCapabilities(modelSelection.instanceId)
+ .pipe(Effect.mapError(unavailable));
+ return { modelSelection, routing, capabilities };
+ });
+
+ const resolveEngine: AgentControllerShape["resolveEngine"] = (input) =>
+ mutationLock.withPermits(1)(
+ Effect.gen(function* () {
+ const modelSelection =
+ input.engine === null
+ ? input.fallback
+ : {
+ instanceId: ProviderInstanceId.make(input.engine.provider),
+ model: input.engine.model,
+ };
+ const inspected = yield* inspectEngine(modelSelection);
+ const resolved: ResolvedEngine = {
+ modelSelection,
+ provider: inspected.routing.driverKind,
+ providerInstanceId: modelSelection.instanceId,
+ mastraModelId: mastraModelId(inspected.routing.driverKind, modelSelection.model),
+ mode: input.mode,
+ };
+ resolvedByThread.set(String(input.threadId), resolved);
+ const active = sessions.get(String(input.threadId));
+ if (active && usesMastraCode(resolved.provider)) {
+ yield* runMastra("model.switch", () =>
+ active.session.model.switch({ modelId: resolved.mastraModelId }),
+ );
+ const nextMode = mastraModeId(input.mode);
+ if (active.session.mode.get() !== nextMode) {
+ yield* runMastra("mode.switch", () =>
+ active.session.mode.switch({ modeId: nextMode }),
+ );
+ }
+ active.model = modelSelection.model;
+ }
+ return { ...inspected, mode: input.mode };
+ }),
+ );
+
+ const startSession: AgentControllerShape["startSession"] = Effect.fn(
+ "AgentController.startSession",
+ )(function* (threadId, input) {
+ const key = String(threadId);
+ const existing = sessions.get(key);
+ if (existing) return toProviderSession(threadId, existing);
+ const resolved = resolvedByThread.get(key);
+ if (!resolved) {
+ return yield* new AgentControllerRuntimeError({
+ operation: "startSession",
+ detail: `Thread '${threadId}' has no resolved engine.`,
+ });
+ }
+ if (!usesMastraCode(resolved.provider)) {
+ return yield* legacyProviderBridge.startSession(threadId, input);
+ }
+ const mcpServers = input.mcpServers ?? [];
+ if (mcpServers.length > 0) {
+ const manager = (options?.makeMcpManager ?? createMcpManager)(
+ NodePath.join(config.stateDir, "bot-mcp-runtime"),
+ ".akeru-runtime",
+ toMcpServerConfigs(mcpServers),
+ );
+ yield* runMastra("mcp.init", () => manager.init());
+ mcpManagers.set(key, manager);
+ }
+ const workspace = yield* runMastra("workspace.create", () =>
+ createBotWorkspace({
+ threadId: key,
+ cwd: input.cwd,
+ sandbox: input.botSandbox,
+ ...(options?.makeRemoteWorkspace
+ ? { makeRemoteWorkspace: options.makeRemoteWorkspace }
+ : {}),
+ }),
+ );
+ if (workspace) workspaces.set(key, workspace);
+ const session = yield* runMastra("createSession", () =>
+ bundle.controller.createSession({
+ id: key,
+ ownerId: "akeru-desktop",
+ resourceId: key,
+ threadId: key,
+ ...(input.cwd ? { tags: { projectPath: input.cwd } } : {}),
+ ...(workspace ? { workspace } : {}),
+ }),
+ ).pipe(
+ Effect.tapError(() =>
+ Effect.all([disconnectMcpManager(key), disconnectWorkspace(key)], { discard: true }),
+ ),
+ );
+ yield* runMastra("state.set", () =>
+ session.state.set({
+ ...(input.cwd ? { projectPath: input.cwd } : {}),
+ yolo: input.runtimeMode === "full-access" || input.runtimeMode === "auto",
+ }),
+ );
+ yield* runMastra("model.switch", () =>
+ session.model.switch({ modelId: resolved.mastraModelId }),
+ );
+ const modeId = mastraModeId(resolved.mode);
+ if (session.mode.get() !== modeId) {
+ yield* runMastra("mode.switch", () => session.mode.switch({ modeId }));
+ }
+ yield* Effect.forEach(
+ ["read", "edit", "execute", "mcp", "other"] as const,
+ (category) =>
+ runMastra("permissions.setForCategory", () =>
+ session.permissions.setForCategory({
+ category,
+ policy: permissionPolicy(input.runtimeMode, category),
+ }),
+ ),
+ { discard: true },
+ );
+ const createdAt = nowIso();
+ const activeWithoutUnsubscribe = {
+ session,
+ provider: resolved.provider,
+ providerInstanceId: resolved.providerInstanceId,
+ cwd: input.cwd,
+ createdAt,
+ mcpServerIds: mcpServers.map((server) => server.id),
+ runtimeMode: input.runtimeMode,
+ model: resolved.modelSelection.model,
+ status: "ready" as const,
+ activeTurn: null,
+ toolNames: new Map<string, string>(),
+ };
+ const unsubscribe = session.subscribe((event) => {
+ const active = sessions.get(key);
+ if (active) handleControllerEvent(threadId, active, event);
+ });
+ const active: ActiveSession = { ...activeWithoutUnsubscribe, unsubscribe };
+ sessions.set(key, active);
+ publish({
+ ...baseEvent(threadId, active),
+ type: "session.started",
+ payload: { message: "Mastra Code session ready" },
+ });
+ publishSessionState(threadId, active, "ready");
+ return toProviderSession(threadId, active);
+ });
+
+ const sendTurn: AgentControllerShape["sendTurn"] = Effect.fn("AgentController.sendTurn")(
+ function* (input) {
+ const key = String(input.threadId);
+ const active = sessions.get(key);
+ if (!active) {
+ if (resolvedByThread.get(key)?.provider === ProviderDriverKind.make("codex")) {
+ return yield* new AgentControllerRuntimeError({
+ operation: "sendTurn",
+ detail: `Mastra session for thread '${input.threadId}' is not running.`,
+ });
+ }
+ return yield* legacyProviderBridge.sendTurn(input);
+ }
+ if (active.activeTurn) {
+ return yield* new AgentControllerRuntimeError({
+ operation: "sendTurn",
+ detail: `Mastra session for thread '${input.threadId}' already has an active turn.`,
+ });
+ }
+ const attachmentFiles = yield* Effect.forEach(input.attachments ?? [], (attachment) => {
+ const path = resolveAttachmentPath({
+ attachmentsDir: config.attachmentsDir,
+ attachment,
+ });
+ if (path === null) {
+ return Effect.fail(
+ new AgentControllerRuntimeError({
+ operation: "sendTurn.attachments",
+ detail: `Attachment '${attachment.id}' has an invalid path.`,
+ }),
+ );
+ }
+ return Effect.try({
+ try: () => ({
+ file: {
+ data: NodeFS.readFileSync(path).toString("base64"),
+ mediaType: attachment.mimeType,
+ filename: attachment.name,
+ },
+ pathLine: `[Attached image "${attachment.name}" is saved at: ${path}]`,
+ }),
+ catch: (cause) =>
+ new AgentControllerRuntimeError({
+ operation: "sendTurn.attachments",
+ detail: `Could not read attachment '${attachment.id}'.`,
+ cause,
+ }),
+ });
+ });
+ const content = [input.input, ...attachmentFiles.map(({ pathLine }) => pathLine)]
+ .filter((part): part is string => typeof part === "string" && part.length > 0)
+ .join("\n\n");
+ const files = attachmentFiles.map(({ file }) => file);
+ const turnId = TurnId.make(`mastra-turn-${NodeCrypto.randomUUID()}`);
+ active.activeTurn = {
+ turnId,
+ assistantItemId: RuntimeItemId.make(`mastra-answer-${turnId}`),
+ assistantLength: 0,
+ assistantStarted: false,
+ assistantCompleted: false,
+ waiting: false,
+ finished: false,
+ };
+ active.status = "running";
+ publish({
+ ...baseEvent(input.threadId, active, turnId),
+ type: "turn.started",
+ payload: { model: active.model },
+ });
+ publishSessionState(input.threadId, active, "running");
+ void active.session
+ .sendMessage({ content, ...(files.length > 0 ? { files } : {}) })
+ .then(() => {
+ if (!active.activeTurn?.waiting) {
+ finishTurn(input.threadId, active, "completed");
+ }
+ })
+ .catch((cause: unknown) => {
+ const detail = failureDetail(cause);
+ publish({
+ ...baseEvent(input.threadId, active, turnId),
+ type: "runtime.error",
+ payload: { message: detail, class: "provider_error" },
+ });
+ finishTurn(input.threadId, active, "failed", detail);
+ });
+ return { threadId: input.threadId, turnId };
+ },
+ );
+
+ const interruptTurn: AgentControllerShape["interruptTurn"] = Effect.fn(
+ "AgentController.interruptTurn",
+ )(function* (input) {
+ const key = String(input.threadId);
+ const active = sessions.get(key);
+ if (!active) {
+ if (
+ usesMastraCode(resolvedByThread.get(key)?.provider ?? ProviderDriverKind.make("codex"))
+ ) {
+ return;
+ }
+ return yield* legacyProviderBridge.interruptTurn(input);
+ }
+ active.session.abort();
+ finishTurn(input.threadId, active, "interrupted");
+ });
+
+ const respondToRequest: AgentControllerShape["respondToRequest"] = Effect.fn(
+ "AgentController.respondToRequest",
+ )(function* (input) {
+ const key = String(input.threadId);
+ const active = sessions.get(key);
+ if (!active) {
+ if (
+ usesMastraCode(resolvedByThread.get(key)?.provider ?? ProviderDriverKind.make("codex"))
+ ) {
+ return;
+ }
+ return yield* legacyProviderBridge.respondToRequest(input);
+ }
+ const toolCallId = String(input.requestId);
+ const toolName = active.toolNames.get(toolCallId);
+ if (input.decision === "acceptForSession" && toolName) {
+ yield* runMastra("permissions.setForTool", () =>
+ active.session.permissions.setForTool({ toolName, policy: "allow" }),
+ );
+ }
+ if (active.activeTurn) active.activeTurn.waiting = false;
+ active.session.respondToToolApproval({
+ toolCallId,
+ decision: approvalDecision(input.decision),
+ });
+ publish({
+ ...baseEvent(input.threadId, active, active.activeTurn?.turnId),
+ requestId: RuntimeRequestId.make(toolCallId),
+ type: "request.resolved",
+ payload: { requestType: "dynamic_tool_call" as const, decision: input.decision },
+ });
+ publishSessionState(input.threadId, active, "running");
+ });
+
+ const respondToUserInput: AgentControllerShape["respondToUserInput"] = Effect.fn(
+ "AgentController.respondToUserInput",
+ )(function* (input) {
+ const key = String(input.threadId);
+ const active = sessions.get(key);
+ if (!active) {
+ if (
+ usesMastraCode(resolvedByThread.get(key)?.provider ?? ProviderDriverKind.make("codex"))
+ ) {
+ return;
+ }
+ return yield* legacyProviderBridge.respondToUserInput(input);
+ }
+ const toolCallId = String(input.requestId);
+ if (active.activeTurn) active.activeTurn.waiting = false;
+ yield* runMastra("respondToToolSuspension", () =>
+ active.session.respondToToolSuspension({ toolCallId, resumeData: input.answers }),
+ );
+ publish({
+ ...baseEvent(input.threadId, active, active.activeTurn?.turnId),
+ requestId: RuntimeRequestId.make(toolCallId),
+ type: "user-input.resolved",
+ payload: { answers: input.answers },
+ });
+ publishSessionState(input.threadId, active, "running");
+ });
+
+ const stopSession: AgentControllerShape["stopSession"] = Effect.fn(
+ "AgentController.stopSession",
+ )(function* (input) {
+ const key = String(input.threadId);
+ const active = sessions.get(key);
+ if (!active) {
+ const legacySessions = yield* legacyProviderBridge.listSessions();
+ if (legacySessions.some((session) => session.threadId === input.threadId)) {
+ return yield* legacyProviderBridge.stopSession(input);
+ }
+ if (
+ usesMastraCode(resolvedByThread.get(key)?.provider ?? ProviderDriverKind.make("codex"))
+ ) {
+ return;
+ }
+ return yield* legacyProviderBridge.stopSession(input);
+ }
+ active.session.abort();
+ active.unsubscribe();
+ publishSessionState(input.threadId, active, "stopped");
+ yield* runMastra("deleteSession", () => bundle.controller.deleteSession({ resourceId: key }));
+ yield* disconnectMcpManager(key);
+ yield* disconnectWorkspace(key);
+ sessions.delete(key);
+ });
+
+ const rollbackConversation: AgentControllerShape["rollbackConversation"] = (input) => {
+ const resolved = resolvedByThread.get(String(input.threadId));
+ if (!sessions.has(String(input.threadId)) && !resolved) {
+ return legacyProviderBridge.rollbackConversation(input);
+ }
+ if (resolved && !usesMastraCode(resolved.provider)) {
+ return legacyProviderBridge.rollbackConversation(input);
+ }
+ return Effect.fail(
+ new AgentControllerRuntimeError({
+ operation: "rollbackConversation",
+ detail: `Mastra conversation rollback is not available for thread '${input.threadId}'.`,
+ }),
+ );
+ };
+
+ yield* Effect.addFinalizer(() =>
+ Effect.gen(function* () {
+ for (const [threadId, active] of sessions) {
+ active.session.abort();
+ active.unsubscribe();
+ yield* runMastra("deleteSession", () =>
+ bundle.controller.deleteSession({ resourceId: threadId }),
+ ).pipe(Effect.ignoreCause({ log: true }));
+ yield* disconnectMcpManager(threadId);
+ yield* disconnectWorkspace(threadId);
+ }
+ sessions.clear();
+ bundle.destroy();
+ yield* runMastra("destroy", () => bundle.controller.destroy()).pipe(
+ Effect.ignoreCause({ log: true }),
+ );
+ }),
+ );
+
+ return AgentController.of({
+ resolveEngine,
+ inspectEngine,
+ startSession,
+ sendTurn,
+ interruptTurn,
+ respondToRequest,
+ respondToUserInput,
+ stopSession,
+ listSessions: () =>
+ Effect.map(legacyProviderBridge.listSessions(), (legacySessions) => [
+ ...legacySessions,
+ ...[...sessions.entries()].map(([threadId, active]) =>
+ toProviderSession(ThreadIdBrand(threadId), active),
+ ),
+ ]),
+ rollbackConversation,
+ uploadFeedback: legacyProviderBridge.uploadFeedback,
+ get streamEvents() {
+ return Stream.merge(legacyProviderBridge.streamEvents, Stream.fromPubSub(runtimeEvents));
+ },
+ });
+ });
+
+function ThreadIdBrand(value: string): ThreadId {
+ return value as ThreadId;
+}
+
+function approvalDecision(
+ decision: ProviderApprovalDecision,
+): "approve" | "decline" | "always_allow_category" {
+ if (decision === "decline" || decision === "cancel") return "decline";
+ if (decision === "acceptAlways") return "always_allow_category";
+ return "approve";
+}
+
+function toProviderSession(threadId: ThreadId, active: ActiveSession): ProviderSession {
+ return {
+ provider: active.provider,
+ providerInstanceId: active.providerInstanceId,
+ status: active.status,
+ runtimeMode: active.runtimeMode,
+ ...(active.cwd ? { cwd: active.cwd } : {}),
+ model: active.model,
+ threadId,
+ mcpServerIds: active.mcpServerIds,
+ ...(active.activeTurn ? { activeTurnId: active.activeTurn.turnId } : {}),
+ createdAt: active.createdAt,
+ updatedAt: nowIso(),
+ };
+}
+
+export const makeAgentControllerLive = (options?: AgentControllerLiveOptions) =>
+ Layer.effect(AgentController, make(options));
+
+export const AgentControllerLive = makeAgentControllerLive();
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 46a7c0266..dd824796b 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -394,24 +394,38 @@ describe("ClaudeAdapterLive", () => {
);
});
- it.effect("uses bypass permissions for full-access claude sessions", () => {
- const harness = makeHarness();
- return Effect.gen(function* () {
- const adapter = yield* ClaudeAdapter;
- yield* adapter.startSession({
- threadId: THREAD_ID,
- provider: ProviderDriverKind.make("claudeAgent"),
- runtimeMode: "full-access",
- });
+ it.effect(
+ "uses bypass permissions and general Akeru instructions for full-access claude sessions",
+ () => {
+ const harness = makeHarness();
+ return Effect.gen(function* () {
+ const adapter = yield* ClaudeAdapter;
+ yield* adapter.startSession({
+ threadId: THREAD_ID,
+ provider: ProviderDriverKind.make("claudeAgent"),
+ runtimeMode: "full-access",
+ });
- const createInput = harness.getLastCreateQueryInput();
- assert.equal(createInput?.options.permissionMode, "bypassPermissions");
- assert.equal(createInput?.options.allowDangerouslySkipPermissions, true);
- }).pipe(
- Effect.provideService(Random.Random, makeDeterministicRandomService()),
- Effect.provide(harness.layer),
- );
- });
+ const createInput = harness.getLastCreateQueryInput();
+ assert.equal(createInput?.options.permissionMode, "bypassPermissions");
+ assert.equal(createInput?.options.allowDangerouslySkipPermissions, true);
+ assert.deepInclude(createInput?.options.systemPrompt, {
+ type: "preset",
+ preset: "claude_code",
+ });
+ assert.include(
+ typeof createInput?.options.systemPrompt === "object" &&
+ "append" in createInput.options.systemPrompt
+ ? (createInput.options.systemPrompt.append ?? "")
+ : "",
+ "general-purpose assistant",
+ );
+ }).pipe(
+ Effect.provideService(Random.Random, makeDeterministicRandomService()),
+ Effect.provide(harness.layer),
+ );
+ },
+ );
it.effect("passes the configured auto-compaction window to Claude", () => {
const harness = makeHarness({ claudeConfig: { autoCompactWindow: "300000" } });
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 173b7a2b0..df48ae473 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -78,7 +78,9 @@ import * as Stream from "effect/Stream";
import { resolveAttachmentPath } from "../../attachmentStore.ts";
import { ServerConfig } from "../../config.ts";
+import { AKERU_AGENT_INSTRUCTIONS } from "../AkeruAgentInstructions.ts";
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { toClaudeMcpServers } from "../McpServerConfig.ts";
import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
import {
@@ -4296,6 +4298,18 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
: {}),
};
const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
+ const mcpServers = {
+ ...toClaudeMcpServers(input.mcpServers ?? []),
+ ...(mcpSession
+ ? {
+ "t3-code": {
+ type: "http" as const,
+ url: mcpSession.endpoint,
+ headers: { Authorization: mcpSession.authorizationHeader },
+ },
+ }
+ : {}),
+ };
// The attachments dir grant lets the agent Read/copy pasted images at
// the paths ProviderService injects into the turn text, without an
// approval prompt. It is a leaf directory holding only attachment
@@ -4308,7 +4322,11 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
...(input.cwd ? { cwd: input.cwd } : {}),
...(apiModelId ? { model: apiModelId } : {}),
pathToClaudeCodeExecutable: claudeBinaryPath,
- systemPrompt: { type: "preset", preset: "claude_code" },
+ systemPrompt: {
+ type: "preset",
+ preset: "claude_code",
+ append: AKERU_AGENT_INSTRUCTIONS,
+ },
settingSources: [...CLAUDE_SETTING_SOURCES],
// `ultracode` is a Claude Code setting, not an API effort level. It is
// normalized to `xhigh` above and paired with `settings.ultracode`.
@@ -4331,19 +4349,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
env: claudeEnvironment,
additionalDirectories,
...(Object.keys(extraArgs).length > 0 ? { extraArgs } : {}),
- ...(mcpSession
- ? {
- mcpServers: {
- "t3-code": {
- type: "http",
- url: mcpSession.endpoint,
- headers: {
- Authorization: mcpSession.authorizationHeader,
- },
- },
- },
- }
- : {}),
+ ...(Object.keys(mcpServers).length > 0 ? { mcpServers } : {}),
};
yield* Effect.annotateCurrentSpan({
diff --git a/apps/server/src/provider/Layers/CursorAdapter.ts b/apps/server/src/provider/Layers/CursorAdapter.ts
index 30c173d8f..502e2673d 100644
--- a/apps/server/src/provider/Layers/CursorAdapter.ts
+++ b/apps/server/src/provider/Layers/CursorAdapter.ts
@@ -43,6 +43,7 @@ import type * as EffectAcpSchema from "effect-acp/schema";
import { resolveAttachmentPath } from "../../attachmentStore.ts";
import { ServerConfig } from "../../config.ts";
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { toAcpMcpServers } from "../McpServerConfig.ts";
import {
ProviderAdapterProcessError,
ProviderAdapterRequestError,
@@ -532,6 +533,24 @@ export function makeCursorAdapter(
: cursorSettings;
const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
+ const mcpServers = [
+ ...toAcpMcpServers(input.mcpServers ?? []),
+ ...(mcpSession
+ ? [
+ {
+ type: "http" as const,
+ name: "t3-code",
+ url: mcpSession.endpoint,
+ headers: [
+ {
+ name: "Authorization",
+ value: mcpSession.authorizationHeader,
+ },
+ ],
+ },
+ ]
+ : []),
+ ];
const acp = yield* makeCursorAcpRuntime({
cursorSettings: effectiveCursorSettings,
...(options?.environment ? { environment: options.environment } : {}),
@@ -539,23 +558,7 @@ export function makeCursorAdapter(
cwd,
...(resumeSessionId ? { resumeSessionId } : {}),
clientInfo: { name: "t3-code", version: "0.0.0" },
- ...(mcpSession
- ? {
- mcpServers: [
- {
- type: "http" as const,
- name: "t3-code",
- url: mcpSession.endpoint,
- headers: [
- {
- name: "Authorization",
- value: mcpSession.authorizationHeader,
- },
- ],
- },
- ],
- }
- : {}),
+ ...(mcpServers.length > 0 ? { mcpServers } : {}),
...acpNativeLoggers,
}).pipe(
Effect.provideService(Crypto.Crypto, crypto),
diff --git a/apps/server/src/provider/Layers/GrokAdapter.ts b/apps/server/src/provider/Layers/GrokAdapter.ts
index 858d862e6..d04cd908a 100644
--- a/apps/server/src/provider/Layers/GrokAdapter.ts
+++ b/apps/server/src/provider/Layers/GrokAdapter.ts
@@ -35,6 +35,7 @@ import type * as EffectAcpSchema from "effect-acp/schema";
import { resolveAttachmentPath } from "../../attachmentStore.ts";
import { ServerConfig } from "../../config.ts";
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { toAcpMcpServers } from "../McpServerConfig.ts";
import {
ProviderAdapterProcessError,
ProviderAdapterRequestError,
@@ -570,6 +571,24 @@ export function makeGrokAdapter(grokSettings: GrokSettings, options?: GrokAdapte
});
const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
+ const mcpServers = [
+ ...toAcpMcpServers(input.mcpServers ?? []),
+ ...(mcpSession
+ ? [
+ {
+ type: "http" as const,
+ name: "t3-code",
+ url: mcpSession.endpoint,
+ headers: [
+ {
+ name: "Authorization",
+ value: mcpSession.authorizationHeader,
+ },
+ ],
+ },
+ ]
+ : []),
+ ];
const acp = yield* makeGrokAcpRuntime({
grokSettings,
...(options?.environment ? { environment: options.environment } : {}),
@@ -577,23 +596,7 @@ export function makeGrokAdapter(grokSettings: GrokSettings, options?: GrokAdapte
cwd,
...(resumeSessionId ? { resumeSessionId } : {}),
clientInfo: { name: "t3-code", version: "0.0.0" },
- ...(mcpSession
- ? {
- mcpServers: [
- {
- type: "http" as const,
- name: "t3-code",
- url: mcpSession.endpoint,
- headers: [
- {
- name: "Authorization",
- value: mcpSession.authorizationHeader,
- },
- ],
- },
- ],
- }
- : {}),
+ ...(mcpServers.length > 0 ? { mcpServers } : {}),
...acpNativeLoggers,
}).pipe(
Effect.provideService(Crypto.Crypto, crypto),
diff --git a/apps/server/src/provider/Layers/LegacyProviderBridge.ts b/apps/server/src/provider/Layers/LegacyProviderBridge.ts
new file mode 100644
index 000000000..d14390bc0
--- /dev/null
+++ b/apps/server/src/provider/Layers/LegacyProviderBridge.ts
@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import { LegacyProviderBridge } from "../Services/LegacyProviderBridge.ts";
+import { ProviderService } from "../Services/ProviderService.ts";
+
+/** The only adapter that calls the existing ProviderService from AgentController. */
+export const LegacyProviderBridgeLive = Layer.effect(
+ LegacyProviderBridge,
+ Effect.map(ProviderService, LegacyProviderBridge.of),
+);
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
index 8f7e42c11..6902253a7 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
@@ -1231,6 +1231,27 @@ export function makeOpenCodeAdapter(
directory,
...(server.external && serverPassword ? { serverPassword } : {}),
});
+ yield* Effect.forEach(
+ input.mcpServers ?? [],
+ (mcpServer) =>
+ runOpenCodeSdk("mcp.add", () =>
+ client.mcp.add({
+ name: String(mcpServer.id),
+ config:
+ mcpServer.transport === "url"
+ ? {
+ type: "remote",
+ url: mcpServer.url,
+ oauth: false,
+ }
+ : {
+ type: "local",
+ command: [mcpServer.command, ...(mcpServer.args ?? [])],
+ },
+ }),
+ ),
+ { discard: true },
+ );
const mcpSession = McpProviderSession.readMcpProviderSession(input.threadId);
if (mcpSession && !server.external) {
yield* runOpenCodeSdk("mcp.add", () =>
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
index 0b1bc9e14..a8c890039 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
@@ -1,12 +1,5 @@
import * as NodeServices from "@effect/platform-node/NodeServices";
-import {
- ProjectId,
- ThreadId,
- TurnId,
- ProviderDriverKind,
- ProviderInstanceId,
-} from "@t3tools/contracts";
-import * as Clock from "effect/Clock";
+import { ProjectId, ThreadId, TurnId, ProviderInstanceId } from "@t3tools/contracts";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
@@ -14,15 +7,14 @@ import * as Layer from "effect/Layer";
import * as ManagedRuntime from "effect/ManagedRuntime";
import * as Option from "effect/Option";
import * as Scope from "effect/Scope";
-import * as Stream from "effect/Stream";
import { afterEach, describe, expect, it, vi } from "vite-plus/test";
import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
import * as ProviderSessionRuntime from "../../persistence/ProviderSessionRuntime.ts";
import { ProviderValidationError } from "../Errors.ts";
+import { AgentController, type AgentControllerShape } from "../Services/AgentController.ts";
import { ProviderSessionReaper } from "../Services/ProviderSessionReaper.ts";
-import { ProviderService, type ProviderServiceShape } from "../Services/ProviderService.ts";
import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
import { makeProviderSessionReaperLive } from "./ProviderSessionReaper.ts";
@@ -31,31 +23,10 @@ const defaultModelSelection = {
model: "gpt-5-codex",
} as const;
-async function waitFor(
- predicate: () => boolean | Promise<boolean>,
- timeoutMs = 2_000,
-): Promise<void> {
- const deadline = (await Effect.runPromise(Clock.currentTimeMillis)) + timeoutMs;
- const poll = async (): Promise<void> => {
- if (await predicate()) {
- return;
- }
- if ((await Effect.runPromise(Clock.currentTimeMillis)) >= deadline) {
- throw new Error("Timed out waiting for expectation.");
- }
- await Effect.runPromise(Effect.yieldNow);
- return poll();
- };
-
- return poll();
-}
-
const drainFibers = Effect.forEach(Array.from({ length: 10 }), () => Effect.yieldNow, {
discard: true,
});
-const unsupported = () => Effect.die(new Error("Unsupported provider call in test")) as never;
-
function makeReadModel(
threads: ReadonlyArray<{
readonly id: ThreadId;
@@ -149,44 +120,27 @@ describe("ProviderSessionReaper", () => {
readonly readModel: ReturnType<typeof makeReadModel>;
readonly stopSessionImplementation?: (input: {
readonly threadId: ThreadId;
- }) => ReturnType<ProviderServiceShape["stopSession"]>;
+ }) => ReturnType<AgentControllerShape["stopSession"]>;
}) {
const stoppedThreadIds = new Set<ThreadId>();
- const stopSession = vi.fn<ProviderServiceShape["stopSession"]>(
- (request) =>
- (input.stopSessionImplementation
- ? input.stopSessionImplementation(request)
- : Effect.sync(() => {
- stoppedThreadIds.add(request.threadId);
- })) as ReturnType<ProviderServiceShape["stopSession"]>,
- );
-
- const providerService: ProviderServiceShape = {
- startSession: () => unsupported(),
- sendTurn: () => unsupported(),
- interruptTurn: () => unsupported(),
- respondToRequest: () => unsupported(),
- respondToUserInput: () => unsupported(),
- stopSession,
- listSessions: () => Effect.succeed([]),
- getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" }),
- getInstanceInfo: (instanceId) => {
- const driverKind = ProviderDriverKind.make(String(instanceId));
- return Effect.succeed({
- instanceId,
- driverKind,
- displayName: undefined,
- enabled: true,
- continuationIdentity: {
- driverKind,
- continuationKey: `${driverKind}:instance:${instanceId}`,
- },
- });
- },
- rollbackConversation: () => unsupported(),
- uploadFeedback: () => unsupported(),
- streamEvents: Stream.empty,
- };
+ const stopWaiters = new Map<number, () => void>();
+ const stopSession = vi.fn<AgentControllerShape["stopSession"]>((request) => {
+ const operation = input.stopSessionImplementation
+ ? input.stopSessionImplementation(request)
+ : Effect.sync(() => stoppedThreadIds.add(request.threadId));
+ return operation.pipe(
+ Effect.ensuring(
+ Effect.sync(() => {
+ for (const [count, resolve] of stopWaiters) {
+ if (stopSession.mock.calls.length >= count) {
+ stopWaiters.delete(count);
+ resolve();
+ }
+ }
+ }),
+ ),
+ ) as ReturnType<AgentControllerShape["stopSession"]>;
+ });
const runtimeRepositoryLayer = ProviderSessionRuntime.layer.pipe(
Layer.provide(SqlitePersistenceMemory),
@@ -200,7 +154,7 @@ describe("ProviderSessionReaper", () => {
}).pipe(
Layer.provideMerge(providerSessionDirectoryLayer),
Layer.provideMerge(runtimeRepositoryLayer),
- Layer.provideMerge(Layer.succeed(ProviderService, providerService)),
+ Layer.provideMerge(Layer.mock(AgentController)({ stopSession })),
Layer.provideMerge(
Layer.succeed(ProjectionSnapshotQuery, {
getCommandReadModel: () => Effect.die("unused"),
@@ -229,11 +183,18 @@ describe("ProviderSessionReaper", () => {
Layer.provideMerge(NodeServices.layer),
);
+ const waitForStopCount = (count: number) => {
+ if (stopSession.mock.calls.length >= count) {
+ return Promise.resolve();
+ }
+ return new Promise<void>((resolve) => stopWaiters.set(count, resolve));
+ };
+
runtime = ManagedRuntime.make(layer);
- return { stopSession, stoppedThreadIds };
+ return { stopSession, stoppedThreadIds, waitForStopCount };
}
- it("reaps stale persisted sessions without active turns", async () => {
+ it("reaps an idle session through AgentController stop", async () => {
const threadId = ThreadId.make("thread-reaper-stale");
const now = "2026-01-01T00:00:00.000Z";
const harness = await createHarness({
@@ -274,7 +235,7 @@ describe("ProviderSessionReaper", () => {
await startReaper();
- await waitFor(() => harness.stopSession.mock.calls.length === 1);
+ await harness.waitForStopCount(1);
expect(harness.stopSession.mock.calls[0]?.[0]).toEqual({ threadId });
expect(harness.stoppedThreadIds.has(threadId)).toBe(true);
@@ -548,7 +509,7 @@ describe("ProviderSessionReaper", () => {
await startReaper();
- await waitFor(() => harness.stopSession.mock.calls.length === 2);
+ await harness.waitForStopCount(2);
expect(harness.stopSession.mock.calls.map(([request]) => request.threadId)).toEqual([
failedThreadId,
@@ -629,7 +590,7 @@ describe("ProviderSessionReaper", () => {
await startReaper();
- await waitFor(() => harness.stopSession.mock.calls.length === 2);
+ await harness.waitForStopCount(2);
expect(harness.stopSession.mock.calls.map(([request]) => request.threadId)).toEqual([
defectThreadId,
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
index 15d4f925c..83124b2e1 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
@@ -6,13 +6,13 @@ import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import { ProjectionSnapshotQuery } from "../../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { AgentController } from "../Services/AgentController.ts";
import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
import {
ProviderSessionReaper,
type ProviderSessionReaperShape,
} from "../Services/ProviderSessionReaper.ts";
import { forkParked } from "../../serverActivation.ts";
-import { ProviderService } from "../Services/ProviderService.ts";
const DEFAULT_INACTIVITY_THRESHOLD_MS = 30 * 60 * 1000;
const DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
@@ -24,7 +24,7 @@ export interface ProviderSessionReaperLiveOptions {
const makeProviderSessionReaper = (options?: ProviderSessionReaperLiveOptions) =>
Effect.gen(function* () {
- const providerService = yield* ProviderService;
+ const agentController = yield* AgentController;
const directory = yield* ProviderSessionDirectory;
const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
@@ -84,7 +84,7 @@ const makeProviderSessionReaper = (options?: ProviderSessionReaperLiveOptions) =
continue;
}
- const reaped = yield* providerService.stopSession({ threadId: binding.threadId }).pipe(
+ const reaped = yield* agentController.stopSession({ threadId: binding.threadId }).pipe(
Effect.tap(() =>
Effect.logInfo("provider.session.reaped", {
threadId: binding.threadId,
diff --git a/apps/server/src/provider/McpServerConfig.test.ts b/apps/server/src/provider/McpServerConfig.test.ts
new file mode 100644
index 000000000..24b1d55e5
--- /dev/null
+++ b/apps/server/src/provider/McpServerConfig.test.ts
@@ -0,0 +1,42 @@
+import { McpServerId, type McpServer } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { toAcpMcpServers, toClaudeMcpServers } from "./McpServerConfig.ts";
+
+const servers: readonly McpServer[] = [
+ {
+ id: McpServerId.make("search"),
+ name: "Search",
+ transport: "url",
+ url: "https://mcp.example.com",
+ enabled: true,
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ },
+ {
+ id: McpServerId.make("local"),
+ name: "Local",
+ transport: "stdio",
+ command: "bunx",
+ args: ["local-mcp"],
+ enabled: true,
+ createdAt: "2026-01-01T00:00:00.000Z",
+ updatedAt: "2026-01-01T00:00:00.000Z",
+ },
+];
+
+describe("provider MCP configuration", () => {
+ it("converts filtered servers for ACP adapters", () => {
+ expect(toAcpMcpServers(servers)).toEqual([
+ { type: "http", name: "Search", url: "https://mcp.example.com", headers: [] },
+ { name: "Local", command: "bunx", args: ["local-mcp"], env: [] },
+ ]);
+ });
+
+ it("converts filtered servers for Claude", () => {
+ expect(toClaudeMcpServers(servers)).toEqual({
+ search: { type: "http", url: "https://mcp.example.com", headers: {} },
+ local: { type: "stdio", command: "bunx", args: ["local-mcp"] },
+ });
+ });
+});
diff --git a/apps/server/src/provider/McpServerConfig.ts b/apps/server/src/provider/McpServerConfig.ts
new file mode 100644
index 000000000..b96130bcb
--- /dev/null
+++ b/apps/server/src/provider/McpServerConfig.ts
@@ -0,0 +1,37 @@
+import type { McpServer } from "@t3tools/contracts";
+import type * as EffectAcpSchema from "effect-acp/schema";
+
+export function toAcpMcpServers(
+ servers: readonly McpServer[],
+): ReadonlyArray<EffectAcpSchema.McpServer> {
+ return servers.map((server) =>
+ server.transport === "url"
+ ? {
+ type: "http" as const,
+ name: server.name,
+ url: server.url,
+ headers: [],
+ }
+ : {
+ name: server.name,
+ command: server.command,
+ args: [...(server.args ?? [])],
+ env: [],
+ },
+ );
+}
+
+export function toClaudeMcpServers(servers: readonly McpServer[]) {
+ return Object.fromEntries(
+ servers.map((server) => [
+ String(server.id),
+ server.transport === "url"
+ ? { type: "http" as const, url: server.url, headers: {} }
+ : {
+ type: "stdio" as const,
+ command: server.command,
+ args: [...(server.args ?? [])],
+ },
+ ]),
+ );
+}
diff --git a/apps/server/src/provider/Services/AgentController.ts b/apps/server/src/provider/Services/AgentController.ts
new file mode 100644
index 000000000..aa0e3f3ed
--- /dev/null
+++ b/apps/server/src/provider/Services/AgentController.ts
@@ -0,0 +1,96 @@
+import type {
+ BotEngine,
+ ModelSelection,
+ ProviderInteractionMode,
+ ProviderInterruptTurnInput,
+ ProviderRespondToRequestInput,
+ ProviderRespondToUserInputInput,
+ ProviderRuntimeEvent,
+ ProviderSendTurnInput,
+ ProviderSession,
+ ProviderSessionStartInput,
+ ProviderStopSessionInput,
+ ProviderTurnStartResult,
+ ProviderUploadFeedbackInput,
+ ProviderUploadFeedbackResult,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+
+import type { AgentControllerError } from "../Errors.ts";
+import type { ProviderAdapterCapabilities } from "./ProviderAdapter.ts";
+import type { ProviderInstanceRoutingInfo } from "./ProviderAdapterRegistry.ts";
+
+export interface AgentControllerAvailableEngine {
+ readonly modelSelection: ModelSelection;
+ readonly routing: ProviderInstanceRoutingInfo;
+ readonly capabilities: ProviderAdapterCapabilities;
+}
+
+export interface AgentControllerEngineSelection extends AgentControllerAvailableEngine {
+ readonly mode: ProviderInteractionMode;
+}
+
+export interface AgentControllerShape {
+ /** Resolve a thread's selected mode and model to an available Akeru provider instance. */
+ readonly resolveEngine: (input: {
+ readonly threadId: ThreadId;
+ readonly engine: BotEngine | null;
+ readonly fallback: ModelSelection;
+ readonly mode: ProviderInteractionMode;
+ }) => Effect.Effect<AgentControllerEngineSelection, AgentControllerError>;
+
+ /** Read routing metadata without changing the thread's active runtime session. */
+ readonly inspectEngine: (
+ modelSelection: ModelSelection,
+ ) => Effect.Effect<AgentControllerAvailableEngine, AgentControllerError>;
+
+ readonly startSession: (
+ threadId: ThreadId,
+ input: ProviderSessionStartInput,
+ ) => Effect.Effect<ProviderSession, AgentControllerError>;
+
+ readonly sendTurn: (
+ input: ProviderSendTurnInput,
+ ) => Effect.Effect<ProviderTurnStartResult, AgentControllerError>;
+
+ readonly interruptTurn: (
+ input: ProviderInterruptTurnInput,
+ ) => Effect.Effect<void, AgentControllerError>;
+
+ readonly respondToRequest: (
+ input: ProviderRespondToRequestInput,
+ ) => Effect.Effect<void, AgentControllerError>;
+
+ readonly respondToUserInput: (
+ input: ProviderRespondToUserInputInput,
+ ) => Effect.Effect<void, AgentControllerError>;
+
+ readonly stopSession: (
+ input: ProviderStopSessionInput,
+ ) => Effect.Effect<void, AgentControllerError>;
+
+ readonly listSessions: () => Effect.Effect<ReadonlyArray<ProviderSession>>;
+
+ readonly rollbackConversation: (input: {
+ readonly threadId: ThreadId;
+ readonly numTurns: number;
+ }) => Effect.Effect<void, AgentControllerError>;
+
+ readonly uploadFeedback: (
+ input: ProviderUploadFeedbackInput,
+ ) => Effect.Effect<ProviderUploadFeedbackResult, AgentControllerError>;
+
+ /**
+ * Codex events are normalized from Mastra controller sessions. Other provider
+ * adapters already produce the canonical event contract. Runtime ingestion
+ * consumes the merged stream once.
+ */
+ readonly streamEvents: Stream.Stream<ProviderRuntimeEvent>;
+}
+
+export class AgentController extends Context.Service<AgentController, AgentControllerShape>()(
+ "t3/provider/Services/AgentController",
+) {}
diff --git a/apps/server/src/provider/Services/LegacyProviderBridge.ts b/apps/server/src/provider/Services/LegacyProviderBridge.ts
new file mode 100644
index 000000000..8e93bb7b3
--- /dev/null
+++ b/apps/server/src/provider/Services/LegacyProviderBridge.ts
@@ -0,0 +1,14 @@
+import * as Context from "effect/Context";
+
+import type { ProviderServiceShape } from "./ProviderService.ts";
+
+/**
+ * Adapter from Akeru's AgentController seam to the existing subscription-backed
+ * provider runtimes. Mastra cannot drive the provider CLI session contract, so
+ * the bridge keeps those adapters behind the controller instead of exposing
+ * them to orchestration reactors.
+ */
+export class LegacyProviderBridge extends Context.Service<
+ LegacyProviderBridge,
+ ProviderServiceShape
+>()("t3/provider/Services/LegacyProviderBridge") {}
diff --git a/apps/server/src/provider/botWorkspace.test.ts b/apps/server/src/provider/botWorkspace.test.ts
new file mode 100644
index 000000000..323122f07
--- /dev/null
+++ b/apps/server/src/provider/botWorkspace.test.ts
@@ -0,0 +1,47 @@
+import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
+import { assert, describe, expect, it, vi } from "vite-plus/test";
+
+import { createBotWorkspace, isRemoteBotSandbox } from "./botWorkspace.ts";
+
+describe("createBotWorkspace", () => {
+ it("treats vercel, akeru-cloud, and upstash as remote sandboxes", () => {
+ expect(isRemoteBotSandbox("local")).toBe(false);
+ expect(isRemoteBotSandbox(null)).toBe(false);
+ expect(isRemoteBotSandbox("vercel")).toBe(true);
+ expect(isRemoteBotSandbox("akeru-cloud")).toBe(true);
+ expect(isRemoteBotSandbox("upstash")).toBe(true);
+ });
+
+ it("builds a local Mastra workspace from the thread cwd", async () => {
+ const workspace = await createBotWorkspace({
+ threadId: "thread-local",
+ cwd: process.cwd(),
+ sandbox: "local",
+ });
+ assert.isDefined(workspace);
+ expect(workspace?.sandbox).toBeInstanceOf(LocalSandbox);
+ expect(workspace?.filesystem).toBeInstanceOf(LocalFilesystem);
+ await workspace?.destroy();
+ });
+
+ it("uses the selected remote sandbox provider", async () => {
+ const remote = new Workspace({
+ filesystem: new LocalFilesystem({ basePath: process.cwd() }),
+ sandbox: new LocalSandbox({ workingDirectory: process.cwd() }),
+ });
+ const makeRemoteWorkspace = vi.fn(async () => remote);
+ const workspace = await createBotWorkspace({
+ threadId: "thread-vercel",
+ cwd: process.cwd(),
+ sandbox: "vercel",
+ makeRemoteWorkspace,
+ });
+ expect(makeRemoteWorkspace).toHaveBeenCalledOnce();
+ expect(makeRemoteWorkspace).toHaveBeenCalledWith({
+ threadId: "thread-vercel",
+ sandbox: "vercel",
+ });
+ expect(workspace).toBe(remote);
+ await workspace?.destroy();
+ });
+});
diff --git a/apps/server/src/provider/botWorkspace.ts b/apps/server/src/provider/botWorkspace.ts
new file mode 100644
index 000000000..fabb0b97e
--- /dev/null
+++ b/apps/server/src/provider/botWorkspace.ts
@@ -0,0 +1,71 @@
+import { TOOL_NAME_OVERRIDES } from "@mastra/code-sdk/tool-names";
+import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
+import type { BotSandbox } from "@t3tools/contracts";
+
+export const REMOTE_BOT_SANDBOXES = ["vercel", "akeru-cloud", "upstash"] as const;
+export type RemoteBotSandbox = (typeof REMOTE_BOT_SANDBOXES)[number];
+
+export function isRemoteBotSandbox(
+ value: BotSandbox | null | undefined,
+): value is RemoteBotSandbox {
+ return value === "vercel" || value === "akeru-cloud" || value === "upstash";
+}
+
+export interface CreateRemoteBotWorkspaceInput {
+ readonly threadId: string;
+ readonly sandbox: RemoteBotSandbox;
+}
+
+export interface CreateBotWorkspaceInput {
+ readonly threadId: string;
+ readonly cwd?: string;
+ readonly sandbox?: BotSandbox | null;
+ readonly makeRemoteWorkspace?: (input: CreateRemoteBotWorkspaceInput) => Promise<Workspace>;
+}
+
+export async function createBotWorkspace(
+ input: CreateBotWorkspaceInput,
+): Promise<Workspace | undefined> {
+ if (isRemoteBotSandbox(input.sandbox)) {
+ return await (input.makeRemoteWorkspace ?? createRemoteMastraWorkspace)({
+ threadId: input.threadId,
+ sandbox: input.sandbox,
+ });
+ }
+ if (!input.cwd) return undefined;
+ return new Workspace({
+ id: `akeru-${input.threadId}`,
+ name: `Akeru ${input.threadId}`,
+ filesystem: new LocalFilesystem({ basePath: input.cwd }),
+ sandbox: new LocalSandbox({ workingDirectory: input.cwd }),
+ tools: TOOL_NAME_OVERRIDES,
+ });
+}
+
+export async function createRemoteMastraWorkspace(
+ input: CreateRemoteBotWorkspaceInput,
+): Promise<Workspace> {
+ const { createMastraWorkspace } = await import("@opencoredev/sandbox-sdk/mastra");
+ return createMastraWorkspace({
+ id: `akeru-${input.threadId}`,
+ provider: await loadSandboxProvider(input.sandbox),
+ workspace: {
+ id: `akeru-${input.threadId}`,
+ name: `Akeru ${input.threadId}`,
+ tools: TOOL_NAME_OVERRIDES,
+ },
+ });
+}
+
+async function loadSandboxProvider(sandbox: RemoteBotSandbox) {
+ if (sandbox === "vercel") {
+ const { vercel } = await import("@opencoredev/sandbox-sdk/vercel");
+ return vercel();
+ }
+ if (sandbox === "upstash") {
+ const { upstash } = await import("@opencoredev/sandbox-sdk/upstash");
+ return upstash();
+ }
+ const { e2b } = await import("@opencoredev/sandbox-sdk/e2b");
+ return e2b();
+}
diff --git a/apps/server/src/subscription-auth/authorizationInput.ts b/apps/server/src/subscription-auth/authorizationInput.ts
new file mode 100644
index 000000000..d39bc9bc4
--- /dev/null
+++ b/apps/server/src/subscription-auth/authorizationInput.ts
@@ -0,0 +1,44 @@
+/**
+ * Forgiving parser for user-pasted OAuth authorization input.
+ *
+ * Ported from Mastra Code (mastra-ai/mastra,
+ * `mastracode/sdk/src/auth/authorization-input.ts`), Apache-2.0.
+ *
+ * Accepts, in order of preference:
+ * - a full redirect URL (`https://.../callback?code=...&state=...`)
+ * - the `code#state` form shown on Anthropic's hosted callback page
+ * - a raw query string (`code=...&state=...`)
+ * - a bare authorization code
+ */
+export function parseAuthorizationInput(input: string): {
+ code?: string | undefined;
+ state?: string | undefined;
+} {
+ const value = input.trim();
+ if (!value) return {};
+
+ try {
+ const url = new URL(value);
+ return {
+ code: url.searchParams.get("code") ?? undefined,
+ state: url.searchParams.get("state") ?? undefined,
+ };
+ } catch {
+ // not a URL
+ }
+
+ if (value.includes("#")) {
+ const [code, state] = value.split("#", 2);
+ return { code, state };
+ }
+
+ if (value.includes("code=")) {
+ const params = new URLSearchParams(value);
+ return {
+ code: params.get("code") ?? undefined,
+ state: params.get("state") ?? undefined,
+ };
+ }
+
+ return { code: value };
+}
diff --git a/apps/server/src/subscription-auth/deviceCode.test.ts b/apps/server/src/subscription-auth/deviceCode.test.ts
new file mode 100644
index 000000000..39731561c
--- /dev/null
+++ b/apps/server/src/subscription-auth/deviceCode.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { createDeviceCodePollState, nextPollDelayMs, stepDeviceCodePoll } from "./deviceCode.ts";
+
+const NOW = 1_700_000_000_000;
+
+describe("device code polling", () => {
+ it("uses the provider interval and expiration", () => {
+ const state = createDeviceCodePollState({
+ intervalSeconds: 5,
+ expiresInSeconds: 600,
+ now: NOW,
+ });
+ expect(state).toEqual({
+ deadlineAt: NOW + 600_000,
+ intervalMs: 5_000,
+ slowDownResponses: 0,
+ });
+ expect(nextPollDelayMs(state, NOW)).toBe(6_000);
+ });
+
+ it("grows the interval after slow_down", async () => {
+ const state = createDeviceCodePollState({ expiresInSeconds: 600, now: NOW });
+ const result = await stepDeviceCodePoll(
+ state,
+ async () => ({ status: "slow_down" as const }),
+ NOW,
+ );
+ expect(result.status).toBe("slow_down");
+ expect(result.state.slowDownResponses).toBe(1);
+ expect(result.state.intervalMs).toBe(10_000);
+ if (result.status === "slow_down") expect(result.nextPollMs).toBe(14_000);
+ });
+
+ it("returns completion without changing the state", async () => {
+ const state = createDeviceCodePollState({ expiresInSeconds: 600, now: NOW });
+ const result = await stepDeviceCodePoll(
+ state,
+ async () => ({ status: "complete" as const, result: "token" }),
+ NOW,
+ );
+ expect(result).toEqual({ status: "complete", result: "token", state });
+ });
+
+ it("fails before polling after expiration", async () => {
+ const state = createDeviceCodePollState({ expiresInSeconds: 1, now: NOW });
+ let polled = false;
+ const result = await stepDeviceCodePoll(
+ state,
+ async () => {
+ polled = true;
+ return { status: "pending" as const };
+ },
+ NOW + 1_001,
+ );
+ expect(polled).toBe(false);
+ expect(result.status).toBe("failed");
+ });
+});
diff --git a/apps/server/src/subscription-auth/deviceCode.ts b/apps/server/src/subscription-auth/deviceCode.ts
new file mode 100644
index 000000000..cce595c9f
--- /dev/null
+++ b/apps/server/src/subscription-auth/deviceCode.ts
@@ -0,0 +1,125 @@
+// @effect-diagnostics globalDate:off
+/**
+ * RFC 8628 (OAuth 2.0 Device Authorization Grant) polling helpers.
+ *
+ * Ported from Mastra Code (mastra-ai/mastra, `mastracode/sdk/src/auth/device-code.ts`),
+ * Apache-2.0. Only the single-step API is kept: the client drives polling over
+ * RPC, so every poll state must be JSON-serializable between requests.
+ */
+
+const DEFAULT_INTERVAL_SECONDS = 5;
+const INITIAL_POLL_INTERVAL_MULTIPLIER = 1.2;
+const SLOW_DOWN_POLL_INTERVAL_MULTIPLIER = 1.4;
+const SLOW_DOWN_INTERVAL_INCREMENT_MS = 5000;
+
+/** Serializable poll-loop state. Safe to round-trip through JSON. */
+export interface DeviceCodePollState {
+ /** ms epoch after which the device authorization is considered expired. */
+ deadlineAt: number;
+ /** Current base poll interval in ms (grows on slow_down responses). */
+ intervalMs: number;
+ /** Number of slow_down responses observed so far. */
+ slowDownResponses: number;
+}
+
+export function createDeviceCodePollState(options: {
+ /** Poll interval suggested by the server, in seconds. Defaults to 5 (RFC 8628). */
+ intervalSeconds?: number | undefined;
+ /** Lifetime of the device code, in seconds. */
+ expiresInSeconds: number;
+ /** Override "now" for tests. */
+ now?: number | undefined;
+}): DeviceCodePollState {
+ const now = options.now ?? Date.now();
+ const intervalSeconds =
+ typeof options.intervalSeconds === "number" && options.intervalSeconds > 0
+ ? options.intervalSeconds
+ : DEFAULT_INTERVAL_SECONDS;
+ return {
+ deadlineAt: now + options.expiresInSeconds * 1000,
+ intervalMs: Math.max(1000, Math.floor(intervalSeconds * 1000)),
+ slowDownResponses: 0,
+ };
+}
+
+/**
+ * Classified result of one upstream token-endpoint poll. Providers implement
+ * the HTTP request and map their response shape onto this union.
+ */
+export type DeviceCodePollOutcome<T> =
+ | { status: "complete"; result: T }
+ | { status: "pending"; intervalSeconds?: number | undefined }
+ | { status: "slow_down"; intervalSeconds?: number | undefined }
+ | { status: "failed"; error: string };
+
+export type DeviceCodeStepResult<T> =
+ | { status: "complete"; result: T; state: DeviceCodePollState }
+ | { status: "pending"; nextPollMs: number; state: DeviceCodePollState }
+ | { status: "slow_down"; nextPollMs: number; state: DeviceCodePollState }
+ | { status: "failed"; error: string; state: DeviceCodePollState };
+
+function timeoutMessage(state: DeviceCodePollState): string {
+ if (state.slowDownResponses > 0) {
+ // Repeated slow_down responses followed by a timeout usually means the
+ // local clock is behind the server's (common in WSL/VMs after sleep).
+ return "Device flow timed out after one or more slow_down responses. This is often caused by clock drift in WSL or VM environments. Sync the clock and try again.";
+ }
+ return "Device flow timed out";
+}
+
+/**
+ * Delay to wait before the next poll, honoring slow_down growth and clamped
+ * to the remaining lifetime of the device code.
+ */
+export function nextPollDelayMs(state: DeviceCodePollState, now: number = Date.now()): number {
+ const multiplier =
+ state.slowDownResponses > 0
+ ? SLOW_DOWN_POLL_INTERVAL_MULTIPLIER
+ : INITIAL_POLL_INTERVAL_MULTIPLIER;
+ const remainingMs = Math.max(0, state.deadlineAt - now);
+ return Math.min(Math.ceil(state.intervalMs * multiplier), remainingMs);
+}
+
+/**
+ * Perform exactly one upstream poll and fold the outcome into the poll state.
+ * Never throws for flow-level conditions — timeouts and provider errors are
+ * reported as `{ status: 'failed' }` so callers can persist/report them.
+ */
+export async function stepDeviceCodePoll<T>(
+ state: DeviceCodePollState,
+ pollOnce: () => Promise<DeviceCodePollOutcome<T>>,
+ now: number = Date.now(),
+): Promise<DeviceCodeStepResult<T>> {
+ if (now >= state.deadlineAt) {
+ return { status: "failed", error: timeoutMessage(state), state };
+ }
+
+ const outcome = await pollOnce();
+
+ switch (outcome.status) {
+ case "complete":
+ return { status: "complete", result: outcome.result, state };
+ case "failed":
+ return { status: "failed", error: outcome.error, state };
+ case "slow_down": {
+ const next: DeviceCodePollState = {
+ ...state,
+ slowDownResponses: state.slowDownResponses + 1,
+ // RFC 8628 section 3.5: grow the interval by 5 seconds, unless the
+ // server told us the interval to use.
+ intervalMs:
+ typeof outcome.intervalSeconds === "number" && outcome.intervalSeconds > 0
+ ? outcome.intervalSeconds * 1000
+ : Math.max(1000, state.intervalMs + SLOW_DOWN_INTERVAL_INCREMENT_MS),
+ };
+ return { status: "slow_down", nextPollMs: nextPollDelayMs(next, now), state: next };
+ }
+ case "pending": {
+ const next: DeviceCodePollState =
+ typeof outcome.intervalSeconds === "number" && outcome.intervalSeconds > 0
+ ? { ...state, intervalMs: Math.max(1000, outcome.intervalSeconds * 1000) }
+ : state;
+ return { status: "pending", nextPollMs: nextPollDelayMs(next, now), state: next };
+ }
+ }
+}
diff --git a/apps/server/src/subscription-auth/pkce.ts b/apps/server/src/subscription-auth/pkce.ts
new file mode 100644
index 000000000..ba398963a
--- /dev/null
+++ b/apps/server/src/subscription-auth/pkce.ts
@@ -0,0 +1,28 @@
+/**
+ * PKCE utilities using the Web Crypto API.
+ * Ported from Mastra Code (mastra-ai/mastra, `mastracode/sdk/src/auth/pkce.ts`), Apache-2.0.
+ */
+
+export function base64urlEncode(bytes: Uint8Array): string {
+ let binary = "";
+ for (const byte of bytes) {
+ binary += String.fromCharCode(byte);
+ }
+ return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+/** Generate a PKCE code verifier and its S256 challenge. */
+export async function generatePKCE(): Promise<{
+ verifier: string;
+ challenge: string;
+}> {
+ const verifierBytes = new Uint8Array(32);
+ crypto.getRandomValues(verifierBytes);
+ const verifier = base64urlEncode(verifierBytes);
+
+ const data = new TextEncoder().encode(verifier);
+ const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+ const challenge = base64urlEncode(new Uint8Array(hashBuffer));
+
+ return { verifier, challenge };
+}
diff --git a/apps/server/src/subscription-auth/providers/anthropic.ts b/apps/server/src/subscription-auth/providers/anthropic.ts
new file mode 100644
index 000000000..0f20894d2
--- /dev/null
+++ b/apps/server/src/subscription-auth/providers/anthropic.ts
@@ -0,0 +1,131 @@
+// @effect-diagnostics globalFetch:off globalDate:off
+/**
+ * Anthropic OAuth flow (Claude Pro/Max).
+ *
+ * Ported from Mastra Code (mastra-ai/mastra,
+ * `mastracode/sdk/src/auth/providers/anthropic.ts`), Apache-2.0; originally
+ * inspired by pi-mono's implementation.
+ *
+ * Paste-code PKCE flow: the redirect lands on Anthropic's hosted callback page
+ * which displays `code#state` for the user to paste back. No inbound
+ * connection to this server is needed, so the flow works locally, remotely,
+ * and from a phone. Only the PKCE verifier spans the two steps.
+ */
+
+import { parseAuthorizationInput } from "../authorizationInput.ts";
+import { generatePKCE } from "../pkce.ts";
+import type { OAuthCredentials } from "../types.ts";
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl");
+const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+const TOKEN_URL = "https://console.anthropic.com/v1/oauth/token";
+const REDIRECT_URI = "https://console.anthropic.com/oauth/code/callback";
+const SCOPES = "org:create_api_key user:profile user:inference";
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+export interface AnthropicLoginStart {
+ /** Authorization URL for the user to open. */
+ url: string;
+ /** PKCE code verifier — persist it to complete the login later. */
+ verifier: string;
+}
+
+/** Start an Anthropic login: generate PKCE state and build the authorization URL. */
+export async function startAnthropicLogin(): Promise<AnthropicLoginStart> {
+ const { verifier, challenge } = await generatePKCE();
+
+ const authParams = new URLSearchParams({
+ code: "true",
+ client_id: CLIENT_ID,
+ response_type: "code",
+ redirect_uri: REDIRECT_URI,
+ scope: SCOPES,
+ code_challenge: challenge,
+ code_challenge_method: "S256",
+ state: verifier,
+ });
+
+ return { url: `${AUTHORIZE_URL}?${authParams.toString()}`, verifier };
+}
+
+/**
+ * Complete an Anthropic login: parse the pasted authorization input
+ * (full URL, `code#state`, or query string), validate its state, and exchange
+ * it for tokens using the verifier from `startAnthropicLogin()`.
+ */
+export async function completeAnthropicLogin(
+ input: string,
+ verifier: string,
+): Promise<OAuthCredentials> {
+ const { code, state } = parseAuthorizationInput(input);
+ if (!code) {
+ throw new Error("Missing authorization code");
+ }
+ if (!state || state !== verifier) {
+ throw new Error("Invalid authorization state");
+ }
+
+ const tokenResponse = await fetch(TOKEN_URL, {
+ method: "POST",
+ // Bound the OAuth exchange so an unresponsive upstream cannot pin the caller.
+ signal: AbortSignal.timeout(15_000),
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ grant_type: "authorization_code",
+ client_id: CLIENT_ID,
+ code,
+ state,
+ redirect_uri: REDIRECT_URI,
+ code_verifier: verifier,
+ }),
+ });
+
+ if (!tokenResponse.ok) {
+ const error = await tokenResponse.text();
+ throw new Error(`Token exchange failed: ${error}`);
+ }
+
+ const tokenData = (await tokenResponse.json()) as {
+ access_token: string;
+ refresh_token: string;
+ expires_in: number;
+ };
+
+ return {
+ refresh: tokenData.refresh_token,
+ access: tokenData.access_token,
+ expires: Date.now() + tokenData.expires_in * 1000 - REFRESH_SKEW_MS,
+ };
+}
+
+/** Refresh an Anthropic OAuth token. */
+export async function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ signal: AbortSignal.timeout(15_000),
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ grant_type: "refresh_token",
+ client_id: CLIENT_ID,
+ refresh_token: refreshToken,
+ }),
+ });
+
+ if (!response.ok) {
+ const error = await response.text();
+ throw new Error(`Anthropic token refresh failed: ${error}`);
+ }
+
+ const data = (await response.json()) as {
+ access_token: string;
+ refresh_token: string;
+ expires_in: number;
+ };
+
+ return {
+ refresh: data.refresh_token,
+ access: data.access_token,
+ expires: Date.now() + data.expires_in * 1000 - REFRESH_SKEW_MS,
+ };
+}
diff --git a/apps/server/src/subscription-auth/providers/cursor.ts b/apps/server/src/subscription-auth/providers/cursor.ts
new file mode 100644
index 000000000..22bea9c1f
--- /dev/null
+++ b/apps/server/src/subscription-auth/providers/cursor.ts
@@ -0,0 +1,169 @@
+// @effect-diagnostics globalFetch:off globalDate:off cryptoRandomUUID:off
+/**
+ * Cursor subscription OAuth.
+ *
+ * Ported from Mastra Code PR mastra-ai/mastra#22427
+ * (`mastracode/sdk/src/auth/providers/cursor.ts`), Apache-2.0. Same flow Pi
+ * uses in pi-cursor-oauth.
+ *
+ * Browser PKCE login against cursor.com/loginDeepControl, then poll
+ * api2.cursor.sh/auth/poll. The poll endpoint returns 404 until the user
+ * approves, so this maps onto the same step-poll shape as a device flow.
+ */
+import type { OAuthCredentials } from "../types.ts";
+import { base64urlEncode } from "../pkce.ts";
+
+const LOGIN_URL = "https://cursor.com/loginDeepControl";
+const POLL_URL = "https://api2.cursor.sh/auth/poll";
+const REFRESH_URL = "https://api2.cursor.sh/auth/exchange_user_api_key";
+const POLL_BACKOFF = 1.2;
+const POLL_BASE_DELAY_MS = 1000;
+const POLL_MAX_DELAY_MS = 10_000;
+const LOGIN_LIFETIME_MS = 10 * 60 * 1000;
+const MAX_CONSECUTIVE_ERRORS = 3;
+const DEFAULT_TOKEN_TTL_MS = 60 * 60 * 1000;
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+/** Serializable pending state for a Cursor login. */
+export interface CursorLoginPending {
+ uuid: string;
+ verifier: string;
+ url: string;
+ /** Current poll delay in ms (grows while the endpoint returns 404). */
+ delayMs: number;
+ /** Consecutive transport/HTTP errors observed so far. */
+ consecutiveErrors: number;
+ /** ms epoch after which the login attempt is abandoned. */
+ deadlineAt: number;
+}
+
+export type CursorPollResult =
+ | { status: "complete"; credentials: OAuthCredentials }
+ | { status: "pending"; nextPollMs: number; pending: CursorLoginPending }
+ | { status: "failed"; error: string };
+
+/** Start a Cursor login: generate PKCE material and the deep-control URL. */
+export async function startCursorLogin(now: number = Date.now()): Promise<CursorLoginPending> {
+ const array = new Uint8Array(32);
+ crypto.getRandomValues(array);
+ const verifier = base64urlEncode(array);
+ const hash = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+ const challenge = base64urlEncode(new Uint8Array(hash));
+ const uuid = crypto.randomUUID();
+ const params = new URLSearchParams({
+ challenge,
+ uuid,
+ mode: "login",
+ redirectTarget: "cli",
+ });
+ return {
+ uuid,
+ verifier,
+ url: `${LOGIN_URL}?${params.toString()}`,
+ delayMs: POLL_BASE_DELAY_MS,
+ consecutiveErrors: 0,
+ deadlineAt: now + LOGIN_LIFETIME_MS,
+ };
+}
+
+export function cursorTokenExpiry(token: string): number {
+ try {
+ const payload = token.split(".")[1];
+ if (!payload) return Date.now() + DEFAULT_TOKEN_TTL_MS - REFRESH_SKEW_MS;
+ const decoded = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/"))) as {
+ exp?: unknown;
+ };
+ if (typeof decoded.exp === "number") return decoded.exp * 1000 - REFRESH_SKEW_MS;
+ } catch {
+ // Fall through to the default TTL.
+ }
+ return Date.now() + DEFAULT_TOKEN_TTL_MS - REFRESH_SKEW_MS;
+}
+
+/**
+ * Perform exactly one poll for a pending Cursor login. 404 means the user has
+ * not approved yet. Never throws for flow-level conditions.
+ */
+export async function pollCursorLogin(
+ pending: CursorLoginPending,
+ options?: { signal?: AbortSignal },
+ now: number = Date.now(),
+): Promise<CursorPollResult> {
+ if (now >= pending.deadlineAt) {
+ return { status: "failed", error: "Cursor authentication timed out" };
+ }
+
+ try {
+ const url = `${POLL_URL}?uuid=${encodeURIComponent(pending.uuid)}&verifier=${encodeURIComponent(
+ pending.verifier,
+ )}`;
+ const response =
+ options?.signal !== undefined
+ ? await fetch(url, { signal: options.signal })
+ : await fetch(url);
+ if (response.status === 404) {
+ const next: CursorLoginPending = {
+ ...pending,
+ consecutiveErrors: 0,
+ delayMs: Math.min(Math.round(pending.delayMs * POLL_BACKOFF), POLL_MAX_DELAY_MS),
+ };
+ return { status: "pending", nextPollMs: next.delayMs, pending: next };
+ }
+ if (!response.ok) throw new Error(`Poll failed: ${response.status}`);
+ const data = (await response.json()) as { accessToken?: unknown; refreshToken?: unknown };
+ if (typeof data.accessToken !== "string" || typeof data.refreshToken !== "string") {
+ throw new Error("Cursor poll response missing tokens");
+ }
+ return {
+ status: "complete",
+ credentials: {
+ refresh: data.refreshToken,
+ access: data.accessToken,
+ expires: cursorTokenExpiry(data.accessToken),
+ },
+ };
+ } catch (error) {
+ const consecutiveErrors = pending.consecutiveErrors + 1;
+ if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+ const message = error instanceof Error ? error.message : String(error);
+ return {
+ status: "failed",
+ error: `Too many consecutive errors during Cursor auth polling: ${message}`,
+ };
+ }
+ const next: CursorLoginPending = { ...pending, consecutiveErrors };
+ return { status: "pending", nextPollMs: next.delayMs, pending: next };
+ }
+}
+
+/** Refresh a Cursor token by exchanging the stored refresh (or access) token. */
+export async function refreshCursorToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+ const bearer =
+ typeof credentials.refresh === "string" && credentials.refresh.length > 0
+ ? credentials.refresh
+ : credentials.access;
+ const response = await fetch(REFRESH_URL, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${bearer}`,
+ "Content-Type": "application/json",
+ },
+ body: "{}",
+ });
+ if (!response.ok) {
+ const text = await response.text().catch(() => "");
+ throw new Error(`Cursor token refresh failed: ${response.status}${text ? ` ${text}` : ""}`);
+ }
+ const data = (await response.json()) as { accessToken?: unknown; refreshToken?: unknown };
+ if (typeof data.accessToken !== "string" || !data.accessToken) {
+ throw new Error("Cursor token refresh response missing accessToken");
+ }
+ return {
+ refresh:
+ typeof data.refreshToken === "string" && data.refreshToken.length > 0
+ ? data.refreshToken
+ : bearer,
+ access: data.accessToken,
+ expires: cursorTokenExpiry(data.accessToken),
+ };
+}
diff --git a/apps/server/src/subscription-auth/providers/kimi.ts b/apps/server/src/subscription-auth/providers/kimi.ts
new file mode 100644
index 000000000..57eb7ee03
--- /dev/null
+++ b/apps/server/src/subscription-auth/providers/kimi.ts
@@ -0,0 +1,278 @@
+// @effect-diagnostics globalFetch:off globalDate:off globalTimers:off
+/**
+ * Kimi For Coding OAuth flow (Moonshot).
+ *
+ * Ported from Mastra Code PR mastra-ai/mastra#22428
+ * (`mastracode/sdk/src/auth/providers/kimi-coding.ts`), Apache-2.0.
+ *
+ * RFC 8628-style device flow against auth.kimi.com. Device metadata headers
+ * identify the client; the device id is random per process.
+ */
+
+import * as NodeCrypto from "node:crypto";
+import * as NodeOS from "node:os";
+
+import { createDeviceCodePollState, stepDeviceCodePoll } from "../deviceCode.ts";
+import type { DeviceCodePollOutcome, DeviceCodePollState } from "../deviceCode.ts";
+import type { OAuthCredentials } from "../types.ts";
+
+const CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098";
+const OAUTH_HOST = "https://auth.kimi.com";
+const DEFAULT_EXPIRES_IN_SECONDS = 15 * 60;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const REQUEST_TIMEOUT_MS = 30_000;
+const REFRESH_MAX_RETRIES = 3;
+
+function asciiHeaderValue(value: string): string {
+ const sanitized = value.replace(/[^\x20-\x7E]/g, "").trim();
+ return sanitized || "unknown";
+}
+
+const KIMI_DEVICE_HEADERS = {
+ "X-Msh-Platform": "akeru",
+ "X-Msh-Device-Name": asciiHeaderValue(NodeOS.hostname()),
+ "X-Msh-Device-Model": "Akeru server",
+ "X-Msh-Os-Version": asciiHeaderValue(NodeOS.release()),
+ "X-Msh-Device-Id": NodeCrypto.randomUUID().replaceAll("-", ""),
+};
+
+function requestSignal(signal?: AbortSignal): AbortSignal {
+ const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+ return signal ? AbortSignal.any([timeout, signal]) : timeout;
+}
+
+function trustedHttpUrl(value: unknown): string | null {
+ if (typeof value !== "string" || !value) return null;
+ try {
+ const url = new URL(value);
+ return url.protocol === "https:" ? url.href : null;
+ } catch {
+ return null;
+ }
+}
+
+async function readJson(response: Response): Promise<Record<string, unknown> | null> {
+ try {
+ const value = (await response.json()) as unknown;
+ return value && typeof value === "object" ? (value as Record<string, unknown>) : null;
+ } catch {
+ return null;
+ }
+}
+
+function credentialsFromTokenResponse(value: unknown, operation: string): OAuthCredentials {
+ const data = (value ?? {}) as Record<string, unknown>;
+ const access = data.access_token;
+ const refresh = data.refresh_token;
+ const expiresIn = data.expires_in;
+ if (
+ typeof access !== "string" ||
+ !access ||
+ typeof refresh !== "string" ||
+ !refresh ||
+ typeof expiresIn !== "number" ||
+ !Number.isFinite(expiresIn) ||
+ expiresIn <= 0
+ ) {
+ throw new Error(`Kimi For Coding token ${operation} response missing fields`);
+ }
+ return { access, refresh, expires: Date.now() + expiresIn * 1000 };
+}
+
+export interface KimiDeviceLoginPending {
+ deviceCode: string;
+ userCode: string;
+ url: string;
+ instructions: string;
+ state: DeviceCodePollState;
+}
+
+export type KimiDevicePollResult =
+ | { status: "complete"; credentials: OAuthCredentials }
+ | { status: "pending"; nextPollMs: number; pending: KimiDeviceLoginPending }
+ | { status: "failed"; error: string };
+
+export async function startKimiDeviceLogin(options?: {
+ signal?: AbortSignal;
+}): Promise<KimiDeviceLoginPending> {
+ const response = await fetch(`${OAUTH_HOST}/api/oauth/device_authorization`, {
+ method: "POST",
+ headers: {
+ ...KIMI_DEVICE_HEADERS,
+ "Content-Type": "application/x-www-form-urlencoded",
+ Accept: "application/json",
+ },
+ body: new URLSearchParams({ client_id: CLIENT_ID }).toString(),
+ signal: requestSignal(options?.signal),
+ });
+ if (!response.ok) {
+ const text = await response.text().catch(() => "");
+ throw new Error(
+ `Kimi For Coding device authorization failed: ${response.status}${text ? ` ${text}` : ""}`,
+ );
+ }
+
+ const data = await readJson(response);
+ const deviceCode = data?.device_code;
+ const userCode = data?.user_code;
+ const verificationUri = trustedHttpUrl(data?.verification_uri);
+ const verificationUriComplete = trustedHttpUrl(data?.verification_uri_complete);
+ if (
+ typeof deviceCode !== "string" ||
+ !deviceCode ||
+ typeof userCode !== "string" ||
+ !userCode ||
+ !verificationUri ||
+ !verificationUriComplete
+ ) {
+ throw new Error("Invalid Kimi For Coding device authorization response");
+ }
+
+ const interval = data?.interval;
+ const expiresIn = data?.expires_in;
+ return {
+ deviceCode,
+ userCode,
+ url: verificationUriComplete,
+ instructions: `Enter code: ${userCode}`,
+ state: createDeviceCodePollState({
+ intervalSeconds:
+ typeof interval === "number" && Number.isFinite(interval) && interval > 0
+ ? interval
+ : DEFAULT_POLL_INTERVAL_SECONDS,
+ expiresInSeconds:
+ typeof expiresIn === "number" && Number.isFinite(expiresIn) && expiresIn > 0
+ ? expiresIn
+ : DEFAULT_EXPIRES_IN_SECONDS,
+ }),
+ };
+}
+
+async function pollKimiTokenOnce(
+ pending: KimiDeviceLoginPending,
+ signal?: AbortSignal,
+): Promise<DeviceCodePollOutcome<OAuthCredentials>> {
+ const response = await fetch(`${OAUTH_HOST}/api/oauth/token`, {
+ method: "POST",
+ headers: {
+ ...KIMI_DEVICE_HEADERS,
+ "Content-Type": "application/x-www-form-urlencoded",
+ Accept: "application/json",
+ },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ device_code: pending.deviceCode,
+ grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+ }).toString(),
+ signal: requestSignal(signal),
+ });
+ const data = await readJson(response);
+ if (response.ok && typeof data?.access_token === "string") {
+ try {
+ return { status: "complete", result: credentialsFromTokenResponse(data, "poll") };
+ } catch (error) {
+ return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+ }
+ }
+
+ const error = data?.error;
+ if (error === "authorization_pending") return { status: "pending" };
+ if (error === "slow_down") {
+ return {
+ status: "slow_down",
+ intervalSeconds:
+ typeof data?.interval === "number" && data.interval > 0 ? data.interval : undefined,
+ };
+ }
+ if (error === "expired_token") {
+ return {
+ status: "failed",
+ error: "Kimi For Coding authorization expired. Restart the login.",
+ };
+ }
+ if (error === "access_denied") {
+ return { status: "failed", error: "Kimi For Coding login was denied." };
+ }
+ const description =
+ typeof data?.error_description === "string" ? `: ${data.error_description}` : "";
+ return {
+ status: "failed",
+ error: `Kimi For Coding token request failed: ${response.status}${
+ typeof error === "string" ? ` ${error}${description}` : ""
+ }`,
+ };
+}
+
+export async function pollKimiDeviceLogin(
+ pending: KimiDeviceLoginPending,
+ options?: { signal?: AbortSignal },
+): Promise<KimiDevicePollResult> {
+ const step = await stepDeviceCodePoll(pending.state, () =>
+ pollKimiTokenOnce(pending, options?.signal),
+ );
+ if (step.status === "complete") return { status: "complete", credentials: step.result };
+ if (step.status === "failed") return { status: "failed", error: step.error };
+ return {
+ status: "pending",
+ nextPollMs: step.nextPollMs,
+ pending: { ...pending, state: step.state },
+ };
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+ return new Promise((resolve, reject) => {
+ if (signal?.aborted) {
+ reject(new Error("Login cancelled"));
+ return;
+ }
+ const timer = setTimeout(resolve, ms);
+ signal?.addEventListener(
+ "abort",
+ () => {
+ clearTimeout(timer);
+ reject(new Error("Login cancelled"));
+ },
+ { once: true },
+ );
+ });
+}
+
+/** Refresh a Kimi For Coding OAuth token, retrying transient upstream failures. */
+export async function refreshKimiToken(
+ refreshToken: string,
+ signal?: AbortSignal,
+): Promise<OAuthCredentials> {
+ let lastError: Error | undefined;
+ for (let attempt = 0; attempt <= REFRESH_MAX_RETRIES; attempt++) {
+ if (attempt > 0) await sleep(1000 * 2 ** (attempt - 1), signal);
+ let response: Response;
+ try {
+ response = await fetch(`${OAUTH_HOST}/api/oauth/token`, {
+ method: "POST",
+ headers: {
+ ...KIMI_DEVICE_HEADERS,
+ "Content-Type": "application/x-www-form-urlencoded",
+ Accept: "application/json",
+ },
+ body: new URLSearchParams({
+ client_id: CLIENT_ID,
+ grant_type: "refresh_token",
+ refresh_token: refreshToken,
+ }).toString(),
+ signal: requestSignal(signal),
+ });
+ } catch (error) {
+ lastError = error instanceof Error ? error : new Error(String(error));
+ if (attempt === REFRESH_MAX_RETRIES) throw lastError;
+ continue;
+ }
+ const data = await readJson(response);
+ if (response.ok) return credentialsFromTokenResponse(data, "refresh");
+
+ const errorSuffix = typeof data?.error === "string" ? ` ${data.error}` : "";
+ lastError = new Error(`Kimi For Coding token refresh failed: ${response.status}${errorSuffix}`);
+ const retryable = response.status === 429 || response.status >= 500;
+ if (!retryable || attempt === REFRESH_MAX_RETRIES) throw lastError;
+ }
+ throw lastError ?? new Error("Kimi For Coding token refresh failed");
+}
diff --git a/apps/server/src/subscription-auth/providers/openaiCodex.ts b/apps/server/src/subscription-auth/providers/openaiCodex.ts
new file mode 100644
index 000000000..c04d80dcd
--- /dev/null
+++ b/apps/server/src/subscription-auth/providers/openaiCodex.ts
@@ -0,0 +1,316 @@
+// @effect-diagnostics globalFetch:off globalDate:off
+/**
+ * OpenAI Codex OAuth (ChatGPT Plus/Pro subscriptions).
+ *
+ * Ported from Mastra Code (mastra-ai/mastra,
+ * `mastracode/sdk/src/auth/providers/openai-codex.ts`), Apache-2.0.
+ *
+ * Only the device-code flow is ported. The upstream browser flow waits for a
+ * callback on the server's localhost, which cannot work when the client is a
+ * phone or a remote browser — every Akeru flow must survive that split, so the
+ * headless flow is the only flow.
+ */
+
+import type { OAuthCredentials } from "../types.ts";
+
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const ISSUER = "https://auth.openai.com";
+const TOKEN_URL = `${ISSUER}/oauth/token`;
+const DEVICE_USER_CODE_URL = `${ISSUER}/api/accounts/deviceauth/usercode`;
+const DEVICE_TOKEN_URL = `${ISSUER}/api/accounts/deviceauth/token`;
+const DEVICE_AUTHORIZE_URL = `${ISSUER}/codex/device`;
+const DEVICE_REDIRECT_URI = `${ISSUER}/deviceauth/callback`;
+const DEFAULT_TOKEN_EXPIRES_IN_SECONDS = 3600;
+const DEVICE_AUTH_TIMEOUT_MS = 15 * 60 * 1000;
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+const USER_AGENT = "akeru";
+
+type JwtPayload = {
+ chatgpt_account_id?: string;
+ [JWT_CLAIM_PATH]?: {
+ chatgpt_account_id?: string;
+ };
+ [key: string]: unknown;
+};
+
+function decodeJwt(token: string): JwtPayload | null {
+ try {
+ const parts = token.split(".");
+ if (parts.length !== 3) return null;
+ const payload = parts[1] ?? "";
+ const padded = payload
+ .replace(/-/g, "+")
+ .replace(/_/g, "/")
+ .padEnd(Math.ceil(payload.length / 4) * 4, "=");
+ return JSON.parse(atob(padded)) as JwtPayload;
+ } catch {
+ return null;
+ }
+}
+
+function extractAccountIdFromClaims(payload: JwtPayload | null): string | null {
+ if (!payload) return null;
+ const accountId = payload.chatgpt_account_id ?? payload[JWT_CLAIM_PATH]?.chatgpt_account_id;
+ return typeof accountId === "string" && accountId.length > 0 ? accountId : null;
+}
+
+function getAccountId(
+ tokens: { idToken?: string | undefined; access: string },
+ fallback?: string,
+): string | undefined {
+ const fromIdToken = tokens.idToken ? extractAccountIdFromClaims(decodeJwt(tokens.idToken)) : null;
+ if (fromIdToken) return fromIdToken;
+
+ const fromAccessToken = extractAccountIdFromClaims(decodeJwt(tokens.access));
+ if (fromAccessToken) return fromAccessToken;
+
+ return fallback;
+}
+
+function requireAccountId(
+ tokens: { idToken?: string | undefined; access: string },
+ fallback?: string,
+): string {
+ const accountId = getAccountId(tokens, fallback);
+ if (!accountId) {
+ throw new Error("Failed to extract ChatGPT account id from OpenAI Codex token");
+ }
+ return accountId;
+}
+
+type TokenResponseJson = {
+ id_token?: string;
+ access_token?: string;
+ refresh_token?: string;
+ expires_in?: number;
+};
+
+type TokenSuccess = {
+ access: string;
+ refresh: string;
+ expires: number;
+ idToken?: string | undefined;
+};
+
+function tokenResponseToResult(json: TokenResponseJson): TokenSuccess | null {
+ if (!json.access_token || !json.refresh_token) {
+ return null;
+ }
+ return {
+ access: json.access_token,
+ refresh: json.refresh_token,
+ expires: Date.now() + (json.expires_in ?? DEFAULT_TOKEN_EXPIRES_IN_SECONDS) * 1000,
+ idToken: json.id_token,
+ };
+}
+
+async function exchangeAuthorizationCode(
+ code: string,
+ verifier: string,
+ redirectUri: string,
+ signal?: AbortSignal,
+): Promise<TokenSuccess | null> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ grant_type: "authorization_code",
+ client_id: CLIENT_ID,
+ code,
+ code_verifier: verifier,
+ redirect_uri: redirectUri,
+ }),
+ ...(signal !== undefined ? { signal } : {}),
+ });
+
+ if (!response.ok) {
+ return null;
+ }
+ return tokenResponseToResult((await response.json()) as TokenResponseJson);
+}
+
+/**
+ * Serializable pending state for a Codex device-code login. The device token
+ * response carries the `code_verifier`, so no PKCE state spans requests.
+ */
+export interface CodexDeviceLoginPending {
+ deviceAuthId: string;
+ userCode: string;
+ /** Verification URL for the user to open. */
+ url: string;
+ instructions: string;
+ /** Poll interval in ms suggested by the server. */
+ intervalMs: number;
+ /** ms epoch after which the device authorization expires. */
+ deadlineAt: number;
+}
+
+export type CodexDevicePollResult =
+ | { status: "complete"; credentials: OAuthCredentials }
+ | { status: "pending"; nextPollMs: number }
+ | { status: "failed"; error: string };
+
+/** Start a Codex device-code login: request a user code and return pending state. */
+export async function startCodexDeviceLogin(options?: {
+ signal?: AbortSignal;
+}): Promise<CodexDeviceLoginPending> {
+ const response = await fetch(DEVICE_USER_CODE_URL, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ "User-Agent": USER_AGENT,
+ },
+ body: JSON.stringify({ client_id: CLIENT_ID, originator: USER_AGENT }),
+ ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+ });
+
+ if (!response.ok) {
+ throw new Error(`Failed to initiate OpenAI Codex device authorization: ${response.status}`);
+ }
+
+ const deviceData = (await response.json()) as {
+ device_auth_id?: string;
+ user_code?: string;
+ usercode?: string;
+ interval?: string | number;
+ };
+
+ const userCode = deviceData.user_code ?? deviceData.usercode;
+
+ if (!deviceData.device_auth_id || !userCode) {
+ throw new Error("OpenAI Codex device authorization response missing required fields");
+ }
+
+ const intervalSeconds =
+ typeof deviceData.interval === "number"
+ ? deviceData.interval
+ : Number.parseInt(deviceData.interval ?? "", 10) || 5;
+
+ return {
+ deviceAuthId: deviceData.device_auth_id,
+ userCode,
+ url: DEVICE_AUTHORIZE_URL,
+ instructions: `Enter code: ${userCode}`,
+ intervalMs: Math.max(intervalSeconds, 1) * 1000,
+ deadlineAt: Date.now() + DEVICE_AUTH_TIMEOUT_MS,
+ };
+}
+
+/**
+ * Perform exactly one upstream poll for a pending Codex device login.
+ * The Codex device endpoint signals "still pending" via HTTP 403/404 (it is
+ * not an RFC 8628 error-JSON endpoint); on success it returns the
+ * authorization code plus server-held PKCE verifier, which is exchanged
+ * immediately for credentials. Never throws for flow-level conditions.
+ */
+export async function pollCodexDeviceLogin(
+ pending: CodexDeviceLoginPending,
+ options?: { signal?: AbortSignal },
+): Promise<CodexDevicePollResult> {
+ if (Date.now() >= pending.deadlineAt) {
+ return {
+ status: "failed",
+ error: "OpenAI Codex device authorization timed out after 15 minutes",
+ };
+ }
+
+ const pollResponse = await fetch(DEVICE_TOKEN_URL, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ "User-Agent": USER_AGENT,
+ },
+ body: JSON.stringify({
+ device_auth_id: pending.deviceAuthId,
+ user_code: pending.userCode,
+ }),
+ ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+ });
+
+ if (pollResponse.ok) {
+ const data = (await pollResponse.json()) as {
+ authorization_code?: string;
+ code_verifier?: string;
+ };
+
+ if (!data.authorization_code || !data.code_verifier) {
+ return {
+ status: "failed",
+ error: "OpenAI Codex device token response missing required fields",
+ };
+ }
+
+ const tokenResult = await exchangeAuthorizationCode(
+ data.authorization_code,
+ data.code_verifier,
+ DEVICE_REDIRECT_URI,
+ options?.signal,
+ );
+ if (!tokenResult) {
+ return { status: "failed", error: "Token exchange failed" };
+ }
+
+ let accountId: string;
+ try {
+ accountId = requireAccountId(tokenResult);
+ } catch (error) {
+ return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+ }
+
+ return {
+ status: "complete",
+ credentials: {
+ access: tokenResult.access,
+ refresh: tokenResult.refresh,
+ expires: tokenResult.expires,
+ accountId,
+ },
+ };
+ }
+
+ if (pollResponse.status !== 403 && pollResponse.status !== 404) {
+ const text = await pollResponse.text().catch(() => "");
+ return {
+ status: "failed",
+ error: `OpenAI Codex device authorization failed: ${pollResponse.status}${text ? ` ${text}` : ""}`,
+ };
+ }
+
+ return { status: "pending", nextPollMs: pending.intervalMs };
+}
+
+/** Refresh an OpenAI Codex OAuth token, preserving the ChatGPT account id. */
+export async function refreshCodexToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+ const response = await fetch(TOKEN_URL, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams({
+ grant_type: "refresh_token",
+ refresh_token: credentials.refresh,
+ client_id: CLIENT_ID,
+ }),
+ signal: AbortSignal.timeout(30_000),
+ });
+
+ if (!response.ok) {
+ const text = await response.text().catch(() => "");
+ throw new Error(
+ `OpenAI Codex token refresh failed: ${response.status}${text ? ` ${text}` : ""}`,
+ );
+ }
+
+ const result = tokenResponseToResult((await response.json()) as TokenResponseJson);
+ if (!result) {
+ throw new Error("OpenAI Codex token refresh response missing fields");
+ }
+
+ const previousAccountId =
+ typeof credentials.accountId === "string" ? credentials.accountId : undefined;
+
+ return {
+ access: result.access,
+ refresh: result.refresh,
+ expires: result.expires,
+ accountId: requireAccountId(result, previousAccountId),
+ };
+}
diff --git a/apps/server/src/subscription-auth/providers/xai.ts b/apps/server/src/subscription-auth/providers/xai.ts
new file mode 100644
index 000000000..d3f527460
--- /dev/null
+++ b/apps/server/src/subscription-auth/providers/xai.ts
@@ -0,0 +1,242 @@
+// @effect-diagnostics globalFetch:off globalDate:off
+/**
+ * xAI OAuth flow (Grok).
+ *
+ * Ported from Mastra Code (mastra-ai/mastra,
+ * `mastracode/sdk/src/auth/providers/xai.ts`), Apache-2.0; originally ported
+ * from pi-mono.
+ *
+ * Standard RFC 8628 device authorization grant: no inbound connection to this
+ * server is needed. `startXAIDeviceLogin()` / `pollXAIDeviceLogin()` keep the
+ * pending state JSON-serializable so polling can span RPC requests.
+ */
+
+import { createDeviceCodePollState, stepDeviceCodePoll } from "../deviceCode.ts";
+import type { DeviceCodePollOutcome, DeviceCodePollState } from "../deviceCode.ts";
+import type { OAuthCredentials } from "../types.ts";
+
+const CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const DEVICE_CODE_URL = "https://auth.x.ai/oauth2/device/code";
+const TOKEN_URL = "https://auth.x.ai/oauth2/token";
+const SCOPE = "openid profile email offline_access grok-cli:access api:access";
+const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const DEFAULT_TOKEN_EXPIRES_IN_SECONDS = 3600;
+const REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+async function postForm(
+ url: string,
+ params: Record<string, string>,
+ signal?: AbortSignal,
+): Promise<Response> {
+ return fetch(url, {
+ method: "POST",
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
+ body: new URLSearchParams(params).toString(),
+ ...(signal !== undefined ? { signal } : {}),
+ });
+}
+
+/** The verification URI is opened by the user; only accept https URLs. */
+function validateVerificationUri(raw: string): string {
+ let parsed: URL;
+ try {
+ parsed = new URL(raw);
+ } catch {
+ throw new Error(`xAI device authorization returned an invalid verification_uri: ${raw}`);
+ }
+ if (parsed.protocol !== "https:") {
+ throw new Error(`xAI device authorization returned a non-https verification_uri: ${raw}`);
+ }
+ return parsed.toString();
+}
+
+function credentialsFromTokenResponse(
+ data: unknown,
+ previousRefreshToken?: string,
+): OAuthCredentials {
+ const record = (data ?? {}) as Record<string, unknown>;
+ const access = record.access_token;
+ if (typeof access !== "string" || access.length === 0) {
+ throw new Error("xAI token response missing access_token");
+ }
+
+ // xAI may not rotate the refresh token on refresh; keep the previous one.
+ const refresh =
+ typeof record.refresh_token === "string" && record.refresh_token.length > 0
+ ? record.refresh_token
+ : previousRefreshToken;
+ if (!refresh) {
+ throw new Error("xAI token response missing refresh_token");
+ }
+
+ const expiresIn =
+ typeof record.expires_in === "number" && record.expires_in > 0
+ ? record.expires_in
+ : DEFAULT_TOKEN_EXPIRES_IN_SECONDS;
+
+ return {
+ access,
+ refresh,
+ expires: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS,
+ };
+}
+
+/** Serializable pending state for an xAI device-code login. */
+export interface XAIDeviceLoginPending {
+ deviceCode: string;
+ userCode: string;
+ /** Verification URL for the user to open (https-only, validated). */
+ url: string;
+ instructions: string;
+ state: DeviceCodePollState;
+}
+
+export type XAIDevicePollResult =
+ | { status: "complete"; credentials: OAuthCredentials }
+ | { status: "pending"; nextPollMs: number; pending: XAIDeviceLoginPending }
+ | { status: "failed"; error: string };
+
+/** Start an xAI device-code login: request a user code and return pending state. */
+export async function startXAIDeviceLogin(options?: {
+ signal?: AbortSignal;
+}): Promise<XAIDeviceLoginPending> {
+ const response = await postForm(
+ DEVICE_CODE_URL,
+ { client_id: CLIENT_ID, scope: SCOPE },
+ options?.signal,
+ );
+
+ if (!response.ok) {
+ const text = await response.text().catch(() => "");
+ throw new Error(
+ `Failed to initiate xAI device authorization: ${response.status}${text ? ` ${text}` : ""}`,
+ );
+ }
+
+ const data = (await response.json()) as {
+ device_code?: string;
+ user_code?: string;
+ verification_uri?: string;
+ verification_uri_complete?: string;
+ interval?: number;
+ expires_in?: number;
+ };
+
+ if (!data.device_code || !data.user_code || !data.verification_uri) {
+ throw new Error("xAI device authorization response missing required fields");
+ }
+
+ const url = validateVerificationUri(data.verification_uri_complete ?? data.verification_uri);
+
+ return {
+ deviceCode: data.device_code,
+ userCode: data.user_code,
+ url,
+ instructions: `Enter code: ${data.user_code}`,
+ state: createDeviceCodePollState({
+ intervalSeconds: data.interval,
+ expiresInSeconds:
+ typeof data.expires_in === "number" && data.expires_in > 0 ? data.expires_in : 600,
+ }),
+ };
+}
+
+async function pollXAITokenOnce(
+ pending: XAIDeviceLoginPending,
+ signal?: AbortSignal,
+): Promise<DeviceCodePollOutcome<OAuthCredentials>> {
+ const response = await postForm(
+ TOKEN_URL,
+ {
+ grant_type: DEVICE_CODE_GRANT_TYPE,
+ device_code: pending.deviceCode,
+ client_id: CLIENT_ID,
+ },
+ signal,
+ );
+
+ if (response.ok) {
+ const data = (await response.json()) as unknown;
+ try {
+ return { status: "complete", result: credentialsFromTokenResponse(data) };
+ } catch (error) {
+ return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+ }
+ }
+
+ const text = await response.text().catch(() => "");
+ let body: { error?: string; interval?: number } = {};
+ try {
+ body = JSON.parse(text) as { error?: string; interval?: number };
+ } catch {
+ // Non-JSON error body — fail loudly below with the raw text.
+ }
+
+ switch (body.error) {
+ case "authorization_pending":
+ return { status: "pending", intervalSeconds: body.interval };
+ case "slow_down":
+ return { status: "slow_down", intervalSeconds: body.interval };
+ case "access_denied":
+ case "authorization_denied":
+ return { status: "failed", error: "xAI authorization was denied" };
+ case "expired_token":
+ return { status: "failed", error: "xAI device code expired before authorization completed" };
+ default:
+ return {
+ status: "failed",
+ error: `xAI device authorization failed: ${response.status}${text ? ` ${text}` : ""}`,
+ };
+ }
+}
+
+/**
+ * Perform exactly one upstream poll for a pending xAI device login.
+ * Returns the updated pending state so callers can persist slow_down interval
+ * growth between polls. Never throws for flow-level conditions.
+ */
+export async function pollXAIDeviceLogin(
+ pending: XAIDeviceLoginPending,
+ options?: { signal?: AbortSignal },
+): Promise<XAIDevicePollResult> {
+ const step = await stepDeviceCodePoll(pending.state, () =>
+ pollXAITokenOnce(pending, options?.signal),
+ );
+
+ switch (step.status) {
+ case "complete":
+ return { status: "complete", credentials: step.result };
+ case "failed":
+ return { status: "failed", error: step.error };
+ case "pending":
+ case "slow_down":
+ return {
+ status: "pending",
+ nextPollMs: step.nextPollMs,
+ pending: { ...pending, state: step.state },
+ };
+ }
+}
+
+/** Refresh an xAI OAuth token. */
+export async function refreshXAIToken(
+ refreshToken: string,
+ signal?: AbortSignal,
+): Promise<OAuthCredentials> {
+ const response = await postForm(
+ TOKEN_URL,
+ {
+ grant_type: "refresh_token",
+ client_id: CLIENT_ID,
+ refresh_token: refreshToken,
+ },
+ signal,
+ );
+
+ if (!response.ok) {
+ const text = await response.text().catch(() => "");
+ throw new Error(`xAI token refresh failed: ${response.status}${text ? ` ${text}` : ""}`);
+ }
+
+ return credentialsFromTokenResponse((await response.json()) as unknown, refreshToken);
+}
diff --git a/apps/server/src/subscription-auth/service.test.ts b/apps/server/src/subscription-auth/service.test.ts
new file mode 100644
index 000000000..2885b7686
--- /dev/null
+++ b/apps/server/src/subscription-auth/service.test.ts
@@ -0,0 +1,89 @@
+// @effect-diagnostics nodeBuiltinImport:off globalDate:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import * as NodeOS from "node:os";
+import * as NodeCrypto from "node:crypto";
+import { describe, expect, it } from "vite-plus/test";
+
+import { SubscriptionAuthService } from "./service.ts";
+
+function fixture() {
+ const directory = NodePath.join(
+ NodeOS.tmpdir(),
+ `akeru-subscription-auth-${NodeCrypto.randomUUID()}`,
+ );
+ NodeFS.mkdirSync(directory, { recursive: true });
+ const authPath = NodePath.join(directory, "subscription-auth.json");
+ return { directory, authPath };
+}
+
+describe("subscription auth storage", () => {
+ it("loads provider status without exposing tokens", () => {
+ const { authPath } = fixture();
+ NodeFS.writeFileSync(
+ authPath,
+ JSON.stringify({
+ anthropic: {
+ type: "oauth",
+ access: "secret-access",
+ refresh: "secret-refresh",
+ expires: 1_800_000_000_000,
+ },
+ }),
+ );
+
+ const service = new SubscriptionAuthService(authPath);
+ const anthropic = service.statuses().find((status) => status.provider === "anthropic");
+ expect(anthropic).toEqual({
+ provider: "anthropic",
+ connected: true,
+ expiresAt: 1_800_000_000_000,
+ });
+ expect(JSON.stringify(service.statuses())).not.toContain("secret-access");
+ expect(JSON.stringify(service.statuses())).not.toContain("secret-refresh");
+ });
+
+ it("returns a still-valid access token without rewriting storage", async () => {
+ const { authPath } = fixture();
+ NodeFS.writeFileSync(
+ authPath,
+ JSON.stringify({
+ xai: {
+ type: "oauth",
+ access: "short-lived-access",
+ refresh: "never-return-this",
+ expires: Date.now() + 60_000,
+ },
+ }),
+ );
+ const before = NodeFS.readFileSync(authPath, "utf-8");
+ const service = new SubscriptionAuthService(authPath);
+ await expect(service.getAccessToken("xai")).resolves.toBe("short-lived-access");
+ expect(NodeFS.readFileSync(authPath, "utf-8")).toBe(before);
+ });
+
+ it("persists pending logins across a server restart", async () => {
+ const { authPath } = fixture();
+ const first = new SubscriptionAuthService(authPath);
+ const started = await first.startLogin("anthropic");
+
+ const restarted = new SubscriptionAuthService(authPath);
+ const result = await restarted.completeLogin(started.loginId, "invalid-code");
+ expect(result).toEqual({ status: "failed", error: "Invalid authorization state" });
+ expect(NodeFS.statSync(`${authPath}.pending`).mode & 0o777).toBe(0o600);
+ });
+
+ it("logs out atomically and secures the rewritten file", () => {
+ const { authPath } = fixture();
+ NodeFS.writeFileSync(
+ authPath,
+ JSON.stringify({
+ cursor: { type: "oauth", access: "a", refresh: "r", expires: 1 },
+ }),
+ );
+ const service = new SubscriptionAuthService(authPath);
+ service.logout("cursor");
+ expect(JSON.parse(NodeFS.readFileSync(authPath, "utf-8"))).toEqual({});
+ expect(NodeFS.statSync(authPath).mode & 0o777).toBe(0o600);
+ });
+});
diff --git a/apps/server/src/subscription-auth/service.ts b/apps/server/src/subscription-auth/service.ts
new file mode 100644
index 000000000..43b8dfaf7
--- /dev/null
+++ b/apps/server/src/subscription-auth/service.ts
@@ -0,0 +1,413 @@
+// @effect-diagnostics nodeBuiltinImport:off globalDate:off
+/**
+ * Subscription auth service: one API over five login flows.
+ *
+ * Storage follows Mastra Code's `AuthStorage` (mastra-ai/mastra,
+ * `mastracode/sdk/src/auth/storage.ts`, Apache-2.0): a mode-0600 JSON file of
+ * OAuth credentials. It lives in the server's secrets directory, never inside
+ * a workspace or sandbox — a sandbox (E2B or local worktree) receives a
+ * short-lived access token per run and holds no refresh token.
+ *
+ * Login flows are client-driven: `start` returns a URL (and user code) to
+ * show, then the client calls `poll` until the flow settles. Every pending
+ * state is JSON-serializable, so a login survives a server restart and any
+ * replica can continue it.
+ */
+
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+import * as NodeCrypto from "node:crypto";
+
+import {
+ completeAnthropicLogin,
+ refreshAnthropicToken,
+ startAnthropicLogin,
+} from "./providers/anthropic.ts";
+import {
+ pollCodexDeviceLogin,
+ refreshCodexToken,
+ startCodexDeviceLogin,
+ type CodexDeviceLoginPending,
+} from "./providers/openaiCodex.ts";
+import {
+ pollCursorLogin,
+ refreshCursorToken,
+ startCursorLogin,
+ type CursorLoginPending,
+} from "./providers/cursor.ts";
+import {
+ pollKimiDeviceLogin,
+ refreshKimiToken,
+ startKimiDeviceLogin,
+ type KimiDeviceLoginPending,
+} from "./providers/kimi.ts";
+import {
+ pollXAIDeviceLogin,
+ refreshXAIToken,
+ startXAIDeviceLogin,
+ type XAIDeviceLoginPending,
+} from "./providers/xai.ts";
+import type { OAuthCredential, OAuthCredentials, SubscriptionAuthData } from "./types.ts";
+
+export const SUBSCRIPTION_PROVIDER_IDS = [
+ "anthropic",
+ "openai-codex",
+ "cursor",
+ "xai",
+ "kimi-for-coding",
+] as const;
+
+export type SubscriptionProviderId = (typeof SUBSCRIPTION_PROVIDER_IDS)[number];
+
+export function isSubscriptionProviderId(value: string): value is SubscriptionProviderId {
+ return (SUBSCRIPTION_PROVIDER_IDS as readonly string[]).includes(value);
+}
+
+/** How a started login is finished: polled by the client, or completed with a pasted code. */
+export type LoginCompletion = "poll" | "paste";
+
+export interface StartedLogin {
+ loginId: string;
+ provider: SubscriptionProviderId;
+ /** URL the user opens (in their own browser, on any device). */
+ url: string;
+ /** Code the user enters on the provider page, for device flows. */
+ userCode?: string;
+ instructions?: string;
+ completion: LoginCompletion;
+}
+
+export type LoginPollStatus =
+ | { status: "connected" }
+ | { status: "pending"; nextPollMs: number }
+ | { status: "failed"; error: string };
+
+export interface ProviderStatus {
+ provider: SubscriptionProviderId;
+ connected: boolean;
+ /** ms epoch when the current access token expires; refreshed on demand. */
+ expiresAt?: number;
+}
+
+type PendingLogin =
+ | { provider: "anthropic"; verifier: string }
+ | { provider: "openai-codex"; pending: CodexDeviceLoginPending }
+ | { provider: "cursor"; pending: CursorLoginPending }
+ | { provider: "xai"; pending: XAIDeviceLoginPending }
+ | { provider: "kimi-for-coding"; pending: KimiDeviceLoginPending };
+
+/** A completed login that the client has not observed yet must not be re-runnable. */
+const PENDING_LOGIN_CAP = 16;
+
+export class SubscriptionAuthService {
+ private data: SubscriptionAuthData = {};
+ private readonly authPath: string;
+ private readonly pendingPath: string;
+ private readonly pendingLogins = new Map<string, PendingLogin>();
+ private readonly refreshInFlight = new Map<string, Promise<string | undefined>>();
+
+ constructor(authPath: string) {
+ this.authPath = authPath;
+ this.pendingPath = `${authPath}.pending`;
+ this.reload();
+ }
+
+ static forSecretsDir(secretsDir: string): SubscriptionAuthService {
+ return new SubscriptionAuthService(NodePath.join(secretsDir, "subscription-auth.json"));
+ }
+
+ reload(): void {
+ if (!NodeFS.existsSync(this.authPath)) {
+ this.data = {};
+ } else {
+ try {
+ this.data = JSON.parse(NodeFS.readFileSync(this.authPath, "utf-8")) as SubscriptionAuthData;
+ } catch {
+ this.data = {};
+ }
+ }
+
+ this.pendingLogins.clear();
+ if (!NodeFS.existsSync(this.pendingPath)) return;
+ try {
+ const entries = JSON.parse(NodeFS.readFileSync(this.pendingPath, "utf-8")) as Array<
+ readonly [string, PendingLogin]
+ >;
+ for (const [loginId, pending] of entries.slice(-PENDING_LOGIN_CAP)) {
+ this.pendingLogins.set(loginId, pending);
+ }
+ } catch {
+ this.pendingLogins.clear();
+ }
+ }
+
+ private writeSecureJson(filePath: string, value: unknown): void {
+ const dir = NodePath.dirname(filePath);
+ if (!NodeFS.existsSync(dir)) {
+ NodeFS.mkdirSync(dir, { recursive: true, mode: 0o700 });
+ }
+ const tempPath = `${filePath}.${NodeCrypto.randomUUID()}.tmp`;
+ NodeFS.writeFileSync(tempPath, JSON.stringify(value, null, 2), {
+ encoding: "utf-8",
+ mode: 0o600,
+ });
+ NodeFS.renameSync(tempPath, filePath);
+ NodeFS.chmodSync(filePath, 0o600);
+ }
+
+ private save(): void {
+ this.writeSecureJson(this.authPath, this.data);
+ }
+
+ private savePending(): void {
+ this.writeSecureJson(this.pendingPath, [...this.pendingLogins.entries()]);
+ }
+
+ statuses(): ProviderStatus[] {
+ return SUBSCRIPTION_PROVIDER_IDS.map((provider) => {
+ const credential = this.data[provider];
+ return credential
+ ? { provider, connected: true, expiresAt: credential.expires }
+ : { provider, connected: false };
+ });
+ }
+
+ isConnected(provider: SubscriptionProviderId): boolean {
+ return this.data[provider] !== undefined;
+ }
+
+ async startLogin(provider: SubscriptionProviderId): Promise<StartedLogin> {
+ const loginId = NodeCrypto.randomUUID();
+ let started: StartedLogin;
+
+ switch (provider) {
+ case "anthropic": {
+ const { url, verifier } = await startAnthropicLogin();
+ this.pendingLogins.set(loginId, { provider, verifier });
+ started = { loginId, provider, url, completion: "paste" };
+ break;
+ }
+ case "openai-codex": {
+ const pending = await startCodexDeviceLogin();
+ this.pendingLogins.set(loginId, { provider, pending });
+ started = {
+ loginId,
+ provider,
+ url: pending.url,
+ userCode: pending.userCode,
+ instructions: pending.instructions,
+ completion: "poll",
+ };
+ break;
+ }
+ case "cursor": {
+ const pending = await startCursorLogin();
+ this.pendingLogins.set(loginId, { provider, pending });
+ started = {
+ loginId,
+ provider,
+ url: pending.url,
+ instructions: "Approve the Cursor login in your browser.",
+ completion: "poll",
+ };
+ break;
+ }
+ case "xai": {
+ const pending = await startXAIDeviceLogin();
+ this.pendingLogins.set(loginId, { provider, pending });
+ started = {
+ loginId,
+ provider,
+ url: pending.url,
+ userCode: pending.userCode,
+ instructions: pending.instructions,
+ completion: "poll",
+ };
+ break;
+ }
+ case "kimi-for-coding": {
+ const pending = await startKimiDeviceLogin();
+ this.pendingLogins.set(loginId, { provider, pending });
+ started = {
+ loginId,
+ provider,
+ url: pending.url,
+ userCode: pending.userCode,
+ instructions: pending.instructions,
+ completion: "poll",
+ };
+ break;
+ }
+ }
+
+ // Drop the oldest abandoned login rather than growing without bound.
+ if (this.pendingLogins.size > PENDING_LOGIN_CAP) {
+ const oldest = this.pendingLogins.keys().next().value;
+ if (oldest !== undefined) this.pendingLogins.delete(oldest);
+ }
+ this.savePending();
+
+ return started;
+ }
+
+ /** One upstream poll for a started login. Persists credentials on success. */
+ async pollLogin(loginId: string): Promise<LoginPollStatus> {
+ const login = this.pendingLogins.get(loginId);
+ if (!login) {
+ return { status: "failed", error: "Login expired or already completed. Start again." };
+ }
+
+ switch (login.provider) {
+ case "anthropic":
+ return { status: "pending", nextPollMs: 2000 };
+ case "openai-codex": {
+ const result = await pollCodexDeviceLogin(login.pending);
+ return this.foldPoll(loginId, login.provider, result);
+ }
+ case "cursor": {
+ const result = await pollCursorLogin(login.pending);
+ if (result.status === "pending") {
+ this.pendingLogins.set(loginId, { provider: "cursor", pending: result.pending });
+ this.savePending();
+ }
+ return this.foldPoll(loginId, login.provider, result);
+ }
+ case "xai": {
+ const result = await pollXAIDeviceLogin(login.pending);
+ if (result.status === "pending") {
+ this.pendingLogins.set(loginId, { provider: "xai", pending: result.pending });
+ this.savePending();
+ }
+ return this.foldPoll(loginId, login.provider, result);
+ }
+ case "kimi-for-coding": {
+ const result = await pollKimiDeviceLogin(login.pending);
+ if (result.status === "pending") {
+ this.pendingLogins.set(loginId, { provider: "kimi-for-coding", pending: result.pending });
+ this.savePending();
+ }
+ return this.foldPoll(loginId, login.provider, result);
+ }
+ }
+ }
+
+ private foldPoll(
+ loginId: string,
+ provider: SubscriptionProviderId,
+ result:
+ | { status: "complete"; credentials: OAuthCredentials }
+ | { status: "pending"; nextPollMs: number }
+ | { status: "pending"; nextPollMs: number; pending: unknown }
+ | { status: "failed"; error: string },
+ ): LoginPollStatus {
+ switch (result.status) {
+ case "complete":
+ this.pendingLogins.delete(loginId);
+ this.savePending();
+ this.setCredential(provider, result.credentials);
+ return { status: "connected" };
+ case "failed":
+ this.pendingLogins.delete(loginId);
+ this.savePending();
+ return { status: "failed", error: result.error };
+ case "pending":
+ return { status: "pending", nextPollMs: result.nextPollMs };
+ }
+ }
+
+ /** Finish a paste-completion login (Anthropic) with the pasted code. */
+ async completeLogin(loginId: string, code: string): Promise<LoginPollStatus> {
+ const login = this.pendingLogins.get(loginId);
+ if (!login) {
+ return { status: "failed", error: "Login expired or already completed. Start again." };
+ }
+ if (login.provider !== "anthropic") {
+ return { status: "failed", error: "This login completes by polling, not with a code." };
+ }
+
+ try {
+ const credentials = await completeAnthropicLogin(code, login.verifier);
+ this.pendingLogins.delete(loginId);
+ this.savePending();
+ this.setCredential("anthropic", credentials);
+ return { status: "connected" };
+ } catch (error) {
+ // Keep the pending login: a mangled paste should not force a restart.
+ return {
+ status: "failed",
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ }
+
+ cancelLogin(loginId: string): void {
+ this.pendingLogins.delete(loginId);
+ this.savePending();
+ }
+
+ logout(provider: SubscriptionProviderId): void {
+ delete this.data[provider];
+ this.save();
+ }
+
+ private setCredential(provider: SubscriptionProviderId, credentials: OAuthCredentials): void {
+ this.data[provider] = { type: "oauth", ...credentials };
+ this.save();
+ }
+
+ /**
+ * Ready-to-use access token for a provider, refreshing first when expired.
+ * Concurrent callers share one refresh; a failed refresh clears nothing —
+ * the user re-connects from Settings.
+ */
+ async getAccessToken(provider: SubscriptionProviderId): Promise<string | undefined> {
+ const credential = this.data[provider];
+ if (!credential) return undefined;
+
+ if (Date.now() < credential.expires) {
+ return credential.access;
+ }
+
+ const inFlight = this.refreshInFlight.get(provider);
+ if (inFlight) return inFlight;
+
+ const refresh = this.refreshCredential(provider, credential).finally(() => {
+ this.refreshInFlight.delete(provider);
+ });
+ this.refreshInFlight.set(provider, refresh);
+ return refresh;
+ }
+
+ private async refreshCredential(
+ provider: SubscriptionProviderId,
+ credential: OAuthCredential,
+ ): Promise<string | undefined> {
+ try {
+ const refreshed = await this.runRefresh(provider, credential);
+ this.setCredential(provider, refreshed);
+ return refreshed.access;
+ } catch {
+ // Refresh failed — the user must re-connect. Keep the stored credential
+ // so status still shows which account was linked.
+ return undefined;
+ }
+ }
+
+ private runRefresh(
+ provider: SubscriptionProviderId,
+ credential: OAuthCredential,
+ ): Promise<OAuthCredentials> {
+ switch (provider) {
+ case "anthropic":
+ return refreshAnthropicToken(credential.refresh);
+ case "openai-codex":
+ return refreshCodexToken(credential);
+ case "cursor":
+ return refreshCursorToken(credential);
+ case "xai":
+ return refreshXAIToken(credential.refresh);
+ case "kimi-for-coding":
+ return refreshKimiToken(credential.refresh);
+ }
+ }
+}
diff --git a/apps/server/src/subscription-auth/types.ts b/apps/server/src/subscription-auth/types.ts
new file mode 100644
index 000000000..b81cdf3da
--- /dev/null
+++ b/apps/server/src/subscription-auth/types.ts
@@ -0,0 +1,22 @@
+/**
+ * Subscription provider OAuth types.
+ *
+ * Ported from Mastra Code (mastra-ai/mastra, `mastracode/sdk/src/auth`),
+ * Apache-2.0. A provider here is a consumer subscription (Claude Pro/Max,
+ * ChatGPT, Cursor, Kimi For Coding, X Premium) that the agent runtime spends,
+ * not an API key with usage billing.
+ */
+
+export interface OAuthCredentials {
+ refresh: string;
+ access: string;
+ /** ms epoch after which `access` must be refreshed. */
+ expires: number;
+ [key: string]: unknown;
+}
+
+export type OAuthCredential = {
+ type: "oauth";
+} & OAuthCredentials;
+
+export type SubscriptionAuthData = Record<string, OAuthCredential>;