@demicodes/agent 0.10.2 → 0.10.3

package/README.md

@@ -8,8 +8,6 @@ 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 { 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-BZwi2YZL.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-CZpGt4Py.mjs";
+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 { ProviderSelection } from "@demicodes/provider";
-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 };
+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 };

package/dist/client-entry.mjs

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

package/dist/index.d.mts

@@ -1,40 +1,9 @@
-import { A as AgentToolContext, B as estimateTranscriptBlockTokens, C as AgentSessionCheckpoint, D as AgentSessionStore, E as AgentSessionRestoreParams, F as SessionEventListener, G as retryDelayMs, H as TurnRetryPolicy, I as CompactionWindow, L as DrainedTranscriptPatches, M as AgentToolInvokeResult, N as ExternalMutationReservation, O as AgentSystemPromptContext, P as SessionEvent, R as TranscriptLog, S as AgentReferenceResolveContext, T as AgentSessionParams, U as isRetryableCode, V as DEFAULT_TURN_RETRY_POLICY, W as resolveRetryPolicy, _ 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 AgentToolInvokeContext, k as AgentTool, 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 AgentSessionOptions, x as AgentPromptContext, y as AgentLifecycleEvent, z as TranscriptOptions } from "./transport-BZwi2YZL.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-CZpGt4Py.mjs";
-import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
+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 { AgentProvider, Provider } from "@demicodes/provider";
-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
+import { Block, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
+
 //#region src/session.d.ts
 type ActiveTurnPhase = 'provider_streaming' | 'tool_executing' | 'compacting' | 'finalizing';
 declare class AgentSession<State> {
@@ -51,7 +20,6 @@ declare class AgentSession<State> {
   private readonly listeners;
   private readonly pendingActions;
   private readonly queued;
-  get modelSelection(): ModelSelection;
   private readonly transcriptLog;
   private readonly agentState;
   private currentPhase;
@@ -61,7 +29,6 @@ declare class AgentSession<State> {
   private activeTurnId;
   private activeTurnPhase;
   private activeProviderRun;
-  private activeMetadata;
   private readonly steerQueue;
   private readonly yields;
   private readonly compaction;
@@ -73,41 +40,19 @@ declare class AgentSession<State> {
   private persistTimer;
   private persistDirty;
   /**
-   * Restores a session from a checkpoint. Ownership of the checkpoint (including
+   * Restores a session from a snapshot. Ownership of the snapshot (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 fromCheckpoint<State>(params: AgentSessionRestoreParams<State>, options?: AgentSessionOptions<State>): AgentSession<State>;
+  static fromSnapshot<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>;
-  /**
-   * 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>;
@@ -126,14 +71,14 @@ declare class AgentSession<State> {
    */
   updateModel(provider: AgentProvider | null, model: ModelSelection): void;
   abort(): Promise<AbortResult>;
-  scheduleYieldWakeup(durationMs: number, metadata?: AgentMetadata | null): AgentToolInvokeResult;
+  scheduleYieldWakeup(durationMs: number): 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(): TranscriptLog;
+  transcript(): Transcript;
   state(): State;
   id(): string;
   phase(): SessionPhase;
@@ -171,13 +116,6 @@ 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;
@@ -196,11 +134,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
-   * checkpoint write. Boundaries (action end, abort, dispose) flush the write.
+   * snapshot write. Boundaries (action end, abort, dispose) flush the write.
    */
   private commitTranscript;
   private schedulePersist;
-  private persistCheckpoint;
+  private persistSnapshot;
   private flushPersist;
   private emit;
   private resolveIdleWaiters;
@@ -226,18 +164,18 @@ interface AgentServerSessionOptions {
   persistIntervalMs?: number;
 }
 /**
- * Host-agnostic hook invoked before each resolved Host's BashEnvironment is built.
+ * Host-agnostic hook invoked once per `open()` before 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 PrepareShellContext {
+interface PrepareSessionShellContext {
   agentSessionId: string;
   host: Host;
   commandNames: readonly string[];
   /** Shell options from AgentServer construction (before this hook). */
   shell: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
 }
-type PrepareShell = (ctx: PrepareShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
+type PrepareSessionShell = (ctx: PrepareSessionShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
 interface AgentServerOptions {
   agent: AgentHarness<unknown>;
   providers: Provider[];
@@ -247,7 +185,7 @@ interface AgentServerOptions {
    * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
    * command bridge wiring lives in `@demicodes/host-local`, not here.
    */
-  prepareShell?: PrepareShell;
+  prepareSessionShell?: PrepareSessionShell;
 }
 interface AgentTransportBinding {
   close(): Promise<void>;
@@ -261,18 +199,12 @@ 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 RunCommandLineShellNotFoundError extends Error {
-  readonly shellId: string;
-  constructor(shellId: string);
-}
-declare class RunCommandLineCommandNotRegisteredError extends Error {
-  readonly commandName: string;
-  constructor(commandName: string);
+declare class RunCommandLineSessionNotFoundError extends Error {
+  readonly agentSessionId: string;
+  constructor(agentSessionId: string);
 }
 declare class RunCommandLineTimeoutError extends Error {
   readonly commandId: string;
@@ -285,7 +217,7 @@ declare class AgentServer {
   private readonly providers;
   private readonly shellOptions;
   private readonly sessionOptions;
-  private readonly prepareShell;
+  private readonly prepareSessionShell;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
@@ -297,15 +229,12 @@ 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(shellId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
+  runCommandLine(agentSessionId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
 }
 //#endregion
 //#region src/tools.d.ts
 interface StandardAgentToolOptions<State = unknown> {
-  environment: BashEnvironment | ((ctx: AgentToolInvokeContext<State>, handle: {
-    shellId?: string;
-    commandId?: string;
-  }) => BashEnvironment | Promise<BashEnvironment>);
+  environment: BashEnvironment;
   scheduleYield(ctx: AgentToolInvokeContext<State>, durationMs: number): AgentToolInvokeResult;
 }
 declare function createStandardAgentTools<State = unknown>(options: StandardAgentToolOptions<State>): AgentTool<State>[];
@@ -313,56 +242,10 @@ 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: 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;
+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;
 //#endregion
-export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, 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 };
+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 };