@demicodes/agent 0.22.1 → 0.24.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 {
@@ -288,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.
@@ -333,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);
@@ -450,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. */
@@ -589,6 +672,11 @@ declare class ChildSupervisor<State = unknown> {
   private notifyIdleParent;
   private childEnvironment;
   private createChildEnvironment;
+  /**
+   * No name means the unnamed inherit profile: the parent harness, model, Host
+   * and commands, always available and never configurable. A name must match a
+   * declared profile; "default" is not a name.
+   */
   private resolveProfile;
   private configuredProfileNames;
   private subagentPreamble;
@@ -616,70 +704,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,
@@ -2751,6 +2751,13 @@ var AgentDirectory = class {
 		return [await build(this.rootId(), null, null, null, this.root.supervisor)];
 	}
 };
+/** The reserved word a harness may not use as a profile name: it is not a profile, it is the absence of one. */
+const INHERIT_PROFILE_NAME = "default";
+const INHERIT_PROFILE_LABEL = "(inherit)";
+const INHERIT_PROFILE = {
+	name: INHERIT_PROFILE_LABEL,
+	description: "Inherits the parent harness, model, Host, and commands."
+};
 /**
 * Per-session subagent supervisor. Every session — root or subagent — owns one
 * and carries the identical `demi agent` command tree, so spawn nests to any
@@ -2767,6 +2774,7 @@ var ChildSupervisor = class ChildSupervisor {
 	parentSession = null;
 	isDisposed = false;
 	constructor(options) {
+		if (options.profiles?.some((profile) => profile.name === INHERIT_PROFILE_NAME)) throw new Error(`subagent profile name "${INHERIT_PROFILE_NAME}" is reserved: omitting --profile already inherits the parent`);
 		this.options = options;
 	}
 	attachParent(session) {
@@ -2798,7 +2806,7 @@ var ChildSupervisor = class ChildSupervisor {
 			failureOutput: "non-zero exit with the abort or failure reason on stderr",
 			input: {
 				prompt: z.string().optional().describe(SPAWN_PROMPT_DESCRIPTION),
-				profile: z.string().optional().describe(`Named subagent profile configured at harness assembly. Available: ${profileNames.join(", ")}.`),
+				profile: z.string().optional().describe(`Named subagent profile configured at harness assembly; omit to inherit the parent's model, prompt, Host and commands. Available: ${profileNames.length > 0 ? profileNames.join(", ") : "none"}.`),
 				description: z.string().optional().describe("Short UI title distinguishing concurrent children."),
 				"no-subagents": z.boolean().optional().describe("Forbid this child from spawning subagents of its own; it can still send, steer, list, and show.")
 			},
@@ -3123,6 +3131,7 @@ var ChildSupervisor = class ChildSupervisor {
 		if (!meta?.closedPhase) throw new Error(`no archived subagent "${id}" (see \`demi agent list\`)`);
 		const checkpoint = await this.childSessionStore(id).loadCheckpoint();
 		if (!checkpoint) throw new Error(`archived subagent "${id}" has no checkpoint left`);
+		this.resolveProfile(meta.profileName ?? void 0);
 		const liveMeta = {
 			description: meta.description,
 			profileName: meta.profileName,
@@ -3174,7 +3183,7 @@ var ChildSupervisor = class ChildSupervisor {
 		const profile = this.resolveProfile(input.profileName);
 		const id = createId();
 		const metadata = parent.actionMetadata();
-		const profileName = input.profileName ?? (this.options.profiles ? profile.name : null);
+		const profileName = input.profileName ?? null;
 		const spawnedAt = Date.now();
 		const canSpawnSubagents = !input.isSpawnForbidden && profile.canSpawnSubagents !== false;
 		const { job, runtime } = this.assembleJob({
@@ -3279,7 +3288,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 }
 				})
 			}
 		};
@@ -3586,25 +3596,20 @@ var ChildSupervisor = class ChildSupervisor {
 			commands: job.commandRegistry
 		});
 	}
+	/**
+	* No name means the unnamed inherit profile: the parent harness, model, Host
+	* and commands, always available and never configurable. A name must match a
+	* declared profile; "default" is not a name.
+	*/
 	resolveProfile(name) {
-		const profiles = this.options.profiles;
-		const implicitDefault = {
-			name: "default",
-			description: "Inherits the parent harness, model, Host, and commands."
-		};
-		if (!profiles || profiles.length === 0) {
-			if (name !== void 0 && name !== "default") throw new Error(`unknown profile "${name}" (available: default)`);
-			return implicitDefault;
-		}
-		const target = name ?? "default";
-		const profile = profiles.find((candidate) => candidate.name === target);
+		if (name === void 0) return INHERIT_PROFILE;
+		const profile = this.options.profiles?.find((candidate) => candidate.name === name);
 		if (profile) return profile;
-		if (name === void 0) return implicitDefault;
-		throw new Error(`unknown profile "${name}" (available: ${this.configuredProfileNames().join(", ")})`);
+		const names = this.configuredProfileNames();
+		throw new Error(`unknown profile "${name}" (available: ${names.length > 0 ? names.join(", ") : "none; omit --profile to inherit the parent"})`);
 	}
 	configuredProfileNames() {
-		const names = (this.options.profiles ?? []).map((profile) => profile.name);
-		return names.includes("default") ? names : ["default", ...names];
+		return (this.options.profiles ?? []).map((profile) => profile.name);
 	}
 	subagentPreamble(childId) {
 		return [
@@ -3710,7 +3715,7 @@ var ChildSupervisor = class ChildSupervisor {
 			job.phase,
 			`up ${formatDuration(now - job.spawnedAt)}`,
 			`last-event ${formatDuration(now - job.lastEventAt)} ago`,
-			`profile=${job.profileName ?? "default"}`,
+			`profile=${job.profileName ?? INHERIT_PROFILE_LABEL}`,
 			job.description ? `"${job.description}"` : "(no description)",
 			`execution=${execution}`,
 			`activity=${this.activityOf(job, execution)}`
@@ -3723,7 +3728,7 @@ var ChildSupervisor = class ChildSupervisor {
 			`id: ${job.id}`,
 			`parent: ${this.ownerId()}`,
 			`description: ${job.description || "(none)"}`,
-			`profile: ${job.profileName ?? "default"}`,
+			`profile: ${job.profileName ?? INHERIT_PROFILE_LABEL}`,
 			`phase: ${job.phase}`,
 			`elapsed: ${formatDuration(now - job.spawnedAt)}`,
 			`execution: ${execution} (for ${formatDuration(this.executionForMs(job, execution, now))})`,
@@ -3920,6 +3925,7 @@ var AgentServer = class {
 	prepareShell;
 	notifyParentOnIdle;
 	maxLiveSubagents;
+	shellPreviewBudgetTokens;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -3930,6 +3936,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();
@@ -3946,6 +3953,7 @@ var AgentServer = class {
 			prepareShell: this.prepareShell,
 			notifyParentOnIdle: this.notifyParentOnIdle,
 			maxLiveSubagents: this.maxLiveSubagents,
+			shellPreviewBudgetTokens: this.shellPreviewBudgetTokens,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -3997,6 +4005,7 @@ var AgentTransportBindingImpl = class {
 	prepareShell;
 	notifyParentOnIdle;
 	maxLiveSubagents;
+	shellPreviewBudgetTokens;
 	sessions;
 	session = null;
 	currentAgent = null;
@@ -4020,6 +4029,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);
@@ -4245,6 +4255,7 @@ var AgentTransportBindingImpl = class {
 			storePrefix: `agent-sessions/${agentSessionId}`,
 			directory,
 			maxLiveSubagents: this.maxLiveSubagents,
+			shellPreviewBudgetTokens: this.shellPreviewBudgetTokens,
 			canSpawn: true,
 			onJobsChanged: null,
 			emit: (subagentFrame) => this.send(subagentFrame)
@@ -4259,7 +4270,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.1",
+  "version": "0.24.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -19,10 +19,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "^0.22.1",
-    "@demicodes/provider": "^0.22.1",
-    "@demicodes/shell": "^0.22.1",
-    "@demicodes/utils": "^0.22.1",
+    "@demicodes/core": "^0.24.0",
+    "@demicodes/provider": "^0.24.0",
+    "@demicodes/shell": "^0.24.0",
+    "@demicodes/utils": "^0.24.0",
     "zod": "^4.0.0"
   },
   "license": "Apache-2.0",