@inixiative/agent-session 0.6.5 → 0.6.7

package/src/codex-session.ts

@@ -23,9 +23,11 @@ import type {
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
+  SessionImage,
   SessionResult,
   ToolGate,
 } from './harness-session';
+import { 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;
@@ -1209,7 +1214,10 @@ 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;
@@ -1344,7 +1352,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

@@ -266,10 +266,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/index.ts

@@ -13,9 +13,19 @@ export {
 // Claude Code adapter (persistent stream-json session, subscription auth).
 export {
   CLAUDE_TEXT_ONLY_ARGS,
+  type ClaudeAgentDefinition,
   ClaudeCodeSession,
   type ClaudeCodeSessionConfig,
+  type ClaudeSessionExtension,
+  type ClaudeSessionHost,
 } from './claude-code-session';
+export {
+  type ClaudeInSessionConfig,
+  ClaudeInSessionDecisions,
+  IN_SESSION_AGENTS,
+  IN_SESSION_SERVER,
+  type InSessionSetup,
+} from './claude-in-session';
 export { type ClaudePrimedConfig, ClaudePrimedSessions } from './claude-primed';
 export { type ClaudeSubagentConfig, ClaudeSubagentSessions } from './claude-subagents';
 export { parseClaudeUsage } from './claude-usage';

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',
     },