@inixiative/agent-session 0.2.0 → 0.3.1

package/README.md

@@ -1,7 +1,10 @@
 # @inixiative/agent-session
 
 Drive coding-agent CLIs as **persistent, streaming, event-captured sessions** —
-one interface, any agent. Claude Code and Codex today; Gemini and Grok planned.
+one interface, any agent, over interchangeable **transports**. Claude Code
+(CLI or Agent SDK) and Codex (MCP or app-server) today; Gemini and Grok planned.
+Also: warm **primed decision sessions**, **subscription pools** with
+deterministic routing, **limit polling** and **session continuity**.
 
 Most ways to script a coding agent are one-shot (`claude -p "…"`) and lose the
 process. `agent-session` keeps a single long-lived agent process, streams turns
@@ -43,13 +46,83 @@ session.kill();
   containers.
 - **fork / resume / interrupt** and pre-send hooks (rewrite the outgoing
   message — e.g. inject just-in-time context per turn).
-- **Zero dependencies.** Just Bun + the agent CLI you're driving.
+- **Transports with declared capabilities.** How a model is reached is a
+  pluggable transport; switching it is a routing change, not a rewrite.
+- **Zero dependencies.** Just Bun + the agent CLI you're driving. The Agent SDK
+  transport takes the SDK's `query` from the caller.
 
 ## Interface
 
 `HarnessSession` is the provider-agnostic contract (`start` / `send` / `kill` /
-`fork` / `interrupt` + an event handler). `ClaudeCodeSession` implements it over
-`claude --print --input-format stream-json --output-format stream-json`.
+`fork` / `interrupt` + an event handler). Optional members where a transport
+supports them: `transport` (its descriptor), `interruptNative()` (acknowledged
+stop), `readLimits()` (account limits without a model turn). Account limits also
+arrive as `rate_limit` events.
+
+## Transports
+
+```ts
+import { createSession, TRANSPORTS } from "@inixiative/agent-session";
+
+const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk, codex-mcp
+if (TRANSPORTS[kind].capabilities.interrupt === "acknowledged") { /* … */ }
+const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOME: profile } });
+```
+
+| | claude-cli | codex-mcp | codex-app-server | claude-agent-sdk | acp | api |
+|---|---|---|---|---|---|---|
+| Status | ✅ live | ✅ live | ✅ live | ✅ live | stub | stub |
+| Resume / fork | native / native | loaded-only / same-thread | native / – | native / native | – | – |
+| Interrupt | acknowledged | local-only | acknowledged | acknowledged | – | – |
+| Push | – | – | steer | – | – | – |
+| Approvals | mode | mode | refuse | callback | – | – |
+| Limits stream / poll | ✅ / ✅ | – / – | ✅ / ✅ | ✅ / – | – | – |
+| Primed reset | fork | – | fork | – | – | – |
+
+Full matrix, notes and what is stubbed: [docs/transports-pools-routing.md](docs/transports-pools-routing.md).
+
+## Primed decision sessions
+
+One live, warm session per middleware role, primed once with its role
+instructions and stable context, reset to that primed state every cycle:
+
+```ts
+import { CodexPrimedSessions } from "@inixiative/agent-session";
+
+const decisions = new CodexPrimedSessions({ model: "gpt-6-luna", effort: "low", cwd: privateDir });
+const result = await decisions.decide(
+  { key: `${threadId}:aux:domain:api`, instructions: rolePrompt, context: layerContent, hash: layerHash },
+  { input: "## Message\n…", onAdmission: register },
+);
+```
+
+Run Codex decisions on a private `CODEX_HOME` that holds only the login (link
+`auth.json` from the account's home; a copy forks its refresh token): Codex has no
+setting that drops the user's own `AGENTS.md`, and a decision thread that reports
+any instruction source is refused.
+
+Codex hosts every key as a thread of one `app-server` process per account and
+forks the primed thread per cycle; Claude forks a persisted primed session with
+a pre-spawned spare. Measured on a ChatGPT login: warm Codex decisions 2.45 s
+median vs 3.9 s for `codex exec` per decision, with 34% fewer input tokens; warm
+Claude (haiku) decisions 1.95 s with the whole primed prefix read from cache.
+
+## Pools, routing and continuity
+
+```ts
+import { SubscriptionPool } from "@inixiative/agent-session";
+
+const pool = new SubscriptionPool({ instances: [
+  { id: "work", transport: "claude-cli", profileDirectory: "/profiles/work", organizationIds: ["org"] },
+  { id: "spare", transport: "claude-cli", profileDirectory: "/profiles/spare", organizationIds: ["org"] },
+] });
+const { session, lease } = await pool.open({ runtime: "claude", model: "sonnet", organizationId: "org", preferredInstanceId: "work" });
+```
+
+Routing is deterministic (quartile-balanced, owner-first or pinned) over
+observed limits, leases and health; stale or unknown limits exclude an instance
+and every exclusion has a reason. `continueOn` moves a thread only between
+instances that share native history, and says why when it cannot.
 
 ## Usage telemetry
 
@@ -71,13 +144,16 @@ snapshots in the artifact but do not fabricate a completed-turn total.
 | Runtime | Status |
 |---|---|
 | Claude Code | ✅ shipped |
-| Codex CLI (`codex mcp-server`, JSON-RPC) | ✅ shipped (`CodexSession`; `CodexAppServerSession` experimental) |
+| Codex CLI (`codex mcp-server`, JSON-RPC) | ✅ shipped (`CodexSession`) |
+| Codex app-server | ✅ shipped (`CodexAppServerSession`, `CodexPrimedSessions`) |
+| Claude Agent SDK | ✅ shipped (`ClaudeAgentSdkSession`; caller supplies `query`) |
+| ACP agents / direct API | typed stubs |
 | Gemini CLI | planned |
 | Grok CLI | planned (when its headless/stream mode matures) |
 
 Opaque runtimes degrade gracefully — fewer event types, never a hard failure.
 
-Proposed [subscription pooling goals](tickets/README.md) cover distributing session workloads across subscriptions while keeping working context independent of the capacity supplying it.
+[Subscription pooling goals](tickets/README.md) (AS-001…005) are implemented as described in [docs/transports-pools-routing.md](docs/transports-pools-routing.md); each ticket lists what remains.
 
 ## Provenance
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.2.0",
-  "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions. Claude Code and Codex today; Gemini, Grok planned.",
+  "version": "0.3.1",
+  "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -14,8 +14,11 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "check": "bun run typecheck && bun run test",
-    "prepublishOnly": "bun run check"
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "prepublishOnly": "bun run check",
+    "measure:primed": "bun scripts/measure-primed.ts",
+    "lint": "biome check .",
+    "prepare": "lefthook install"
   },
   "keywords": [
     "claude-code",
@@ -32,7 +35,10 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@biomejs/biome": "2.5.2",
+    "@inixiative/config": "^0.5.41",
     "@types/bun": "1.4.2",
+    "lefthook": "2.1.9",
     "typescript": "6.0.3"
   },
   "packageManager": "bun@1.4.2",

package/src/claude-agent-sdk-session.ts

@@ -0,0 +1,316 @@
+// ---------------------------------------------------------------------------
+// ClaudeAgentSdkSession — Claude through @anthropic-ai/claude-agent-sdk
+// ---------------------------------------------------------------------------
+//
+// The Agent SDK drives the same Claude Code runtime and yields the same
+// stream-json messages. This transport feeds SDK `query()` through a
+// process-shaped bridge, so ClaudeCodeSession's classification, admission and
+// ownership evidence apply unchanged. The caller supplies `query` (this
+// package keeps zero dependencies):
+//
+//   import { query } from "@anthropic-ai/claude-agent-sdk";
+//   const session = new ClaudeAgentSdkSession({ query, model: "sonnet", cwd });
+//
+// Launch options come from the same argv the CLI transport would use, mapped
+// to SDK options; unmapped flags pass through `extraArgs`. Adds per-call
+// approvals (`canUseTool`) and SDK-native interrupt. Limit polling
+// (`get_usage`) is not exposed by the SDK Query API and is refused.
+// ---------------------------------------------------------------------------
+
+import {
+  ClaudeCodeSession,
+  type ClaudeCodeSessionConfig,
+  type PipedSubprocess,
+} from './claude-code-session';
+import { TRANSPORTS } from './transport';
+
+/** The subset of the SDK's Query this transport uses. */
+export interface ClaudeAgentSdkQuery extends AsyncIterable<unknown> {
+  interrupt(): Promise<unknown>;
+  /** Stops the underlying CLI. The bridge reports exit only after the message stream ends. */
+  close(): void;
+}
+export type ClaudeAgentSdkQueryFunction = (params: {
+  prompt: AsyncIterable<unknown>;
+  options: Record<string, unknown>;
+}) => ClaudeAgentSdkQuery;
+export type ClaudeAgentSdkCanUseTool = (
+  toolName: string,
+  input: Record<string, unknown>,
+  context: unknown,
+) => Promise<unknown>;
+
+export interface ClaudeAgentSdkSessionConfig extends Omit<ClaudeCodeSessionConfig, 'spawn'> {
+  /** `query` from @anthropic-ai/claude-agent-sdk. */
+  query: ClaudeAgentSdkQueryFunction;
+  /** Per-call tool approval. Defaults permissionMode to "default"; combining it with "bypassPermissions" throws. */
+  canUseTool?: ClaudeAgentSdkCanUseTool;
+  /** Use the SDK's bundled CLI instead of resolving `bin` on PATH. Default false. */
+  bundledCli?: boolean;
+  /** Additional SDK options, passed verbatim (e.g. hooks). Mapped options take precedence. */
+  sdkOptions?: Record<string, unknown>;
+}
+
+const SDK_OWNED = new Set(['--print', '--verbose']);
+const SDK_OWNED_VALUE = new Set(['--input-format', '--output-format']);
+
+/** Map a ClaudeCodeSession argv (without the binary) to SDK options. Exported for tests. */
+export function sdkOptionsFromArgv(argv: readonly string[]): Record<string, unknown> {
+  const options: Record<string, unknown> = {};
+  const extraArgs: Record<string, string | null> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]!;
+    const hasValue = i + 1 < argv.length && !argv[i + 1]!.startsWith('--');
+    const value = () => argv[++i]!;
+    if (SDK_OWNED.has(flag)) continue;
+    if (SDK_OWNED_VALUE.has(flag)) {
+      i++;
+      continue;
+    }
+    switch (flag) {
+      case '--model':
+        options.model = value();
+        break;
+      case '--max-turns':
+        options.maxTurns = Number(value());
+        break;
+      case '--permission-mode': {
+        options.permissionMode = value();
+        if (options.permissionMode === 'bypassPermissions')
+          options.allowDangerouslySkipPermissions = true;
+        break;
+      }
+      case '--resume':
+        options.resume = value();
+        break;
+      case '--fork-session':
+        options.forkSession = true;
+        break;
+      case '--append-system-prompt':
+        options.systemPrompt = { type: 'preset', preset: 'claude_code', append: value() };
+        break;
+      case '--no-session-persistence':
+        options.persistSession = false;
+        break;
+      case '--strict-mcp-config':
+        options.strictMcpConfig = true;
+        break;
+      case '--mcp-config': {
+        const parsed = JSON.parse(value()) as { mcpServers?: Record<string, unknown> };
+        options.mcpServers = parsed.mcpServers ?? {};
+        break;
+      }
+      case '--tools': {
+        // `--tools ""` (text-only) is an empty list; the SDK spells that `tools: []`.
+        const list = argv[i + 1] !== undefined && !argv[i + 1]!.startsWith('--') ? value() : '';
+        options.tools = list ? list.split(',') : [];
+        break;
+      }
+      default:
+        extraArgs[flag.replace(/^--/, '')] = hasValue ? value() : null;
+    }
+  }
+  if (Object.keys(extraArgs).length) options.extraArgs = extraArgs;
+  return options;
+}
+
+function bridge(
+  config: ClaudeAgentSdkSessionConfig,
+): NonNullable<ClaudeCodeSessionConfig['spawn']> {
+  return (cmd, { cwd, env }) => {
+    const encoder = new TextEncoder();
+    let out!: ReadableStreamDefaultController<Uint8Array>,
+      err!: ReadableStreamDefaultController<Uint8Array>;
+    let finish!: (code: number) => void,
+      finished = false;
+    const exited = new Promise<number>((resolve) => {
+      finish = resolve;
+    });
+    const stdout = new ReadableStream<Uint8Array>({
+      start(c) {
+        out = c;
+      },
+    });
+    const stderr = new ReadableStream<Uint8Array>({
+      start(c) {
+        err = c;
+      },
+    });
+    const end = (code: number) => {
+      if (finished) return;
+      finished = true;
+      try {
+        out.close();
+      } catch {
+        /* closed */
+      }
+      try {
+        err.close();
+      } catch {
+        /* closed */
+      }
+      finish(code);
+    };
+    const emit = (message: unknown) => {
+      if (!finished) out.enqueue(encoder.encode(`${JSON.stringify(message)}\n`));
+    };
+
+    const inbox: unknown[] = [];
+    let wake: (() => void) | undefined,
+      inputEnded = false;
+    const prompt: AsyncIterable<unknown> = {
+      async *[Symbol.asyncIterator]() {
+        while (true) {
+          while (inbox.length) yield inbox.shift();
+          if (inputEnded) return;
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+        }
+      },
+    };
+
+    const stringEnv = Object.fromEntries(
+      Object.entries(env).filter(
+        (entry): entry is [string, string] => typeof entry[1] === 'string',
+      ),
+    );
+    const options: Record<string, unknown> = {
+      ...config.sdkOptions,
+      ...sdkOptionsFromArgv(cmd.slice(1)),
+      cwd,
+      env: stringEnv,
+      ...(config.canUseTool ? { canUseTool: config.canUseTool } : {}),
+      ...(config.bundledCli ? {} : { pathToClaudeCodeExecutable: Bun.which(cmd[0]!) ?? cmd[0] }),
+    };
+    let query: ClaudeAgentSdkQuery,
+      killed = false;
+    try {
+      query = config.query({ prompt, options });
+    } catch (error) {
+      queueMicrotask(() => {
+        err.enqueue(encoder.encode(String((error as Error).message ?? error)));
+        end(1);
+      });
+      query = { interrupt: async () => {}, close() {}, async *[Symbol.asyncIterator]() {} };
+    }
+    // `exited` resolves only when the SDK's message stream has ended, so it is evidence that the CLI stopped.
+    void (async () => {
+      try {
+        for await (const message of query) if (!killed) emit(message);
+        end(killed ? 143 : 0);
+      } catch (error) {
+        if (!finished && !killed)
+          err.enqueue(encoder.encode(String((error as Error)?.message ?? error)));
+        end(killed ? 143 : 1);
+      }
+    })();
+
+    const respond = (requestId: string, error?: string) =>
+      emit({
+        type: 'control_response',
+        response: error
+          ? { subtype: 'error', request_id: requestId, error }
+          : { subtype: 'success', request_id: requestId, response: {} },
+      });
+    const process: PipedSubprocess = {
+      stdin: {
+        write(data: string) {
+          for (const line of data.split('\n')) {
+            if (!line.trim()) continue;
+            const message = JSON.parse(line) as Record<string, unknown>;
+            if (message.type === 'user') {
+              inbox.push({ ...message, parent_tool_use_id: null, session_id: '' });
+              wake?.();
+              wake = undefined;
+            } else if (message.type === 'control_request') {
+              const id = String(message.request_id);
+              const subtype = (message.request as Record<string, unknown> | undefined)?.subtype;
+              if (subtype === 'interrupt')
+                query.interrupt().then(
+                  () => respond(id),
+                  (e) => respond(id, String((e as Error)?.message ?? e)),
+                );
+              else
+                queueMicrotask(() =>
+                  respond(
+                    id,
+                    `Control request ${String(subtype)} is not exposed by the Agent SDK transport`,
+                  ),
+                );
+            }
+          }
+        },
+        flush() {},
+        end() {
+          inputEnded = true;
+          wake?.();
+          wake = undefined;
+        },
+      },
+      stdout,
+      stderr,
+      exited,
+      kill() {
+        if (killed) return;
+        killed = true;
+        inputEnded = true;
+        wake?.();
+        wake = undefined;
+        try {
+          query.close();
+        } catch {
+          /* already closed */
+        }
+      },
+    };
+    return process;
+  };
+}
+
+export class ClaudeAgentSdkSession extends ClaudeCodeSession {
+  override get transport() {
+    return TRANSPORTS['claude-agent-sdk'];
+  }
+  private readonly _sdk: ClaudeAgentSdkSessionConfig;
+
+  constructor(config: ClaudeAgentSdkSessionConfig) {
+    if (typeof config?.query !== 'function')
+      throw Error('ClaudeAgentSdkSession requires `query` from @anthropic-ai/claude-agent-sdk');
+    if (config.canUseTool && config.permissionMode === 'bypassPermissions')
+      throw Error(
+        'ClaudeAgentSdkSession: canUseTool is never consulted under permissionMode "bypassPermissions"; pass another mode or drop canUseTool',
+      );
+    const {
+      query: _query,
+      canUseTool: _canUseTool,
+      bundledCli: _bundled,
+      sdkOptions: _options,
+      ...session
+    } = config;
+    super({
+      ...session,
+      ...(config.canUseTool ? { permissionMode: config.permissionMode ?? 'default' } : {}),
+      spawn: bridge(config),
+    });
+    this._sdk = config;
+  }
+
+  /** get_usage is not reachable through the SDK Query API. */
+  override async readLimits(): Promise<never> {
+    throw Error(
+      'Limit polling is not exposed by the Agent SDK transport; use the claude-cli transport or rate_limit events',
+    );
+  }
+
+  protected override _construct(config: ClaudeCodeSessionConfig): ClaudeCodeSession {
+    const { spawn: _spawn, ...rest } = config;
+    return new ClaudeAgentSdkSession({
+      ...rest,
+      query: this._sdk.query,
+      canUseTool: this._sdk.canUseTool,
+      bundledCli: this._sdk.bundledCli,
+      sdkOptions: this._sdk.sdkOptions,
+    });
+  }
+}