@demicodes/agent 0.3.5 → 0.4.0

package/README.md

@@ -8,6 +8,8 @@ that the REPL and web UI both consume.
 - `AgentServer` — owns sessions; `server.client()` returns an in-process client.
 - `AgentClient` — `open` / `send` / `steer` / `abort` / `close` / `subscribe`.
 - Transports: in-process, stdio (`@demicodes/agent/stdio`), or WebSocket.
+- Actions accept caller-defined `metadata` that is available to harness and
+  tool contexts without becoming transcript or provider content.
 
 ```ts
 import { AgentServer } from '@demicodes/agent'

package/dist/client-entry.d.mts

@@ -1,4 +1,4 @@
-import { 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-0l1a6QD9.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C0R8AiHD.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 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 { 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 ShellCommandStatusLike, type TranscriptPatch, createWebSocketClientTransport, createWebSocketServerTransport };
+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-CcSuuo4T.mjs";
+import { n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-DajIApki.mjs";
 export { AgentClient, createWebSocketClientTransport, createWebSocketServerTransport };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentToolInvokeResult, B as TurnRetryPolicy, C as AgentSessionParams, D as AgentTool, E as AgentSystemPromptContext, F as DrainedTranscriptPatches, H as resolveRetryPolicy, I as TranscriptLog, L as TranscriptOptions, M as SessionEvent, N as SessionEventListener, O as AgentToolContext, P as CompactionWindow, R as estimateTranscriptBlockTokens, S as AgentSessionOptions, T as AgentSessionStore, U as retryDelayMs, V as isRetryableCode, _ 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 ShellCommandStatusLike, v as AgentLifecycleEvent, w as AgentSessionRestoreParams, x as AgentSessionCheckpoint, y as AgentPromptContext, z as DEFAULT_TURN_RETRY_POLICY } from "./transport-0l1a6QD9.mjs";
-import { a as AgentClientListener, i as AgentClient, n as createWebSocketClientTransport, r as createWebSocketServerTransport, t as JsonWebSocket } from "./websocket-transport-C0R8AiHD.mjs";
+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 { 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";
@@ -29,6 +29,7 @@ declare class AgentSession<State> {
   private activeTurnId;
   private activeTurnPhase;
   private activeProviderRun;
+  private activeMetadata;
   private readonly steerQueue;
   private readonly yields;
   private readonly compaction;
@@ -49,10 +50,17 @@ declare class AgentSession<State> {
   constructor(params: AgentSessionParams<State>, options?: AgentSessionOptions<State>);
   send(content: UserContentBlock[], options?: {
     id?: string;
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  retry(options?: {
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  resume(options?: {
+    metadata?: AgentMetadata;
+  }): Promise<void>;
+  compact(options?: {
+    metadata?: AgentMetadata;
   }): Promise<void>;
-  retry(): Promise<void>;
-  resume(): Promise<void>;
-  compact(): Promise<void>;
   steer(content: UserContentBlock[], options?: {
     id?: string;
   }): Promise<void>;
@@ -71,7 +79,7 @@ declare class AgentSession<State> {
    */
   updateModel(provider: AgentProvider | null, model: ModelSelection): void;
   abort(): Promise<AbortResult>;
-  scheduleYieldWakeup(durationMs: number): AgentToolInvokeResult;
+  scheduleYieldWakeup(durationMs: number, metadata?: AgentMetadata | null): AgentToolInvokeResult;
   waitUntilDone(): Promise<void>;
   /**
    * Tears the session down: aborts any in-flight turn and releases provider-held resources
@@ -279,4 +287,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, AgentClient, AgentClientListener, AgentClientTransport, AgentDisposeContext, AgentHarness, AgentHarnessContext, AgentHarnessRuntime, AgentLifecycleEvent, 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, 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 };

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-CcSuuo4T.mjs";
+import { a as cloneBlocks, i as applyTranscriptPatches, n as createWebSocketServerTransport, r as AgentClient, t as createWebSocketClientTransport } from "./websocket-transport-DajIApki.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";
@@ -621,14 +621,15 @@ var YieldScheduler = class {
 		return this.pending.length > 0;
 	}
 	/** Registers a new (unarmed) wakeup and returns its id. */
-	schedule(durationMs) {
+	schedule(durationMs, metadata) {
 		const id = this.idFactory();
 		this.pending.push({
 			id,
 			durationMs,
 			timer: null,
 			dueAt: null,
-			armed: false
+			armed: false,
+			metadata
 		});
 		return id;
 	}
@@ -639,7 +640,7 @@ var YieldScheduler = class {
 			if (wakeup.armed) continue;
 			wakeup.armed = true;
 			wakeup.dueAt = now + wakeup.durationMs;
-			wakeup.timer = setTimeout(() => this.onFire(wakeup.id), wakeup.durationMs);
+			wakeup.timer = setTimeout(() => this.onFire(wakeup.id, wakeup.metadata), wakeup.durationMs);
 		}
 	}
 	/** Removes the wakeup with `wakeupId` (clearing its timer); returns whether it existed. */
@@ -1041,7 +1042,8 @@ var ProviderTurnLoop = class {
 					transcript: this.host.transcript,
 					toolCallId: toolCall.toolUseId,
 					toolName: toolCall.toolName,
-					result
+					result,
+					metadata: this.host.metadata
 				});
 				await this.host.commitTranscript();
 				if (!options.deferSteerMaterialization) await this.host.materializeSteersArrivedSince(steerContinuationBeforeTool);
@@ -1064,6 +1066,7 @@ var ProviderTurnLoop = class {
 			model: this.host.model,
 			toolCallId,
 			signal,
+			metadata: this.host.metadata,
 			emitProgress: (progress) => {
 				this.host.emit({
 					type: "tool_progress",
@@ -1097,7 +1100,8 @@ var ProviderTurnLoop = class {
 		return this.host.runtime.tools({
 			agentSessionId: this.host.agentSessionId,
 			state: this.host.agentState,
-			cwd: this.host.cwd
+			cwd: this.host.cwd,
+			metadata: this.host.metadata
 		});
 	}
 	buildInferenceRequest() {
@@ -1163,6 +1167,7 @@ var AgentSession = class AgentSession {
 	activeTurnId = null;
 	activeTurnPhase = null;
 	activeProviderRun = null;
+	activeMetadata = null;
 	steerQueue = new PendingSteerQueue();
 	yields;
 	compaction;
@@ -1204,8 +1209,8 @@ var AgentSession = class AgentSession {
 		this.agentState = params.state === void 0 ? params.runtime.initialState() : params.state;
 		this.agentSessionId = options.agentSessionId ?? createId();
 		this.idFactory = options.idFactory ?? createId;
-		this.yields = new YieldScheduler(this.idFactory, (wakeupId) => {
-			this.deliverYieldWakeup(wakeupId);
+		this.yields = new YieldScheduler(this.idFactory, (wakeupId, metadata) => {
+			this.deliverYieldWakeup(wakeupId, metadata);
 		});
 		this.store = options.store;
 		this.persistIntervalMs = options.persistIntervalMs ?? DEFAULT_PERSIST_INTERVAL_MS;
@@ -1283,6 +1288,9 @@ var AgentSession = class AgentSession {
 			get retryPolicy() {
 				return self.retryPolicy;
 			},
+			get metadata() {
+				return self.activeMetadata;
+			},
 			currentSignal: () => self.currentSignal(),
 			currentTurnId: () => self.currentTurnId(),
 			nextRequestId: () => self.idFactory(),
@@ -1311,27 +1319,31 @@ var AgentSession = class AgentSession {
 			type: "send",
 			id,
 			content,
+			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	retry() {
+	retry(options = {}) {
 		return this.enqueue({
 			type: "retry",
+			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	resume() {
+	resume(options = {}) {
 		return this.enqueue({
 			type: "resume",
+			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
 	}
-	compact() {
+	compact(options = {}) {
 		return this.enqueue({
 			type: "compact",
+			metadata: cloneMetadata(options.metadata),
 			resolve: noop,
 			reject: noop
 		});
@@ -1434,8 +1446,8 @@ var AgentSession = class AgentSession {
 			canAbortAgain: false
 		};
 	}
-	scheduleYieldWakeup(durationMs) {
-		const wakeupId = this.yields.schedule(durationMs);
+	scheduleYieldWakeup(durationMs, metadata = this.activeMetadata) {
+		const wakeupId = this.yields.schedule(durationMs, metadata);
 		return {
 			output: [{
 				type: "text",
@@ -1594,13 +1606,13 @@ var AgentSession = class AgentSession {
 			action.resolve();
 		}
 	}
-	async deliverYieldWakeup(wakeupId) {
+	async deliverYieldWakeup(wakeupId, metadata) {
 		if (!this.yields.take(wakeupId)) return;
 		const content = [{
 			type: "text",
 			text: "Scheduled yield wakeup fired. Continue the previous work and inspect any running command with shell_status when needed."
 		}];
-		if (this.canAcceptInternalSteer()) try {
+		if (metadata === this.activeMetadata && this.canAcceptInternalSteer()) try {
 			await this.steerInternal(content, wakeupId, true);
 			return;
 		} catch (error) {
@@ -1609,7 +1621,7 @@ var AgentSession = class AgentSession {
 				error: asError(error)
 			});
 		}
-		this.enqueueHiddenSend(content);
+		this.enqueueHiddenSend(content, metadata);
 	}
 	canAcceptInternalSteer() {
 		try {
@@ -1641,11 +1653,12 @@ var AgentSession = class AgentSession {
 			hidden
 		});
 	}
-	enqueueHiddenSend(content) {
+	enqueueHiddenSend(content, metadata) {
 		this.enqueue({
 			type: "send",
 			id: this.idFactory(),
 			content,
+			metadata,
 			hidden: true,
 			resolve: noop,
 			reject: noop
@@ -1693,6 +1706,7 @@ var AgentSession = class AgentSession {
 				if (action.type === "send") this.removeQueuedMessage(action.id);
 				this.currentAbortController = new AbortController();
 				this.activeTurnId = action.type === "send" ? action.id : this.idFactory();
+				this.activeMetadata = action.metadata;
 				this.abortRecorded = false;
 				try {
 					await this.executeAction(action);
@@ -1734,6 +1748,7 @@ var AgentSession = class AgentSession {
 					this.discardPendingSteersForCurrentTurn();
 					this.activeTurnPhase = "finalizing";
 					this.activeProviderRun = null;
+					this.activeMetadata = null;
 					this.currentAbortController = null;
 					this.activeTurnId = null;
 					this.activeTurnPhase = null;
@@ -1808,7 +1823,8 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			transcript: this.transcriptLog,
-			content
+			content,
+			metadata: this.activeMetadata
 		});
 		const resolvedContent = await this.resolveReferences(content);
 		await this.applyPendingModelSwitch();
@@ -1827,7 +1843,8 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			cwd: this.cwd,
 			transcript: this.transcriptLog,
-			signal
+			signal,
+			metadata: this.activeMetadata
 		}, content)), signal);
 	}
 	async executeRetry() {
@@ -1839,7 +1856,8 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			transcript: this.transcriptLog,
-			reason: "retry"
+			reason: "retry",
+			metadata: this.activeMetadata
 		});
 		await this.commitTranscript();
 		await this.applyPendingModelSwitch();
@@ -1875,7 +1893,8 @@ var AgentSession = class AgentSession {
 			agentSessionId: this.agentSessionId,
 			state: this.agentState,
 			cwd: this.cwd,
-			transcript: this.transcriptLog
+			transcript: this.transcriptLog,
+			metadata: this.activeMetadata
 		};
 	}
 	currentSignal() {
@@ -2022,6 +2041,9 @@ var AgentSession = class AgentSession {
 function textContentSummary(content) {
 	return truncate(content.map((block) => block.type === "text" ? block.text : `[${block.type}]`).join("\n").trim(), 120, "...");
 }
+function cloneMetadata(metadata) {
+	return metadata === void 0 ? null : structuredClone(metadata);
+}
 async function readProviderIterator(iterator, signal) {
 	try {
 		return await abortable(iterator.next(), signal);
@@ -2621,7 +2643,10 @@ var AgentTransportBindingImpl = class {
 				case "send": {
 					const session = this.sessionFor("send");
 					if (!session) return;
-					this.observeSessionAction(session.send(frame.content, { id: frame.messageId }));
+					this.observeSessionAction(session.send(frame.content, {
+						id: frame.messageId,
+						metadata: frame.metadata
+					}));
 					return;
 				}
 				case "dequeue_message": {
@@ -2714,19 +2739,19 @@ var AgentTransportBindingImpl = class {
 				case "retry": {
 					const session = this.sessionFor("retry");
 					if (!session || this.rejectIfBusy(session, "retry")) return;
-					this.observeSessionAction(session.retry());
+					this.observeSessionAction(session.retry({ metadata: frame.metadata }));
 					return;
 				}
 				case "resume": {
 					const session = this.sessionFor("resume");
 					if (!session || this.rejectIfBusy(session, "resume")) return;
-					this.observeSessionAction(session.resume());
+					this.observeSessionAction(session.resume({ metadata: frame.metadata }));
 					return;
 				}
 				case "compact": {
 					const session = this.sessionFor("compact");
 					if (!session || this.rejectIfBusy(session, "compact")) return;
-					this.observeSessionAction(session.compact());
+					this.observeSessionAction(session.compact({ metadata: frame.metadata }));
 					return;
 				}
 				case "abort": {
@@ -2805,9 +2830,9 @@ var AgentTransportBindingImpl = class {
 		let sessionRef = null;
 		const tools = createStandardAgentTools({
 			environment,
-			scheduleYield: (_ctx, durationMs) => {
+			scheduleYield: (ctx, durationMs) => {
 				if (!sessionRef) throw new Error("AgentServer: session is not ready for yield scheduling");
-				return sessionRef.scheduleYieldWakeup(durationMs);
+				return sessionRef.scheduleYieldWakeup(durationMs, ctx.metadata);
 			}
 		});
 		const commandsPrompt = commandRegistry.renderHelp();

package/dist/stdio-transport.d.mts

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

package/dist/{transport-0l1a6QD9.d.mts → transport-qMjHM60a.d.mts}

@@ -1,3 +1,4 @@
+import { PortableJsonValue } from "@demicodes/utils";
 import { BashAuditEvent, Command, Host, ShellCommandStatus } from "@demicodes/shell";
 import { AgentProvider, InferenceItem, ProviderEvent, ProviderSelection, ToolDefinition } from "@demicodes/provider";
 import { Block, ModelSelection, QueuedMessage, SessionPhase, ToolResultContentBlock, Transcript, UserContentBlock } from "@demicodes/core";
@@ -127,11 +128,14 @@ declare class TranscriptLog implements Transcript {
 declare function estimateTranscriptBlockTokens(block: Block): number;
 //#endregion
 //#region src/types.d.ts
+/** Caller-defined data carried with one agent action. Demi transports it without interpreting it. */
+type AgentMetadata = Readonly<Record<string, PortableJsonValue>>;
 interface AgentPromptContext<State> {
   agentSessionId: string;
   state: State;
   cwd: string;
   transcript: TranscriptLog;
+  metadata: AgentMetadata | null;
 }
 interface AgentSystemPromptContext<State> extends AgentPromptContext<State> {
   /**
@@ -146,6 +150,7 @@ interface AgentToolContext<State> {
   agentSessionId: string;
   state: State;
   cwd: string;
+  metadata: AgentMetadata | null;
 }
 interface AgentDisposeContext<State> {
   agentSessionId: string;
@@ -159,6 +164,7 @@ interface AgentReferenceResolveContext<State> {
   cwd: string;
   transcript: TranscriptLog;
   signal: AbortSignal;
+  metadata: AgentMetadata | null;
 }
 interface AgentHarnessContext<State> {
   state: State;
@@ -182,6 +188,7 @@ interface AgentToolInvokeContext<State> {
   model: ModelSelection;
   toolCallId: string;
   signal: AbortSignal;
+  metadata: AgentMetadata | null;
   emitProgress(progress: unknown): void;
 }
 interface AgentToolInvokeResult {
@@ -206,6 +213,7 @@ type AgentLifecycleEvent<State> = {
   state: State;
   transcript: TranscriptLog;
   content: UserContentBlock[];
+  metadata: AgentMetadata | null;
 } | {
   type: 'after_tool_call';
   agentSessionId: string;
@@ -214,12 +222,14 @@ type AgentLifecycleEvent<State> = {
   toolCallId: string;
   toolName: string;
   result: AgentToolInvokeResult;
+  metadata: AgentMetadata | null;
 } | {
   type: 'after_transcript_rewrite';
   agentSessionId: string;
   state: State;
   transcript: TranscriptLog;
   reason: 'retry';
+  metadata: AgentMetadata | null;
 };
 interface AgentHarnessRuntime<State> {
   harnessName: string;
@@ -322,6 +332,7 @@ type ClientFrame = {
   type: 'send';
   messageId: string;
   content: UserContentBlock[];
+  metadata?: AgentMetadata;
 } | {
   type: 'dequeue_message';
   messageId: string;
@@ -348,10 +359,13 @@ type ClientFrame = {
   type: 'abort';
 } | {
   type: 'retry';
+  metadata?: AgentMetadata;
 } | {
   type: 'resume';
+  metadata?: AgentMetadata;
 } | {
   type: 'compact';
+  metadata?: AgentMetadata;
 } | {
   type: 'shell_write';
   commandId: string;
@@ -528,4 +542,4 @@ interface InProcessTransportPair {
 }
 declare function createInProcessTransportPair(): InProcessTransportPair;
 //#endregion
-export { AgentToolInvokeResult as A, TurnRetryPolicy as B, AgentSessionParams as C, AgentTool as D, AgentSystemPromptContext as E, DrainedTranscriptPatches as F, resolveRetryPolicy as H, TranscriptLog as I, TranscriptOptions as L, SessionEvent as M, SessionEventListener as N, AgentToolContext as O, CompactionWindow as P, estimateTranscriptBlockTokens as R, AgentSessionOptions as S, AgentSessionStore as T, retryDelayMs as U, isRetryableCode as V, AgentHarnessRuntime as _, createInProcessTransportPair as a, AgentReferenceResolveContext as b, ConversationSummary as c, TranscriptPatch as d, AbortResult as f, AgentHarnessContext as g, AgentHarness as h, InProcessTransportPair as i, ExternalMutationReservation as j, AgentToolInvokeContext 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, AgentSessionRestoreParams as w, AgentSessionCheckpoint as x, AgentPromptContext as y, DEFAULT_TURN_RETRY_POLICY as z };
+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 };

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

@@ -1,8 +1,11 @@
-import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport } from "./transport-0l1a6QD9.mjs";
+import { c as ConversationSummary, f as AbortResult, n as AgentServerTransport, s as ClientSessionEvent, t as AgentClientTransport, y as AgentMetadata } from "./transport-qMjHM60a.mjs";
 import { ProviderSelection } from "@demicodes/provider";
 import { Block, UserContentBlock } from "@demicodes/core";
 //#region src/client.d.ts
 type AgentClientListener = (event: ClientSessionEvent) => void;
+interface AgentActionOptions {
+  metadata?: AgentMetadata;
+}
 declare class AgentClient {
   private readonly transport;
   private readonly listeners;
@@ -19,8 +22,8 @@ declare class AgentClient {
   constructor(transport: AgentClientTransport);
   open(provider: ProviderSelection, cwd: string, sessionId: string): Promise<void>;
   listConversations(cwd: string): Promise<ConversationSummary[]>;
-  sendMessage(content: UserContentBlock[]): Promise<void>;
-  send(content: UserContentBlock[]): Promise<void>;
+  sendMessage(content: UserContentBlock[], options?: AgentActionOptions): Promise<void>;
+  send(content: UserContentBlock[], options?: AgentActionOptions): Promise<void>;
   dequeueMessage(messageId: string): void;
   sendQueuedMessage(messageId: string): void;
   steerQueuedMessage(messageId: string, options?: {
@@ -36,9 +39,9 @@ declare class AgentClient {
    * turn (the server applies it at a turn boundary), so this is fire-and-forget.
    */
   setProvider(provider: ProviderSelection): void;
-  retry(): Promise<void>;
-  resume(): Promise<void>;
-  compact(): Promise<void>;
+  retry(options?: AgentActionOptions): Promise<void>;
+  resume(options?: AgentActionOptions): Promise<void>;
+  compact(options?: AgentActionOptions): Promise<void>;
   abort(): Promise<AbortResult>;
   shellWrite(commandId: string, stdin: string): Promise<void>;
   close(): Promise<void>;
@@ -84,4 +87,4 @@ interface JsonWebSocket {
 declare function createWebSocketClientTransport(socket: JsonWebSocket): AgentClientTransport;
 declare function createWebSocketServerTransport(socket: JsonWebSocket): AgentServerTransport;
 //#endregion
-export { AgentClientListener as a, AgentClient as i, createWebSocketClientTransport as n, createWebSocketServerTransport as r, JsonWebSocket as t };
+export { AgentClient as a, AgentActionOptions as i, createWebSocketClientTransport as n, AgentClientListener as o, createWebSocketServerTransport as r, JsonWebSocket as t };

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

@@ -73,18 +73,19 @@ var AgentClient = class {
 			});
 		});
 	}
-	sendMessage(content) {
+	sendMessage(content, options = {}) {
 		const messageId = globalThis.crypto.randomUUID();
 		const wait = this.waitForAction("send", messageId);
 		this.sendFrame({
 			type: "send",
 			messageId,
-			content
+			content,
+			metadata: options.metadata
 		});
 		return wait;
 	}
-	send(content) {
-		return this.sendMessage(content);
+	send(content, options = {}) {
+		return this.sendMessage(content, options);
 	}
 	dequeueMessage(messageId) {
 		this.sendFrame({
@@ -147,19 +148,28 @@ var AgentClient = class {
 			provider
 		});
 	}
-	retry() {
+	retry(options = {}) {
 		const wait = this.waitForAction("retry");
-		this.sendFrame({ type: "retry" });
+		this.sendFrame({
+			type: "retry",
+			metadata: options.metadata
+		});
 		return wait;
 	}
-	resume() {
+	resume(options = {}) {
 		const wait = this.waitForAction("resume");
-		this.sendFrame({ type: "resume" });
+		this.sendFrame({
+			type: "resume",
+			metadata: options.metadata
+		});
 		return wait;
 	}
-	compact() {
+	compact(options = {}) {
 		const wait = this.waitForAction("compact");
-		this.sendFrame({ type: "compact" });
+		this.sendFrame({
+			type: "compact",
+			metadata: options.metadata
+		});
 		return wait;
 	}
 	abort() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@demicodes/agent",
   "description": "Session runtime and transport-neutral client and server protocol for Demi.",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,9 +20,9 @@
   },
   "dependencies": {
     "@demicodes/core": "^0.3.2",
-    "@demicodes/provider": "^0.4.2",
-    "@demicodes/shell": "^0.3.2",
-    "@demicodes/utils": "^0.3.2"
+    "@demicodes/provider": "^0.4.3",
+    "@demicodes/shell": "^0.3.3",
+    "@demicodes/utils": "^0.4.0"
   },
   "license": "Apache-2.0",
   "main": "./dist/index.mjs",