@inixiative/agent-session 0.1.0 → 0.3.0

package/src/harness-session.ts

@@ -10,35 +10,154 @@
 // 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
 // ---------------------------------------------------------------------------
 
+/** IDs are native only when observed. admissionId is generated locally, never a native turn ID. */
+export interface SessionIdentity {
+  readonly admissionId?: string;
+  readonly nativeSessionId?: string;
+  readonly threadId?: string;
+  readonly turnId?: string;
+  readonly itemId?: string;
+  readonly callId?: string;
+  readonly messageId?: string;
+  readonly rpcRequestId?: number;
+  readonly correlation?: 'native-turn' | 'ordered-stream' | 'unknown';
+}
+export type NativeOutcome = 'unknown' | 'completed' | 'failed';
+export interface NativeTerminal {
+  readonly type: string;
+  readonly eventId?: string;
+  readonly turnId?: string;
+  readonly subtype?: string;
+  readonly reason?: string;
+  readonly apiErrorStatus?: number;
+}
+export interface SessionAttempt extends SessionIdentity {
+  readonly nativeOutcome: NativeOutcome;
+  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 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';
+  }
+  get attempt(): SessionAttempt {
+    return this.evidence();
+  }
+}
+
 export type SessionEventKind =
-  | "session_start"
-  | "session_end"
-  | "session_compact"
-  | "text"
-  | "tool_use"
-  | "tool_result"
-  | "thinking"
-  | "result"
-  | "error";
-
-export interface SessionEvent {
+  | '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.
+ * Missing optional counters mean the runtime did not report them.
+ */
+export interface SessionTokens {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cacheWrite5m?: number;
+  cacheWrite1h?: number;
+  thinking?: number;
+  /** Original provider usage, including tags and future fields. Never summed. */
+  providerUsage?: Readonly<Record<string, unknown>>;
+}
+
+export interface SessionEvent extends SessionIdentity {
+  /**
+   * Session-history evidence excluded from admission results and state transitions.
+   * "session-configuration": a native lifecycle/configuration envelope (Claude system/init)
+   * retained with its binding; it belongs to the session, never to an admission, and a
+   * 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'
+    | 'account-status';
+  /** Local transport observation, not a native terminal acknowledgment. */
+  readonly transportOutcome?: SessionAttempt['transportOutcome'];
+  readonly nativeOutcome?: NativeOutcome;
+  readonly terminal?: NativeTerminal;
   readonly kind: SessionEventKind;
   readonly timestamp: number;
   /** Text content (for text, thinking, result, error). */
   readonly text?: string;
   /** Tool name (for tool_use). */
   readonly toolName?: string;
+  /** Native MCP invocation identity, separate from call ID and SDK request IDs.
+   * Display name is mcp__<server>__<tool>; use these fields for exact comparisons. */
+  readonly toolServer?: string;
+  readonly toolMethod?: string;
   /** Tool input arguments (for tool_use). */
   readonly toolInput?: Record<string, unknown>;
   /** Tool output (for tool_result). */
   readonly toolOutput?: string;
+  /** Public text content is retained; unsupported/non-text result payload is omitted. */
+  readonly toolOutputOmitted?: boolean;
+  /** Exact public tool names from `tool_reference` result blocks (tool search), in order,
+   * duplicates preserved; a separately owned guard judges ownership. Absent when none. */
+  readonly toolReferences?: readonly string[];
+  /** Public type labels of omitted non-text result blocks, in first-seen order; unknown or
+   * malformed shapes are "unsupported". Present only when toolOutputOmitted is true. */
+  readonly toolOutputOmittedTypes?: readonly string[];
+  readonly toolInputOmitted?: string;
   /** Whether the tool call failed (for tool_result). */
   readonly toolError?: boolean;
   /** Compaction source runtime (for session_compact): "claude-code" | "codex" | etc. */
@@ -49,30 +168,45 @@ export interface SessionEvent {
    * this is NOT the Foundry thread ID. A SessionAdapter maps between the two.
    */
   readonly externalSessionId?: string;
-  /** Token usage (for result). */
-  readonly tokens?: { input: number; output: number };
-  /** Raw message from the stream (for Oracle introspection). */
+  /** 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 {
+export interface SessionResult extends SessionIdentity {
+  readonly localOutcome?: SessionAttempt['localOutcome'];
+  readonly transportOutcome?: SessionAttempt['transportOutcome'];
+  readonly rpcOutcome?: SessionAttempt['rpcOutcome'];
+  readonly nativeOutcome?: NativeOutcome;
+  readonly terminal?: NativeTerminal;
   readonly content: string;
   readonly events: readonly SessionEvent[];
-  readonly tokens?: { input: number; output: number };
+  readonly tokens?: SessionTokens;
   /** The runtime's native session ID. See SessionEvent.externalSessionId. */
   readonly externalSessionId?: string;
 }
 
 /** Full session record for Oracle evaluation. */
+export interface SessionDiagnostics {
+  /** Counts only: observer exception messages/objects are never retained. */
+  readonly observerFailures: { readonly synchronous: number; readonly asynchronous: number };
+}
 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';
   /** The runtime's native session ID. See SessionEvent.externalSessionId. */
   readonly externalSessionId?: string;
   readonly events: readonly SessionEvent[];
   readonly startedAt: number;
   readonly endedAt?: number;
   readonly turns: number;
-  readonly totalTokens: { input: number; output: number };
+  readonly totalTokens: SessionTokens;
   readonly toolCalls: number;
   readonly toolResults: number;
   readonly errors: number;
@@ -90,15 +224,39 @@ 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;
+  /** Required ownership registration, not an observer. Rejection prevents the native write. */
+  onAdmission?: (attempt: SessionAttempt) => void | Promise<void>;
+}
 
 // ---------------------------------------------------------------------------
 // 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 diagnostics?: SessionDiagnostics;
+  readonly attempts?: readonly SessionAttempt[];
+  readonly accounting?: 'observed-only';
   readonly alive: boolean;
   /**
    * The agent runtime's native session ID — external to Foundry.
@@ -109,13 +267,13 @@ export interface HarnessSession {
   readonly externalSessionId: string | undefined;
   readonly events: readonly SessionEvent[];
   readonly turns: number;
-  readonly totalTokens: Readonly<{ input: number; output: number }>;
+  readonly totalTokens: Readonly<SessionTokens>;
 
   /** Spawn the underlying process. Must be called before send(). */
   start(): Promise<void>;
 
   /** Send a message. Queued if another turn is in-flight. */
-  send(message: string, opts?: { timeout?: number }): Promise<SessionResult>;
+  send(message: string, opts?: SessionSendOptions): Promise<SessionResult>;
 
   /**
    * Fork: create a new (unstarted) session branching from current state.
@@ -123,7 +281,7 @@ export interface HarnessSession {
    */
   fork(opts?: { cwd?: string; baseContext?: string }): HarnessSession;
 
-  /** Interrupt the current in-flight turn (best-effort). */
+  /** Reject the local waiter. No native cancellation acknowledgment is currently implemented. */
   interrupt(): void;
 
   /** Kill the session process and reject any pending turns. */

package/src/index.ts

@@ -1,21 +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";
+} 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 */
+    }
+  }
+}