@inixiative/agent-session 0.6.7 → 0.7.0

package/README.md

@@ -50,6 +50,12 @@ session.kill();
   refused before a byte is written.
 - **fork / resume / interrupt** and pre-send hooks (rewrite the outgoing
   message — e.g. inject just-in-time context per turn).
+- **A resume whose native conversation is not found is typed.** Claude finding no transcript
+  ("No conversation found with session ID": cleaned up, deleted, or under another project
+  directory or config home) and Codex finding no rollout ("no rollout found for thread id") both
+  raise `NativeBindingMissingError` (`nativeBindingMissing(error)` finds it behind a turn error,
+  with the `cwd` the lookup ran in). No turn ran, so the attempt settles as a no-send instead of
+  uncertain native work, and the caller can start fresh from its own record.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "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",
@@ -36,18 +36,18 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.5.4"
+    "@inixiative/json-rules": "^3.16.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.105",
-    "@types/bun": "1.4.2",
+    "@inixiative/config": "^0.5.166",
+    "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"
   },
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.4",
   "engines": {
-    "bun": ">=1.4.2"
+    "bun": ">=1.4.4"
   },
   "repository": {
     "type": "git",

package/src/claude-code-session.ts

@@ -59,11 +59,12 @@ import type {
   SessionSendOptions,
   SessionTokens,
   SubagentLifecycle,
+  TaskLifecycle,
   ToolDecision,
   ToolGate,
   ToolRequest,
 } from './harness-session';
-import { sendableImages } from './harness-session';
+import { NativeBindingMissingError, sendableImages } from './harness-session';
 
 // Re-export types so existing import paths keep working
 export type {
@@ -354,6 +355,8 @@ export class ClaudeCodeSession implements HarnessSession {
   // so we know the concrete types at runtime.
   private _proc: PipedSubprocess | null = null;
   private _stderr = '';
+  /** The stderr reader of the running process; awaited (capped) before stderr is interpreted. */
+  private _stderrDone: Promise<void> = Promise.resolve();
 
   // -- Session state --
   /**
@@ -383,6 +386,8 @@ export class ClaudeCodeSession implements HarnessSession {
   private _seenBoundaries = new Set<string>();
   /** Task ids whose task_started was a subagent (local_agent); later task frames carry no type. */
   private _agentTasks = new Set<string>();
+  /** Task ids whose task_started was another task type (a background shell, a monitor): id → type. */
+  private _otherTasks = new Map<string, string>();
 
   // -- Turn queue --
   private _queue: QueuedTurn[] = [];
@@ -560,7 +565,7 @@ export class ClaudeCodeSession implements HarnessSession {
     // Background readers — run for session lifetime (don't await)
     const proc = this._proc;
     const stdoutDone = this._readStdout(proc);
-    this._readStderr();
+    this._stderrDone = this._readStderr();
 
     // Monitor process exit for cleanup
     // The process read its base context file at startup; it goes when the process does.
@@ -577,7 +582,7 @@ export class ClaudeCodeSession implements HarnessSession {
       const errMsg = this._stderr.trim()
         ? `Process exited (code ${code}): ${this._stderr.trim().slice(0, 500)}`
         : `Process exited with code ${code}`;
-      this._rejectInflight(new Error(errMsg));
+      this._rejectInflight((await this._settleMissing(errMsg)) ?? new Error(errMsg));
       this._rejectQueue(new Error('Session ended'));
       this._rejectControl(new Error('Session ended'));
       this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
@@ -616,6 +621,8 @@ export class ClaudeCodeSession implements HarnessSession {
         );
       } catch (error) {
         this.kill();
+        const missing = this._missingBinding((error as Error).message);
+        if (missing) throw missing;
         throw new Error(
           `${this._toolGate ? 'Tool gate' : 'Extension'} registration failed: ${(error as Error).message}`,
         );
@@ -630,6 +637,41 @@ export class ClaudeCodeSession implements HarnessSession {
     }
   }
 
+  /**
+   * The CLI refused to resume because the transcript is gone (Claude Code's cleanup of
+   * `~/.claude/projects`, or a deleted file): it says so and exits before reading a turn.
+   */
+  private _missingBinding(detail: string): NativeBindingMissingError | undefined {
+    const binding = this._externalSessionId;
+    if (!binding) return undefined;
+    const marker = `No conversation found with session ID: ${binding}`;
+    return this._stderr.includes(marker) || detail.includes(marker)
+      ? new NativeBindingMissingError('claude-code', binding, marker, this._cwd)
+      : undefined;
+  }
+
+  /**
+   * After the process ended: was the binding missing? stderr is read first (capped), since the
+   * marker is there. A turn written to a CLI that never loaded the conversation (no `system/init`,
+   * no terminal) could not run: it settles as a no-send rather than uncertain native work.
+   */
+  private async _settleMissing(detail: string): Promise<NativeBindingMissingError | undefined> {
+    await Promise.race([this._stderrDone, Bun.sleep(250)]);
+    const missing = this._missingBinding(detail);
+    const a = this._inflight?.evidence;
+    if (
+      missing &&
+      a &&
+      a.nativeOutcome === 'unknown' &&
+      !a.events.some((event) => {
+        const raw = event.raw as { type?: unknown; subtype?: unknown } | undefined;
+        return raw?.type === 'system' && raw.subtype === 'init';
+      })
+    )
+      a.dispatch = 'not-dispatched';
+    return missing;
+  }
+
   private _detachExtension(reason: string): void {
     try {
       this._extension?.detach(reason);
@@ -790,6 +832,11 @@ export class ClaudeCodeSession implements HarnessSession {
     return turn.evidence.nativeOutcome === 'unknown' ? 'unacknowledged' : 'acknowledged';
   }
 
+  /** Stop a background task via the CLI control protocol (`stop_task`); its end comes as lifecycle. */
+  async stopTask(taskId: string, opts?: { timeoutMs?: number }): Promise<void> {
+    await this._controlRequest({ subtype: 'stop_task', task_id: taskId }, opts?.timeoutMs ?? 5_000);
+  }
+
   /** Account limits via the CLI control protocol (`get_usage`); no model turn. Requires a started session. */
   async readLimits(opts?: { timeoutMs?: number }): Promise<LimitSnapshot | undefined> {
     const response = await this._controlRequest(
@@ -1065,14 +1112,12 @@ export class ClaudeCodeSession implements HarnessSession {
       if (buffer.trim() && (this._proc === proc || !this._proc)) {
         this._processLine(buffer);
       }
-      if (this._proc === proc && this._alive)
-        this._transportFailure(
-          new Error(
-            this._stderr.trim()
-              ? `Native stdout closed: ${this._stderr.trim().slice(0, 500)}`
-              : 'Native stdout closed',
-          ),
-        );
+      if (this._proc === proc && this._alive) {
+        const detail = this._stderr.trim()
+          ? `Native stdout closed: ${this._stderr.trim().slice(0, 500)}`
+          : 'Native stdout closed';
+        this._transportFailure((await this._settleMissing(detail)) ?? new Error(detail));
+      }
     } catch (err) {
       if (this._proc === proc) this._transportFailure(err as Error);
     }
@@ -1260,6 +1305,20 @@ export class ClaudeCodeSession implements HarnessSession {
         ? raw.parent_tool_use_id
         : undefined;
     const lifecycle = this._subagentLifecycle(raw);
+    // A background task (a shell, a monitor) outlives its turn like a subagent: never an admission's.
+    const task = lifecycle || parentToolUseId ? undefined : this._taskLifecycle(raw);
+    if (task) {
+      this._emit({
+        kind: 'task',
+        timestamp: Date.now(),
+        task,
+        raw,
+        correlation: 'unknown',
+        unattributedReason: 'task',
+        nativeSessionId: typeof raw.session_id === 'string' ? raw.session_id : undefined,
+      });
+      return;
+    }
     if (parentToolUseId || lifecycle) {
       const message = raw.message as Record<string, unknown> | undefined;
       const events: SessionEvent[] = lifecycle
@@ -1632,6 +1691,40 @@ export class ClaudeCodeSession implements HarnessSession {
     return claudeSubagentLifecycle(msg, phase, taskId);
   }
 
+  /**
+   * A Claude Code `system` task frame for a task that is not a subagent (`task_type` other than
+   * `local_agent`), as lifecycle. Later phases carry no task type: the session remembers it.
+   */
+  private _taskLifecycle(msg: Record<string, unknown>): TaskLifecycle | undefined {
+    if (msg.type !== 'system' || typeof msg.subtype !== 'string') return undefined;
+    const phase = CLAUDE_TASK_PHASES[msg.subtype];
+    const taskId = typeof msg.task_id === 'string' && msg.task_id ? msg.task_id : undefined;
+    if (!phase || !taskId) return undefined;
+    if (phase === 'started') {
+      if (typeof msg.task_type !== 'string' || msg.task_type === 'local_agent') return undefined;
+      this._otherTasks.set(taskId, msg.task_type);
+    }
+    const taskType = this._otherTasks.get(taskId);
+    if (!taskType) return undefined;
+    if (phase === 'ended') this._otherTasks.delete(taskId);
+    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    const patch =
+      msg.patch && typeof msg.patch === 'object' && !Array.isArray(msg.patch)
+        ? (msg.patch as Record<string, unknown>)
+        : undefined;
+    const status = text(msg.status) ?? text(patch?.status);
+    return {
+      phase,
+      taskId,
+      taskType,
+      ...(text(msg.tool_use_id) ? { toolUseId: text(msg.tool_use_id) } : {}),
+      ...(text(msg.description) ? { description: text(msg.description) } : {}),
+      ...(status ? { status } : {}),
+      ...(text(msg.reason) ? { reason: text(msg.reason) } : {}),
+      ...(text(msg.summary) ? { summary: text(msg.summary) } : {}),
+    };
+  }
+
   private _classify(msg: Record<string, unknown>, parentToolUseId?: string): SessionEvent[] {
     return this._classifyFrame(msg).map((event) =>
       parentToolUseId ? { ...event, parentToolUseId } : event,

package/src/codex-session.ts

@@ -27,7 +27,7 @@ import type {
   SessionResult,
   ToolGate,
 } from './harness-session';
-import { sendableImages } from './harness-session';
+import { NativeBindingMissingError, sendableImages } from './harness-session';
 
 // Re-export types so importers can stay on one path (mirrors claude-code-session).
 export type {
@@ -592,8 +592,11 @@ export class CodexAppServerSession implements HarnessSession {
 
   private _releaseKnownTurn(): void {
     const a = this._inflight?.evidence;
-    if (!a || !this._canReleaseAttempt(a) || a.nativeOutcome === 'unknown') return;
-    this._turns++;
+    if (!a) return;
+    // Refused before `turn/start` was written: nothing native is outstanding.
+    const noSend = a.dispatch === 'not-dispatched' && a.localOutcome === 'rejected';
+    if (!noSend && (!this._canReleaseAttempt(a) || a.nativeOutcome === 'unknown')) return;
+    if (!noSend) this._turns++;
     this._inflight = null;
     this._processNextTurn();
   }
@@ -1222,8 +1225,9 @@ export class CodexAppServerSession implements HarnessSession {
     if (!this._threadReady) {
       const binding = this._externalSessionId;
       const method = binding ? 'thread/resume' : 'thread/start';
-      const response = object(
-        await this._rpcRequest(method, {
+      let resumed: unknown;
+      try {
+        resumed = await this._rpcRequest(method, {
           ...(binding ? { threadId: binding } : {}),
           model: this._model,
           cwd: this._cwd,
@@ -1232,8 +1236,22 @@ export class CodexAppServerSession implements HarnessSession {
           ...(this._gated ? { approvalsReviewer: 'user' } : {}),
           sandbox: this._sandbox,
           ...(this._options.config ? { config: this._options.config } : {}),
-        }),
-      );
+        });
+      } catch (error) {
+        // The rollout is gone (Codex's own cleanup, or deleted). Codex answered that no thread
+        // exists, so no turn could run and none was written: a settled no-send, not uncertain
+        // native work. Any other failure here keeps its outcome unknown.
+        if (binding && /^no rollout found for thread id\b/i.test((error as Error).message ?? '')) {
+          a.dispatch = 'not-dispatched';
+          throw new NativeBindingMissingError(
+            'codex-app-server',
+            binding,
+            (error as Error).message,
+          );
+        }
+        throw error;
+      }
+      const response = object(resumed);
       const thread = object(response?.thread),
         id = thread?.id;
       if (typeof id !== 'string' || !id || (binding && id !== binding))

package/src/harness-session.ts

@@ -79,6 +79,35 @@ export class SessionTurnError extends Error {
   }
 }
 
+/**
+ * The native binding a session was told to resume was not found by the runtime, from this
+ * session's cwd and config home: Claude found no transcript ("No conversation found with session
+ * ID": cleaned up, deleted, or kept under another project directory or `CLAUDE_CONFIG_DIR`), or
+ * Codex found no rollout ("no rollout found for thread id": deleted, or under another
+ * `CODEX_HOME`). No turn ran. The caller decides what comes next, typically a fresh session seeded
+ * from its own record of the conversation; `cwd` says where the lookup was made.
+ */
+export class NativeBindingMissingError extends Error {
+  constructor(
+    readonly runtime: 'claude-code' | 'codex-app-server',
+    readonly binding: string,
+    message: string,
+    readonly cwd?: string,
+  ) {
+    super(message);
+    this.name = 'NativeBindingMissingError';
+  }
+}
+
+/** The missing-binding error behind a session error, if any (it may ride as a turn error's cause). */
+export function nativeBindingMissing(error: unknown): NativeBindingMissingError | undefined {
+  for (let current = error, depth = 0; current && depth < 5; depth++) {
+    if (current instanceof NativeBindingMissingError) return current;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return undefined;
+}
+
 export type SessionEventKind =
   | 'text_delta'
   | 'native_status'
@@ -93,7 +122,8 @@ export type SessionEventKind =
   | 'rate_limit'
   | 'result'
   | 'error'
-  | 'subagent';
+  | 'subagent'
+  | 'task';
 
 /**
  * A subagent's lifecycle as the native runtime reports it (kind `subagent`). Claude Code: its
@@ -125,6 +155,26 @@ export interface SubagentLifecycle {
   };
 }
 
+/**
+ * A background task that is not a subagent (kind `task`): Claude Code's `system` task frames for a
+ * background shell (`local_bash`), a monitor or a workflow. Like a subagent it can outlive the turn
+ * that started it, so its events belong to no admission (`unattributedReason: "task"`).
+ */
+export interface TaskLifecycle {
+  readonly phase: 'started' | 'progress' | 'updated' | 'ended';
+  /** The native task id (the id the agent's own task tools name). */
+  readonly taskId: string;
+  /** The runtime's task type, e.g. `local_bash`. */
+  readonly taskType: string;
+  /** The tool call that started it, in the session's stream (its command is that call's input). */
+  readonly toolUseId?: string;
+  readonly description?: string;
+  /** The native status at the end (completed, failed, stopped, killed). */
+  readonly status?: string;
+  readonly reason?: string;
+  readonly summary?: string;
+}
+
 /** 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.
@@ -162,7 +212,8 @@ export interface SessionEvent extends SessionIdentity {
     | 'unmatched-tool'
     | 'malformed-tool'
     | 'account-status'
-    | 'subagent';
+    | 'subagent'
+    | 'task';
   /** Local transport observation, not a native terminal acknowledgment. */
   readonly transportOutcome?: SessionAttempt['transportOutcome'];
   readonly nativeOutcome?: NativeOutcome;
@@ -214,6 +265,8 @@ export interface SessionEvent extends SessionIdentity {
   readonly parentToolUseId?: string;
   /** A subagent's lifecycle (kind `subagent`). */
   readonly subagent?: SubagentLifecycle;
+  /** A background task's lifecycle (kind `task`). */
+  readonly task?: TaskLifecycle;
 }
 
 /** Result of a single send() — the turn's content plus all classified events. */
@@ -369,6 +422,11 @@ export interface HarnessSession {
   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>;
+  /**
+   * Stop one background task (a `task` lifecycle's `taskId`) through the runtime's own control
+   * channel. Its end arrives as the task's `ended` lifecycle. Claude Code: the `stop_task` request.
+   */
+  stopTask?(taskId: string, opts?: { timeoutMs?: number }): Promise<void>;
   /** One immutable admission snapshot, without copying unrelated session history. */
   inspectAttempt?(admissionId: string): SessionAttempt | undefined;
   readonly admissionProtocol?: 'prewrite-v1';