@demicodes/agent 0.1.0 → 0.2.1

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-BkAbPvRc.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-D6zJ4PLC.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-DVa_82EW.mjs";
+import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Cn_rhIIX.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 };

package/dist/client-entry.mjs

@@ -1,2 +1,2 @@
-import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-o6r-jV5p.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,9 +1,8 @@
-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-BkAbPvRc.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-D6zJ4PLC.mjs";
-import { BashEnvironment, BashEnvironmentOptions, ShellCommandSnapshot } 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-DVa_82EW.mjs";
+import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Cn_rhIIX.mjs";
+import { BashEnvironment, BashEnvironmentOptions, Host, ShellCommandSnapshot } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
-import { Block, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
-
+import { Block, Model, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
 //#region src/session.d.ts
 type ActiveTurnPhase = 'provider_streaming' | 'tool_executing' | 'compacting' | 'finalizing';
 declare class AgentSession<State> {
@@ -20,6 +19,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;
@@ -144,10 +144,6 @@ declare class AgentSession<State> {
   private resolveIdleWaiters;
 }
 //#endregion
-//#region src/json-codec.d.ts
-declare function stringifyAgentJson(value: unknown): string;
-declare function parseAgentJson<T>(text: string): T;
-//#endregion
 //#region src/patch.d.ts
 /**
  * Applies journal-produced transcript patches to a block list, returning a new
@@ -157,21 +153,6 @@ declare function parseAgentJson<T>(text: string): T;
 declare function applyTranscriptPatches(blocks: Block[], patches: TranscriptPatch[]): Block[];
 declare function cloneBlocks(blocks: Block[]): Block[];
 //#endregion
-//#region src/command-tools.d.ts
-interface CommandToolProjectionOptions {
-  /** Leaf paths to project (e.g. 'editor create'). Empty/absent = all leaves. */
-  include?: string[];
-  exclude?: string[];
-}
-/**
- * Projects registered command leaves onto the native tool surface: one
- * AgentTool per leaf, named by its path (editor create -> editor_create).
- * The tool renders the same shell invocation the model could type and runs it
- * through BashEnvironment.exec, so both projections share one implementation,
- * one audit trail, and one artifact store.
- */
-declare function createCommandProjectionTools<State = unknown>(environment: BashEnvironment, options?: CommandToolProjectionOptions, reservedNames?: ReadonlySet<string>): AgentTool<State>[];
-//#endregion
 //#region src/server.d.ts
 /** Session tuning forwarded to every AgentSession this server creates. */
 interface AgentServerSessionOptions {
@@ -182,33 +163,79 @@ interface AgentServerSessionOptions {
   };
   persistIntervalMs?: number;
 }
+/**
+ * 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 PrepareSessionShellContext {
+  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'>>;
 interface AgentServerOptions {
   agent: AgentHarness<unknown>;
   providers: Provider[];
   shell?: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
   session?: AgentServerSessionOptions;
   /**
-   * When set, registered command leaves are ALSO exposed as native tools (the
-   * second projection of the same CommandSpec implementations). Off by default:
-   * the shell form alone keeps the smallest tool surface.
+   * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
+   * command bridge wiring lives in `@demicodes/host-local`, not here.
    */
-  commandTools?: CommandToolProjectionOptions;
+  prepareSessionShell?: PrepareSessionShell;
 }
 interface AgentTransportBinding {
   close(): Promise<void>;
 }
+/** Options for {@link AgentServer.runCommandLine}. */
+interface RunCommandLineOptions {
+  cwd: string;
+  stdin: string;
+  signal?: AbortSignal;
+}
+/** 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 RunCommandLineCommandNotRegisteredError extends Error {
+  readonly commandName: string;
+  constructor(commandName: string);
+}
+declare class RunCommandLineTimeoutError extends Error {
+  readonly commandId: string;
+  readonly partialStdout: string;
+  readonly partialStderr: string;
+  constructor(commandId: string, partialStdout: string, partialStderr: string);
+}
 declare class AgentServer {
   private readonly agent;
   private readonly providers;
   private readonly shellOptions;
   private readonly sessionOptions;
-  private readonly commandToolOptions;
+  private readonly prepareSessionShell;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
   client(): AgentClient;
   attachTransport(transport: AgentServerTransport): AgentTransportBinding;
   close(): Promise<void>;
+  /**
+   * Runs one registered-command invocation to completion for a live session.
+   * 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>;
 }
 //#endregion
 //#region src/tools.d.ts
@@ -221,10 +248,12 @@ interface ShellToolResultOptions {
   includePreview?: boolean;
   previewBudgetTokens?: number;
   exposeCommandHandle?: boolean;
+  /** Model receiving this result; gates binary-stream media attachment. */
+  model?: Model;
 }
 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;
 //#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, CommandToolProjectionOptions, CompactionWindow, ConversationSummary, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, ServerFrame, SessionEvent, SessionEventListener, ShellCommandSnapshotLike, ShellToolResultOptions, StandardAgentToolOptions, ToolContinuation, Transcript, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createCommandProjectionTools, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, parseAgentJson, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, stringifyAgentJson, 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, RunCommandLineCommandNotRegisteredError, 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 };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-o6r-jV5p.mjs";
-import { n as stringifyAgentJson, t as parseAgentJson } from "./json-codec-BFLXlg3K.mjs";
-import { AbortError, abortable, asError, asRecord, asString, createId, delay, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, throwIfAborted, truncate } from "@demicodes/utils";
-import { BashEnvironment, CommandRegistry, listRegisteredCommandOperations } from "@demicodes/shell";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-Bod0puog.mjs";
+import { AbortError, abortable, asError, asRecord, asString, bytesToBase64, createId, delay, isAbortError, isRecord, noop, parseJsonOrString, safeJsonStringify, throwIfAborted, truncate } from "@demicodes/utils";
+import { BashEnvironment, CommandRegistry, MAX_TIMEOUT_MS, heredocDelimiter, shellQuote } from "@demicodes/shell";
 import { providerRuntime } from "@demicodes/provider";
+import { modelAcceptsMediaType, sniffModelMediaType } from "@demicodes/core";
 //#region src/transcript.ts
 const DEFAULT_MODEL_TEXT_HEAD_CHARS = 8e3;
 const DEFAULT_MODEL_TEXT_TAIL_CHARS = 8e3;
@@ -532,6 +532,7 @@ function stringifyUserContent(content) {
 	switch (content.type) {
 		case "text": return content.text;
 		case "image": return content.source.type === "url" ? content.source.url : content.source.mediaType;
+		case "video": return content.source.type === "url" ? content.source.url : content.source.mediaType;
 		case "document": return `${content.source.fileName} ${content.source.mediaType}`;
 		case "reference": return content.reference;
 	}
@@ -540,6 +541,7 @@ function stringifyToolResult(content) {
 	switch (content.type) {
 		case "text": return content.text;
 		case "image": return content.source.mediaType;
+		case "video": return content.source.mediaType;
 	}
 }
 function boundUserContent(content, headChars, tailChars) {
@@ -1139,6 +1141,9 @@ var AgentSession = class AgentSession {
 	listeners = /* @__PURE__ */ new Set();
 	pendingActions = [];
 	queued = [];
+	get modelSelection() {
+		return this.model;
+	}
 	transcriptLog;
 	agentState;
 	currentPhase = "idle";
@@ -2212,13 +2217,14 @@ function toShellToolResult(result, toolCallId = "", options = {}) {
 		type: "text",
 		text: formatShellToolResult(result, options)
 	}];
-	if (result.status === "exited" && result.assets) for (const asset of result.assets) output.push({
-		type: "image",
-		source: {
-			mediaType: asset.mediaType,
-			data: asset.data
-		}
-	});
+	if (result.status === "exited" && result.binaryStdout) {
+		const verdict = binaryStreamVerdict(result.binaryStdout, result.commandId, options.model);
+		if (verdict.block) output.push(verdict.block);
+		if (verdict.note) output.push({
+			type: "text",
+			text: verdict.note
+		});
+	}
 	return {
 		output,
 		isError: false,
@@ -2231,6 +2237,32 @@ function toShellToolResult(result, toolCallId = "", options = {}) {
 		} : void 0
 	};
 }
+/**
+* Boundary decision for a binary final stream: attach as native media when the
+* magic matches the closed model-media set, the model accepts the type, and
+* the stream was not truncated; otherwise explain why nothing was attached.
+*/
+function binaryStreamVerdict(binary, commandId, model) {
+	const media = sniffModelMediaType(binary.data);
+	const binPath = `/@/commands/${commandId}/stdout.bin`;
+	if (binary.truncated) return { note: `Binary stdout was truncated at the output limit (${binary.data.length} of ${binary.totalBytes} bytes)${media ? ` and looks like ${media.mediaType}` : ""}; it was not attached. Redirect to a file or raise the output limit and re-run.` };
+	if (!media) return { note: `Binary stdout does not match any model-viewable media type; the raw bytes remain readable at ${binPath}.` };
+	if (!model || !modelAcceptsMediaType(model, media.mediaType)) return { note: `Binary stdout is ${media.mediaType}, which this model does not accept natively; the raw bytes remain readable at ${binPath}.` };
+	const source = {
+		mediaType: media.mediaType,
+		data: bytesToBase64(binary.data)
+	};
+	return {
+		block: media.kind === "video" ? {
+			type: "video",
+			source
+		} : {
+			type: "image",
+			source
+		},
+		note: `Attached stdout as ${media.mediaType} (${binary.totalBytes} bytes).`
+	};
+}
 function parseShellExecInput(input) {
 	const record = asRecord(input, "agent tool input must be an object");
 	if (typeof record.script !== "string") throw new Error("shell_exec requires string field \"script\"");
@@ -2352,7 +2384,8 @@ async function finishShellToolResult(environment, result, ctx) {
 	const toolResult = toShellToolResult(result, ctx.toolCallId, {
 		includePreview: true,
 		previewBudgetTokens,
-		exposeCommandHandle
+		exposeCommandHandle,
+		model: ctx.model.model
 	});
 	if (!exposeCommandHandle) await environment.releaseCommand(result.commandId);
 	return toolResult;
@@ -2364,56 +2397,41 @@ function shellCommandHandleRequired(result, budgetTokens) {
 	return preview.truncated || result.output.truncated || result.output.bytes > maxChars || result.stdout.truncated || result.stderr.truncated;
 }
 //#endregion
-//#region src/command-tools.ts
-/** Observation window for projected command invocations. Registered commands
-* execute in-process and complete quickly; long work belongs to shell_exec. */
-const COMMAND_TOOL_TIMEOUT_MS = 6e4;
-/**
-* Projects registered command leaves onto the native tool surface: one
-* AgentTool per leaf, named by its path (editor create -> editor_create).
-* The tool renders the same shell invocation the model could type and runs it
-* through BashEnvironment.exec, so both projections share one implementation,
-* one audit trail, and one artifact store.
-*/
-function createCommandProjectionTools(environment, options = {}, reservedNames = /* @__PURE__ */ new Set()) {
-	const operations = listRegisteredCommandOperations(environment.registeredCommands()).filter((operation) => operationSelected(operation, options));
-	const seen = new Set(reservedNames);
-	return operations.map((operation) => {
-		const name = operation.path.join("_");
-		if (seen.has(name)) throw new Error(`Command tool projection: tool name "${name}" conflicts with an existing tool`);
-		seen.add(name);
-		return {
-			name,
-			description: operation.description,
-			inputSchema: operation.inputSchema,
-			invoke: async (ctx, input) => {
-				const values = asRecord(input, `${name} input must be an object`);
-				const result = await environment.exec({
-					script: operation.renderScript(values),
-					agentSessionId: ctx.agentSessionId,
-					timeoutMs: COMMAND_TOOL_TIMEOUT_MS,
-					signal: ctx.signal
-				});
-				ctx.emitProgress(result);
-				return finishShellToolResult(environment, result, ctx);
-			}
-		};
-	});
-}
-function operationSelected(operation, options) {
-	const path = operation.path.join(" ");
-	if (options.exclude?.includes(path)) return false;
-	if (options.include && options.include.length > 0) return options.include.includes(path);
-	return true;
-}
-//#endregion
 //#region src/server.ts
+var RunCommandLineSessionNotFoundError = class extends Error {
+	agentSessionId;
+	constructor(agentSessionId) {
+		super(`runCommandLine: no session "${agentSessionId}" is open in this process`);
+		this.agentSessionId = agentSessionId;
+		this.name = "RunCommandLineSessionNotFoundError";
+	}
+};
+var RunCommandLineCommandNotRegisteredError = class extends Error {
+	commandName;
+	constructor(commandName) {
+		super(`runCommandLine: command "${commandName}" is not registered for this session`);
+		this.commandName = commandName;
+		this.name = "RunCommandLineCommandNotRegisteredError";
+	}
+};
+var RunCommandLineTimeoutError = class extends Error {
+	commandId;
+	partialStdout;
+	partialStderr;
+	constructor(commandId, partialStdout, partialStderr) {
+		super(`runCommandLine: command "${commandId}" exceeded the ${MAX_TIMEOUT_MS}ms ceiling and was aborted`);
+		this.commandId = commandId;
+		this.partialStdout = partialStdout;
+		this.partialStderr = partialStderr;
+		this.name = "RunCommandLineTimeoutError";
+	}
+};
 var AgentServer = class {
 	agent;
 	providers;
 	shellOptions;
 	sessionOptions;
-	commandToolOptions;
+	prepareSessionShell;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -2421,7 +2439,7 @@ var AgentServer = class {
 		this.providers = createProviderMap(options.providers);
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.commandToolOptions = options.commandTools ?? null;
+		this.prepareSessionShell = options.prepareSessionShell ?? null;
 	}
 	client() {
 		const transports = createInProcessTransportPair();
@@ -2435,7 +2453,7 @@ var AgentServer = class {
 			providers: this.providers,
 			shell: this.shellOptions,
 			session: this.sessionOptions,
-			commandTools: this.commandToolOptions,
+			prepareSessionShell: this.prepareSessionShell,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -2446,6 +2464,16 @@ var AgentServer = class {
 		this.bindings.clear();
 		await Promise.all(bindings.map((binding) => binding.close()));
 	}
+	/**
+	* Runs one registered-command invocation to completion for a live session.
+	* Transport-agnostic: callers (e.g. LocalHost command bridge) supply their
+	* own IPC; AgentServer only knows how to exec against the open session shell.
+	*/
+	async runCommandLine(agentSessionId, name, args, opts) {
+		const binding = this.sessionOwnership.get(agentSessionId);
+		if (!binding) throw new RunCommandLineSessionNotFoundError(agentSessionId);
+		return binding.runCommandLine(name, args, opts);
+	}
 };
 /**
 * Tracks which transport binding currently owns each client-provided session
@@ -2463,6 +2491,9 @@ var SessionOwnershipRegistry = class {
 	release(sessionId, binding) {
 		if (this.holders.get(sessionId) === binding) this.holders.delete(sessionId);
 	}
+	get(sessionId) {
+		return this.holders.get(sessionId);
+	}
 };
 var AgentTransportBindingImpl = class {
 	transport;
@@ -2470,7 +2501,7 @@ var AgentTransportBindingImpl = class {
 	providers;
 	shellOptions;
 	sessionOptions;
-	commandToolOptions;
+	prepareSessionShell;
 	sessions;
 	session = null;
 	currentAgent = null;
@@ -2478,6 +2509,7 @@ var AgentTransportBindingImpl = class {
 	currentCwd = null;
 	currentProviderId = null;
 	currentSessionId = null;
+	currentCommandNames = /* @__PURE__ */ new Set();
 	unsubscribeSession = null;
 	unsubscribeTransport = null;
 	closed = false;
@@ -2487,7 +2519,7 @@ var AgentTransportBindingImpl = class {
 		this.providers = options.providers;
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.commandToolOptions = options.commandTools;
+		this.prepareSessionShell = options.prepareSessionShell;
 		this.sessions = options.sessions;
 		this.unsubscribeTransport = this.transport.onFrame((frame) => {
 			this.handleFrame(frame);
@@ -2694,26 +2726,26 @@ var AgentTransportBindingImpl = class {
 		const commands = agent.commands?.(harnessContext) ?? [];
 		const commandRegistry = new CommandRegistry();
 		for (const command of commands) commandRegistry.register(command);
+		const commandNames = commandRegistry.list().map((command) => command.name);
 		const environment = new BashEnvironment({
-			...this.shellOptions,
+			...this.prepareSessionShell ? await this.prepareSessionShell({
+				agentSessionId,
+				host,
+				commandNames,
+				shell: this.shellOptions
+			}) : this.shellOptions,
 			host,
 			commands: commandRegistry
 		});
 		let sessionRef = null;
-		const standardTools = createStandardAgentTools({
+		const tools = createStandardAgentTools({
 			environment,
 			scheduleYield: (_ctx, durationMs) => {
 				if (!sessionRef) throw new Error("AgentServer: session is not ready for yield scheduling");
 				return sessionRef.scheduleYieldWakeup(durationMs);
 			}
 		});
-		const projectedTools = this.commandToolOptions ? createCommandProjectionTools(environment, this.commandToolOptions, new Set(standardTools.map((tool) => tool.name))) : [];
-		const tools = [...standardTools, ...projectedTools];
-		let commandsPrompt = commandRegistry.renderPrompt();
-		if (projectedTools.length > 0) {
-			const names = projectedTools.map((tool) => tool.name).join(", ");
-			commandsPrompt += `\n\nNative tool forms: ${names} — identical behavior, audit, and artifacts to the shell commands above.`;
-		}
+		const commandsPrompt = commandRegistry.renderHelp();
 		const runtime = {
 			harnessName: agent.name,
 			initialState: () => agent.initialState(),
@@ -2754,6 +2786,7 @@ var AgentTransportBindingImpl = class {
 		this.currentEnvironment = environment;
 		this.currentCwd = frame.cwd;
 		this.currentProviderId = frame.provider.providerId;
+		this.currentCommandNames = new Set(commandNames);
 		if (restoring) session.updateModel(null, frame.provider.model);
 		this.unsubscribeSession = this.session.subscribe((event) => this.handleSessionEvent(event));
 		this.send({ type: "opened" });
@@ -2858,6 +2891,7 @@ var AgentTransportBindingImpl = class {
 			this.currentEnvironment = null;
 			this.currentCwd = null;
 			this.currentProviderId = null;
+			this.currentCommandNames = /* @__PURE__ */ new Set();
 			if (this.currentSessionId) {
 				this.sessions.release(this.currentSessionId, this);
 				this.currentSessionId = null;
@@ -2891,6 +2925,50 @@ var AgentTransportBindingImpl = class {
 		});
 		this.sendShellWriteResult(frame.commandId, result);
 	}
+	/** Backs `AgentServer.runCommandLine` — see its doc comment for the contract. */
+	async runCommandLine(name, args, opts) {
+		const environment = this.currentEnvironment;
+		const agentSessionId = this.currentSessionId;
+		if (!environment || !agentSessionId) throw new Error("runCommandLine: session has no active shell environment");
+		if (!this.currentCommandNames.has(name)) throw new RunCommandLineCommandNotRegisteredError(name);
+		const words = [name, ...args].map(shellQuote).join(" ");
+		let script = words;
+		if (opts.stdin.length > 0) {
+			const delimiter = heredocDelimiter(opts.stdin);
+			script = `${words} <<'${delimiter}'\n${opts.stdin.endsWith("\n") ? opts.stdin : `${opts.stdin}\n`}${delimiter}`;
+		}
+		const result = await environment.exec({
+			agentSessionId,
+			script,
+			timeoutMs: MAX_TIMEOUT_MS,
+			signal: opts.signal,
+			ephemeral: true,
+			cwd: opts.cwd
+		});
+		try {
+			if (result.status === "exited") {
+				if (result.binaryStdout) {
+					const truncationNote = result.binaryStdout.truncated ? `command bridge: binary stdout truncated at the output limit (${result.binaryStdout.data.length} of ${result.binaryStdout.totalBytes} bytes)\n` : "";
+					return {
+						exitCode: result.exitCode,
+						stdout: bytesToBase64(result.binaryStdout.data),
+						stdoutEncoding: "base64",
+						stderr: `${result.stderr.delta}${truncationNote}`
+					};
+				}
+				return {
+					exitCode: result.exitCode,
+					stdout: result.stdout.delta,
+					stderr: result.stderr.delta
+				};
+			}
+			if (result.status === "aborted") throw new Error(`runCommandLine: call for "${name}" was cancelled before it completed`);
+			const aborted = await environment.abort({ commandId: result.commandId });
+			throw new RunCommandLineTimeoutError(result.commandId, aborted.status === "aborted" ? aborted.stdout.delta : "", aborted.status === "aborted" ? aborted.stderr.delta : "");
+		} finally {
+			await environment.disposeShell(result.shellId).catch(() => {});
+		}
+	}
 	sessionFor(command) {
 		if (!this.session) {
 			this.send({
@@ -3056,4 +3134,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, Transcript, applyTranscriptPatches, cloneBlocks, createCommandProjectionTools, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, parseAgentJson, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, stringifyAgentJson, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineCommandNotRegisteredError, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, Transcript, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/stdio-transport.d.mts

@@ -1,6 +1,5 @@
-import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-BkAbPvRc.mjs";
+import { n as AgentServerTransport, t as AgentClientTransport } from "./transport-DVa_82EW.mjs";
 import { Readable, Writable } from "node:stream";
-
 //#region src/stdio-transport.d.ts
 declare function createStdioClientTransport(readable: Readable, writable: Writable): AgentClientTransport;
 declare function createStdioServerTransport(readable: Readable, writable: Writable): AgentServerTransport;

package/dist/stdio-transport.mjs

@@ -1,4 +1,4 @@
-import { n as stringifyAgentJson, t as parseAgentJson } from "./json-codec-BFLXlg3K.mjs";
+import { parsePortableJson, stringifyPortableJson } from "@demicodes/utils";
 import { createInterface } from "node:readline";
 //#region src/stdio-transport.ts
 function createStdioClientTransport(readable, writable) {
@@ -19,13 +19,13 @@ var JsonLineTransport = class {
 		this.readline = createInterface({ input: readable });
 		this.readline.on("line", (line) => {
 			if (this.closed || line.trim() === "") return;
-			const frame = parseAgentJson(line);
+			const frame = parsePortableJson(line);
 			for (const handler of this.handlers) handler(frame);
 		});
 	}
 	send(frame) {
 		if (this.closed) throw new Error("Agent transport is closed");
-		this.writable.write(`${stringifyAgentJson(frame)}\n`);
+		this.writable.write(`${stringifyPortableJson(frame)}\n`);
 	}
 	onFrame(handler) {
 		this.handlers.add(handler);

package/dist/{transport-BkAbPvRc.d.mts → transport-DVa_82EW.d.mts}

@@ -1,7 +1,6 @@
-import { BashAuditEvent, CommandSpec, Host, ShellCommandSnapshot } from "@demicodes/shell";
+import { BashAuditEvent, Command, Host, ShellCommandSnapshot } from "@demicodes/shell";
 import { AgentProvider, InferenceItem, ProviderEvent, ProviderSelection, ToolDefinition } from "@demicodes/provider";
 import { Block, ModelSelection, QueuedMessage, SessionPhase, ToolResultContentBlock, Transcript, UserContentBlock } from "@demicodes/core";
-
 //#region src/retry-policy.d.ts
 /**
  * Retry policy for provider requests, applied by the agent runtime (turn loop
@@ -164,7 +163,7 @@ interface AgentHarness<State = unknown> {
   name: string;
   initialState(): State;
   host(ctx: AgentHarnessContext<State>): Host;
-  commands?(ctx: AgentHarnessContext<State>): CommandSpec[];
+  commands?(ctx: AgentHarnessContext<State>): Command[];
   systemPrompt(ctx: AgentSystemPromptContext<State>): string;
   preamble?(ctx: AgentPromptContext<State>): string | null;
   resolveReferences?(ctx: AgentReferenceResolveContext<State>, content: UserContentBlock[]): Promise<UserContentBlock[]> | UserContentBlock[];

package/dist/{websocket-transport-o6r-jV5p.mjs → websocket-transport-Bod0puog.mjs}

@@ -1,4 +1,4 @@
-import { n as stringifyAgentJson, t as parseAgentJson } from "./json-codec-BFLXlg3K.mjs";
+import { parsePortableJson, stringifyPortableJson } from "@demicodes/utils";
 //#region src/patch.ts
 /**
 * Applies journal-produced transcript patches to a block list, returning a new
@@ -447,7 +447,7 @@ var WebSocketJsonTransport = class {
 	socket;
 	handlers = /* @__PURE__ */ new Set();
 	onMessage = (event) => {
-		const frame = parseAgentJson(typeof event.data === "string" ? event.data : String(event.data));
+		const frame = parsePortableJson(typeof event.data === "string" ? event.data : String(event.data));
 		for (const handler of this.handlers) handler(frame);
 	};
 	constructor(socket) {
@@ -455,7 +455,7 @@ var WebSocketJsonTransport = class {
 		this.socket.addEventListener("message", this.onMessage);
 	}
 	send(frame) {
-		this.socket.send(stringifyAgentJson(frame));
+		this.socket.send(stringifyPortableJson(frame));
 	}
 	onFrame(handler) {
 		this.handlers.add(handler);

package/dist/{websocket-transport-D6zJ4PLC.d.mts → websocket-transport-Cn_rhIIX.d.mts}

@@ -1,7 +1,6 @@
-import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-BkAbPvRc.mjs";
+import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-DVa_82EW.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
-
 //#region src/client.d.ts
 type AgentClientListener = (event: ClientSessionEvent) => void;
 declare class AgentClient {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -22,10 +22,10 @@
     }
   },
   "dependencies": {
-    "@demicodes/core": "workspace:*",
-    "@demicodes/provider": "workspace:*",
-    "@demicodes/shell": "workspace:*",
-    "@demicodes/utils": "workspace:*"
+    "@demicodes/core": "^0.2.1",
+    "@demicodes/provider": "^0.2.1",
+    "@demicodes/shell": "^0.2.1",
+    "@demicodes/utils": "^0.2.1"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",

package/dist/json-codec-BFLXlg3K.mjs

@@ -1,70 +0,0 @@
-//#region src/json-codec.ts
-const BINARY_MARKER = "__demiUint8Array";
-const BIGINT_MARKER = "__demiBigInt";
-const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-function stringifyAgentJson(value) {
-	return JSON.stringify(value, (_key, nested) => {
-		if (nested instanceof Uint8Array) return {
-			[BINARY_MARKER]: true,
-			base64: bytesToBase64(nested)
-		};
-		if (typeof nested === "bigint") return {
-			[BIGINT_MARKER]: true,
-			value: nested.toString()
-		};
-		return nested;
-	});
-}
-function parseAgentJson(text) {
-	return JSON.parse(text, (_key, nested) => {
-		if (isEncodedUint8Array(nested)) return base64ToBytes(nested.base64);
-		if (isEncodedBigInt(nested)) return BigInt(nested.value);
-		return nested;
-	});
-}
-function isEncodedUint8Array(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) && value[BINARY_MARKER] === true && typeof value.base64 === "string";
-}
-function isEncodedBigInt(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) && value[BIGINT_MARKER] === true && typeof value.value === "string";
-}
-function bytesToBase64(bytes) {
-	let output = "";
-	for (let index = 0; index < bytes.byteLength; index += 3) {
-		const first = bytes[index];
-		const second = bytes[index + 1];
-		const third = bytes[index + 2];
-		output += BASE64_ALPHABET[first >> 2];
-		output += BASE64_ALPHABET[(first & 3) << 4 | (second ?? 0) >> 4];
-		output += second === void 0 ? "=" : BASE64_ALPHABET[(second & 15) << 2 | (third ?? 0) >> 6];
-		output += third === void 0 ? "=" : BASE64_ALPHABET[third & 63];
-	}
-	return output;
-}
-function base64ToBytes(base64) {
-	const clean = base64.replace(/\s+/g, "");
-	if (clean.length === 0) return /* @__PURE__ */ new Uint8Array();
-	if (clean.length % 4 !== 0) throw new Error("Invalid base64 payload length");
-	const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
-	const bytes = new Uint8Array(clean.length / 4 * 3 - padding);
-	let offset = 0;
-	for (let index = 0; index < clean.length; index += 4) {
-		const first = base64Value(clean[index]);
-		const second = base64Value(clean[index + 1]);
-		const third = clean[index + 2] === "=" ? 0 : base64Value(clean[index + 2]);
-		const fourth = clean[index + 3] === "=" ? 0 : base64Value(clean[index + 3]);
-		const triple = first << 18 | second << 12 | third << 6 | fourth;
-		if (offset < bytes.byteLength) bytes[offset++] = triple >> 16 & 255;
-		if (offset < bytes.byteLength) bytes[offset++] = triple >> 8 & 255;
-		if (offset < bytes.byteLength) bytes[offset++] = triple & 255;
-	}
-	return bytes;
-}
-function base64Value(char) {
-	if (!char || char === "=") throw new Error("Invalid base64 payload");
-	const value = BASE64_ALPHABET.indexOf(char);
-	if (value === -1) throw new Error("Invalid base64 payload");
-	return value;
-}
-//#endregion
-export { stringifyAgentJson as n, parseAgentJson as t };