@inixiative/agent-session 0.1.0 → 0.2.0

package/src/harness-session.ts

@@ -17,7 +17,50 @@
 // 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 =
+  | "text_delta"
+  | "native_status"
   | "session_start"
   | "session_end"
   | "session_compact"
@@ -25,20 +68,63 @@ export type SessionEventKind =
   | "tool_use"
   | "tool_result"
   | "thinking"
+  | "usage"
   | "result"
   | "error";
 
-export interface SessionEvent {
+/** 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";
+  /** 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 +135,43 @@ 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;
+  /** 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;
@@ -94,11 +193,23 @@ 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
 // ---------------------------------------------------------------------------
 
 export interface HarnessSession {
+  /** 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 +220,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 +234,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

@@ -19,3 +19,5 @@ export {
   type CodexSessionConfig,
   type CodexSpawn,
 } from "./codex-session";
+
+export { parseClaudeUsage } from "./claude-usage";

package/src/retained-evidence.ts

@@ -0,0 +1,20 @@
+// Native envelopes are JSON data. Take ownership once, before exposing them to
+// observers, then share deeply frozen evidence across histories and snapshots.
+// Do not traverse/copy the accumulated transcript when a new event arrives.
+const owned = new WeakSet<object>();
+
+export function retainEvidence<T>(value: T): T {
+  if (value === null || typeof value !== "object" || owned.has(value)) return value;
+  const copy = structuredClone(value);
+  const pending: object[] = [copy];
+  while (pending.length) {
+    const item = pending.pop()!;
+    if (owned.has(item)) continue;
+    owned.add(item);
+    for (const nested of Object.values(item)) {
+      if (nested !== null && typeof nested === "object") pending.push(nested);
+    }
+    Object.freeze(item);
+  }
+  return copy;
+}

package/src/turn-state.ts

@@ -0,0 +1,42 @@
+import { SessionTurnError, type SessionAttempt, type SessionEvent, type SessionIdentity, type SessionResult, type SessionTokens } 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); }
+  events: SessionEvent[] = [];
+  content = "";
+  private _tokens?: SessionTokens;
+  get tokens() { return this._tokens; }
+  set tokens(value: SessionTokens | undefined) { this._tokens = retainEvidence(value); }
+  localFailure?: SessionAttempt["localFailure"];
+  rpcSettled = false;
+  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 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;
+    // Usage events are per-request snapshots; the terminal result carries the turn total.
+    if (e.tokens && e.kind !== "usage") this.tokens = e.tokens;
+    return e;
+  }
+}