@demicodes/agent 0.10.3 → 0.11.0

package/README.md

@@ -8,6 +8,8 @@ that the REPL and web UI both consume.
 - `AgentServer` — owns sessions; `server.client()` returns an in-process client.
 - `AgentClient` — `open` / `send` / `steer` / `abort` / `close` / `subscribe`.
 - Transports: in-process, stdio (`@demicodes/agent/stdio`), or WebSocket.
+- Actions accept caller-defined `metadata` that is available to harness and
+  tool contexts without becoming transcript or provider content.
 
 ```ts
 import { AgentServer } from '@demicodes/agent'

package/dist/client-entry.d.mts

@@ -1,4 +1,4 @@
-import { d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandSnapshotLike } from "./transport-Bhf0h9FY.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-D_Awo7zN.mjs";
+import { b as AgentMetadata, d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike } from "./transport-yyfRK0gJ.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C-dQGV-s.mjs";
 import { ProviderSelection } from "@demicodes/provider";
-export { AgentClient, type AgentClientListener, type AgentClientTransport, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandSnapshotLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };
+export { type AgentActionOptions, AgentClient, type AgentClientListener, type AgentClientTransport, type AgentMetadata, type AgentServerTransport, type AgentTransport, type ClientFrame, type ClientSessionEvent, type JsonWebSocket, type ProviderSelection, type ServerFrame, type ShellCommandStatusLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/client-entry.mjs

@@ -1,2 +1,2 @@
-import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-Bod0puog.mjs";
+import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-BjSj3U0I.mjs";
 export { AgentClient, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/index.d.mts

@@ -1,9 +1,40 @@
-import { A as AgentToolInvokeResult, B as DEFAULT_TURN_RETRY_POLICY, C as AgentSessionRestoreParams, D as AgentTool, E as AgentSystemPromptContext, F as CompactionWindow, H as isRetryableCode, I as DrainedTranscriptPatches, L as Transcript, M as SessionEvent, N as SessionEventListener, O as AgentToolContext, P as ToolContinuation, R as TranscriptOptions, S as AgentSessionParams, T as AgentSessionStore, U as resolveRetryPolicy, V as TurnRetryPolicy, W as retryDelayMs, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentReferenceResolveContext, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as ExternalMutationReservation, k as AgentToolInvokeContext, l as ServerFrame, m as AgentDisposeContext, n as AgentServerTransport, o as ClientFrame, p as AbortTarget, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandSnapshotLike, v as AgentLifecycleEvent, w as AgentSessionSnapshot, x as AgentSessionOptions, y as AgentPromptContext, z as estimateTranscriptBlockTokens } from "./transport-Bhf0h9FY.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-D_Awo7zN.mjs";
-import { BashEnvironment, BashEnvironmentOptions, Host, ShellCommandSnapshot } from "@demicodes/shell";
+import { A as AgentTool, B as TranscriptOptions, C as AgentSessionCheckpoint, D as AgentSessionRestoreParams, E as AgentSessionParams, F as SessionEvent, G as resolveRetryPolicy, H as DEFAULT_TURN_RETRY_POLICY, I as SessionEventListener, K as retryDelayMs, L as CompactionWindow, M as AgentToolInvokeContext, N as AgentToolInvokeResult, O as AgentSessionStore, P as ExternalMutationReservation, R as DrainedTranscriptPatches, S as AgentReferenceResolveContext, T as AgentSessionOptions, U as TurnRetryPolicy, V as estimateTranscriptBlockTokens, W as isRetryableCode, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentMetadata, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as AgentToolContext, k as AgentSystemPromptContext, l as ServerFrame, m as AgentDisposeContext, n as AgentServerTransport, o as ClientFrame, p as AbortTarget, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike, v as AgentHostContext, w as AgentSessionCloneParams, x as AgentPromptContext, y as AgentLifecycleEvent, z as TranscriptLog } from "./transport-yyfRK0gJ.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C-dQGV-s.mjs";
+import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
-import { Block, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
-
+import { Block, Model, ModelMediaKind, ModelSelection, ProviderErrorDiagnostics, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
+//#region src/recovery.d.ts
+/**
+ * Where re-inference must restart after a turn failed to finish.
+ *
+ * `cut` is the index from which blocks are discardable; `isFullRerun` is true when
+ * that reaches all the way back to the user turn, meaning the turn produced nothing
+ * and can simply be run again.
+ */
+interface ResumePoint {
+  cut: number;
+  isFullRerun: boolean;
+}
+/**
+ * Finds how far back an unfinished turn can be unwound before re-inferring.
+ *
+ * This is the single decision behind both recovery paths. A transient provider
+ * failure and a human asking to continue a dead round ask the same question — how
+ * do we finish this turn — and the answer depends only on what has already left
+ * the process, never on which of the two asked or on how the turn died.
+ */
+declare function findResumePoint(blocks: readonly Block[]): ResumePoint;
+//#endregion
+//#region src/provider-stream-error.d.ts
+/** Error carrying a provider stream's normalized code and bounded diagnostics. */
+declare class ProviderStreamError extends Error {
+  readonly code: string | null;
+  readonly diagnostics: ProviderErrorDiagnostics | undefined;
+  constructor(message: string, code: string | null, diagnostics?: ProviderErrorDiagnostics);
+}
+/** Whether an error is a provider stream error reporting the context window was exceeded. */
+declare function isContextLengthExceeded(error: unknown): boolean;
+//#endregion
 //#region src/session.d.ts
 type ActiveTurnPhase = 'provider_streaming' | 'tool_executing' | 'compacting' | 'finalizing';
 declare class AgentSession<State> {
@@ -20,6 +51,7 @@ declare class AgentSession<State> {
   private readonly listeners;
   private readonly pendingActions;
   private readonly queued;
+  get modelSelection(): ModelSelection;
   private readonly transcriptLog;
   private readonly agentState;
   private currentPhase;
@@ -29,6 +61,7 @@ declare class AgentSession<State> {
   private activeTurnId;
   private activeTurnPhase;
   private activeProviderRun;
+  private activeMetadata;
   private readonly steerQueue;
   private readonly yields;
   private readonly compaction;
@@ -40,19 +73,50 @@ declare class AgentSession<State> {
   private persistTimer;
   private persistDirty;
   /**
-   * Restores a session from a snapshot. Ownership of the snapshot (including
+   * Restores a session from a checkpoint. Ownership of the checkpoint (including
    * `state`) transfers to the session: the caller must not mutate it afterwards.
    * Passing state by reference — not a clone — lets the caller share the same
    * object with harness closures (host/commands), keeping one live state.
    */
-  static fromSnapshot<State>(params: AgentSessionRestoreParams<State>, options?: AgentSessionOptions<State>): AgentSession<State>;
+  static fromCheckpoint<State>(params: AgentSessionRestoreParams<State>, options?: AgentSessionOptions<State>): AgentSession<State>;
   constructor(params: AgentSessionParams<State>, options?: AgentSessionOptions<State>);
   send(content: UserContentBlock[], options?: {
     id?: string;
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  /**
+   * Creates an isolated session from a point-in-time copy.
+   *
+   * Model, transcript, and state are copied by default. Runtime configuration
+   * (harness runtime, cwd) is shared unless overridden. The provider is an
+   * independent runtime from `AgentProvider.clone()` unless `provider` is
+   * supplied. Parent persistence store is never inherited.
+   */
+  clone(overrides?: AgentSessionCloneParams<State>): AgentSession<State>;
+  /**
+   * Discards the whole latest turn and runs it again from the user's input.
+   *
+   * This is "regenerate": it is only meaningful when the caller wants a different
+   * answer to the same question and knows the turn's effects can be repeated. It is
+   * NOT the way to recover a failed turn — use `resume`, which unwinds only as far
+   * as is safe.
+   */
+  retry(options?: {
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  /**
+   * Finishes a turn that did not finish, after an abort or a terminal provider
+   * error. Unwinds to the turn's resume point — dropping the failed attempt's
+   * leftovers, keeping everything that already left the process — and re-infers
+   * from there. Callers do not choose the granularity and do not need to know how
+   * the turn died.
+   */
+  resume(options?: {
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  compact(options?: {
+    metadata?: AgentMetadata;
   }): Promise<void>;
-  retry(): Promise<void>;
-  resume(): Promise<void>;
-  compact(): Promise<void>;
   steer(content: UserContentBlock[], options?: {
     id?: string;
   }): Promise<void>;
@@ -71,14 +135,14 @@ declare class AgentSession<State> {
    */
   updateModel(provider: AgentProvider | null, model: ModelSelection): void;
   abort(): Promise<AbortResult>;
-  scheduleYieldWakeup(durationMs: number): AgentToolInvokeResult;
+  scheduleYieldWakeup(durationMs: number, metadata?: AgentMetadata | null): AgentToolInvokeResult;
   waitUntilDone(): Promise<void>;
   /**
    * Tears the session down: aborts any in-flight turn and releases provider-held resources
    * (e.g. a long-lived CLI subprocess). Called when the owning connection closes.
    */
   dispose(): Promise<void>;
-  transcript(): Transcript;
+  transcript(): TranscriptLog;
   state(): State;
   id(): string;
   phase(): SessionPhase;
@@ -116,6 +180,13 @@ declare class AgentSession<State> {
   private executeSend;
   private resolveReferences;
   private executeRetry;
+  /**
+   * Finishes an unfinished turn. Unwinds to its resume point — dropping the failed
+   * attempt's leftovers, keeping everything that already left the process — and
+   * re-infers from there. When the whole turn turns out to be discardable this is
+   * a plain rerun, which spares the model a continuation boundary attached to a
+   * stub of its own aborted output.
+   */
   private executeResume;
   private providerEvents;
   private promptContext;
@@ -134,11 +205,11 @@ declare class AgentSession<State> {
   /**
    * Publishes transcript changes: drains the mutation journal into a patch
    * event (O(changed content), not O(transcript)) and schedules a throttled
-   * snapshot write. Boundaries (action end, abort, dispose) flush the write.
+   * checkpoint write. Boundaries (action end, abort, dispose) flush the write.
    */
   private commitTranscript;
   private schedulePersist;
-  private persistSnapshot;
+  private persistCheckpoint;
   private flushPersist;
   private emit;
   private resolveIdleWaiters;
@@ -164,18 +235,18 @@ interface AgentServerSessionOptions {
   persistIntervalMs?: number;
 }
 /**
- * Host-agnostic hook invoked once per `open()` before BashEnvironment is built.
+ * Host-agnostic hook invoked before each resolved Host's BashEnvironment is built.
  * LocalHost uses this to inject PATH / env for the command bridge; AgentServer
  * itself does not know about UDS, shims, or bin directories.
  */
-interface PrepareSessionShellContext {
+interface PrepareShellContext {
   agentSessionId: string;
   host: Host;
   commandNames: readonly string[];
   /** Shell options from AgentServer construction (before this hook). */
   shell: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
 }
-type PrepareSessionShell = (ctx: PrepareSessionShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
+type PrepareShell = (ctx: PrepareShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
 interface AgentServerOptions {
   agent: AgentHarness<unknown>;
   providers: Provider[];
@@ -185,7 +256,7 @@ interface AgentServerOptions {
    * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
    * command bridge wiring lives in `@demicodes/host-local`, not here.
    */
-  prepareSessionShell?: PrepareSessionShell;
+  prepareShell?: PrepareShell;
 }
 interface AgentTransportBinding {
   close(): Promise<void>;
@@ -199,12 +270,18 @@ interface RunCommandLineOptions {
 /** Result of {@link AgentServer.runCommandLine}. */
 interface RunCommandLineResult {
   exitCode: number;
+  /** UTF-8 text, or base64 when `stdoutEncoding` is 'base64'. */
   stdout: string;
+  stdoutEncoding?: 'base64';
   stderr: string;
 }
-declare class RunCommandLineSessionNotFoundError extends Error {
-  readonly agentSessionId: string;
-  constructor(agentSessionId: string);
+declare class RunCommandLineShellNotFoundError extends Error {
+  readonly shellId: string;
+  constructor(shellId: string);
+}
+declare class RunCommandLineCommandNotRegisteredError extends Error {
+  readonly commandName: string;
+  constructor(commandName: string);
 }
 declare class RunCommandLineTimeoutError extends Error {
   readonly commandId: string;
@@ -217,7 +294,7 @@ declare class AgentServer {
   private readonly providers;
   private readonly shellOptions;
   private readonly sessionOptions;
-  private readonly prepareSessionShell;
+  private readonly prepareShell;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
@@ -229,12 +306,15 @@ declare class AgentServer {
    * Transport-agnostic: callers (e.g. LocalHost command bridge) supply their
    * own IPC; AgentServer only knows how to exec against the open session shell.
    */
-  runCommandLine(agentSessionId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
+  runCommandLine(shellId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
 }
 //#endregion
 //#region src/tools.d.ts
 interface StandardAgentToolOptions<State = unknown> {
-  environment: BashEnvironment;
+  environment: BashEnvironment | ((ctx: AgentToolInvokeContext<State>, handle: {
+    shellId?: string;
+    commandId?: string;
+  }) => BashEnvironment | Promise<BashEnvironment>);
   scheduleYield(ctx: AgentToolInvokeContext<State>, durationMs: number): AgentToolInvokeResult;
 }
 declare function createStandardAgentTools<State = unknown>(options: StandardAgentToolOptions<State>): AgentTool<State>[];
@@ -242,10 +322,56 @@ interface ShellToolResultOptions {
   includePreview?: boolean;
   previewBudgetTokens?: number;
   exposeCommandHandle?: boolean;
+  /** Model receiving this result; gates binary-stream media attachment. */
+  model?: Model;
+  /** Per-modality byte caps on attached media; unset modalities keep the defaults. */
+  maxMediaBytes?: Partial<Record<ModelMediaKind, number>>;
 }
+/**
+ * How many bytes of each modality a tool may hand to the model.
+ *
+ * One number cannot serve both, because bytes buy wildly different amounts of
+ * context per modality — measured against a frontier model, a KiB of video
+ * costs ~2 tokens where a KiB of image costs ~50. A cap generous enough to show
+ * a five-minute clip would let a single still eat a six-figure token budget.
+ *
+ * image (4 MiB): well past any sane still — a 4000x3000 PNG lands under it — so
+ *   crossing this line is a mistake, not a use case.
+ * video (16 MiB): roughly ten minutes at a viewing-grade encoding, and
+ *   deliberately under the ~20 MB inline-payload ceiling the major APIs enforce.
+ *   A larger cap buys no reach, only a rejection further downstream where the
+ *   reason is harder to read.
+ *
+ * Bytes are a proxy, not a budget: for video they track cost reasonably at a
+ * fixed encoding, but an image's real driver is its pixel dimensions.
+ */
+declare const DEFAULT_MAX_MEDIA_BYTES: Record<ModelMediaKind, number>;
 declare function shellPreviewBudgetTokens(contextWindow: number): number;
-declare function toShellToolResult(result: ShellCommandSnapshot, toolCallId?: string, options?: ShellToolResultOptions): AgentToolInvokeResult;
-declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandSnapshot, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
-declare function shellCommandHandleRequired(result: ShellCommandSnapshot, budgetTokens: number): boolean;
+declare function toShellToolResult(result: ShellCommandStatus, options?: ShellToolResultOptions): AgentToolInvokeResult;
+/** Character budget for a shell view's render window (tail-biased). */
+declare const SHELL_VIEW_MAX_CHARS = 32768;
+/**
+ * Bounded UI view of a shell command stored on the tool_call block. Full
+ * output lives in the command artifact (`/@/commands/<commandId>/…`), keyed by
+ * `commandId`; the view carries only the tail render window and never embeds
+ * raw or base64 bytes.
+ */
+interface ShellToolView {
+  kind: 'shell';
+  status: 'running' | 'exited' | 'aborted';
+  shellId: string;
+  commandId: string;
+  exitCode?: number;
+  runningMs: number;
+  idleMs: number;
+  /** Tail of the merged output, capped at SHELL_VIEW_MAX_CHARS. */
+  chunks: ShellOutputChunk[];
+  /** True when chunks were capped; the artifact has the full output. */
+  viewTruncated: boolean;
+  audit?: BashAuditEvent[];
+  commandMeta?: CommandMetadataRecord[];
+}
+declare function finishShellToolResult<State>(environment: BashEnvironment, result: ShellCommandStatus, ctx: AgentToolInvokeContext<State>): Promise<AgentToolInvokeResult>;
+declare function shellCommandHandleRequired(result: ShellCommandStatus, budgetTokens: number): boolean;
 //#endregion
-export { AbortResult, AbortTarget, ActiveTurnPhase, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentLifecycleEvent, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionSnapshot, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareSessionShell, PrepareSessionShellContext, RunCommandLineOptions, RunCommandLineResult, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, ServerFrame, SessionEvent, SessionEventListener, ShellCommandSnapshotLike, ShellToolResultOptions, StandardAgentToolOptions, ToolContinuation, Transcript, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionCloneParams, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };