@inixiative/agent-session 0.2.0 → 0.3.0

package/src/harness-session.ts

@@ -10,9 +10,14 @@
 // HarnessSession is stateful: it owns a running process, tracks turns,
 // captures every event for Oracle, and supports fork/interrupt.
 //
-// Implementations: ClaudeCodeSession (now), CodexSession / CursorSession (future)
+// Implementations: ClaudeCodeSession, CodexMcpSession, CodexAppServerSession,
+// ClaudeAgentSdkSession. How a model is reached is the session's transport
+// (see transport.ts); every transport implements this one contract.
 // ---------------------------------------------------------------------------
 
+import type { LimitSnapshot } from './limits';
+import type { TransportDescriptor } from './transport';
+
 // ---------------------------------------------------------------------------
 // Event taxonomy — classified events from the agent stream
 // ---------------------------------------------------------------------------
@@ -27,9 +32,9 @@ export interface SessionIdentity {
   readonly callId?: string;
   readonly messageId?: string;
   readonly rpcRequestId?: number;
-  readonly correlation?: "native-turn" | "ordered-stream" | "unknown";
+  readonly correlation?: 'native-turn' | 'ordered-stream' | 'unknown';
 }
-export type NativeOutcome = "unknown" | "completed" | "failed";
+export type NativeOutcome = 'unknown' | 'completed' | 'failed';
 export interface NativeTerminal {
   readonly type: string;
   readonly eventId?: string;
@@ -40,37 +45,54 @@ export interface NativeTerminal {
 }
 export interface SessionAttempt extends SessionIdentity {
   readonly nativeOutcome: NativeOutcome;
-  readonly localOutcome: "pending" | "resolved" | "rejected";
-  readonly dispatch: "not-dispatched" | "attempted";
-  readonly transportOutcome: "open" | "failed" | "closed";
+  readonly localOutcome: 'pending' | 'resolved' | 'rejected';
+  readonly dispatch: 'not-dispatched' | 'attempted';
+  readonly transportOutcome: 'open' | 'failed' | 'closed';
   readonly terminal?: NativeTerminal;
-  readonly rpcOutcome?: "pending" | "resolved" | "failed" | "unknown";
-  readonly localFailure?: "timeout" | "interrupt-request" | "transport" | "rpc" | "validation" | "blocked" | "killed" | "unrecognized-terminal" | "registration";
+  readonly rpcOutcome?: 'pending' | 'resolved' | 'failed' | 'unknown';
+  readonly localFailure?:
+    | 'timeout'
+    | 'interrupt-request'
+    | 'transport'
+    | 'rpc'
+    | 'validation'
+    | 'blocked'
+    | 'killed'
+    | 'unrecognized-terminal'
+    | 'registration';
   readonly content: string;
   readonly events: readonly SessionEvent[];
   readonly tokens?: SessionTokens;
 }
 /** A rejected local send can still have a later native terminal; read attempt again to reconcile. */
 export class SessionTurnError extends Error {
-  constructor(message: string, private readonly evidence: () => SessionAttempt, options?: ErrorOptions) {
-    super(message, options); this.name = "SessionTurnError";
+  constructor(
+    message: string,
+    private readonly evidence: () => SessionAttempt,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = 'SessionTurnError';
+  }
+  get attempt(): SessionAttempt {
+    return this.evidence();
   }
-  get attempt(): SessionAttempt { return this.evidence(); }
 }
 
 export type SessionEventKind =
-  | "text_delta"
-  | "native_status"
-  | "session_start"
-  | "session_end"
-  | "session_compact"
-  | "text"
-  | "tool_use"
-  | "tool_result"
-  | "thinking"
-  | "usage"
-  | "result"
-  | "error";
+  | 'text_delta'
+  | 'native_status'
+  | 'session_start'
+  | 'session_end'
+  | 'session_compact'
+  | 'text'
+  | 'tool_use'
+  | 'tool_result'
+  | 'thinking'
+  | 'usage'
+  | 'rate_limit'
+  | 'result'
+  | 'error';
 
 /** Input excludes cache reads/writes when those disjoint counters are supplied.
  * Thinking is a subset of output; TTL counters are subsets of cacheWrite.
@@ -96,10 +118,21 @@ export interface SessionEvent extends SessionIdentity {
    * repeated one is not evidence of compaction or restart. "duplicate-boundary": an explicit
    * compaction boundary whose native uuid was already recorded.
    */
-  readonly unattributedReason?: "no-admission" | "foreign-session" | "foreign-turn" | "duplicate-terminal" | "after-terminal"
-    | "unrecognized-event" | "session-configuration" | "duplicate-boundary" | "duplicate-tool" | "unmatched-tool" | "malformed-tool";
+  readonly unattributedReason?:
+    | 'no-admission'
+    | 'foreign-session'
+    | 'foreign-turn'
+    | 'duplicate-terminal'
+    | 'after-terminal'
+    | 'unrecognized-event'
+    | 'session-configuration'
+    | 'duplicate-boundary'
+    | 'duplicate-tool'
+    | 'unmatched-tool'
+    | 'malformed-tool'
+    | 'account-status';
   /** Local transport observation, not a native terminal acknowledgment. */
-  readonly transportOutcome?: SessionAttempt["transportOutcome"];
+  readonly transportOutcome?: SessionAttempt['transportOutcome'];
   readonly nativeOutcome?: NativeOutcome;
   readonly terminal?: NativeTerminal;
   readonly kind: SessionEventKind;
@@ -137,15 +170,17 @@ export interface SessionEvent extends SessionIdentity {
   readonly externalSessionId?: string;
   /** Turn totals on result; request snapshots on usage. Do not sum both. */
   readonly tokens?: SessionTokens;
+  /** Account-level usage limits (for rate_limit). Never attributed to an admission. */
+  readonly limits?: LimitSnapshot;
   /** Owned, deeply frozen native JSON data (for Oracle introspection). */
   readonly raw?: unknown;
 }
 
 /** Result of a single send() — the turn's content plus all classified events. */
 export interface SessionResult extends SessionIdentity {
-  readonly localOutcome?: SessionAttempt["localOutcome"];
-  readonly transportOutcome?: SessionAttempt["transportOutcome"];
-  readonly rpcOutcome?: SessionAttempt["rpcOutcome"];
+  readonly localOutcome?: SessionAttempt['localOutcome'];
+  readonly transportOutcome?: SessionAttempt['transportOutcome'];
+  readonly rpcOutcome?: SessionAttempt['rpcOutcome'];
   readonly nativeOutcome?: NativeOutcome;
   readonly terminal?: NativeTerminal;
   readonly content: string;
@@ -164,7 +199,7 @@ export interface SessionArtifact {
   readonly diagnostics?: SessionDiagnostics;
   readonly attempts?: readonly SessionAttempt[];
   /** Legacy totalTokens contains observed counts only, not proof of complete accounting. */
-  readonly accounting?: "observed-only";
+  readonly accounting?: 'observed-only';
   /** The runtime's native session ID. See SessionEvent.externalSessionId. */
   readonly externalSessionId?: string;
   readonly events: readonly SessionEvent[];
@@ -189,9 +224,7 @@ export type SessionEventHandler = (event: SessionEvent) => void;
  * computes "what's new since the last injection," formats it as a prefix,
  * and the composed message goes to send().
  */
-export type BeforeSendHook = (
-  message: string,
-) => string | Promise<string>;
+export type BeforeSendHook = (message: string) => string | Promise<string>;
 
 export interface SessionSendOptions {
   timeout?: number;
@@ -203,13 +236,27 @@ export interface SessionSendOptions {
 // HarnessSession interface
 // ---------------------------------------------------------------------------
 
+/** `acknowledged`: the runtime confirmed the stop and the turn reached a native terminal. */
+export type NativeInterruptOutcome = 'acknowledged' | 'no-turn' | 'unacknowledged';
+
 export interface HarnessSession {
+  /** How this session reaches its model, with the capabilities that transport declares. */
+  readonly transport?: TransportDescriptor;
+  /**
+   * Ask the runtime to stop the in-flight turn and wait (bounded) for its
+   * acknowledgment. Present only where the transport declares
+   * `interrupt: "acknowledged"`. Unlike interrupt(), a confirmed stop settles
+   * native ownership through the turn's own terminal.
+   */
+  interruptNative?(opts?: { timeoutMs?: number }): Promise<NativeInterruptOutcome>;
+  /** Poll account usage limits without a model turn. Present where the transport declares `limits.poll`. */
+  readLimits?(opts?: { timeoutMs?: number }): Promise<LimitSnapshot | undefined>;
   /** One immutable admission snapshot, without copying unrelated session history. */
   inspectAttempt?(admissionId: string): SessionAttempt | undefined;
-  readonly admissionProtocol?: "prewrite-v1";
+  readonly admissionProtocol?: 'prewrite-v1';
   readonly diagnostics?: SessionDiagnostics;
   readonly attempts?: readonly SessionAttempt[];
-  readonly accounting?: "observed-only";
+  readonly accounting?: 'observed-only';
   readonly alive: boolean;
   /**
    * The agent runtime's native session ID — external to Foundry.

package/src/index.ts

@@ -1,23 +1,117 @@
-// @inixiative/agent-session — drive coding-agent CLIs as persistent,
-// streaming, event-captured sessions.
-
-// The provider-agnostic interface + event taxonomy.
-export * from "./harness-session";
+// @inixiative/agent-session — drive coding-agent runtimes as persistent,
+// streaming, event-captured sessions, over interchangeable transports.
 
+// Claude through the Agent SDK (caller supplies `query`; zero dependencies here).
+export {
+  type ClaudeAgentSdkCanUseTool,
+  type ClaudeAgentSdkQuery,
+  type ClaudeAgentSdkQueryFunction,
+  ClaudeAgentSdkSession,
+  type ClaudeAgentSdkSessionConfig,
+  sdkOptionsFromArgv,
+} from './claude-agent-sdk-session';
 // Claude Code adapter (persistent stream-json session, subscription auth).
 export {
+  CLAUDE_TEXT_ONLY_ARGS,
   ClaudeCodeSession,
   type ClaudeCodeSessionConfig,
-} from "./claude-code-session";
+} from './claude-code-session';
+export { type ClaudePrimedConfig, ClaudePrimedSessions } from './claude-primed';
+export { parseClaudeUsage } from './claude-usage';
+export {
+  CODEX_DECISION_DISABLED_FEATURES,
+  CODEX_DECISION_THREAD_CONFIG,
+  type CodexPrimedConfig,
+  CodexPrimedSessions,
+  codexDecisionLaunchArgs,
+  codexTokens,
+} from './codex-primed';
 
 // Codex CLI adapter (persistent JSON-RPC session). CodexSession defaults to the
-// mcp-server variant; CodexAppServerSession is the experimental app-server one.
+// mcp-server variant; CodexAppServerSession is the app-server one.
 export {
-  CodexSession,
-  CodexMcpSession,
   CodexAppServerSession,
+  CodexMcpSession,
+  CodexSession,
   type CodexSessionConfig,
   type CodexSpawn,
-} from "./codex-session";
-
-export { parseClaudeUsage } from "./claude-usage";
+} from './codex-session';
+// The provider-agnostic interface + event taxonomy.
+export * from './harness-session';
+export {
+  JsonRpcClosedError,
+  JsonRpcConnection,
+  JsonRpcError,
+  JsonRpcTimeoutError,
+} from './json-rpc';
+// Subscription limits, polling, routing and pools.
+export {
+  claudeRateLimitSnapshot,
+  claudeUsageSnapshot,
+  codexLimitSnapshot,
+  type LimitRuntime,
+  type LimitSnapshot,
+  type LimitWindow,
+  limitUtilization,
+  mergeLimits,
+} from './limits';
+export { type LimitProbeOptions, probeClaudeLimits, probeCodexLimits } from './limits-probe';
+export {
+  ContinuityError,
+  type ContinuityRefusal,
+  type FailureKind,
+  type InstanceConfig,
+  type InstanceStatus,
+  type Lease,
+  type PoolEvent,
+  PoolExhaustedError,
+  type PooledSessionConfig,
+  type PooledTransport,
+  type PoolRequest,
+  SubscriptionPool,
+  type SubscriptionPoolOptions,
+} from './pool';
+// Primed decision sessions: one live, warm session per middleware role.
+export {
+  type DecisionAdmission,
+  DecisionError,
+  type DecisionFailure,
+  type DecisionRequest,
+  type DecisionResult,
+  type PrimedEvent,
+  type PrimedSessions,
+  type PrimedSnapshot,
+  type PrimeSpec,
+  primeHash,
+} from './primed';
+export {
+  assessCandidate,
+  type CandidateRequest,
+  type ExclusionReason,
+  type RankedCandidate,
+  type RepositoryRoute,
+  type RoutingMode,
+  type RoutingRequest,
+  rankCandidates,
+  rankSubscriptionAccounts,
+  repositoryIdentity,
+  type SubscriptionCandidate,
+} from './routing';
+// Transports: how a session reaches its model, with declared capabilities.
+export {
+  TRANSPORTS,
+  type TransportCapabilities,
+  type TransportDescriptor,
+  type TransportKind,
+  type TransportRuntime,
+  TransportUnavailableError,
+} from './transport';
+export {
+  AcpSession,
+  type AcpSessionConfig,
+  ApiSession,
+  type ApiSessionConfig,
+  createSession,
+  describeTransport,
+  type TransportConfigs,
+} from './transports';

package/src/json-rpc.ts

@@ -0,0 +1,240 @@
+// Minimal JSON-RPC 2.0 over a child's stdio, one JSON object per line.
+// Used where a caller multiplexes many threads over one native process
+// (Codex app-server) or makes short control reads (limit polls).
+
+import type { PipedSubprocess } from './codex-session';
+
+export class JsonRpcError extends Error {
+  constructor(
+    readonly code: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'JsonRpcError';
+  }
+}
+/** No response within the caller's bound; the request may still be processed. */
+export class JsonRpcTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'JsonRpcTimeoutError';
+  }
+}
+export class JsonRpcClosedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'JsonRpcClosedError';
+  }
+}
+
+export interface JsonRpcHandlers {
+  onNotification?(method: string, params: Record<string, unknown> | undefined): void;
+  /** Return true when the request was answered; unanswered requests are refused (-32601). */
+  onRequest?(
+    id: string | number,
+    method: string,
+    params: Record<string, unknown> | undefined,
+  ): boolean;
+  onClose?(error: Error): void;
+}
+
+const object = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+export class JsonRpcConnection {
+  private _id = 0;
+  private _pending = new Map<
+    number,
+    {
+      resolve(value: unknown): void;
+      reject(error: Error): void;
+      timer?: ReturnType<typeof setTimeout>;
+    }
+  >();
+  private _stderr = '';
+  private _closeError?: Error;
+  readonly exited: Promise<number>;
+
+  constructor(
+    private readonly _proc: PipedSubprocess,
+    private readonly _handlers: JsonRpcHandlers = {},
+  ) {
+    this.exited = _proc.exited;
+    void this._read();
+    void this._readStderr();
+    _proc.exited.then(
+      (code) =>
+        this._close(
+          new JsonRpcClosedError(
+            `Native process exited (code ${code})${this._stderr.trim() ? `: ${this._stderr.trim().slice(-300)}` : ''}`,
+          ),
+        ),
+      () => this._close(new JsonRpcClosedError('Native process exit unobserved')),
+    );
+  }
+
+  get closed(): boolean {
+    return this._closeError !== undefined;
+  }
+  get stderrTail(): string {
+    return this._stderr.slice(-2_000);
+  }
+
+  request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown> {
+    if (this._closeError) return Promise.reject(this._closeError);
+    const id = ++this._id;
+    return new Promise((resolve, reject) => {
+      const entry: {
+        resolve(value: unknown): void;
+        reject(error: Error): void;
+        timer?: ReturnType<typeof setTimeout>;
+      } = { resolve, reject };
+      if (timeoutMs !== undefined && timeoutMs > 0)
+        entry.timer = setTimeout(() => {
+          this._pending.delete(id);
+          reject(new JsonRpcTimeoutError(`${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      this._pending.set(id, entry);
+      try {
+        this._write({ jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) });
+      } catch (error) {
+        clearTimeout(entry.timer);
+        this._pending.delete(id);
+        reject(error as Error);
+      }
+    });
+  }
+
+  notify(method: string, params?: unknown): void {
+    this._write({ jsonrpc: '2.0', method, ...(params === undefined ? {} : { params }) });
+  }
+
+  /** Kill the process. Pending requests reject once its exit is observed. */
+  kill(): void {
+    try {
+      this._proc.stdin.end();
+    } catch {
+      /* already closed */
+    }
+    try {
+      this._proc.kill();
+    } catch {
+      /* already dead */
+    }
+  }
+
+  private _write(message: unknown): void {
+    if (this._closeError) throw this._closeError;
+    this._proc.stdin.write(`${JSON.stringify(message)}\n`);
+    this._proc.stdin.flush();
+  }
+
+  private _close(error: Error): void {
+    if (this._closeError) return;
+    this._closeError = error;
+    for (const entry of this._pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    this._pending.clear();
+    try {
+      this._handlers.onClose?.(error);
+    } catch {
+      /* observer */
+    }
+  }
+
+  private async _read(): Promise<void> {
+    const reader = this._proc.stdout.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop()!;
+        for (const line of lines) this._line(line);
+      }
+      this._line(buffer + decoder.decode());
+      this._close(
+        new JsonRpcClosedError(
+          `Native stdout closed${this._stderr.trim() ? `: ${this._stderr.trim().slice(-300)}` : ''}`,
+        ),
+      );
+    } catch (error) {
+      this._close(error instanceof Error ? error : new JsonRpcClosedError(String(error)));
+    }
+  }
+
+  private async _readStderr(): Promise<void> {
+    const reader = this._proc.stderr.getReader();
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        this._stderr = (this._stderr + decoder.decode(value, { stream: true })).slice(-8_192);
+      }
+    } catch {
+      /* diagnostics only */
+    }
+  }
+
+  private _line(line: string): void {
+    if (!line.trim()) return;
+    let message: Record<string, unknown> | undefined;
+    try {
+      message = object(JSON.parse(line));
+    } catch {
+      return;
+    }
+    if (!message) return;
+    const id = message.id,
+      method = typeof message.method === 'string' ? message.method : undefined;
+    if (method && (typeof id === 'string' || typeof id === 'number')) {
+      let answered = false;
+      try {
+        answered = this._handlers.onRequest?.(id, method, object(message.params)) === true;
+      } catch {
+        answered = false;
+      }
+      if (!answered)
+        this.respondError(id, -32601, 'Client interaction is unsupported by this adapter');
+      return;
+    }
+    if (method) {
+      try {
+        this._handlers.onNotification?.(method, object(message.params));
+      } catch {
+        /* observer */
+      }
+      return;
+    }
+    if (typeof id !== 'number') return;
+    const entry = this._pending.get(id);
+    if (!entry) return;
+    this._pending.delete(id);
+    clearTimeout(entry.timer);
+    const error = object(message.error);
+    if (error)
+      entry.reject(
+        new JsonRpcError(
+          typeof error.code === 'number' ? error.code : -32000,
+          typeof error.message === 'string' ? error.message : 'JSON-RPC error',
+        ),
+      );
+    else entry.resolve(message.result);
+  }
+
+  respondError(id: string | number, code: number, message: string): void {
+    try {
+      this._write({ jsonrpc: '2.0', id, error: { code, message } });
+    } catch {
+      /* closing */
+    }
+  }
+}

package/src/limits-probe.ts

@@ -0,0 +1,78 @@
+// One-shot account limit reads without a model turn: a short-lived native
+// process asks the runtime for its usage, then exits. Account identity is not read.
+
+import { ClaudeCodeSession, type ClaudeCodeSessionConfig } from './claude-code-session';
+import type { CodexSpawn, PipedSubprocess } from './codex-session';
+import { JsonRpcConnection } from './json-rpc';
+import { codexLimitSnapshot, type LimitSnapshot } from './limits';
+
+export interface LimitProbeOptions {
+  bin?: string;
+  /** Merged over process.env (CODEX_HOME / CLAUDE_CONFIG_DIR for a profile). */
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+/** `codex app-server` → account/rateLimits/read. */
+export async function probeCodexLimits(
+  options: LimitProbeOptions & { spawn?: CodexSpawn } = {},
+): Promise<LimitSnapshot | undefined> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const argv = [options.bin ?? 'codex', 'app-server', '--listen', 'stdio://'];
+  const env: Record<string, string | undefined> = {
+    ...process.env,
+    ...options.env,
+    DISABLE_AUTOUPDATER: '1',
+  };
+  delete env.OPENAI_API_KEY;
+  delete env.CODEX_API_KEY;
+  for (const key of Object.keys(env)) if (env[key] === undefined) delete env[key];
+  const cwd = options.cwd ?? process.cwd();
+  const proc = options.spawn
+    ? options.spawn(argv, { cwd, env })
+    : (Bun.spawn(argv, {
+        cwd,
+        env,
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+      }) as unknown as PipedSubprocess);
+  const conn = new JsonRpcConnection(proc);
+  try {
+    await conn.request(
+      'initialize',
+      { clientInfo: { name: 'agent-session-limits', version: '0.2.0' }, capabilities: {} },
+      timeoutMs,
+    );
+    conn.notify('initialized');
+    return codexLimitSnapshot(
+      await conn.request('account/rateLimits/read', { excludeResetCreditDetails: true }, timeoutMs),
+      'poll',
+    );
+  } finally {
+    conn.kill();
+    await Promise.race([conn.exited.catch(() => 0), Bun.sleep(2_000)]);
+  }
+}
+
+/** Text-only `claude` process → control request get_usage. */
+export async function probeClaudeLimits(
+  options: LimitProbeOptions & { spawn?: ClaudeCodeSessionConfig['spawn'] } = {},
+): Promise<LimitSnapshot | undefined> {
+  const session = new ClaudeCodeSession({
+    bin: options.bin,
+    env: options.env,
+    cwd: options.cwd,
+    spawn: options.spawn,
+    textOnly: true,
+    persistSession: false,
+    maxTurns: 1,
+  });
+  try {
+    await session.start();
+    return await session.readLimits({ timeoutMs: options.timeoutMs ?? 15_000 });
+  } finally {
+    session.kill();
+  }
+}