@inixiative/agent-session 0.6.6 → 0.6.8

package/README.md

@@ -44,8 +44,18 @@ session.kill();
   `ANTHROPIC_API_KEY` and authenticates via the CLI's subscription / an
   `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` — works headless and in
   containers.
+- **Images with a turn.** `send(text, { images: [{ mediaType, data }] })` (png, jpeg, gif or
+  webp, base64) where the transport declares `capabilities.images`: Claude gets base64 `image`
+  blocks in the same user message, Codex `image` inputs with a `data:` URL. Anything else is
+  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.6",
+  "version": "0.6.8",
   "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",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.88",
+    "@inixiative/config": "^0.5.118",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-code-session.ts

@@ -54,6 +54,7 @@ import type {
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
+  SessionImage,
   SessionResult,
   SessionSendOptions,
   SessionTokens,
@@ -62,6 +63,7 @@ import type {
   ToolGate,
   ToolRequest,
 } from './harness-session';
+import { NativeBindingMissingError, sendableImages } from './harness-session';
 
 // Re-export types so existing import paths keep working
 export type {
@@ -211,6 +213,7 @@ interface QueuedTurn {
   onAdmission?: SessionSendOptions['onAdmission'];
   evidence: TurnState;
   message: string;
+  images: readonly SessionImage[];
   timeout: number;
   resolve: (result: SessionResult) => void;
   reject: (error: Error) => void;
@@ -351,6 +354,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 --
   /**
@@ -557,7 +562,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.
@@ -574,7 +579,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' });
@@ -613,6 +618,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}`,
         );
@@ -627,6 +634,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);
@@ -671,6 +713,7 @@ export class ClaudeCodeSession implements HarnessSession {
     if (!this._alive) throw new Error('Session ended');
 
     const timeout = opts?.timeout ?? this._defaultTimeout;
+    const images = sendableImages(this.transport, opts?.images);
 
     // Compose pre-send hooks in registration order. Each sees the previous
     // hook's output. Errors in a hook reject the send() — callers should
@@ -686,6 +729,7 @@ export class ClaudeCodeSession implements HarnessSession {
       const turn: QueuedTurn = {
         evidence,
         message: transformed,
+        images,
         timeout,
         resolve,
         reject,
@@ -937,11 +981,18 @@ export class ClaudeCodeSession implements HarnessSession {
     // Wire format validated empirically against claude 2.1.114:
     // {type:"user", message:{role,content:[{type:"text",text}]}}
     // Alternative shapes ({type:"user_message"}, {role,content}) are silently dropped.
+    // Images are Messages API base64 image blocks, ahead of the text they accompany.
     const payload = `${JSON.stringify({
       type: 'user',
       message: {
         role: 'user',
-        content: [{ type: 'text', text: turn.message }],
+        content: [
+          ...turn.images.map((image) => ({
+            type: 'image',
+            source: { type: 'base64', media_type: image.mediaType, data: image.data },
+          })),
+          { type: 'text', text: turn.message },
+        ],
       },
     })}\n`;
     try {
@@ -1053,14 +1104,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);
     }

package/src/codex-session.ts

@@ -23,9 +23,11 @@ import type {
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
+  SessionImage,
   SessionResult,
   ToolGate,
 } 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 {
@@ -153,6 +155,7 @@ interface QueuedTurn {
   onAdmission?: import('./harness-session').SessionSendOptions['onAdmission'];
   evidence: TurnState;
   message: string;
+  images: readonly SessionImage[];
   timeout: number;
   resolve: (result: SessionResult) => void;
   reject: (error: Error) => void;
@@ -455,6 +458,7 @@ export class CodexAppServerSession implements HarnessSession {
     if (!this._alive) throw new Error('Session ended');
 
     const timeout = opts?.timeout ?? this._defaultTimeout;
+    const images = sendableImages(this.transport, opts?.images);
 
     let transformed = message;
     for (const hook of this._beforeSendHooks) {
@@ -473,6 +477,7 @@ export class CodexAppServerSession implements HarnessSession {
       const turn: QueuedTurn = {
         evidence,
         message: transformed,
+        images,
         timeout,
         resolve,
         reject,
@@ -539,7 +544,7 @@ export class CodexAppServerSession implements HarnessSession {
     this._resultText = '';
 
     // Resolves once the native terminal and the turn/start RPC have both settled.
-    this._sendTurn(turn.message)
+    this._sendTurn(turn.message, turn.images)
       .then((tokens) => {
         if (this._inflight !== turn) return;
         turn.evidence.rpcSettled = true;
@@ -587,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();
   }
@@ -1209,13 +1217,17 @@ export class CodexAppServerSession implements HarnessSession {
     this._rpcNotify('initialized');
   }
 
-  private async _sendTurn(message: string): Promise<{ input: number; output: number } | undefined> {
+  private async _sendTurn(
+    message: string,
+    images: readonly SessionImage[],
+  ): Promise<{ input: number; output: number } | undefined> {
     const a = this._inflight!.evidence;
     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,
@@ -1224,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))
@@ -1344,7 +1370,13 @@ export class CodexAppServerSession implements HarnessSession {
     });
     await this._rpcRequest('turn/start', {
       threadId: this._externalSessionId,
-      input: [{ type: 'text', text: message }],
+      input: [
+        { type: 'text', text: message },
+        ...images.map((image) => ({
+          type: 'image',
+          url: `data:${image.mediaType};base64,${image.data}`,
+        })),
+      ],
       ...(this._effort ? { effort: this._effort } : {}),
     });
     await completed; // Native terminal and RPC acknowledgment are both required.

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'
@@ -266,10 +295,47 @@ export type SessionEventHandler = (event: SessionEvent) => void;
  */
 export type BeforeSendHook = (message: string) => string | Promise<string>;
 
+export const SESSION_IMAGE_MEDIA_TYPES = [
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+] as const;
+export type SessionImageMediaType = (typeof SESSION_IMAGE_MEDIA_TYPES)[number];
+
+/** An image sent with a turn's text, where the transport declares `capabilities.images`. */
+export interface SessionImage {
+  readonly mediaType: SessionImageMediaType;
+  /** The image bytes, base64 (no `data:` prefix). */
+  readonly data: string;
+}
+
 export interface SessionSendOptions {
   timeout?: number;
   /** Required ownership registration, not an observer. Rejection prevents the native write. */
   onAdmission?: (attempt: SessionAttempt) => void | Promise<void>;
+  /**
+   * Images sent with the message, in order, as part of the same user turn. Refused (before
+   * anything is written) by a transport without `capabilities.images` and for any other media type.
+   */
+  images?: readonly SessionImage[];
+}
+
+/** Images a send may write: a copy of each, or a refusal naming the first one that is not. */
+export function sendableImages(
+  transport: TransportDescriptor | undefined,
+  images: readonly SessionImage[] | undefined,
+): SessionImage[] {
+  if (!images?.length) return [];
+  if (!transport?.capabilities.images)
+    throw new Error(`Transport "${transport?.kind ?? 'unknown'}" does not accept image input`);
+  return images.map((image, index) => {
+    if (!SESSION_IMAGE_MEDIA_TYPES.includes(image?.mediaType))
+      throw new Error(`Image ${index + 1}: unsupported media type ${String(image?.mediaType)}`);
+    if (typeof image.data !== 'string' || !image.data || /[^A-Za-z0-9+/=]/.test(image.data))
+      throw new Error(`Image ${index + 1}: data must be non-empty base64`);
+    return { mediaType: image.mediaType, data: image.data };
+  });
 }
 
 // ---------------------------------------------------------------------------

package/src/transport.ts

@@ -36,6 +36,8 @@ export interface TransportCapabilities {
   readonly limits: { readonly stream: boolean; readonly poll: boolean };
   /** A tool-free, text-only session can be enforced (decisions). */
   readonly textOnly: boolean;
+  /** send() takes images beside the text (`SessionSendOptions.images`): png, jpeg, gif, webp. */
+  readonly images: 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';
@@ -70,6 +72,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       usage: true,
       limits: { stream: true, poll: true },
       textOnly: true,
+      images: true,
       primed: 'fork',
       billing: 'subscription',
     },
@@ -80,6 +83,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       "interruptNative() and readLimits() use the CLI's stdio control protocol (`interrupt`, `get_usage`).",
       'toolGate: true launches with `--permission-prompt-tool stdio` and registers a PreToolUse callback over the control protocol: onToolRequest() gates see every call (`pre-use`, any mode, bypass included; only a deny counts) and the asks the permission mode raises (`permission`, final).',
       'Rollback (`--resume-session-at`) exists natively but is not wired here.',
+      'Images ride in the same stream-json user message as base64 `image` content blocks, before the text.',
     ],
   },
   'codex-app-server': {
@@ -97,6 +101,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       usage: true,
       limits: { stream: true, poll: true },
       textOnly: false,
+      images: true,
       primed: 'fork',
       billing: 'subscription',
     },
@@ -107,6 +112,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       'appServer.approvalPolicy/sandbox (default never / danger-full-access; `codexPermissions(mode)`) set the thread policy; command and file-change approvals for the owned turn go to onToolRequest() gates (`permission`) and are answered accept/decline. Other server requests are refused (-32601).',
       '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.',
+      'Images go to turn/start as `image` inputs with a `data:` URL, after the text.',
     ],
   },
   'claude-agent-sdk': {
@@ -124,6 +130,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       usage: true,
       limits: { stream: true, poll: false },
       textOnly: true,
+      images: true,
       primed: 'none',
       billing: 'subscription',
     },
@@ -147,6 +154,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       usage: false,
       limits: none,
       textOnly: false,
+      images: false,
       primed: 'none',
       billing: 'subscription',
     },
@@ -169,6 +177,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       usage: false,
       limits: none,
       textOnly: false,
+      images: false,
       primed: 'none',
       billing: 'api',
     },