@demicodes/agent 0.5.0 → 0.6.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 ShellCommandStatusLike, y as AgentMetadata } from "./transport-qMjHM60a.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Bf-hWn0D.mjs";
+import { b as AgentMetadata, d as TranscriptPatch, l as ServerFrame, n as AgentServerTransport, o as ClientFrame, r as AgentTransport, s as ClientSessionEvent, t as AgentClientTransport, u as ShellCommandStatusLike } from "./transport-bAa-oKZZ.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-mG7mSLtZ.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 };

package/dist/client-entry.mjs

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

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentToolInvokeContext, B as DEFAULT_TURN_RETRY_POLICY, C as AgentSessionOptions, D as AgentSystemPromptContext, E as AgentSessionStore, F as CompactionWindow, H as isRetryableCode, I as DrainedTranscriptPatches, L as TranscriptLog, M as ExternalMutationReservation, N as SessionEvent, O as AgentTool, P as SessionEventListener, R as TranscriptOptions, S as AgentSessionCheckpoint, T as AgentSessionRestoreParams, U as resolveRetryPolicy, V as TurnRetryPolicy, W as retryDelayMs, _ as AgentHarnessRuntime, a as createInProcessTransportPair, b as AgentPromptContext, c as ConversationSummary, d as TranscriptPatch, f as AbortResult, g as AgentHarnessContext, h as AgentHarness, i as InProcessTransportPair, j as AgentToolInvokeResult, k as AgentToolContext, 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 AgentLifecycleEvent, w as AgentSessionParams, x as AgentReferenceResolveContext, y as AgentMetadata, z as estimateTranscriptBlockTokens } from "./transport-qMjHM60a.mjs";
-import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-Bf-hWn0D.mjs";
+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-bAa-oKZZ.mjs";
+import { a as AgentClient, i as AgentActionOptions, n as createWebSocketClientTransport, o as AgentClientListener, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-mG7mSLtZ.mjs";
 import { BashAuditEvent, BashEnvironment, BashEnvironmentOptions, CommandMetadataRecord, Host, ShellCommandStatus, ShellOutputChunk } from "@demicodes/shell";
 import { AgentProvider, Provider } from "@demicodes/provider";
 import { Block, Model, ModelSelection, QueuedMessage, SessionPhase, UserContentBlock } from "@demicodes/core";
@@ -172,18 +172,18 @@ interface AgentServerSessionOptions {
   persistIntervalMs?: number;
 }
 /**
- * Host-agnostic hook invoked once per `open()` before BashEnvironment is built.
+ * Host-agnostic hook invoked before each resolved Host's BashEnvironment is built.
  * LocalHost uses this to inject PATH / env for the command bridge; AgentServer
  * itself does not know about UDS, shims, or bin directories.
  */
-interface PrepareSessionShellContext {
+interface PrepareShellContext {
   agentSessionId: string;
   host: Host;
   commandNames: readonly string[];
   /** Shell options from AgentServer construction (before this hook). */
   shell: Omit<BashEnvironmentOptions, 'host' | 'commands'>;
 }
-type PrepareSessionShell = (ctx: PrepareSessionShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
+type PrepareShell = (ctx: PrepareShellContext) => Omit<BashEnvironmentOptions, 'host' | 'commands'> | Promise<Omit<BashEnvironmentOptions, 'host' | 'commands'>>;
 interface AgentServerOptions {
   agent: AgentHarness<unknown>;
   providers: Provider[];
@@ -193,7 +193,7 @@ interface AgentServerOptions {
    * Optional host-side shell prep (env, PATH, etc.). Implementation-agnostic —
    * command bridge wiring lives in `@demicodes/host-local`, not here.
    */
-  prepareSessionShell?: PrepareSessionShell;
+  prepareShell?: PrepareShell;
 }
 interface AgentTransportBinding {
   close(): Promise<void>;
@@ -212,9 +212,9 @@ interface RunCommandLineResult {
   stdoutEncoding?: 'base64';
   stderr: string;
 }
-declare class RunCommandLineSessionNotFoundError extends Error {
-  readonly agentSessionId: string;
-  constructor(agentSessionId: string);
+declare class RunCommandLineShellNotFoundError extends Error {
+  readonly shellId: string;
+  constructor(shellId: string);
 }
 declare class RunCommandLineCommandNotRegisteredError extends Error {
   readonly commandName: string;
@@ -231,7 +231,7 @@ declare class AgentServer {
   private readonly providers;
   private readonly shellOptions;
   private readonly sessionOptions;
-  private readonly prepareSessionShell;
+  private readonly prepareShell;
   private readonly bindings;
   private readonly sessionOwnership;
   constructor(options: AgentServerOptions);
@@ -243,12 +243,15 @@ declare class AgentServer {
    * Transport-agnostic: callers (e.g. LocalHost command bridge) supply their
    * own IPC; AgentServer only knows how to exec against the open session shell.
    */
-  runCommandLine(agentSessionId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
+  runCommandLine(shellId: string, name: string, args: string[], opts: RunCommandLineOptions): Promise<RunCommandLineResult>;
 }
 //#endregion
 //#region src/tools.d.ts
 interface StandardAgentToolOptions<State = unknown> {
-  environment: BashEnvironment;
+  environment: BashEnvironment | ((ctx: AgentToolInvokeContext<State>, handle: {
+    shellId?: string;
+    commandId?: string;
+  }) => BashEnvironment | Promise<BashEnvironment>);
   scheduleYield(ctx: AgentToolInvokeContext<State>, durationMs: number): AgentToolInvokeResult;
 }
 declare function createStandardAgentTools<State = unknown>(options: StandardAgentToolOptions<State>): AgentTool<State>[];
@@ -287,4 +290,4 @@ interface ShellToolView {
 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, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, 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_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareSessionShell, PrepareSessionShellContext, RunCommandLineCommandNotRegisteredError, RunCommandLineOptions, RunCommandLineResult, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, ServerFrame, SessionEvent, SessionEventListener, ShellCommandStatusLike, ShellToolResultOptions, ShellToolView, StandardAgentToolOptions, TranscriptLog, TranscriptOptions, TranscriptPatch, TurnRetryPolicy, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AbortResult, AbortTarget, ActiveTurnPhase, AgentActionOptions, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentHostContext, AgentLifecycleEvent, AgentMetadata, AgentPromptContext, AgentReferenceResolveContext, AgentServer, AgentServerOptions, AgentServerSessionOptions, AgentServerTransport, AgentSession, AgentSessionCheckpoint, AgentSessionOptions, AgentSessionParams, AgentSessionRestoreParams, AgentSessionStore, AgentSystemPromptContext, AgentTool, AgentToolContext, AgentToolInvokeContext, AgentToolInvokeResult, AgentTransport, AgentTransportBinding, ClientFrame, ClientSessionEvent, CompactionWindow, ConversationSummary, DEFAULT_TURN_RETRY_POLICY, DrainedTranscriptPatches, ExternalMutationReservation, InProcessTransportPair, JsonWebSocket, PrepareShell, PrepareShellContext, 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, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-DajIApki.mjs";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-DGk5U5EK.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";
@@ -2119,7 +2119,6 @@ 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.";
 const execRepeatStates = /* @__PURE__ */ new WeakMap();
 function createStandardAgentTools(options) {
-	const { environment } = options;
 	return [
 		{
 			name: "shell_exec",
@@ -2144,6 +2143,7 @@ function createStandardAgentTools(options) {
 			},
 			invoke: async (ctx, input) => {
 				const parsed = parseShellExecInput(input);
+				const environment = await resolveEnvironment(options.environment, ctx, { shellId: parsed.shellId });
 				const repeatGuard = repeatedShellExecResult(environment, ctx.agentSessionId, parsed.script);
 				if (repeatGuard) return repeatGuard;
 				const result = await environment.exec({
@@ -2171,7 +2171,9 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
-				const result = await environment.status(parseShellStatusInput(input));
+				const parsed = parseShellStatusInput(input);
+				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
+				const result = await environment.status(parsed);
 				ctx.emitProgress(result);
 				return finishShellToolResult(environment, result, ctx);
 			}
@@ -2193,8 +2195,10 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
+				const parsed = parseShellWriteInput(input);
+				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
 				const result = await environment.write({
-					...parseShellWriteInput(input),
+					...parsed,
 					signal: ctx.signal
 				});
 				ctx.emitProgress(result);
@@ -2217,7 +2221,9 @@ function createStandardAgentTools(options) {
 				}
 			},
 			invoke: async (ctx, input) => {
-				const result = await environment.abort(parseShellAbortInput(input));
+				const parsed = parseShellAbortInput(input);
+				const environment = await resolveEnvironment(options.environment, ctx, { commandId: parsed.commandId });
+				const result = await environment.abort(parsed);
 				ctx.emitProgress(result);
 				return {
 					...await finishShellToolResult(environment, result, ctx),
@@ -2248,6 +2254,9 @@ function createStandardAgentTools(options) {
 		}
 	];
 }
+function resolveEnvironment(source, ctx, handle) {
+	return typeof source === "function" ? source(ctx, handle) : source;
+}
 function shellPreviewBudgetTokens(contextWindow) {
 	return contextWindow >= LARGE_CONTEXT_THRESHOLD_TOKENS ? LARGE_CONTEXT_PREVIEW_TOKENS : SMALL_CONTEXT_PREVIEW_TOKENS;
 }
@@ -2485,12 +2494,12 @@ function shellCommandHandleRequired(result, budgetTokens) {
 }
 //#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 RunCommandLineShellNotFoundError = class extends Error {
+	shellId;
+	constructor(shellId) {
+		super(`runCommandLine: shell "${shellId}" is not open in this process`);
+		this.shellId = shellId;
+		this.name = "RunCommandLineShellNotFoundError";
 	}
 };
 var RunCommandLineCommandNotRegisteredError = class extends Error {
@@ -2518,7 +2527,7 @@ var AgentServer = class {
 	providers;
 	shellOptions;
 	sessionOptions;
-	prepareSessionShell;
+	prepareShell;
 	bindings = /* @__PURE__ */ new Set();
 	sessionOwnership = new SessionOwnershipRegistry();
 	constructor(options) {
@@ -2526,7 +2535,7 @@ var AgentServer = class {
 		this.providers = createProviderMap(options.providers);
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.prepareSessionShell = options.prepareSessionShell ?? null;
+		this.prepareShell = options.prepareShell ?? null;
 	}
 	client() {
 		const transports = createInProcessTransportPair();
@@ -2540,7 +2549,7 @@ var AgentServer = class {
 			providers: this.providers,
 			shell: this.shellOptions,
 			session: this.sessionOptions,
-			prepareSessionShell: this.prepareSessionShell,
+			prepareShell: this.prepareShell,
 			sessions: this.sessionOwnership
 		});
 		this.bindings.add(binding);
@@ -2556,10 +2565,11 @@ var AgentServer = class {
 	* 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);
+	async runCommandLine(shellId, name, args, opts) {
+		const owners = [...this.bindings].filter((binding) => binding.hasShell(shellId));
+		if (owners.length === 0) throw new RunCommandLineShellNotFoundError(shellId);
+		if (owners.length > 1) throw new Error(`runCommandLine: shell id "${shellId}" is not unique`);
+		return owners[0].runCommandLine(shellId, name, args, opts);
 	}
 };
 /**
@@ -2588,11 +2598,13 @@ var AgentTransportBindingImpl = class {
 	providers;
 	shellOptions;
 	sessionOptions;
-	prepareSessionShell;
+	prepareShell;
 	sessions;
 	session = null;
 	currentAgent = null;
-	currentEnvironment = null;
+	environmentsByHost = /* @__PURE__ */ new Map();
+	pendingEnvironmentsByHost = /* @__PURE__ */ new Map();
+	currentCommandRegistry = null;
 	currentCwd = null;
 	currentProviderId = null;
 	currentSessionId = null;
@@ -2606,7 +2618,7 @@ var AgentTransportBindingImpl = class {
 		this.providers = options.providers;
 		this.shellOptions = options.shell ?? {};
 		this.sessionOptions = options.session ?? {};
-		this.prepareSessionShell = options.prepareSessionShell;
+		this.prepareShell = options.prepareShell;
 		this.sessions = options.sessions;
 		this.unsubscribeTransport = this.transport.onFrame((frame) => {
 			this.handleFrame(frame);
@@ -2800,11 +2812,10 @@ var AgentTransportBindingImpl = class {
 		await this.sessions.claim(agentSessionId, this);
 		this.currentSessionId = agentSessionId;
 		const initialState = agent.initialState();
-		const provisionalHost = agent.host({
+		const store = new HostAgentSessionStore((await agent.host({
 			state: initialState,
 			cwd: frame.cwd
-		});
-		const store = new HostAgentSessionStore(provisionalHost.store, agentSessionId);
+		})).store, agentSessionId);
 		const checkpoint = await store.loadCheckpoint();
 		const restoring = checkpoint !== null && checkpoint.harnessName === agent.name;
 		const state = restoring ? structuredClone(checkpoint.state) : initialState;
@@ -2812,24 +2823,13 @@ var AgentTransportBindingImpl = class {
 			state,
 			cwd: frame.cwd
 		};
-		const host = restoring ? agent.host(harnessContext) : provisionalHost;
 		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.prepareSessionShell ? await this.prepareSessionShell({
-				agentSessionId,
-				host,
-				commandNames,
-				shell: this.shellOptions
-			}) : this.shellOptions,
-			host,
-			commands: commandRegistry
-		});
 		let sessionRef = null;
 		const tools = createStandardAgentTools({
-			environment,
+			environment: (ctx, handle) => this.resolveEnvironment(ctx, handle),
 			scheduleYield: (ctx, durationMs) => {
 				if (!sessionRef) throw new Error("AgentServer: session is not ready for yield scheduling");
 				return sessionRef.scheduleYieldWakeup(durationMs, ctx.metadata);
@@ -2873,7 +2873,7 @@ var AgentTransportBindingImpl = class {
 		sessionRef = session;
 		this.session = session;
 		this.currentAgent = agent;
-		this.currentEnvironment = environment;
+		this.currentCommandRegistry = commandRegistry;
 		this.currentCwd = frame.cwd;
 		this.currentProviderId = frame.provider.providerId;
 		this.currentCommandNames = new Set(commandNames);
@@ -2962,11 +2962,13 @@ var AgentTransportBindingImpl = class {
 	async closeSession() {
 		const session = this.session;
 		const agent = this.currentAgent;
-		const environment = this.currentEnvironment;
 		const cwd = this.currentCwd;
 		try {
 			if (session) await session.dispose();
-			if (environment) await environment.disposeAllShells();
+			const pendingEnvironments = await Promise.allSettled(this.pendingEnvironmentsByHost.values());
+			const environments = new Set(this.environmentsByHost.values());
+			for (const result of pendingEnvironments) if (result.status === "fulfilled") environments.add(result.value);
+			await Promise.all([...environments].map((environment) => environment.disposeAllShells()));
 			if (session && agent && cwd) await agent.dispose?.({
 				agentSessionId: session.id(),
 				state: session.state(),
@@ -2978,7 +2980,9 @@ var AgentTransportBindingImpl = class {
 			this.unsubscribeSession = null;
 			this.session = null;
 			this.currentAgent = null;
-			this.currentEnvironment = null;
+			this.environmentsByHost.clear();
+			this.pendingEnvironmentsByHost.clear();
+			this.currentCommandRegistry = null;
 			this.currentCwd = null;
 			this.currentProviderId = null;
 			this.currentCommandNames = /* @__PURE__ */ new Set();
@@ -2989,7 +2993,7 @@ var AgentTransportBindingImpl = class {
 		}
 	}
 	async listConversations(cwd) {
-		const host = this.agent.host({
+		const host = await this.agent.host({
 			state: this.agent.initialState(),
 			cwd
 		});
@@ -3008,16 +3012,22 @@ var AgentTransportBindingImpl = class {
 		});
 	}
 	async handleShellWrite(frame) {
-		if (!this.sessionFor("shell_write") || !this.currentEnvironment || !this.currentCwd) return;
-		const result = await this.currentEnvironment.write({
+		const session = this.sessionFor("shell_write");
+		if (!session || !this.currentCwd) return;
+		const result = await (await this.resolveEnvironment({
+			agentSessionId: session.id(),
+			state: session.state(),
+			cwd: this.currentCwd,
+			metadata: frame.metadata ?? null
+		}, { commandId: frame.commandId })).write({
 			commandId: frame.commandId,
 			stdin: frame.stdin
 		});
 		this.sendShellWriteResult(frame.commandId, result);
 	}
 	/** Backs `AgentServer.runCommandLine` — see its doc comment for the contract. */
-	async runCommandLine(name, args, opts) {
-		const environment = this.currentEnvironment;
+	async runCommandLine(shellId, name, args, opts) {
+		const environment = this.environmentForShell(shellId);
 		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);
@@ -3059,6 +3069,66 @@ var AgentTransportBindingImpl = class {
 			await environment.disposeShell(result.shellId).catch(() => {});
 		}
 	}
+	hasShell(shellId) {
+		return this.environmentForShell(shellId) !== null;
+	}
+	async resolveEnvironment(ctx, handle) {
+		const agent = this.currentAgent;
+		const commandRegistry = this.currentCommandRegistry;
+		if (!agent || !commandRegistry) throw new Error("Shell environment is not available before session open");
+		const host = await agent.host({
+			agentSessionId: ctx.agentSessionId,
+			state: ctx.state,
+			cwd: ctx.cwd,
+			metadata: ctx.metadata
+		});
+		const environment = await this.environmentForHost(host, commandRegistry);
+		const owner = handle.shellId ? this.environmentForShell(handle.shellId) : handle.commandId ? this.environmentForCommand(handle.commandId) : null;
+		if (owner && owner !== environment) {
+			const id = handle.shellId ?? handle.commandId;
+			throw new Error(`Shell handle "${id}" belongs to a different Host`);
+		}
+		return environment;
+	}
+	async environmentForHost(host, commands) {
+		const existing = this.environmentsByHost.get(host);
+		if (existing) return existing;
+		const pending = this.pendingEnvironmentsByHost.get(host);
+		if (pending) return pending;
+		const creation = this.createEnvironment(host, commands);
+		this.pendingEnvironmentsByHost.set(host, creation);
+		try {
+			const environment = await creation;
+			this.environmentsByHost.set(host, environment);
+			return environment;
+		} finally {
+			this.pendingEnvironmentsByHost.delete(host);
+		}
+	}
+	async createEnvironment(host, commands) {
+		const agentSessionId = this.currentSessionId;
+		if (!agentSessionId) throw new Error("Shell environment is not available before session open");
+		return new BashEnvironment({
+			...this.prepareShell ? await this.prepareShell({
+				agentSessionId,
+				host,
+				commandNames: commands.list().map((command) => command.name),
+				shell: this.shellOptions
+			}) : this.shellOptions,
+			host,
+			commands
+		});
+	}
+	environmentForShell(shellId) {
+		const matches = [...this.environmentsByHost.values()].filter((environment) => environment.getShell(shellId));
+		if (matches.length > 1) throw new Error(`Shell id "${shellId}" is not unique in this session`);
+		return matches[0] ?? null;
+	}
+	environmentForCommand(commandId) {
+		const matches = [...this.environmentsByHost.values()].filter((environment) => environment.hasCommand(commandId));
+		if (matches.length > 1) throw new Error(`Command id "${commandId}" is not unique in this session`);
+		return matches[0] ?? null;
+	}
 	sessionFor(command) {
 		if (!this.session) {
 			this.send({
@@ -3224,4 +3294,4 @@ function createProviderMap(providers) {
 	return map;
 }
 //#endregion
-export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineCommandNotRegisteredError, RunCommandLineSessionNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };
+export { AgentClient, AgentServer, AgentSession, DEFAULT_TURN_RETRY_POLICY, RunCommandLineCommandNotRegisteredError, RunCommandLineShellNotFoundError, RunCommandLineTimeoutError, SHELL_VIEW_MAX_CHARS, TranscriptLog, applyTranscriptPatches, cloneBlocks, createInProcessTransportPair, createStandardAgentTools, createWebSocketClientTransport, createWebSocketServerTransport, estimateTranscriptBlockTokens, finishShellToolResult, isRetryableCode, resolveRetryPolicy, retryDelayMs, shellCommandHandleRequired, shellPreviewBudgetTokens, toShellToolResult };

package/dist/stdio-transport.d.mts

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

package/dist/{transport-qMjHM60a.d.mts → transport-bAa-oKZZ.d.mts}

@@ -170,10 +170,16 @@ interface AgentHarnessContext<State> {
   state: State;
   cwd: string;
 }
+/** Context used when a shell operation resolves its action-specific Host. */
+interface AgentHostContext<State> extends AgentHarnessContext<State> {
+  agentSessionId: string;
+  metadata: AgentMetadata | null;
+}
 interface AgentHarness<State = unknown> {
   name: string;
   initialState(): State;
-  host(ctx: AgentHarnessContext<State>): Host;
+  /** Return the same Host object for calls that target the same execution environment. */
+  host(ctx: AgentHarnessContext<State> | AgentHostContext<State>): Host | Promise<Host>;
   commands?(ctx: AgentHarnessContext<State>): Command[];
   systemPrompt(ctx: AgentSystemPromptContext<State>): string;
   preamble?(ctx: AgentPromptContext<State>): string | null;
@@ -370,6 +376,7 @@ type ClientFrame = {
   type: 'shell_write';
   commandId: string;
   stdin: string;
+  metadata?: AgentMetadata;
 } | {
   type: 'list_conversations';
   cwd: string;
@@ -542,4 +549,4 @@ interface InProcessTransportPair {
 }
 declare function createInProcessTransportPair(): InProcessTransportPair;
 //#endregion
-export { AgentToolInvokeContext as A, DEFAULT_TURN_RETRY_POLICY as B, AgentSessionOptions as C, AgentSystemPromptContext as D, AgentSessionStore as E, CompactionWindow as F, isRetryableCode as H, DrainedTranscriptPatches as I, TranscriptLog as L, ExternalMutationReservation as M, SessionEvent as N, AgentTool as O, SessionEventListener as P, TranscriptOptions as R, AgentSessionCheckpoint as S, AgentSessionRestoreParams as T, resolveRetryPolicy as U, TurnRetryPolicy as V, retryDelayMs as W, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentPromptContext as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, AgentToolInvokeResult as j, AgentToolContext as k, ServerFrame as l, AgentDisposeContext as m, AgentServerTransport as n, ClientFrame as o, AbortTarget as p, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandStatusLike as u, AgentLifecycleEvent as v, AgentSessionParams as w, AgentReferenceResolveContext as x, AgentMetadata as y, estimateTranscriptBlockTokens as z };
+export { AgentToolContext as A, estimateTranscriptBlockTokens as B, AgentSessionCheckpoint as C, AgentSessionStore as D, AgentSessionRestoreParams as E, SessionEventListener as F, retryDelayMs as G, TurnRetryPolicy as H, CompactionWindow as I, DrainedTranscriptPatches as L, AgentToolInvokeResult as M, ExternalMutationReservation as N, AgentSystemPromptContext as O, SessionEvent as P, TranscriptLog as R, AgentReferenceResolveContext as S, AgentSessionParams as T, isRetryableCode as U, DEFAULT_TURN_RETRY_POLICY as V, resolveRetryPolicy as W, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentMetadata as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, AgentToolInvokeContext as j, AgentTool as k, ServerFrame as l, AgentDisposeContext as m, AgentServerTransport as n, ClientFrame as o, AbortTarget as p, AgentTransport as r, ClientSessionEvent as s, AgentClientTransport as t, ShellCommandStatusLike as u, AgentHostContext as v, AgentSessionOptions as w, AgentPromptContext as x, AgentLifecycleEvent as y, TranscriptOptions as z };

package/dist/{websocket-transport-DajIApki.mjs → websocket-transport-DGk5U5EK.mjs}

@@ -177,12 +177,13 @@ var AgentClient = class {
 		this.sendFrame({ type: "abort" });
 		return wait;
 	}
-	shellWrite(commandId, stdin) {
+	shellWrite(commandId, stdin, options = {}) {
 		const wait = this.waitForShellWrite(commandId);
 		this.sendFrame({
 			type: "shell_write",
 			commandId,
-			stdin
+			stdin,
+			metadata: options.metadata
 		});
 		return wait;
 	}

package/dist/{websocket-transport-Bf-hWn0D.d.mts → websocket-transport-mG7mSLtZ.d.mts}

@@ -1,4 +1,4 @@
-import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport, y as AgentMetadata } from "./transport-qMjHM60a.mjs";
+import { b as AgentMetadata, c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-bAa-oKZZ.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
 //#region src/client.d.ts
@@ -43,7 +43,7 @@ declare class AgentClient {
   resume(options?: AgentActionOptions): Promise<void>;
   compact(options?: AgentActionOptions): Promise<void>;
   abort(): Promise<AbortResult>;
-  shellWrite(commandId: string, stdin: string): Promise<void>;
+  shellWrite(commandId: string, stdin: string, options?: AgentActionOptions): Promise<void>;
   close(): Promise<void>;
   subscribe(listener: AgentClientListener): () => void;
   transcript(): {

package/package.json

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