@minpeter/pss-runtime 0.1.0-next.0 → 0.1.0-next.2

package/dist/agent-loop.js

@@ -1,53 +1,36 @@
 import { modelMessageToAgentEvents } from "./session/mapping.js";
 //#region src/agent-loop.ts
-async function runAgentLoop({ emit, history, llm, signal = new AbortController().signal, stepLifecycle }) {
-	let stepIndex = 0;
+async function runAgentLoop({ captureObserverEvents = captureNoObserverEvents, emit, history, llm, signal = new AbortController().signal, toolExecution }) {
 	while (true) {
-		if (signal.aborted) return "aborted";
-		await stepLifecycle?.beforeStep?.({
-			history: history.modelSnapshot(),
-			signal,
-			stepIndex
-		});
 		if (signal.aborted) return "aborted";
 		if (await emitBoundary({
 			emit,
 			event: { type: "step-start" },
 			signal
 		}) === "aborted") return "aborted";
-		await stepLifecycle?.beforeInference?.({
-			history: history.modelSnapshot(),
-			signal,
-			stepIndex
-		});
-		if (signal.aborted) return "aborted";
-		const output = await readLlmOutput({
+		const capturedOutput = await captureObserverEvents(() => readLlmOutput({
 			history,
 			llm,
-			signal
-		});
+			signal,
+			toolExecution
+		}));
+		const output = capturedOutput.value;
 		if (output === "aborted") return "aborted";
-		const result = appendStepOutput({
+		const result = await appendCapturedStepOutput({
+			capturedOutput,
 			emit,
 			history,
 			output,
 			signal
 		});
 		if (result === "aborted") return "aborted";
-		await runAfterStepLifecycle(stepLifecycle, {
-			history: history.modelSnapshot(),
-			result,
-			signal,
-			stepIndex
-		});
 		const stepEndDecision = await emitBoundary({
 			emit,
 			event: { type: "step-end" },
 			signal
 		});
 		if (stepEndDecision === "aborted") return "aborted";
-		if (result === "completed" && !stepEndDecision?.runtimeInputAdded && !stepEndDecision?.overlayInputAdded) return "completed";
-		stepIndex += 1;
+		if (result === "completed" && !stepEndDecision?.runtimeInputAdded) return "completed";
 	}
 }
 async function emitBoundary({ emit, event, signal }) {
@@ -74,34 +57,75 @@ function createAbortBoundary(signal) {
 		promise
 	};
 }
-async function runAfterStepLifecycle(stepLifecycle, context) {
-	const afterStep = stepLifecycle?.afterStep;
-	if (!afterStep) return;
-	await Promise.allSettled([Promise.resolve().then(() => afterStep(context))]);
+async function captureNoObserverEvents(callback) {
+	return {
+		events: [],
+		release: releaseNoObserverEvents,
+		value: await callback()
+	};
 }
-async function readLlmOutput({ history, llm, signal }) {
+function releaseNoObserverEvents() {}
+async function readLlmOutput({ history, llm, signal, toolExecution }) {
 	try {
 		return await llm({
 			history: history.modelSnapshot(),
-			signal
+			signal,
+			toolExecution
 		});
 	} catch (error) {
 		if (signal.aborted) return "aborted";
 		throw error;
 	}
 }
-function appendStepOutput({ emit, history, output, signal }) {
+async function appendCapturedStepOutput({ capturedOutput, emit, history, output, signal }) {
+	try {
+		return await appendStepOutput({
+			emit,
+			history,
+			observerEvents: capturedOutput.events,
+			output,
+			signal
+		});
+	} finally {
+		capturedOutput.release();
+	}
+}
+async function appendStepOutput({ emit, history, observerEvents, output, signal }) {
 	if (signal.aborted) return "aborted";
 	let shouldContinue = false;
+	const pendingObserverEvents = observerEvents;
+	const flushObserverEvents = async (shouldFlush = () => true) => {
+		for (let index = 0; index < pendingObserverEvents.length;) {
+			const event = pendingObserverEvents[index];
+			if (!(event && shouldFlush(event))) {
+				index += 1;
+				continue;
+			}
+			pendingObserverEvents.splice(index, 1);
+			await emit(event);
+		}
+	};
 	for (const message of output) {
 		if (signal.aborted) return "aborted";
 		history.appendModelMessage(message);
 		const events = modelMessageToAgentEvents(message);
-		for (const event of events) emit(event);
-		if (events.some((event) => event.type === "tool-call")) shouldContinue = true;
+		const hasToolResult = events.some((event) => event.type === "tool-result");
+		for (const event of events) {
+			await emit(event);
+			if (event.type === "tool-call") {
+				shouldContinue = true;
+				await flushObserverEvents(isLaunchOrBlockingObserverEvent);
+			}
+		}
+		if (hasToolResult) await flushObserverEvents();
 	}
+	await flushObserverEvents();
 	return shouldContinue ? "continue" : "completed";
 }
+function isLaunchOrBlockingObserverEvent(event) {
+	if (event.type === "subagent-job-update") return false;
+	return !(event.type === "subagent-job-end" && event.task_id);
+}
 //#endregion
 export { runAgentLoop };
 

package/dist/agent-loop.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.js","names":[],"sources":["../src/agent-loop.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport type { Llm, LlmOutput } from \"./llm\";\nimport type { AgentEvent, AgentEventListener } from \"./session/events\";\nimport { modelMessageToAgentEvents } from \"./session/mapping\";\n\ntype MaybePromise<T> = Promise<T> | T;\n\ninterface ModelHistory {\n  appendModelMessage(message: ModelMessage): void;\n  modelSnapshot(): ModelMessage[];\n}\n\ninterface RunAgentLoopOptions {\n  emit: AgentLoopEventListener;\n  history: ModelHistory;\n  llm: Llm;\n  signal?: AbortSignal;\n  stepLifecycle?: AgentStepLifecycle;\n}\n\nexport type AgentLoopResult = \"completed\" | \"aborted\";\nexport type AgentStepResult = \"completed\" | \"continue\";\nexport interface AgentBeforeStepContext {\n  readonly history: readonly ModelMessage[];\n  readonly signal: AbortSignal;\n  readonly stepIndex: number;\n}\nexport interface AgentAfterStepContext extends AgentBeforeStepContext {\n  readonly result: AgentStepResult;\n}\nexport interface AgentStepLifecycle {\n  afterStep?(context: AgentAfterStepContext): MaybePromise<void>;\n  beforeInference?(context: AgentBeforeStepContext): MaybePromise<void>;\n  beforeStep?(context: AgentBeforeStepContext): MaybePromise<void>;\n}\ntype AgentLoopBoundaryEvent = Extract<\n  AgentEvent,\n  { type: \"step-end\" } | { type: \"step-start\" }\n>;\ninterface AgentLoopBoundaryDecision {\n  readonly overlayInputAdded?: boolean;\n  readonly runtimeInputAdded?: boolean;\n}\ntype AgentLoopEventListener = (\n  event: AgentEvent\n) =>\n  | AgentLoopBoundaryDecision\n  | Promise<AgentLoopBoundaryDecision | undefined>\n  | undefined;\ntype StepOutputResult = AgentStepResult | \"aborted\";\n\nexport async function runAgentLoop({\n  emit,\n  history,\n  llm,\n  signal = new AbortController().signal,\n  stepLifecycle,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  let stepIndex = 0;\n\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    await stepLifecycle?.beforeStep?.({\n      history: history.modelSnapshot(),\n      signal,\n      stepIndex,\n    });\n\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    const stepStartDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-start\" },\n      signal,\n    });\n\n    if (stepStartDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    await stepLifecycle?.beforeInference?.({\n      history: history.modelSnapshot(),\n      signal,\n      stepIndex,\n    });\n\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    const output = await readLlmOutput({ history, llm, signal });\n\n    if (output === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const result = appendStepOutput({ emit, history, output, signal });\n\n    if (result === \"aborted\") {\n      return \"aborted\";\n    }\n\n    await runAfterStepLifecycle(stepLifecycle, {\n      history: history.modelSnapshot(),\n      result,\n      signal,\n      stepIndex,\n    });\n\n    const stepEndDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-end\" },\n      signal,\n    });\n\n    if (stepEndDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    // Runtime input after step-end intentionally forces another inference step,\n    // even after final-looking assistant text. Unconditional insertion on every\n    // step-end can create an unbounded loop.\n    if (\n      result === \"completed\" &&\n      !stepEndDecision?.runtimeInputAdded &&\n      !stepEndDecision?.overlayInputAdded\n    ) {\n      return \"completed\";\n    }\n\n    stepIndex += 1;\n  }\n}\n\nasync function emitBoundary({\n  emit,\n  event,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & {\n  event: AgentLoopBoundaryEvent;\n  signal: AbortSignal;\n}): Promise<AgentLoopBoundaryDecision | \"aborted\" | undefined> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  const abort = createAbortBoundary(signal);\n  try {\n    return await Promise.race([Promise.resolve(emit(event)), abort.promise]);\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  } finally {\n    abort.dispose();\n  }\n}\n\nfunction createAbortBoundary(signal: AbortSignal): {\n  dispose: () => void;\n  promise: Promise<\"aborted\">;\n} {\n  let dispose: () => void = () => undefined;\n\n  const promise = new Promise<\"aborted\">((resolve) => {\n    const onAbort = () => resolve(\"aborted\");\n    dispose = () => signal.removeEventListener(\"abort\", onAbort);\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n  });\n\n  return { dispose, promise };\n}\n\nasync function runAfterStepLifecycle(\n  stepLifecycle: AgentStepLifecycle | undefined,\n  context: AgentAfterStepContext\n): Promise<void> {\n  const afterStep = stepLifecycle?.afterStep;\n  if (!afterStep) {\n    return;\n  }\n\n  await Promise.allSettled([Promise.resolve().then(() => afterStep(context))]);\n}\n\nasync function readLlmOutput({\n  history,\n  llm,\n  signal,\n}: Pick<RunAgentLoopOptions, \"history\" | \"llm\"> & {\n  signal: AbortSignal;\n}): Promise<LlmOutput | \"aborted\"> {\n  try {\n    return await llm({ history: history.modelSnapshot(), signal });\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  }\n}\n\nfunction appendStepOutput({\n  emit,\n  history,\n  output,\n  signal,\n}: { emit: AgentEventListener; history: ModelHistory } & {\n  output: LlmOutput;\n  signal: AbortSignal;\n}): StepOutputResult {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  let shouldContinue = false;\n\n  for (const message of output) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    history.appendModelMessage(message);\n    const events = modelMessageToAgentEvents(message);\n\n    for (const event of events) {\n      emit(event);\n    }\n\n    if (events.some((event) => event.type === \"tool-call\")) {\n      shouldContinue = true;\n    }\n  }\n\n  return shouldContinue ? \"continue\" : \"completed\";\n}\n"],"mappings":";;AAmDA,eAAsB,aAAa,EACjC,MACA,SACA,KACA,SAAS,IAAI,gBAAgB,EAAE,QAC/B,iBACgD;CAChD,IAAI,YAAY;CAEhB,OAAO,MAAM;EACX,IAAI,OAAO,SACT,OAAO;EAGT,MAAM,eAAe,aAAa;GAChC,SAAS,QAAQ,cAAc;GAC/B;GACA;EACF,CAAC;EAED,IAAI,OAAO,SACT,OAAO;EAST,IAAI,MAN4B,aAAa;GAC3C;GACA,OAAO,EAAE,MAAM,aAAa;GAC5B;EACF,CAAC,MAEyB,WACxB,OAAO;EAGT,MAAM,eAAe,kBAAkB;GACrC,SAAS,QAAQ,cAAc;GAC/B;GACA;EACF,CAAC;EAED,IAAI,OAAO,SACT,OAAO;EAGT,MAAM,SAAS,MAAM,cAAc;GAAE;GAAS;GAAK;EAAO,CAAC;EAE3D,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,SAAS,iBAAiB;GAAE;GAAM;GAAS;GAAQ;EAAO,CAAC;EAEjE,IAAI,WAAW,WACb,OAAO;EAGT,MAAM,sBAAsB,eAAe;GACzC,SAAS,QAAQ,cAAc;GAC/B;GACA;GACA;EACF,CAAC;EAED,MAAM,kBAAkB,MAAM,aAAa;GACzC;GACA,OAAO,EAAE,MAAM,WAAW;GAC1B;EACF,CAAC;EAED,IAAI,oBAAoB,WACtB,OAAO;EAMT,IACE,WAAW,eACX,CAAC,iBAAiB,qBAClB,CAAC,iBAAiB,mBAElB,OAAO;EAGT,aAAa;CACf;AACF;AAEA,eAAe,aAAa,EAC1B,MACA,OACA,UAI6D;CAC7D,IAAI,OAAO,SACT,OAAO;CAGT,MAAM,QAAQ,oBAAoB,MAAM;CACxC,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,QAAQ,QAAQ,KAAK,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC;CACzE,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR,UAAU;EACR,MAAM,QAAQ;CAChB;AACF;AAEA,SAAS,oBAAoB,QAG3B;CACA,IAAI,gBAA4B,KAAA;CAEhC,MAAM,UAAU,IAAI,SAAoB,YAAY;EAClD,MAAM,gBAAgB,QAAQ,SAAS;EACvC,gBAAgB,OAAO,oBAAoB,SAAS,OAAO;EAC3D,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;CAC1D,CAAC;CAED,OAAO;EAAE;EAAS;CAAQ;AAC5B;AAEA,eAAe,sBACb,eACA,SACe;CACf,MAAM,YAAY,eAAe;CACjC,IAAI,CAAC,WACH;CAGF,MAAM,QAAQ,WAAW,CAAC,QAAQ,QAAQ,EAAE,WAAW,UAAU,OAAO,CAAC,CAAC,CAAC;AAC7E;AAEA,eAAe,cAAc,EAC3B,SACA,KACA,UAGiC;CACjC,IAAI;EACF,OAAO,MAAM,IAAI;GAAE,SAAS,QAAQ,cAAc;GAAG;EAAO,CAAC;CAC/D,SAAS,OAAO;EACd,IAAI,OAAO,SACT,OAAO;EAGT,MAAM;CACR;AACF;AAEA,SAAS,iBAAiB,EACxB,MACA,SACA,QACA,UAImB;CACnB,IAAI,OAAO,SACT,OAAO;CAGT,IAAI,iBAAiB;CAErB,KAAK,MAAM,WAAW,QAAQ;EAC5B,IAAI,OAAO,SACT,OAAO;EAGT,QAAQ,mBAAmB,OAAO;EAClC,MAAM,SAAS,0BAA0B,OAAO;EAEhD,KAAK,MAAM,SAAS,QAClB,KAAK,KAAK;EAGZ,IAAI,OAAO,MAAM,UAAU,MAAM,SAAS,WAAW,GACnD,iBAAiB;CAErB;CAEA,OAAO,iBAAiB,aAAa;AACvC"}
+{"version":3,"file":"agent-loop.js","names":[],"sources":["../src/agent-loop.ts"],"sourcesContent":["import type { ModelMessage } from \"ai\";\nimport type { RuntimeLlm, RuntimeLlmOutput } from \"./llm\";\nimport type { RuntimeToolExecutionContext } from \"./llm-tool-execution\";\nimport type { AgentEvent } from \"./session/events\";\nimport { modelMessageToAgentEvents } from \"./session/mapping\";\n\ninterface ModelHistory {\n  appendModelMessage(message: ModelMessage): void;\n  modelSnapshot(): ModelMessage[];\n}\n\ninterface RunAgentLoopOptions {\n  captureObserverEvents?: ObserverEventCapture;\n  emit: AgentLoopEventListener;\n  history: ModelHistory;\n  llm: RuntimeLlm;\n  signal?: AbortSignal;\n  toolExecution?: RuntimeToolExecutionContext;\n}\n\ntype AgentLoopResult = \"completed\" | \"aborted\";\ntype AgentLoopBoundaryEvent = Extract<\n  AgentEvent,\n  { type: \"step-end\" } | { type: \"step-start\" }\n>;\ninterface AgentLoopBoundaryDecision {\n  readonly runtimeInputAdded?: boolean;\n}\ntype AgentLoopEventListener = (\n  event: AgentEvent\n) =>\n  | AgentLoopBoundaryDecision\n  | Promise<AgentLoopBoundaryDecision | undefined>\n  | undefined;\ntype StepOutputResult = \"aborted\" | \"completed\" | \"continue\";\ninterface ObserverEventCaptureResult<T> {\n  readonly events: AgentEvent[];\n  readonly release: () => void;\n  readonly value: T;\n}\ntype ObserverEventCapture = <T>(\n  callback: () => Promise<T>\n) => Promise<ObserverEventCaptureResult<T>>;\n\nexport async function runAgentLoop({\n  captureObserverEvents = captureNoObserverEvents,\n  emit,\n  history,\n  llm,\n  signal = new AbortController().signal,\n  toolExecution,\n}: RunAgentLoopOptions): Promise<AgentLoopResult> {\n  while (true) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    const stepStartDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-start\" },\n      signal,\n    });\n\n    if (stepStartDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const capturedOutput = await captureObserverEvents(() =>\n      readLlmOutput({ history, llm, signal, toolExecution })\n    );\n    const output = capturedOutput.value;\n\n    if (output === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const result = await appendCapturedStepOutput({\n      capturedOutput,\n      emit,\n      history,\n      output,\n      signal,\n    });\n\n    if (result === \"aborted\") {\n      return \"aborted\";\n    }\n\n    const stepEndDecision = await emitBoundary({\n      emit,\n      event: { type: \"step-end\" },\n      signal,\n    });\n\n    if (stepEndDecision === \"aborted\") {\n      return \"aborted\";\n    }\n\n    // Runtime input after step-end intentionally forces another inference step,\n    // even after final-looking assistant text. Unconditional insertion on every\n    // step-end can create an unbounded loop.\n    if (result === \"completed\" && !stepEndDecision?.runtimeInputAdded) {\n      return \"completed\";\n    }\n  }\n}\n\nasync function emitBoundary({\n  emit,\n  event,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & {\n  event: AgentLoopBoundaryEvent;\n  signal: AbortSignal;\n}): Promise<AgentLoopBoundaryDecision | \"aborted\" | undefined> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  const abort = createAbortBoundary(signal);\n  try {\n    return await Promise.race([Promise.resolve(emit(event)), abort.promise]);\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  } finally {\n    abort.dispose();\n  }\n}\n\nfunction createAbortBoundary(signal: AbortSignal): {\n  dispose: () => void;\n  promise: Promise<\"aborted\">;\n} {\n  let dispose: () => void = () => undefined;\n\n  const promise = new Promise<\"aborted\">((resolve) => {\n    const onAbort = () => resolve(\"aborted\");\n    dispose = () => signal.removeEventListener(\"abort\", onAbort);\n    signal.addEventListener(\"abort\", onAbort, { once: true });\n  });\n\n  return { dispose, promise };\n}\n\nasync function captureNoObserverEvents<T>(callback: () => Promise<T>): Promise<{\n  readonly events: AgentEvent[];\n  readonly release: () => void;\n  readonly value: T;\n}> {\n  return {\n    events: [],\n    release: releaseNoObserverEvents,\n    value: await callback(),\n  };\n}\n\nfunction releaseNoObserverEvents(): void {\n  return;\n}\n\nasync function readLlmOutput({\n  history,\n  llm,\n  signal,\n  toolExecution,\n}: Pick<RunAgentLoopOptions, \"history\" | \"llm\"> & {\n  signal: AbortSignal;\n  toolExecution?: RuntimeToolExecutionContext;\n}): Promise<RuntimeLlmOutput | \"aborted\"> {\n  try {\n    return await llm({\n      history: history.modelSnapshot(),\n      signal,\n      toolExecution,\n    });\n  } catch (error) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    throw error;\n  }\n}\n\nasync function appendCapturedStepOutput({\n  capturedOutput,\n  emit,\n  history,\n  output,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & { history: ModelHistory } & {\n  capturedOutput: ObserverEventCaptureResult<RuntimeLlmOutput | \"aborted\">;\n  output: RuntimeLlmOutput;\n  signal: AbortSignal;\n}): Promise<StepOutputResult> {\n  try {\n    return await appendStepOutput({\n      emit,\n      history,\n      observerEvents: capturedOutput.events,\n      output,\n      signal,\n    });\n  } finally {\n    capturedOutput.release();\n  }\n}\n\nasync function appendStepOutput({\n  emit,\n  history,\n  observerEvents,\n  output,\n  signal,\n}: Pick<RunAgentLoopOptions, \"emit\"> & { history: ModelHistory } & {\n  observerEvents: AgentEvent[];\n  output: RuntimeLlmOutput;\n  signal: AbortSignal;\n}): Promise<StepOutputResult> {\n  if (signal.aborted) {\n    return \"aborted\";\n  }\n\n  let shouldContinue = false;\n  const pendingObserverEvents = observerEvents;\n  const flushObserverEvents = async (\n    shouldFlush: (event: AgentEvent) => boolean = () => true\n  ) => {\n    for (let index = 0; index < pendingObserverEvents.length; ) {\n      const event = pendingObserverEvents[index];\n      if (!(event && shouldFlush(event))) {\n        index += 1;\n        continue;\n      }\n      pendingObserverEvents.splice(index, 1);\n      await emit(event);\n    }\n  };\n\n  for (const message of output) {\n    if (signal.aborted) {\n      return \"aborted\";\n    }\n\n    history.appendModelMessage(message);\n    const events = modelMessageToAgentEvents(message);\n    const hasToolResult = events.some((event) => event.type === \"tool-result\");\n\n    for (const event of events) {\n      await emit(event);\n      if (event.type === \"tool-call\") {\n        shouldContinue = true;\n        await flushObserverEvents(isLaunchOrBlockingObserverEvent);\n      }\n    }\n\n    if (hasToolResult) {\n      await flushObserverEvents();\n    }\n  }\n\n  await flushObserverEvents();\n\n  return shouldContinue ? \"continue\" : \"completed\";\n}\n\nfunction isLaunchOrBlockingObserverEvent(event: AgentEvent): boolean {\n  if (event.type === \"subagent-job-update\") {\n    return false;\n  }\n\n  return !(event.type === \"subagent-job-end\" && event.task_id);\n}\n"],"mappings":"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"}

package/dist/agent-namespace.js

@@ -0,0 +1,24 @@
+//#region src/agent-namespace.ts
+function randomAgentNamespace() {
+	return agentNamespace(crypto.randomUUID());
+}
+function agentNamespace(namespace) {
+	return `agent:${namespacePart(namespace)}`;
+}
+function namespacePart(value) {
+	return encodeURIComponent(value);
+}
+function parentSessionNamespace({ generation, sessionKey, sessionNamespace }) {
+	return `${sessionNamespace}:session:${namespacePart(sessionKey)}:generation:${generation}`;
+}
+function ownsAgentNamespace(ownerNamespace, sessionNamespace) {
+	return ownerNamespace === sessionNamespace || ownerNamespace?.startsWith(`${sessionNamespace}:session:`) === true;
+}
+function stableAgentNamespace({ name, namespace }) {
+	const stableNamespace = namespace ?? name;
+	return stableNamespace ? agentNamespace(stableNamespace) : randomAgentNamespace();
+}
+//#endregion
+export { ownsAgentNamespace, parentSessionNamespace, stableAgentNamespace };
+
+//# sourceMappingURL=agent-namespace.js.map

package/dist/agent-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-namespace.js","names":[],"sources":["../src/agent-namespace.ts"],"sourcesContent":["export function randomAgentNamespace(): string {\n  return agentNamespace(crypto.randomUUID());\n}\n\nexport function agentNamespace(namespace: string): string {\n  return `agent:${namespacePart(namespace)}`;\n}\n\nexport function namespacePart(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport function parentSessionNamespace({\n  generation,\n  sessionKey,\n  sessionNamespace,\n}: {\n  readonly generation: number;\n  readonly sessionKey: string;\n  readonly sessionNamespace: string;\n}): string {\n  return `${sessionNamespace}:session:${namespacePart(\n    sessionKey\n  )}:generation:${generation}`;\n}\n\nexport function ownsAgentNamespace(\n  ownerNamespace: string | undefined,\n  sessionNamespace: string\n): boolean {\n  return (\n    ownerNamespace === sessionNamespace ||\n    ownerNamespace?.startsWith(`${sessionNamespace}:session:`) === true\n  );\n}\n\nexport function stableAgentNamespace({\n  name,\n  namespace,\n}: {\n  readonly name?: string;\n  readonly namespace?: string;\n}): string {\n  const stableNamespace = namespace ?? name;\n  return stableNamespace\n    ? agentNamespace(stableNamespace)\n    : randomAgentNamespace();\n}\n"],"mappings":";AAAA,SAAgB,uBAA+B;CAC7C,OAAO,eAAe,OAAO,WAAW,CAAC;AAC3C;AAEA,SAAgB,eAAe,WAA2B;CACxD,OAAO,SAAS,cAAc,SAAS;AACzC;AAEA,SAAgB,cAAc,OAAuB;CACnD,OAAO,mBAAmB,KAAK;AACjC;AAEA,SAAgB,uBAAuB,EACrC,YACA,YACA,oBAKS;CACT,OAAO,GAAG,iBAAiB,WAAW,cACpC,UACF,EAAE,cAAc;AAClB;AAEA,SAAgB,mBACd,gBACA,kBACS;CACT,OACE,mBAAmB,oBACnB,gBAAgB,WAAW,GAAG,iBAAiB,UAAU,MAAM;AAEnE;AAEA,SAAgB,qBAAqB,EACnC,MACA,aAIS;CACT,MAAM,kBAAkB,aAAa;CACrC,OAAO,kBACH,eAAe,eAAe,IAC9B,qBAAqB;AAC3B"}

package/dist/agent-options.d.ts

@@ -0,0 +1,35 @@
+import { AgentToolChoice, RuntimeLlm } from "./llm.js";
+import { AgentHost } from "./execution/types.js";
+import { AgentPlugin } from "./plugins.js";
+import { Agent } from "./agent.js";
+import { LanguageModel, ToolSet } from "ai";
+
+//#region src/agent-options.d.ts
+interface AgentLanguageModelOptions {
+  readonly description?: string;
+  readonly host?: AgentHost;
+  readonly instructions?: string;
+  readonly model: LanguageModel;
+  readonly name?: string;
+  readonly namespace?: string;
+  readonly plugins?: readonly AgentPlugin[];
+  readonly subagents?: readonly Agent[];
+  readonly toolChoice?: AgentToolChoice;
+  readonly tools?: ToolSet;
+}
+interface AgentRuntimeModelOptions {
+  readonly description?: string;
+  readonly host?: AgentHost;
+  readonly instructions?: never;
+  readonly model: RuntimeLlm;
+  readonly name?: string;
+  readonly namespace?: string;
+  readonly plugins?: readonly AgentPlugin[];
+  readonly subagents?: never;
+  readonly toolChoice?: never;
+  readonly tools?: never;
+}
+type AgentOptions = AgentLanguageModelOptions | AgentRuntimeModelOptions;
+//#endregion
+export { AgentOptions };
+//# sourceMappingURL=agent-options.d.ts.map

package/dist/agent-options.js

@@ -0,0 +1,16 @@
+//#region src/agent-options.ts
+function assertAgentOptions(options) {
+	if (options === null || typeof options !== "object") throw new TypeError("Agent options are required. Provide { model }.");
+	if ("sessions" in options) throw new TypeError("Agent: unsupported options.sessions. Use host: { sessionStore } and namespace instead.");
+	if ("runtime" in options) throw new TypeError("Agent: unsupported options.runtime. Use host.");
+	if ("llm" in options) throw new TypeError("Agent: unsupported options.llm. Use model for both AI SDK models and custom RuntimeLlm functions.");
+	if (!("model" in options && options.model != null)) throw new TypeError("Agent: missing options.model.");
+	if (typeof options.model !== "function" && (typeof options.model !== "object" || options.model === null)) throw new TypeError("Agent: invalid options.model.");
+}
+function hasRuntimeModel(options) {
+	return typeof options.model === "function";
+}
+//#endregion
+export { assertAgentOptions, hasRuntimeModel };
+
+//# sourceMappingURL=agent-options.js.map

package/dist/agent-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-options.js","names":[],"sources":["../src/agent-options.ts"],"sourcesContent":["import type { LanguageModel, ToolSet } from \"ai\";\nimport type { Agent } from \"./agent\";\nimport type { AgentHost } from \"./execution/types\";\nimport type { AgentToolChoice, RuntimeLlm } from \"./llm\";\nimport type { AgentPlugin } from \"./plugins\";\n\ninterface AgentLanguageModelOptions {\n  readonly description?: string;\n  readonly host?: AgentHost;\n  readonly instructions?: string;\n  readonly model: LanguageModel;\n  readonly name?: string;\n  readonly namespace?: string;\n  readonly plugins?: readonly AgentPlugin[];\n  readonly subagents?: readonly Agent[];\n  readonly toolChoice?: AgentToolChoice;\n  readonly tools?: ToolSet;\n}\n\ninterface AgentRuntimeModelOptions {\n  readonly description?: string;\n  readonly host?: AgentHost;\n  readonly instructions?: never;\n  readonly model: RuntimeLlm;\n  readonly name?: string;\n  readonly namespace?: string;\n  readonly plugins?: readonly AgentPlugin[];\n  readonly subagents?: never;\n  readonly toolChoice?: never;\n  readonly tools?: never;\n}\n\nexport type AgentModelOptions = Pick<\n  AgentLanguageModelOptions,\n  \"instructions\" | \"model\" | \"toolChoice\"\n>;\nexport type AgentOptions = AgentLanguageModelOptions | AgentRuntimeModelOptions;\n\nexport function assertAgentOptions(\n  options: unknown\n): asserts options is AgentOptions {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\"Agent options are required. Provide { model }.\");\n  }\n\n  if (\"sessions\" in options) {\n    throw new TypeError(\n      \"Agent: unsupported options.sessions. Use host: { sessionStore } and namespace instead.\"\n    );\n  }\n\n  if (\"runtime\" in options) {\n    throw new TypeError(\"Agent: unsupported options.runtime. Use host.\");\n  }\n\n  if (\"llm\" in options) {\n    throw new TypeError(\n      \"Agent: unsupported options.llm. Use model for both AI SDK models and custom RuntimeLlm functions.\"\n    );\n  }\n\n  const hasModel = \"model\" in options && options.model != null;\n\n  if (!hasModel) {\n    throw new TypeError(\"Agent: missing options.model.\");\n  }\n\n  if (\n    typeof options.model !== \"function\" &&\n    (typeof options.model !== \"object\" || options.model === null)\n  ) {\n    throw new TypeError(\"Agent: invalid options.model.\");\n  }\n}\n\nexport function hasRuntimeModel(\n  options: AgentOptions\n): options is AgentRuntimeModelOptions {\n  return typeof options.model === \"function\";\n}\n"],"mappings":";AAsCA,SAAgB,mBACd,SACiC;CACjC,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,UAAU,gDAAgD;CAGtE,IAAI,cAAc,SAChB,MAAM,IAAI,UACR,wFACF;CAGF,IAAI,aAAa,SACf,MAAM,IAAI,UAAU,+CAA+C;CAGrE,IAAI,SAAS,SACX,MAAM,IAAI,UACR,mGACF;CAKF,IAAI,EAFa,WAAW,WAAW,QAAQ,SAAS,OAGtD,MAAM,IAAI,UAAU,+BAA+B;CAGrD,IACE,OAAO,QAAQ,UAAU,eACxB,OAAO,QAAQ,UAAU,YAAY,QAAQ,UAAU,OAExD,MAAM,IAAI,UAAU,+BAA+B;AAEvD;AAEA,SAAgB,gBACd,SACqC;CACrC,OAAO,OAAO,QAAQ,UAAU;AAClC"}

package/dist/agent-resume.js

@@ -0,0 +1,143 @@
+import { readDurableBackgroundChildRunState } from "./subagent-background-child-run-state.js";
+import { ownsAgentNamespace } from "./agent-namespace.js";
+import { StoredAgentRun } from "./execution/run.js";
+import { BufferedAgentRun } from "./session/run.js";
+import { buildDurableResumeGroups } from "./subagent-background-resume-group.js";
+import { runBackgroundJob } from "./subagent-background-runner.js";
+//#region src/agent-resume.ts
+const defaultResumeLeaseMs = 3e5;
+async function resumeAgentRun({ host, ownerNamespace, resumeNotification, runId, subagents }) {
+	const run = await host.store.runs.get(runId);
+	if (!run) return null;
+	if (!canAccessRun(run, ownerNamespace)) return null;
+	if (run.kind === "background-subagent") return await resumeBackgroundSubagentRun({
+		host,
+		run,
+		subagents
+	});
+	if (run.kind === "notification" && run.dedupeKey) {
+		const idempotencyKey = run.dedupeKey;
+		const claimed = await claimRun(host, run);
+		if (!claimed) return null;
+		const notification = await claimNotificationForRun({
+			host,
+			idempotencyKey,
+			ownerNamespace
+		});
+		if (!notification) return null;
+		try {
+			const notificationRun = await resumeNotification(notification);
+			await completeNotificationRun(host, claimed.runId);
+			return notificationRun;
+		} catch (error) {
+			await host.store.notifications.releaseByIdempotencyKey(idempotencyKey);
+			throw error;
+		}
+	}
+	return null;
+}
+async function claimNotificationForRun({ host, idempotencyKey, ownerNamespace }) {
+	if (!ownsAgentNamespace((await host.store.notifications.getByIdempotencyKey(idempotencyKey))?.ownerNamespace, ownerNamespace)) return null;
+	const claim = await host.store.notifications.claimByIdempotencyKey(idempotencyKey);
+	if (claim.ok) {
+		if (ownsAgentNamespace(claim.record.ownerNamespace, ownerNamespace)) return claim.record;
+		await host.store.notifications.releaseByIdempotencyKey(idempotencyKey);
+		return null;
+	}
+	if (claim.reason === "already-claimed" && ownsAgentNamespace(claim.record?.ownerNamespace, ownerNamespace)) return claim.record ?? null;
+	return null;
+}
+function canAccessRun(run, ownerNamespace) {
+	if (run.ownerNamespace) return ownsAgentNamespace(run.ownerNamespace, ownerNamespace);
+	return run.sessionKey.startsWith(`parent:${ownerNamespace}:`) || run.parentRunId?.startsWith(`${ownerNamespace}:session:`) === true;
+}
+async function completeNotificationRun(host, runId) {
+	const run = await host.store.runs.get(runId);
+	if (run?.kind !== "notification" || run.status === "completed") return;
+	await host.store.runs.update({
+		...run,
+		status: "completed"
+	});
+}
+async function resumeBackgroundSubagentRun({ host, run, subagents }) {
+	const claimed = await claimRun(host, run);
+	if (!claimed) return null;
+	const state = readDurableBackgroundChildRunState(await host.store.checkpoints.latest(run.runId));
+	if (!state) throw new AgentResumeError(run.runId, "missing background run state");
+	const subagent = subagents.find((candidate) => candidate.name === state.subagent);
+	if (!subagent) throw new AgentResumeError(run.runId, `missing subagent ${JSON.stringify(state.subagent)}`);
+	const childSession = subagent.session(claimed.sessionKey);
+	const job = {
+		abort: () => childSession.interrupt(),
+		childRunId: claimed.runId,
+		childRunLeaseId: claimed.lease?.leaseId,
+		cleanup: () => Promise.resolve(),
+		dedupeKey: claimed.dedupeKey,
+		delegateToolCallId: state.delegateToolCallId,
+		description: state.description,
+		executionHost: host,
+		groupId: state.groupId,
+		id: claimed.publicTaskId ?? claimed.runId,
+		ownerNamespace: claimed.ownerNamespace,
+		parentRunId: claimed.parentRunId,
+		parentSessionKey: state.parentSessionKey,
+		promise: Promise.resolve(),
+		sessionKey: claimed.sessionKey,
+		settled: false,
+		status: "running",
+		subagent: state.subagent
+	};
+	const jobs = new Map([[job.id, job]]);
+	job.promise = runBackgroundJob({
+		childSession,
+		groups: await buildDurableResumeGroups({
+			currentJob: job,
+			host,
+			run: claimed,
+			state,
+			jobs
+		}),
+		jobs,
+		job,
+		parentSession: durableParentSession(host, run.runId),
+		prompt: state.prompt
+	}).finally(() => {
+		job.settled = true;
+	});
+	await job.promise;
+	return new StoredAgentRun({
+		eventStore: host.store.events,
+		runId: run.runId
+	});
+}
+async function claimRun(host, run) {
+	const claim = await host.store.runs.claim(run.runId, {
+		attempt: (run.lease?.attempt ?? 0) + 1,
+		leaseId: crypto.randomUUID(),
+		leaseMs: defaultResumeLeaseMs,
+		nowMs: Date.now()
+	});
+	return claim.ok ? claim.record : null;
+}
+function durableParentSession(host, runId) {
+	return {
+		emitObserverEvent: (event) => host.store.events.append(runId, event).then(),
+		enqueueRuntimeInput: () => void 0,
+		notify: () => Promise.resolve(emptyRun())
+	};
+}
+function emptyRun() {
+	const run = new BufferedAgentRun();
+	run.close();
+	return run;
+}
+var AgentResumeError = class extends Error {
+	constructor(runId, reason) {
+		super(`Cannot resume agent run ${runId}: ${reason}`);
+		this.name = "AgentResumeError";
+	}
+};
+//#endregion
+export { resumeAgentRun };
+
+//# sourceMappingURL=agent-resume.js.map

package/dist/agent-resume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-resume.js","names":[],"sources":["../src/agent-resume.ts"],"sourcesContent":["import { ownsAgentNamespace } from \"./agent-namespace\";\nimport { StoredAgentRun } from \"./execution/run\";\nimport type {\n  ExecutionHost,\n  NotificationRecord,\n  RunRecord,\n} from \"./execution/types\";\nimport { type AgentRun, BufferedAgentRun } from \"./session/run\";\nimport { readDurableBackgroundChildRunState } from \"./subagent-background-child-run-state\";\nimport { buildDurableResumeGroups } from \"./subagent-background-resume-group\";\nimport { runBackgroundJob } from \"./subagent-background-runner\";\nimport type { RuntimeInputSink, Subagent, SubagentJob } from \"./subagent-types\";\n\nconst defaultResumeLeaseMs = 300_000;\n\ninterface ResumeAgentRunInput {\n  readonly host: ExecutionHost;\n  readonly ownerNamespace: string;\n  resumeNotification(notification: NotificationRecord): Promise<AgentRun>;\n  readonly runId: string;\n  readonly subagents: readonly Subagent[];\n}\n\nexport async function resumeAgentRun({\n  host,\n  ownerNamespace,\n  resumeNotification,\n  runId,\n  subagents,\n}: ResumeAgentRunInput): Promise<AgentRun | null> {\n  const run = await host.store.runs.get(runId);\n  if (!run) {\n    return null;\n  }\n  if (!canAccessRun(run, ownerNamespace)) {\n    return null;\n  }\n\n  if (run.kind === \"background-subagent\") {\n    return await resumeBackgroundSubagentRun({ host, run, subagents });\n  }\n\n  if (run.kind === \"notification\" && run.dedupeKey) {\n    const idempotencyKey = run.dedupeKey;\n    const claimed = await claimRun(host, run);\n    if (!claimed) {\n      return null;\n    }\n\n    const notification = await claimNotificationForRun({\n      host,\n      idempotencyKey,\n      ownerNamespace,\n    });\n    if (!notification) {\n      return null;\n    }\n\n    try {\n      const notificationRun = await resumeNotification(notification);\n      await completeNotificationRun(host, claimed.runId);\n      return notificationRun;\n    } catch (error) {\n      await host.store.notifications.releaseByIdempotencyKey(idempotencyKey);\n      throw error;\n    }\n  }\n\n  return null;\n}\n\nasync function claimNotificationForRun({\n  host,\n  idempotencyKey,\n  ownerNamespace,\n}: {\n  readonly host: ExecutionHost;\n  readonly idempotencyKey: string;\n  readonly ownerNamespace: string;\n}): Promise<NotificationRecord | null> {\n  const current =\n    await host.store.notifications.getByIdempotencyKey(idempotencyKey);\n  if (!ownsAgentNamespace(current?.ownerNamespace, ownerNamespace)) {\n    return null;\n  }\n\n  const claim =\n    await host.store.notifications.claimByIdempotencyKey(idempotencyKey);\n  if (claim.ok) {\n    if (ownsAgentNamespace(claim.record.ownerNamespace, ownerNamespace)) {\n      return claim.record;\n    }\n    await host.store.notifications.releaseByIdempotencyKey(idempotencyKey);\n    return null;\n  }\n\n  if (\n    claim.reason === \"already-claimed\" &&\n    ownsAgentNamespace(claim.record?.ownerNamespace, ownerNamespace)\n  ) {\n    return claim.record ?? null;\n  }\n\n  return null;\n}\n\nfunction canAccessRun(run: RunRecord, ownerNamespace: string): boolean {\n  if (run.ownerNamespace) {\n    return ownsAgentNamespace(run.ownerNamespace, ownerNamespace);\n  }\n\n  return (\n    run.sessionKey.startsWith(`parent:${ownerNamespace}:`) ||\n    run.parentRunId?.startsWith(`${ownerNamespace}:session:`) === true\n  );\n}\n\nexport async function completeNotificationRun(\n  host: ExecutionHost,\n  runId: string\n): Promise<void> {\n  const run = await host.store.runs.get(runId);\n  if (run?.kind !== \"notification\" || run.status === \"completed\") {\n    return;\n  }\n\n  await host.store.runs.update({ ...run, status: \"completed\" });\n}\n\nasync function resumeBackgroundSubagentRun({\n  host,\n  run,\n  subagents,\n}: {\n  readonly host: ExecutionHost;\n  readonly run: RunRecord;\n  readonly subagents: readonly Subagent[];\n}): Promise<AgentRun | null> {\n  const claimed = await claimRun(host, run);\n  if (!claimed) {\n    return null;\n  }\n\n  const checkpoint = await host.store.checkpoints.latest(run.runId);\n  const state = readDurableBackgroundChildRunState(checkpoint);\n  if (!state) {\n    throw new AgentResumeError(run.runId, \"missing background run state\");\n  }\n\n  const subagent = subagents.find(\n    (candidate) => candidate.name === state.subagent\n  );\n  if (!subagent) {\n    throw new AgentResumeError(\n      run.runId,\n      `missing subagent ${JSON.stringify(state.subagent)}`\n    );\n  }\n\n  const childSession = subagent.session(claimed.sessionKey);\n  const job: SubagentJob = {\n    abort: () => childSession.interrupt(),\n    childRunId: claimed.runId,\n    childRunLeaseId: claimed.lease?.leaseId,\n    cleanup: () => Promise.resolve(),\n    dedupeKey: claimed.dedupeKey,\n    delegateToolCallId: state.delegateToolCallId,\n    description: state.description,\n    executionHost: host,\n    groupId: state.groupId,\n    id: claimed.publicTaskId ?? claimed.runId,\n    ownerNamespace: claimed.ownerNamespace,\n    parentRunId: claimed.parentRunId,\n    parentSessionKey: state.parentSessionKey,\n    promise: Promise.resolve(),\n    sessionKey: claimed.sessionKey,\n    settled: false,\n    status: \"running\",\n    subagent: state.subagent,\n  };\n  const jobs = new Map([[job.id, job]]);\n  const groups = await buildDurableResumeGroups({\n    currentJob: job,\n    host,\n    run: claimed,\n    state,\n    jobs,\n  });\n  const parentSession = durableParentSession(host, run.runId);\n\n  job.promise = runBackgroundJob({\n    childSession,\n    groups,\n    jobs,\n    job,\n    parentSession,\n    prompt: state.prompt,\n  }).finally(() => {\n    job.settled = true;\n  });\n  await job.promise;\n\n  return new StoredAgentRun({\n    eventStore: host.store.events,\n    runId: run.runId,\n  });\n}\n\nasync function claimRun(\n  host: ExecutionHost,\n  run: RunRecord\n): Promise<RunRecord | null> {\n  const claim = await host.store.runs.claim(run.runId, {\n    attempt: (run.lease?.attempt ?? 0) + 1,\n    leaseId: crypto.randomUUID(),\n    leaseMs: defaultResumeLeaseMs,\n    nowMs: Date.now(),\n  });\n  return claim.ok ? claim.record : null;\n}\n\nfunction durableParentSession(\n  host: ExecutionHost,\n  runId: string\n): RuntimeInputSink {\n  return {\n    emitObserverEvent: (event) => host.store.events.append(runId, event).then(),\n    enqueueRuntimeInput: () => undefined,\n    notify: () => Promise.resolve(emptyRun()),\n  };\n}\n\nfunction emptyRun(): AgentRun {\n  const run = new BufferedAgentRun();\n  run.close();\n  return run;\n}\n\nclass AgentResumeError extends Error {\n  constructor(runId: string, reason: string) {\n    super(`Cannot resume agent run ${runId}: ${reason}`);\n    this.name = \"AgentResumeError\";\n  }\n}\n"],"mappings":"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"}

package/dist/agent-session-entry.d.ts

@@ -0,0 +1,13 @@
+import { AgentInput } from "./session/input.js";
+import { AgentRun } from "./session/run.js";
+//#region src/agent-session-entry.d.ts
+interface SessionHandle {
+  delete(): Promise<void>;
+  interrupt(): void;
+  kill(): Promise<void>;
+  send(input: AgentInput): Promise<AgentRun>;
+  steer(input: AgentInput): Promise<AgentRun>;
+}
+//#endregion
+export { SessionHandle };
+//# sourceMappingURL=agent-session-entry.d.ts.map

package/dist/agent-validation.js

@@ -0,0 +1,35 @@
+//#region src/agent-validation.ts
+const subagentNamePattern = /^[a-z][a-z0-9_-]{0,51}$/;
+function assertSubagents(options, agentClass, hasRuntimeModel) {
+	if (!("subagents" in options) || options.subagents === void 0) return;
+	if (hasRuntimeModel) throw new TypeError("Agent: subagents require an AI SDK model.");
+	if (!Array.isArray(options.subagents)) throw new TypeError("Agent: subagents must be an array.");
+	assertSubagentTools(options.subagents, agentClass, options.tools ?? {});
+}
+function assertSubagentTools(subagents, agentClass, tools) {
+	const toolNames = new Set(Object.keys(tools));
+	const generatedToolNames = /* @__PURE__ */ new Set();
+	for (const [index, subagent] of subagents.entries()) {
+		const toolName = `delegate_to_${assertSubagentMetadata(subagent, index, agentClass).replaceAll("-", "_")}`;
+		if (toolNames.has(toolName)) throw new TypeError(`Agent: subagent tool ${toolName} collides with an existing tool.`);
+		if (generatedToolNames.has(toolName)) throw new TypeError(`Agent: duplicate subagent tool name ${toolName}.`);
+		generatedToolNames.add(toolName);
+	}
+	for (const reservedToolName of ["background_output", "background_cancel"]) if (toolNames.has(reservedToolName)) throw new TypeError(`Agent: ${reservedToolName} collides with a reserved subagent tool.`);
+}
+function assertSubagentMetadata(subagent, index, agentClass) {
+	if (!(subagent instanceof agentClass)) throw new TypeError(`Agent: subagents[${index}] must be an Agent.`);
+	if (!isValidSubagentName(subagent.name)) throw new TypeError(`Agent: subagents[${index}].name is required or too long.`);
+	if (!isNonEmptyText(subagent.description)) throw new TypeError(`Agent: subagents[${index}].description is required.`);
+	return subagent.name;
+}
+function isNonEmptyText(value) {
+	return typeof value === "string" && value.trim().length > 0;
+}
+function isValidSubagentName(value) {
+	return typeof value === "string" && subagentNamePattern.test(value);
+}
+//#endregion
+export { assertSubagents };
+
+//# sourceMappingURL=agent-validation.js.map

package/dist/agent-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-validation.js","names":[],"sources":["../src/agent-validation.ts"],"sourcesContent":["import type { ToolSet } from \"ai\";\nimport type { Agent } from \"./agent\";\nimport type { AgentOptions } from \"./agent-options\";\n\nconst subagentNamePattern = /^[a-z][a-z0-9_-]{0,51}$/;\n\nexport function assertSubagents(\n  options: AgentOptions,\n  agentClass: new (options: AgentOptions) => Agent,\n  hasRuntimeModel: boolean\n): void {\n  if (!(\"subagents\" in options) || options.subagents === undefined) {\n    return;\n  }\n\n  if (hasRuntimeModel) {\n    throw new TypeError(\"Agent: subagents require an AI SDK model.\");\n  }\n\n  if (!Array.isArray(options.subagents)) {\n    throw new TypeError(\"Agent: subagents must be an array.\");\n  }\n\n  assertSubagentTools(options.subagents, agentClass, options.tools ?? {});\n}\n\nfunction assertSubagentTools(\n  subagents: readonly Agent[],\n  agentClass: new (options: AgentOptions) => Agent,\n  tools: ToolSet\n): void {\n  const toolNames = new Set(Object.keys(tools));\n  const generatedToolNames = new Set<string>();\n  for (const [index, subagent] of subagents.entries()) {\n    const name = assertSubagentMetadata(subagent, index, agentClass);\n    const toolName = `delegate_to_${name.replaceAll(\"-\", \"_\")}`;\n    if (toolNames.has(toolName)) {\n      throw new TypeError(\n        `Agent: subagent tool ${toolName} collides with an existing tool.`\n      );\n    }\n\n    if (generatedToolNames.has(toolName)) {\n      throw new TypeError(`Agent: duplicate subagent tool name ${toolName}.`);\n    }\n\n    generatedToolNames.add(toolName);\n  }\n\n  for (const reservedToolName of [\"background_output\", \"background_cancel\"]) {\n    if (toolNames.has(reservedToolName)) {\n      throw new TypeError(\n        `Agent: ${reservedToolName} collides with a reserved subagent tool.`\n      );\n    }\n  }\n}\n\nfunction assertSubagentMetadata(\n  subagent: Agent,\n  index: number,\n  agentClass: new (options: AgentOptions) => Agent\n): string {\n  if (!(subagent instanceof agentClass)) {\n    throw new TypeError(`Agent: subagents[${index}] must be an Agent.`);\n  }\n\n  if (!isValidSubagentName(subagent.name)) {\n    throw new TypeError(\n      `Agent: subagents[${index}].name is required or too long.`\n    );\n  }\n\n  if (!isNonEmptyText(subagent.description)) {\n    throw new TypeError(`Agent: subagents[${index}].description is required.`);\n  }\n\n  return subagent.name;\n}\n\nfunction isNonEmptyText(value: string | undefined): value is string {\n  return typeof value === \"string\" && value.trim().length > 0;\n}\n\nfunction isValidSubagentName(value: string | undefined): value is string {\n  return typeof value === \"string\" && subagentNamePattern.test(value);\n}\n"],"mappings":";AAIA,MAAM,sBAAsB;AAE5B,SAAgB,gBACd,SACA,YACA,iBACM;CACN,IAAI,EAAE,eAAe,YAAY,QAAQ,cAAc,KAAA,GACrD;CAGF,IAAI,iBACF,MAAM,IAAI,UAAU,2CAA2C;CAGjE,IAAI,CAAC,MAAM,QAAQ,QAAQ,SAAS,GAClC,MAAM,IAAI,UAAU,oCAAoC;CAG1D,oBAAoB,QAAQ,WAAW,YAAY,QAAQ,SAAS,CAAC,CAAC;AACxE;AAEA,SAAS,oBACP,WACA,YACA,OACM;CACN,MAAM,YAAY,IAAI,IAAI,OAAO,KAAK,KAAK,CAAC;CAC5C,MAAM,qCAAqB,IAAI,IAAY;CAC3C,KAAK,MAAM,CAAC,OAAO,aAAa,UAAU,QAAQ,GAAG;EAEnD,MAAM,WAAW,eADJ,uBAAuB,UAAU,OAAO,UAClB,EAAE,WAAW,KAAK,GAAG;EACxD,IAAI,UAAU,IAAI,QAAQ,GACxB,MAAM,IAAI,UACR,wBAAwB,SAAS,iCACnC;EAGF,IAAI,mBAAmB,IAAI,QAAQ,GACjC,MAAM,IAAI,UAAU,uCAAuC,SAAS,EAAE;EAGxE,mBAAmB,IAAI,QAAQ;CACjC;CAEA,KAAK,MAAM,oBAAoB,CAAC,qBAAqB,mBAAmB,GACtE,IAAI,UAAU,IAAI,gBAAgB,GAChC,MAAM,IAAI,UACR,UAAU,iBAAiB,yCAC7B;AAGN;AAEA,SAAS,uBACP,UACA,OACA,YACQ;CACR,IAAI,EAAE,oBAAoB,aACxB,MAAM,IAAI,UAAU,oBAAoB,MAAM,oBAAoB;CAGpE,IAAI,CAAC,oBAAoB,SAAS,IAAI,GACpC,MAAM,IAAI,UACR,oBAAoB,MAAM,gCAC5B;CAGF,IAAI,CAAC,eAAe,SAAS,WAAW,GACtC,MAAM,IAAI,UAAU,oBAAoB,MAAM,2BAA2B;CAG3E,OAAO,SAAS;AAClB;AAEA,SAAS,eAAe,OAA4C;CAClE,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,SAAS;AAC5D;AAEA,SAAS,oBAAoB,OAA4C;CACvE,OAAO,OAAO,UAAU,YAAY,oBAAoB,KAAK,KAAK;AACpE"}

package/dist/agent.d.ts

@@ -1,44 +1,19 @@
-import { AgentToolChoice, Llm } from "./llm.js";
 import { AgentInput } from "./session/input.js";
+import { AgentHost } from "./execution/types.js";
+import { AgentOptions } from "./agent-options.js";
 import { AgentRun } from "./session/run.js";
-import { AgentPlugin } from "./plugins/types.js";
-import { AgentPluginErrorHandler } from "./session/lifecycle.js";
-import { LanguageModel, ToolSet } from "ai";
+import { SessionHandle } from "./agent-session-entry.js";
 
 //#region src/agent.d.ts
-interface AgentLanguageModelOptions {
-  instructions?: string;
-  llm?: never;
-  model: LanguageModel;
-  onPluginError?: AgentPluginErrorHandler;
-  plugins?: readonly AgentPlugin[];
-  toolChoice?: AgentToolChoice;
-  tools?: ToolSet;
-}
-interface AgentLlmOptions {
-  instructions?: never;
-  llm: Llm;
-  model?: never;
-  onPluginError?: AgentPluginErrorHandler;
-  plugins?: readonly AgentPlugin[];
-  toolChoice?: never;
-  tools?: never;
-}
-interface SessionHandle {
-  interrupt(): void;
-  kill(): void;
-  overlay(input: AgentInput): Promise<AgentRun>;
-  send(input: AgentInput): Promise<AgentRun>;
-  steer(input: AgentInput): Promise<AgentRun>;
-}
-type AgentOptions = AgentLanguageModelOptions | AgentLlmOptions;
 declare class Agent {
   #private;
-  private constructor();
-  static create(options: AgentOptions): Promise<Agent>;
+  readonly description?: string;
+  readonly name?: string;
+  constructor(options: AgentOptions);
   send(input: AgentInput): Promise<AgentRun>;
+  resume(runId: string): Promise<AgentRun | null>;
   session(key: string): SessionHandle;
 }
 //#endregion
-export { Agent, AgentOptions, SessionHandle };
+export { Agent };
 //# sourceMappingURL=agent.d.ts.map