@inixiative/agent-session 0.2.0 → 0.3.1

package/src/transport.ts

@@ -0,0 +1,215 @@
+// ---------------------------------------------------------------------------
+// Transports — how a session reaches its model
+// ---------------------------------------------------------------------------
+//
+// Every transport implements the same HarnessSession contract. Switching how a
+// model is reached (native CLI on a subscription, a warm app-server, the Agent
+// SDK, ACP, a metered API) is a routing change, not a rewrite. Each transport
+// declares what it can actually do; callers branch on capabilities, never on
+// the transport kind.
+//
+// Capabilities describe this package's implementation, not what the runtime
+// could do in principle. A native feature that exists but is not wired up here
+// is declared absent, with a note.
+// ---------------------------------------------------------------------------
+
+export type TransportKind =
+  | 'claude-cli'
+  | 'codex-mcp'
+  | 'codex-app-server'
+  | 'claude-agent-sdk'
+  | 'acp'
+  | 'api';
+
+export type TransportRuntime = 'claude' | 'codex' | 'external';
+
+export interface TransportCapabilities {
+  /** Continue a thread by native ID in a new process (`loaded-only`: only while the original process holds it). */
+  readonly resume: 'native' | 'loaded-only' | 'none';
+  /** `native`: a new branch with its own ID; `same-thread`: continues the parent thread (not a real fork). */
+  readonly fork: 'native' | 'same-thread' | 'none';
+  /** Drop the last N turns of native history. */
+  readonly rollback: 'native' | 'none';
+  /** `acknowledged`: interruptNative() confirms the stop through the turn's terminal; `local-only`: interrupt() releases the local waiter only. */
+  readonly interrupt: 'acknowledged' | 'local-only';
+  /** `steer`: push() adds input to the in-flight turn; `none`: push() records push_ignored. */
+  readonly push: 'steer' | 'none';
+  /** `callback`: per-call decision hook; `mode`: a fixed launch policy (bypass); `refuse`: runtime requests are refused. */
+  readonly approvals: 'callback' | 'mode' | 'refuse';
+  /** Token usage reported per turn. */
+  readonly usage: boolean;
+  /** Account limits: `stream` as rate_limit events during turns, `poll` via readLimits() without a model turn. */
+  readonly limits: { readonly stream: boolean; readonly poll: boolean };
+  /** A tool-free, text-only session can be enforced (decisions). */
+  readonly textOnly: boolean;
+  /** Primed decision host on this transport and how it returns to its primed state each cycle (see primed.ts). */
+  readonly primed: 'fork' | 'none';
+  readonly billing: 'subscription' | 'api';
+}
+
+export interface TransportDescriptor {
+  readonly kind: TransportKind;
+  readonly runtime: TransportRuntime;
+  /** `stub`: the session constructor throws TransportUnavailableError. */
+  readonly status: 'implemented' | 'stub';
+  /** Strongest evidence behind the capabilities: `live` runs against the real CLI, `controlled` uses fake processes only. */
+  readonly verified: 'live' | 'controlled' | 'none';
+  readonly capabilities: TransportCapabilities;
+  readonly notes: readonly string[];
+}
+
+const none = { stream: false, poll: false } as const;
+
+export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> = Object.freeze({
+  'claude-cli': {
+    kind: 'claude-cli',
+    runtime: 'claude',
+    status: 'implemented',
+    verified: 'live',
+    capabilities: {
+      resume: 'native',
+      fork: 'native',
+      rollback: 'none',
+      interrupt: 'acknowledged',
+      push: 'none',
+      approvals: 'mode',
+      usage: true,
+      limits: { stream: true, poll: true },
+      textOnly: true,
+      primed: 'fork',
+      billing: 'subscription',
+    },
+    notes: [
+      'Persistent `claude --print --input-format stream-json` process.',
+      'textOnly launches with no tools, MCP servers, slash commands or user settings.',
+      'Primed decisions (ClaudePrimedSessions) fork a persisted primed session per cycle with a pre-spawned spare.',
+      "interruptNative() and readLimits() use the CLI's stdio control protocol (`interrupt`, `get_usage`).",
+      'Rollback (`--resume-session-at`) and per-call approvals (`--permission-prompt-tool stdio`) exist natively but are not wired here.',
+    ],
+  },
+  'codex-mcp': {
+    kind: 'codex-mcp',
+    runtime: 'codex',
+    status: 'implemented',
+    verified: 'live',
+    capabilities: {
+      resume: 'loaded-only',
+      fork: 'same-thread',
+      rollback: 'none',
+      interrupt: 'local-only',
+      push: 'none',
+      approvals: 'mode',
+      usage: true,
+      limits: none,
+      textOnly: false,
+      primed: 'none',
+      billing: 'subscription',
+    },
+    notes: [
+      '`codex mcp-server`; `codex-reply` continues only threads loaded in the same process.',
+      'fork() continues the parent thread; it is not a native fork.',
+    ],
+  },
+  'codex-app-server': {
+    kind: 'codex-app-server',
+    runtime: 'codex',
+    status: 'implemented',
+    verified: 'live',
+    capabilities: {
+      resume: 'native',
+      fork: 'none',
+      rollback: 'none',
+      interrupt: 'acknowledged',
+      push: 'steer',
+      approvals: 'refuse',
+      usage: true,
+      limits: { stream: true, poll: true },
+      textOnly: false,
+      primed: 'fork',
+      billing: 'subscription',
+    },
+    notes: [
+      '`codex app-server --listen stdio://` with thread/start, thread/resume, turn/start.',
+      "CodexAppServerSession runs with the profile's tools; tool-free text sessions are CodexPrimedSessions (primed: fork).",
+      'interruptNative() sends turn/interrupt; push() sends turn/steer against the owned turn.',
+      'Primed decisions (CodexPrimedSessions) host every key as a thread of one process per account and fork the primed thread per cycle.',
+      'thread/rollback is refused by codex-cli 0.155 for both ephemeral and paginated threads; session fork() is not wired.',
+    ],
+  },
+  'claude-agent-sdk': {
+    kind: 'claude-agent-sdk',
+    runtime: 'claude',
+    status: 'implemented',
+    verified: 'live',
+    capabilities: {
+      resume: 'native',
+      fork: 'native',
+      rollback: 'none',
+      interrupt: 'acknowledged',
+      push: 'none',
+      approvals: 'callback',
+      usage: true,
+      limits: { stream: true, poll: false },
+      textOnly: true,
+      primed: 'none',
+      billing: 'subscription',
+    },
+    notes: [
+      'Drives `@anthropic-ai/claude-agent-sdk` query() supplied by the caller; this package keeps zero dependencies.',
+      "Reuses ClaudeCodeSession's event classification and admission evidence over the SDK message stream.",
+    ],
+  },
+  acp: {
+    kind: 'acp',
+    runtime: 'external',
+    status: 'stub',
+    verified: 'none',
+    capabilities: {
+      resume: 'none',
+      fork: 'none',
+      rollback: 'none',
+      interrupt: 'local-only',
+      push: 'none',
+      approvals: 'refuse',
+      usage: false,
+      limits: none,
+      textOnly: false,
+      primed: 'none',
+      billing: 'subscription',
+    },
+    notes: [
+      'Agent Client Protocol (JSON-RPC over stdio). Not implemented: no ACP agent is available to verify against.',
+    ],
+  },
+  api: {
+    kind: 'api',
+    runtime: 'external',
+    status: 'stub',
+    verified: 'none',
+    capabilities: {
+      resume: 'none',
+      fork: 'none',
+      rollback: 'none',
+      interrupt: 'local-only',
+      push: 'none',
+      approvals: 'refuse',
+      usage: false,
+      limits: none,
+      textOnly: false,
+      primed: 'none',
+      billing: 'api',
+    },
+    notes: ['Direct metered API. Explicit opt-in only; not implemented.'],
+  },
+} satisfies Record<TransportKind, TransportDescriptor>);
+
+/** Thrown by stub transports. Never falls back to another transport. */
+export class TransportUnavailableError extends Error {
+  constructor(
+    readonly kind: TransportKind,
+    detail: string,
+  ) {
+    super(`Transport "${kind}" is not available: ${detail}`);
+    this.name = 'TransportUnavailableError';
+  }
+}

package/src/transports.ts

@@ -0,0 +1,97 @@
+// Construct a HarnessSession by transport kind. Switching how a model is
+// reached is a change of `kind` (a routing decision), not of calling code.
+
+import {
+  ClaudeAgentSdkSession,
+  type ClaudeAgentSdkSessionConfig,
+} from './claude-agent-sdk-session';
+import { ClaudeCodeSession, type ClaudeCodeSessionConfig } from './claude-code-session';
+import { CodexAppServerSession, CodexMcpSession, type CodexSessionConfig } from './codex-session';
+import type { HarnessSession } from './harness-session';
+import {
+  TRANSPORTS,
+  type TransportDescriptor,
+  type TransportKind,
+  TransportUnavailableError,
+} from './transport';
+
+/** Agent Client Protocol agent launched over stdio. Typed for callers; not implemented. */
+export interface AcpSessionConfig {
+  /** Agent command, e.g. ["gemini", "--experimental-acp"]. */
+  command: readonly string[];
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  timeout?: number;
+}
+
+/** Direct metered API. Requires an explicit opt-in and an explicit key; never read from the environment. */
+export interface ApiSessionConfig {
+  provider: 'anthropic' | 'openai';
+  model: string;
+  apiKey: string;
+  allowApiBilling: true;
+  baseContext?: string;
+  timeout?: number;
+}
+
+export interface TransportConfigs {
+  'claude-cli': ClaudeCodeSessionConfig;
+  'codex-mcp': CodexSessionConfig;
+  'codex-app-server': CodexSessionConfig;
+  'claude-agent-sdk': ClaudeAgentSdkSessionConfig;
+  acp: AcpSessionConfig;
+  api: ApiSessionConfig;
+}
+
+/** Typed stub: constructing it throws TransportUnavailableError. */
+export class AcpSession {
+  constructor(_config: AcpSessionConfig) {
+    throw new TransportUnavailableError(
+      'acp',
+      'no ACP client is implemented in this package; use claude-cli, claude-agent-sdk or codex-app-server',
+    );
+  }
+}
+
+/** Typed stub: constructing it throws TransportUnavailableError, even with the opt-in set. */
+export class ApiSession {
+  constructor(config: ApiSessionConfig) {
+    if (config?.allowApiBilling !== true)
+      throw new TransportUnavailableError(
+        'api',
+        'metered API billing requires allowApiBilling: true',
+      );
+    throw new TransportUnavailableError(
+      'api',
+      'the direct API transport is not implemented in this package; subscription transports never fall back to it',
+    );
+  }
+}
+
+export function describeTransport(kind: TransportKind): TransportDescriptor {
+  const descriptor = TRANSPORTS[kind];
+  if (!descriptor) throw Error(`Unknown transport "${String(kind)}"`);
+  return descriptor;
+}
+
+export function createSession<K extends TransportKind>(
+  kind: K,
+  config: TransportConfigs[K],
+): HarnessSession {
+  switch (kind) {
+    case 'claude-cli':
+      return new ClaudeCodeSession(config as ClaudeCodeSessionConfig);
+    case 'codex-mcp':
+      return new CodexMcpSession(config as CodexSessionConfig);
+    case 'codex-app-server':
+      return new CodexAppServerSession(config as CodexSessionConfig);
+    case 'claude-agent-sdk':
+      return new ClaudeAgentSdkSession(config as ClaudeAgentSdkSessionConfig);
+    case 'acp':
+      return new AcpSession(config as AcpSessionConfig) as unknown as HarnessSession;
+    case 'api':
+      return new ApiSession(config as ApiSessionConfig) as unknown as HarnessSession;
+    default:
+      throw Error(`Unknown transport "${String(kind)}"`);
+  }
+}

package/src/turn-state.ts

@@ -1,42 +1,72 @@
-import { SessionTurnError, type SessionAttempt, type SessionEvent, type SessionIdentity, type SessionResult, type SessionTokens } from "./harness-session";
-import { retainEvidence } from "./retained-evidence";
+import {
+  type SessionAttempt,
+  type SessionEvent,
+  type SessionIdentity,
+  type SessionResult,
+  type SessionTokens,
+  SessionTurnError,
+} from './harness-session';
+import { retainEvidence } from './retained-evidence';
 /** Per-admission evidence. Caller settlement never transfers native ownership. */
 export class TurnState {
   readonly admissionId = crypto.randomUUID();
   identity: SessionIdentity = {};
-  nativeOutcome: SessionAttempt["nativeOutcome"] = "unknown";
-  localOutcome: SessionAttempt["localOutcome"] = "pending";
-  dispatch: SessionAttempt["dispatch"] = "not-dispatched";
-  transportOutcome: SessionAttempt["transportOutcome"] = "open";
-  private _terminal?: SessionAttempt["terminal"];
-  get terminal() { return this._terminal; }
-  set terminal(value: SessionAttempt["terminal"]) { this._terminal = retainEvidence(value); }
+  nativeOutcome: SessionAttempt['nativeOutcome'] = 'unknown';
+  localOutcome: SessionAttempt['localOutcome'] = 'pending';
+  dispatch: SessionAttempt['dispatch'] = 'not-dispatched';
+  transportOutcome: SessionAttempt['transportOutcome'] = 'open';
+  private _terminal?: SessionAttempt['terminal'];
+  get terminal() {
+    return this._terminal;
+  }
+  set terminal(value: SessionAttempt['terminal']) {
+    this._terminal = retainEvidence(value);
+  }
   events: SessionEvent[] = [];
-  content = "";
+  content = '';
   private _tokens?: SessionTokens;
-  get tokens() { return this._tokens; }
-  set tokens(value: SessionTokens | undefined) { this._tokens = retainEvidence(value); }
-  localFailure?: SessionAttempt["localFailure"];
+  get tokens() {
+    return this._tokens;
+  }
+  set tokens(value: SessionTokens | undefined) {
+    this._tokens = retainEvidence(value);
+  }
+  localFailure?: SessionAttempt['localFailure'];
   rpcSettled = false;
-  rpcOutcome?: SessionAttempt["rpcOutcome"];
+  rpcOutcome?: SessionAttempt['rpcOutcome'];
   snapshot(): SessionAttempt {
-    return Object.freeze({ ...this.identity, admissionId: this.admissionId, nativeOutcome: this.nativeOutcome,
-      localOutcome: this.localOutcome, dispatch: this.dispatch, transportOutcome: this.transportOutcome,
-      rpcOutcome: this.rpcOutcome, terminal: this.terminal, localFailure: this.localFailure,
-      content: this.content, events: Object.freeze([...this.events]), tokens: this.tokens });
-  }
-  result(externalSessionId?: string): SessionResult { return Object.freeze({ ...this.snapshot(), externalSessionId }); }
-  fail(error: Error, reason: SessionAttempt["localFailure"]): SessionTurnError {
-    if (this.localOutcome === "pending") { this.localOutcome = "rejected"; this.localFailure = reason; }
+    return Object.freeze({
+      ...this.identity,
+      admissionId: this.admissionId,
+      nativeOutcome: this.nativeOutcome,
+      localOutcome: this.localOutcome,
+      dispatch: this.dispatch,
+      transportOutcome: this.transportOutcome,
+      rpcOutcome: this.rpcOutcome,
+      terminal: this.terminal,
+      localFailure: this.localFailure,
+      content: this.content,
+      events: Object.freeze([...this.events]),
+      tokens: this.tokens,
+    });
+  }
+  result(externalSessionId?: string): SessionResult {
+    return Object.freeze({ ...this.snapshot(), externalSessionId });
+  }
+  fail(error: Error, reason: SessionAttempt['localFailure']): SessionTurnError {
+    if (this.localOutcome === 'pending') {
+      this.localOutcome = 'rejected';
+      this.localFailure = reason;
+    }
     return new SessionTurnError(error.message, () => this.snapshot(), { cause: error });
   }
   record(event: SessionEvent): SessionEvent {
     const e = retainEvidence({ ...this.identity, ...event, admissionId: this.admissionId });
     this.events.push(e);
-    if ((e.kind === "text" || e.kind === "result") && e.text) this.content = e.text;
-    if (e.kind === "text_delta" && e.text) this.content += e.text;
+    if ((e.kind === 'text' || e.kind === 'result') && e.text) this.content = e.text;
+    if (e.kind === 'text_delta' && e.text) this.content += e.text;
     // Usage events are per-request snapshots; the terminal result carries the turn total.
-    if (e.tokens && e.kind !== "usage") this.tokens = e.tokens;
+    if (e.tokens && e.kind !== 'usage') this.tokens = e.tokens;
     return e;
   }
 }