@narumitw/pi-subagents 2.0.6 → 2.1.1

package/src/stateful-render.ts

@@ -17,7 +17,7 @@ import {
 	toolHeader,
 } from "./render-common.js";
 
-export type StatefulRenderTool = "spawn" | "send" | "manage" | "mailbox";
+export type StatefulRenderTool = "spawn" | "send" | "await" | "manage" | "mailbox";
 
 export function createStatefulToolRenderer(tool: StatefulRenderTool) {
 	return {
@@ -71,6 +71,11 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 			0,
 		);
 	}
+	if (tool === "await") {
+		const metadata = ["blocking"];
+		if (typeof args.timeoutMs === "number") metadata.push(`timeout:${args.timeoutMs}ms`);
+		return new Text(toolHeader(theme, "subagent_await", args.agentId, metadata), 0, 0);
+	}
 	if (tool === "manage") {
 		const metadata: string[] = [];
 		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
@@ -98,9 +103,12 @@ function renderStatefulResult(
 	const details = recordValue(result.details);
 	const args = recordValue(context.args) ?? {};
 	if (!details) return renderFallbackResult(result, options, theme, context.isError);
-	if (tool === "spawn" || tool === "send") {
+	if (tool === "spawn" || tool === "send" || tool === "await") {
 		const agent = recordValue(details.agent);
 		if (!agent) return renderFallbackResult(result, options, theme, context.isError);
+		if (tool === "await" && details.timedOut === true) {
+			return new Text(renderAwaitTimeout(agent, result, options.expanded, theme), 0, 0);
+		}
 		return new Text(renderAgentResult(agent, result, options.expanded, theme), 0, 0);
 	}
 	if (tool === "manage") {
@@ -173,6 +181,22 @@ function renderAgentResult(
 	return lines.join("\n");
 }
 
+function renderAwaitTimeout(
+	agent: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const lines = [
+		`${statusBadge(theme, "running")} · ${theme.fg("accent", safeLine(agent.id, "agent", 256))} · ${theme.fg("warning", "wait timed out")} · ${theme.fg("muted", safeLine(agent.state, "unknown", 128))}`,
+	];
+	if (expanded) {
+		const content = safeBlock(textResult(result), "", 8 * 1024).trim();
+		if (content) lines.push(theme.fg("toolOutput", content));
+	} else lines.push(expansionHint());
+	return lines.join("\n");
+}
+
 function renderManageResult(
 	args: Record<string, unknown>,
 	details: Record<string, unknown>,
@@ -276,6 +300,7 @@ function lifecycleStatus(state: string): RenderStatus {
 			return "running";
 		case "idle":
 			return "idle";
+		case "partial":
 		case "blocked":
 		case "needs-input":
 		case "abstained":

package/src/subagent-details.ts

@@ -0,0 +1,43 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { SchedulingDecision } from "./adaptive-scheduler.js";
+import type { AgentScope } from "./agents/types.js";
+import type { OrchestrationMetrics } from "./orchestration-metrics.js";
+import type { PanelSynthesis } from "./panel-contract.js";
+import type { PanelEvidenceArtifact } from "./panel-evidence.js";
+import type { PanelFailure } from "./panel-failure.js";
+import type { PanelPhaseBudgets, PanelPreset } from "./panel-planning.js";
+import type { SingleResult } from "./runner-types.js";
+import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+
+export interface PanelDetails {
+	id: string;
+	preset: PanelPreset;
+	sharedTaskPreview: string;
+	state: "running" | "completed" | "degraded" | "insufficient-panel" | "failed" | "cancelled";
+	reviewerIds: string[];
+	validReviewCount: number;
+	failedReviewCount: number;
+	blockingObjectionCount: number;
+	dissentCount: number;
+	budgets: PanelPhaseBudgets;
+	evidence: PanelEvidenceArtifact[];
+	failures: PanelFailure[];
+	synthesis?: PanelSynthesis;
+	synthesizerResult?: SingleResult;
+	cleanupComplete: boolean;
+}
+
+export interface SubagentDetails {
+	mode: "single" | "parallel" | "chain" | "workflow" | "panel";
+	agentScope: AgentScope;
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+	aggregator?: SingleResult;
+	workflow?: WorkItemLedgerSnapshot;
+	schedulerDecisions?: SchedulingDecision[];
+	metrics?: OrchestrationMetrics;
+	panel?: PanelDetails;
+	isError?: boolean;
+}
+
+export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;

package/src/subagents-extension.ts

@@ -39,7 +39,10 @@ import {
 import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
-import type { SubagentDetails } from "./runner.js";
+import {
+	registerSubagentSessionGuidance,
+	type SubagentSessionGuidanceSnapshot,
+} from "./session-guidance-contract.js";
 import {
 	consumeSubagentSettingsNotice,
 	DEFAULT_CONSULT_RESOURCE_POLICY,
@@ -50,7 +53,14 @@ import {
 	resolveBlockingMaxParallelTasks,
 } from "./settings-reader.js";
 import { registerStatefulSubagents } from "./stateful-registration.js";
+import type { SubagentDetails } from "./subagent-details.js";
 import type { SubagentTransport } from "./transport.js";
+import {
+	registerUsageRecording,
+	type UsageRecordingDependencies,
+	type UsageSurfaceArm,
+} from "./usage-recording.js";
+import { resolveUsageRecordingEnabled } from "./usage-recording-config.js";
 
 type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
 
@@ -60,6 +70,7 @@ export interface SubagentsDependencies {
 	config?: ConfigRegistrationDependencies;
 	consult?: ConsultRegistrationDependencies;
 	inspect?: InspectRegistrationDependencies;
+	usageRecording?: Partial<UsageRecordingDependencies>;
 }
 
 export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
@@ -68,17 +79,17 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
 	);
 	const configOwner = registerSubagentConfigLifecycle(pi);
+	const usageRecording = registerUsageRecording(pi, dependencies.usageRecording);
 	const settings = readSubagentSettings();
 	let currentSettings: SubagentSettings | undefined = settings;
 	let currentCatalog = "";
 	const blockingEnabled = settings?.blocking?.enabled !== false;
-	const refreshBlockingCatalog = blockingEnabled
-		? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution)
-		: () => undefined;
-	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
-	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
+	const statefulEnabled = settings?.stateful?.enabled !== false;
+	if (blockingEnabled) {
+		registerBlockingSubagent(pi, () => currentSettings, statefulEnabled, loadBlockingExecution);
+	}
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		// Preserve a one-shot migration notice from extension load while refreshing
 		// validation against settings that may have changed before this session.
 		const loadNotice = consumeSubagentSettingsNotice();
@@ -93,9 +104,14 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		currentCatalog = formatAgentCatalog(
 			discoverAgentCatalog(ctx.cwd, ctx.isProjectTrusted(), refreshedSettings),
 		).text;
-		refreshBlockingCatalog(currentCatalog);
-		refreshStatefulCatalog(currentCatalog);
-		refreshConsultCatalog(currentCatalog);
+		await usageRecording.startSession({
+			enabled: resolveUsageRecordingEnabled(currentSettings?.usageRecording),
+			surfaceArm: usageSurfaceArm(blockingEnabled, statefulRuntime.getRuntimeStatus().enabled),
+			reason: event.reason,
+			onWarning: (message) => {
+				if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			},
+		});
 	});
 
 	const statefulRuntime = registerStatefulSubagents(pi, {
@@ -103,8 +119,8 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		settings: settings?.stateful,
 		getSettings: () => currentSettings,
 		loadTransport: dependencies.loadStatefulTransport,
+		usageRecording,
 	});
-	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	const getBlockingEnabled = () => blockingEnabled;
 	const getMaxParallelTasks = () => resolveBlockingMaxParallelTasks(currentSettings);
 	const getConsultResourcePolicy = () =>
@@ -122,80 +138,102 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 			getConsultResourcePolicy,
 			getConsultationCwdPolicy,
 			getDelegationCwdPolicy,
+			getUsageRecordingStatus: () => usageRecording.getStatus(),
 		},
 		dependencies.inspect,
 	);
 	if (blockingEnabled) {
-		refreshConsultCatalog = registerSubagentConsult(
-			pi,
-			{ getSettings: () => currentSettings },
-			dependencies.consult,
-		);
+		registerSubagentConsult(pi, { getSettings: () => currentSettings }, dependencies.consult);
 	}
+	const sessionGuidance = registerSubagentSessionGuidance(
+		pi,
+		(): SubagentSessionGuidanceSnapshot => {
+			const runtimeStatus = statefulRuntime.getRuntimeStatus();
+			return {
+				blockingEnabled,
+				statefulEnabled: runtimeStatus.enabled,
+				completionDelivery: runtimeStatus.completionDelivery,
+				blockingMaxParallelTasks: resolveBlockingMaxParallelTasks(currentSettings),
+				statefulLimits: runtimeStatus.limits,
+				consultationCwdPolicy: getConsultationCwdPolicy(),
+				delegationCwdPolicy: getDelegationCwdPolicy(),
+				consultResourcePolicy: getConsultResourcePolicy(),
+				agentCatalog: currentCatalog,
+			};
+		},
+		() => statefulRuntime.listAgents(),
+	);
 	registerSubagentConfigCommand(
 		pi,
 		{
 			...statefulRuntime,
+			setCompletionDelivery(value) {
+				statefulRuntime.setCompletionDelivery(value);
+				sessionGuidance.publish();
+			},
 			getBlockingEnabled,
 			getMaxParallelTasks,
 			getConsultResourcePolicy,
 			getConsultationCwdPolicy,
 			getDelegationCwdPolicy,
+			getUsageRecordingEnabled: () => usageRecording.getStatus().enabled,
+			getUsageRecordingStatus: () => usageRecording.getStatus(),
+			setUsageRecordingEnabled: async (value: boolean) => {
+				await usageRecording.setEnabled(value);
+				currentSettings = {
+					...(currentSettings ?? {}),
+					usageRecording: { ...(currentSettings?.usageRecording ?? {}), enabled: value },
+				};
+			},
 			setMaxParallelTasks(value: number) {
-				const previousSettings = currentSettings;
 				currentSettings = {
 					...(currentSettings ?? {}),
 					blocking: { ...(currentSettings?.blocking ?? {}), maxParallelTasks: value },
 				};
-				try {
-					refreshBlockingCatalog(currentCatalog);
-				} catch (applyError) {
-					currentSettings = previousSettings;
-					try {
-						refreshBlockingCatalog(currentCatalog);
-					} catch (rollbackError) {
-						throw new AggregateError(
-							[applyError, rollbackError],
-							"Failed to apply and roll back the parallel-worker limit",
-						);
-					}
-					throw applyError;
-				}
+				sessionGuidance.publish();
 			},
 			setConsultResourcePolicy(value: ConsultResourcePolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					consult: { ...(currentSettings?.consult ?? {}), resources: value },
 				};
-				refreshConsultCatalog(currentCatalog);
+				sessionGuidance.publish();
 			},
 			setConsultationCwdPolicy(value: ConsultationCwdPolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), consultation: value },
 				};
-				refreshConsultCatalog(currentCatalog);
+				sessionGuidance.publish();
 			},
 			setDelegationCwdPolicy(value: DelegationCwdPolicy) {
 				currentSettings = {
 					...(currentSettings ?? {}),
 					cwdPolicy: { ...(currentSettings?.cwdPolicy ?? {}), delegation: value },
 				};
-				refreshBlockingCatalog(currentCatalog);
-				statefulRuntime.refreshSettingsGuidance();
+				sessionGuidance.publish();
 			},
 		},
 		configOwner,
 		dependencies.config,
 	);
+	pi.on("session_shutdown", (event) => usageRecording.shutdown(event.reason));
+}
+
+function usageSurfaceArm(blockingEnabled: boolean, statefulEnabled: boolean): UsageSurfaceArm {
+	if (blockingEnabled && statefulEnabled) return "all";
+	if (statefulEnabled) return "async-only";
+	if (blockingEnabled) return "blocking-only";
+	return "disabled";
 }
 
 function registerBlockingSubagent(
 	pi: ExtensionAPI,
 	getSettings: () => SubagentSettings | undefined,
+	statefulEnabled: boolean,
 	loadExecution: () => Promise<BlockingExecutionModule>,
-): (catalog: string) => void {
-	let catalog = "";
+): void {
+	let deprecationWarningShown = false;
 	const activeControllers = new Set<AbortController>();
 	const activeWork = new Set<Promise<unknown>>();
 	const cancelAndWaitForWork = async (reason: string) => {
@@ -204,29 +242,40 @@ function registerBlockingSubagent(
 		}
 		await Promise.allSettled([...activeWork]);
 	};
-	pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
+	pi.on("session_start", () => {
+		deprecationWarningShown = false;
+		return cancelAndWaitForWork("Blocking subagent session replaced");
+	});
 	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
-	const baseDescription = () =>
-		[
-			"Run specialized subagents as a blocking operation with isolated contexts.",
-			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
-			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
-			"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
-			'Default agent scope is "user" (from ~/.pi/agent/agents).',
-			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
-			`Maximum parallel worker tasks per call: ${resolveBlockingMaxParallelTasks(getSettings())}. Parallel execution starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
-			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
-		].join(" ");
-	const promptGuidelines = () => [
-		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+	const deprecationAlternatives = () =>
+		statefulEnabled
+			? "Prefer the main agent for tightly coupled work, subagent_spawn for detached work, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
+			: "Prefer the main agent for tightly coupled work or subagent_consult for bounded synchronous read-only evidence; enable the background workflow before using detached alternatives.";
+	const baseDescription = [
+		"Deprecated compatibility tool: do not choose subagent for new work.",
+		deprecationAlternatives(),
+		"Run specialized subagents as a blocking operation with isolated contexts.",
+		"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
+		"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
+		"Parallel mode may include an aggregator fan-in step; workflow mode validates dependencies, authority, artifacts, scope conflicts, retries, and hedging before scheduling. Use subagent_consult instead for one synchronous child that must be executor-constrained to read-only tools.",
+		'Default agent scope is "user" (from ~/.pi/agent/agents).',
+		`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, pass agentScope: "both" (or "project") as a top-level argument for that call.`,
+		`Configured parallel limits never exceed ${MAX_BLOCKING_PARALLEL_CONCURRENCY} concurrently started workers. The current call limit, working-directory policy, and available agent definitions are published in the pi-subagents session-guidance message.`,
+		"Working-directory policy controls launch targets and protected project resources, not filesystem access or sandboxing.",
+	].join(" ");
+	const promptGuidelines = [
+		statefulEnabled
+			? "The subagent tool is deprecated for new work; prefer the main agent, subagent_spawn with supported completion delivery, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
+			: "The subagent tool is deprecated for new work; prefer the main agent or subagent_consult for bounded synchronous read-only evidence, and enable the background workflow before using detached alternatives.",
+		"Use deprecated subagent only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement.",
+		"When compatibility requires subagent, decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
 		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
 		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
 		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
 		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
-		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
-		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
-		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
+		"A compatibility subagent call blocks the main agent from processing queued steering until it returns; use it only when the explicit legacy workflow justifies making Pi unavailable.",
+		"If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured maximum from the current pi-subagents session-guidance message, and avoid write-heavy implementation touching the same files or shared state.",
 		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
 		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
 		"Use panel mode only for consequential review or research that benefits from at least two independent reviewers and one bounded synthesis; agreement is not proof, dissent and blocking objections remain visible, and simple or latency-sensitive work should not use a panel.",
@@ -236,11 +285,11 @@ function registerBlockingSubagent(
 	];
 	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
-		label: "Blocking Subagent",
-		description: appendAgentCatalog(baseDescription(), catalog),
+		label: "Blocking Subagent · Deprecated",
+		description: baseDescription,
 		promptSnippet:
-			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
-		promptGuidelines: promptGuidelines(),
+			"Deprecated blocking subagent compatibility tool; prefer detached or read-only alternatives.",
+		promptGuidelines,
 		parameters: SubagentParams,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -251,6 +300,15 @@ function registerBlockingSubagent(
 				: lifecycleController.signal;
 			const work = (async () => {
 				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
+				if (!deprecationWarningShown && ctx.hasUI) {
+					deprecationWarningShown = true;
+					ctx.ui.notify(
+						statefulEnabled
+							? "subagent is deprecated for new work. Prefer the main agent, subagent_spawn with completion delivery, subagent_await for an intentional join, or subagent_consult for synchronous read-only evidence."
+							: "subagent is deprecated for new work. Prefer the main agent or subagent_consult; enable the background workflow before using detached alternatives.",
+						"warning",
+					);
+				}
 				let executionModule: BlockingExecutionModule;
 				try {
 					executionModule = await loadExecution();
@@ -294,14 +352,4 @@ function registerBlockingSubagent(
 		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
 			return { isError: true };
 	});
-	return (nextCatalog: string) => {
-		catalog = nextCatalog;
-		definition.description = appendAgentCatalog(baseDescription(), catalog);
-		definition.promptGuidelines = promptGuidelines();
-		pi.registerTool<typeof SubagentParams, SubagentDetails>(definition);
-	};
-}
-
-function appendAgentCatalog(baseDescription: string, catalog: string): string {
-	return catalog ? `${baseDescription}\n\n${catalog}` : baseDescription;
 }

package/src/subagents.ts

@@ -11,6 +11,7 @@ export {
 	inspectDelegationWorkflowSettings,
 	inspectStatefulLimitSettings,
 	inspectSubagentSettings,
+	inspectUsageRecordingSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
@@ -27,6 +28,7 @@ export {
 	updateCwdPolicySetting,
 	updateDelegationWorkflowSetting,
 	updateStatefulLimitSetting,
+	updateUsageRecordingSetting,
 } from "./settings.js";
 export { default, type SubagentsDependencies } from "./subagents-extension.js";
 export { formatTokens, formatUsageStats } from "./usage-format.js";

package/src/subprocess-transport.ts

@@ -8,9 +8,10 @@ import {
 } from "./peer-transport.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
-import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
+import { getResultFinalOutput, runSingleAgent } from "./runner.js";
 import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
 import { buildStatefulTurnPrompt, resolveStatefulTurnTimeout } from "./stateful-prompt.js";
+import type { SubagentDetails } from "./subagent-details.js";
 import type { SubagentTransport } from "./transport.js";
 import type { TransportProgressCallback, TransportTelemetry } from "./transport-types.js";
 

package/src/supervision.ts

@@ -1,4 +1,5 @@
-import { isResultError, type SingleResult } from "./runner.js";
+import { isResultError } from "./runner-outcome.js";
+import type { SingleResult } from "./runner-types.js";
 
 const HEDGE_LOSER_GRACE_MS = 5_000;
 

package/src/timeout-finalization.ts

@@ -1,7 +1,7 @@
 import { redactPrivateText } from "./context.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { appendResultInstruction, type SubagentResultFormat } from "./result-contract.js";
-import type { RecentActivityItem } from "./runner.js";
+import type { RecentActivityItem } from "./runner-types.js";
 import {
 	formatTimeoutCheckpoint,
 	type TimeoutCheckpoint,

package/src/tool-schema-compatibility.ts

@@ -0,0 +1,73 @@
+import { type TObject, type TObjectOptions, type TProperties, type TSchema, Type } from "typebox";
+
+const LLAMA_CPP_MAX_REPETITION_THRESHOLD = 2_000;
+
+/**
+ * Remove large nested string repetitions that llama.cpp cannot compile into GBNF.
+ *
+ * Runtime normalization and validation continue to bound these inputs.
+ * See https://github.com/ggml-org/llama.cpp/issues/25746.
+ */
+export function grammarSafeToolObject<Properties extends TProperties>(
+	properties: Properties,
+	options?: TObjectOptions,
+): TObject<Properties> {
+	return makeGrammarSafeToolSchema(Type.Object(properties, options));
+}
+
+function makeGrammarSafeToolSchema<Schema extends TSchema>(schema: Schema): Schema {
+	return cloneSchema(schema, 0) as Schema;
+}
+
+function cloneSchema(schema: unknown, depth: number): unknown {
+	if (!isRecord(schema)) return schema;
+	const clone = cloneWithDescriptors(schema);
+	if (
+		depth > 1 &&
+		clone.type === "string" &&
+		typeof clone.maxLength === "number" &&
+		clone.maxLength >= LLAMA_CPP_MAX_REPETITION_THRESHOLD
+	) {
+		delete clone.maxLength;
+	}
+	if (isRecord(clone.properties)) {
+		clone.properties = mapSchemas(clone.properties, depth + 1);
+	}
+	if (clone.items !== undefined) {
+		clone.items = Array.isArray(clone.items)
+			? clone.items.map((item) => cloneSchema(item, depth + 1))
+			: cloneSchema(clone.items, depth + 1);
+	}
+	if (Array.isArray(clone.prefixItems)) {
+		clone.prefixItems = clone.prefixItems.map((item) => cloneSchema(item, depth + 1));
+	}
+	for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+		if (Array.isArray(clone[keyword])) {
+			clone[keyword] = clone[keyword].map((item) => cloneSchema(item, depth));
+		}
+	}
+	if (isRecord(clone.patternProperties)) {
+		clone.patternProperties = mapSchemas(clone.patternProperties, depth + 1);
+	}
+	if (isRecord(clone.additionalProperties)) {
+		clone.additionalProperties = cloneSchema(clone.additionalProperties, depth + 1);
+	}
+	return clone;
+}
+
+function mapSchemas(schemas: Record<string, unknown>, depth: number): Record<string, unknown> {
+	return Object.fromEntries(
+		Object.entries(schemas).map(([name, schema]) => [name, cloneSchema(schema, depth)]),
+	);
+}
+
+function cloneWithDescriptors(value: Record<string, unknown>): Record<string, unknown> {
+	return Object.defineProperties(
+		Object.create(Object.getPrototypeOf(value)),
+		Object.getOwnPropertyDescriptors(value),
+	) as Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/transport-types.ts

@@ -50,6 +50,12 @@ export interface TransportTelemetry {
 	model?: string;
 	thinkingLevel?: SubagentThinkingLevel;
 	usage?: TransportUsage;
+	budgetSource?: {
+		timeout: "runtime" | "explicit";
+		idleTimeout: "runtime" | "explicit";
+		turnLimit: "runtime" | "explicit";
+		toolCallLimit: "runtime" | "explicit";
+	};
 	failurePhase?: TransportProgressPhase;
 }