@demicodes/agent 0.22.0 → 0.23.0

package/dist/index.d.mts

@@ -244,6 +244,78 @@ declare class AgentSession<State> {
 declare function applyTranscriptPatches(blocks: Block[], patches: TranscriptPatch[]): Block[];
 declare function cloneBlocks(blocks: Block[]): Block[];
 //#endregion
+//#region src/tools.d.ts
+interface StandardAgentToolOptions<State = unknown> {
+  environment: BashEnvironment | ((ctx: AgentToolInvokeContext<State>, handle: {
+    shellId?: string;
+    commandId?: string;
+  }) => BashEnvironment | Promise<BashEnvironment>);
+  scheduleYield(ctx: AgentToolInvokeContext<State>, durationMs: number): AgentToolInvokeResult;
+  /**
+   * Tool-result preview budget in tokens for a given model context window.
+   * Defaults to {@link shellPreviewBudgetTokens}.
+   */
+  previewBudgetTokens?: ShellPreviewBudget;
+}
+type ShellPreviewBudget = (contextWindow: number) => number;
+declare function createStandardAgentTools<State = unknown>(options: StandardAgentToolOptions<State>): AgentTool<State>[];
+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 directory (real files on the host
+ * filesystem, see `artifactDir`), 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>, previewBudget?: ShellPreviewBudget): Promise<AgentToolInvokeResult>;
+declare function shellCommandHandleRequired(result: ShellCommandStatus, budgetTokens: number): boolean;
+//#endregion
 //#region src/server.d.ts
 /** Session tuning forwarded to every AgentSession this server creates. */
 interface AgentServerSessionOptions {
@@ -275,9 +347,11 @@ interface AgentServerOptions {
   session?: AgentServerSessionOptions;
   subagents?: {
     /**
-     * When false, a child closing never wakes an idle parent with an automatic
-     * user send; the host app observes the `subagent closed` frame and drives
-     * the parent itself. Defaults to true.
+     * When false, a child of the ROOT session closing never wakes the idle
+     * root with an automatic user send; the host app observes the `subagent
+     * closed` frame and drives the root itself. Applies to the root level
+     * only: a subagent parent has no host-side message channel, so deeper
+     * levels always self-notify. Defaults to true.
      */
     notifyParentOnIdle?: boolean;
     /**
@@ -286,6 +360,14 @@ interface AgentServerOptions {
      */
     maxLiveSubagents?: number;
   };
+  tools?: {
+    /**
+     * Shell tool-result preview budget in tokens as a function of the current
+     * model's context window, applied to every session in the tree. Defaults
+     * to the built-in 10k / 100k split at an 800k context window.
+     */
+    shellPreviewBudgetTokens?: ShellPreviewBudget;
+  };
   /**
    * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
    * command bridge wiring lives in `@demicodes/host-local`, not here.
@@ -331,6 +413,7 @@ declare class AgentServer {
   private readonly prepareShell;
   private readonly notifyParentOnIdle;
   private readonly maxLiveSubagents;
+  private readonly shellPreviewBudgetTokens;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
@@ -448,6 +531,8 @@ interface ChildSupervisorOptions<State> {
   directory: AgentDirectory<State>;
   /** Live-children ceiling for this supervisor (from `AgentServerOptions.subagents.maxLiveSubagents`). */
   maxLiveSubagents: number;
+  /** Shell preview budget for every child (from `AgentServerOptions.tools.shellPreviewBudgetTokens`); null uses the built-in split. */
+  shellPreviewBudgetTokens: ShellPreviewBudget | null;
   /** When false, this supervisor's owner may not spawn: its `demi agent` tree carries communication and reads only. */
   canSpawn: boolean;
   /** Invoked whenever the live-children set changes; wired to the owning job's settle loop. */
@@ -614,70 +699,4 @@ declare function injectSubagentCommand(commands: Command[], agentNode: Command):
  */
 declare function createReadonlyHost(host: Host): Host;
 //#endregion
-//#region src/tools.d.ts
-interface StandardAgentToolOptions<State = unknown> {
-  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>[];
-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 directory (real files on the host
- * filesystem, see `artifactDir`), 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, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDirectory, 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, AgentTreeNode, ChildSupervisor, ChildSupervisorOptions, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, MAX_LIVE_SUBAGENTS, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, SubagentExecution, SubagentJob, SubagentProfile, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDirectory, 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, AgentTreeNode, ChildSupervisor, ChildSupervisorOptions, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_MAX_MEDIA_BYTES, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, MAX_LIVE_SUBAGENTS, ModelSwitchApply, PrepareShell, PrepareShellContext, ProviderStreamError, ResumePoint, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, SUBAGENT_RESULT_MAX_BYTES, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellPreviewBudget, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, SubagentExecution, SubagentJob, SubagentProfile, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createReadonlyHost, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, findResumePoint, finishShellToolResult, injectSubagentCommand, isContextLengthExceeded, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/index.mjs

@@ -2248,8 +2248,8 @@ var InProcessEndpoint = class {
 const MAX_CONSECUTIVE_IDENTICAL_EXEC = 6;
 const REPEAT_WINDOW_MS = 6e4;
 const MAX_DELAY_MS = 6e5;
-const SMALL_CONTEXT_PREVIEW_TOKENS = 1e3;
-const LARGE_CONTEXT_PREVIEW_TOKENS = 1e4;
+const SMALL_CONTEXT_PREVIEW_TOKENS = 1e4;
+const LARGE_CONTEXT_PREVIEW_TOKENS = 1e5;
 const LARGE_CONTEXT_THRESHOLD_TOKENS = 8e5;
 const APPROX_CHARS_PER_TOKEN = 4;
 const TOOL_DESCRIPTION_FIELD = "Concise title for the concrete user-visible state or result to make visible or confirm. Do not describe waiting, pausing, tool mechanics, generic actions, object labels, steps, tool names, ids, internals, or reasons.";
@@ -2288,7 +2288,7 @@ function createStandardAgentTools(options) {
 					signal: ctx.signal
 				});
 				ctx.emitProgress(result);
-				return finishShellToolResult(environment, result, ctx);
+				return finishShellToolResult(environment, result, ctx, options.previewBudgetTokens);
 			}
 		},
 		{
@@ -2311,7 +2311,7 @@ function createStandardAgentTools(options) {
 				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
 				const result = await environment.status(parsed);
 				ctx.emitProgress(result);
-				return finishShellToolResult(environment, result, ctx);
+				return finishShellToolResult(environment, result, ctx, options.previewBudgetTokens);
 			}
 		},
 		{
@@ -2338,7 +2338,7 @@ function createStandardAgentTools(options) {
 					signal: ctx.signal
 				});
 				ctx.emitProgress(result);
-				return finishShellToolResult(environment, result, ctx);
+				return finishShellToolResult(environment, result, ctx, options.previewBudgetTokens);
 			}
 		},
 		{
@@ -2362,7 +2362,7 @@ function createStandardAgentTools(options) {
 				const result = await environment.abort(parsed);
 				ctx.emitProgress(result);
 				return {
-					...await finishShellToolResult(environment, result, ctx),
+					...await finishShellToolResult(environment, result, ctx, options.previewBudgetTokens),
 					isError: false
 				};
 			}
@@ -2636,8 +2636,8 @@ function boundedPreview(text, budgetTokens) {
 		truncated: true
 	};
 }
-async function finishShellToolResult(environment, result, ctx) {
-	const previewBudgetTokens = shellPreviewBudgetTokens(ctx.model.model.contextWindow);
+async function finishShellToolResult(environment, result, ctx, previewBudget = shellPreviewBudgetTokens) {
+	const previewBudgetTokens = previewBudget(ctx.model.model.contextWindow);
 	const exposeCommandHandle = shellCommandHandleRequired(result, previewBudgetTokens);
 	const toolResult = toShellToolResult(result, {
 		includePreview: true,
@@ -3255,6 +3255,7 @@ var ChildSupervisor = class ChildSupervisor {
 			parentCommands: inherited,
 			storePrefix: `${this.options.storePrefix}/subagents/${id}`,
 			canSpawn: input.canSpawnSubagents,
+			notifyParentOnIdle: true,
 			onJobsChanged: () => job.wake?.()
 		});
 		const commands = injectSubagentCommand(inherited, job.ownSupervisor.rootCommandNode());
@@ -3278,7 +3279,8 @@ var ChildSupervisor = class ChildSupervisor {
 				},
 				tools: () => createStandardAgentTools({
 					environment: (ctx) => this.childEnvironment(job, ctx),
-					scheduleYield: (ctx, durationMs) => job.session.scheduleYieldWakeup(durationMs, ctx.metadata)
+					scheduleYield: (ctx, durationMs) => job.session.scheduleYieldWakeup(durationMs, ctx.metadata),
+					...this.options.shellPreviewBudgetTokens === null ? {} : { previewBudgetTokens: this.options.shellPreviewBudgetTokens }
 				})
 			}
 		};
@@ -3919,6 +3921,7 @@ var AgentServer = class {
 	prepareShell;
 	notifyParentOnIdle;
 	maxLiveSubagents;
+	shellPreviewBudgetTokens;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -3929,6 +3932,7 @@ var AgentServer = class {
 		this.prepareShell = options.prepareShell ?? null;
 		this.notifyParentOnIdle = options.subagents?.notifyParentOnIdle ?? true;
 		this.maxLiveSubagents = options.subagents?.maxLiveSubagents ?? 8;
+		this.shellPreviewBudgetTokens = options.tools?.shellPreviewBudgetTokens ?? null;
 	}
 	client() {
 		const transports = createInProcessTransportPair();
@@ -3945,6 +3949,7 @@ var AgentServer = class {
 			prepareShell: this.prepareShell,
 			notifyParentOnIdle: this.notifyParentOnIdle,
 			maxLiveSubagents: this.maxLiveSubagents,
+			shellPreviewBudgetTokens: this.shellPreviewBudgetTokens,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -3996,6 +4001,7 @@ var AgentTransportBindingImpl = class {
 	prepareShell;
 	notifyParentOnIdle;
 	maxLiveSubagents;
+	shellPreviewBudgetTokens;
 	sessions;
 	session = null;
 	currentAgent = null;
@@ -4019,6 +4025,7 @@ var AgentTransportBindingImpl = class {
 		this.prepareShell = options.prepareShell;
 		this.notifyParentOnIdle = options.notifyParentOnIdle;
 		this.maxLiveSubagents = options.maxLiveSubagents;
+		this.shellPreviewBudgetTokens = options.shellPreviewBudgetTokens;
 		this.sessions = options.sessions;
 		this.unsubscribeTransport = this.transport.onFrame((frame) => {
 			this.handleFrame(frame);
@@ -4244,6 +4251,7 @@ var AgentTransportBindingImpl = class {
 			storePrefix: `agent-sessions/${agentSessionId}`,
 			directory,
 			maxLiveSubagents: this.maxLiveSubagents,
+			shellPreviewBudgetTokens: this.shellPreviewBudgetTokens,
 			canSpawn: true,
 			onJobsChanged: null,
 			emit: (subagentFrame) => this.send(subagentFrame)
@@ -4258,7 +4266,8 @@ var AgentTransportBindingImpl = class {
 			scheduleYield: (ctx, durationMs) => {
 				if (!sessionRef) throw new Error("AgentServer: session is not ready for yield scheduling");
 				return sessionRef.scheduleYieldWakeup(durationMs, ctx.metadata);
-			}
+			},
+			...this.shellPreviewBudgetTokens === null ? {} : { previewBudgetTokens: this.shellPreviewBudgetTokens }
 		});
 		const commandsPrompt = commandRegistry.renderHelp();
 		const runtime = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,10 +19,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.22.0",
-    "@demicodes/provider": "^0.22.0",
-    "@demicodes/shell": "^0.22.0",
-    "@demicodes/utils": "^0.22.0",
+    "@demicodes/core": "^0.23.0",
+    "@demicodes/provider": "^0.23.0",
+    "@demicodes/shell": "^0.23.0",
+    "@demicodes/utils": "^0.23.0",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",