@themoltnet/pi-extension 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -1,7 +1,11 @@
+import { AgentSession } from '@earendil-works/pi-coding-agent';
+import { Api } from '@earendil-works/pi-ai';
 import { BashOperations } from '@earendil-works/pi-coding-agent';
 import { connect } from '@themoltnet/sdk';
 import { EditOperations } from '@earendil-works/pi-coding-agent';
 import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
+import { Model } from '@earendil-works/pi-ai';
 import { ReadOperations } from '@earendil-works/pi-coding-agent';
 import { Skill } from '@earendil-works/pi-coding-agent';
 import { Static } from '@sinclair/typebox';
@@ -27,6 +31,33 @@ import { WriteOperations } from '@earendil-works/pi-coding-agent';
  */
 export declare function activateAgentEnv(agentEnv: Record<string, string | undefined>, repoRoot: string): void;
 
+/**
+ * Construct an in-memory `AgentSession`. The caller is responsible for
+ * eventually invoking `session.prompt(...)` and for tearing down — the
+ * helper does no lifecycle management beyond construction.
+ */
+export declare function buildAgentSession(args: BuildAgentSessionArgs): Promise<AgentSession>;
+
+declare interface BuildAgentSessionArgs {
+    /** Host directory mounted at /workspace inside the VM. */
+    mountPath: string;
+    /** pi auth directory (resolved from `PI_CODING_AGENT_DIR` or `~/.pi/agent`). */
+    piAuthDir: string;
+    /** Resolved pi model handle (provider + model id). */
+    modelHandle: Model<Api>;
+    /** Pre-built customTools array. Caller composes Gondolin + MoltNet + submit tools. */
+    customTools: ToolDefinition[];
+    /** System-prompt fragments appended after pi's defaults. Parent passes the
+     *  runtime instructor; subagents pass their narrower variant. */
+    appendSystemPrompt: string[];
+    /** Skills to advertise in `<available_skills>`. Default: empty list. */
+    skillsOverride?: () => LoadSkillsResult;
+    /** Span attributes merged onto every OTel span the session emits. */
+    otelSpanAttrs: Record<string, string | number | boolean>;
+    /** Agent name for `gen_ai.agent.name` on the root span. */
+    agentName: string;
+}
+
 declare interface ClaimedTask {
     /** The claimed task payload itself. */
     task: Task;
@@ -83,6 +114,73 @@ export declare function createPiOtelExtension(options?: PiOtelOptions): (pi: Ext
  */
 export declare function createPiTaskExecutor(opts: ExecutePiTaskOptions): (claimedTask: ClaimedTask, reporter: TaskReporter) => Promise<TaskOutput>;
 
+/**
+ * Build the subagent custom tool for a parent session. The handle
+ * exposes the call counter so executors can emit summary telemetry
+ * when the parent terminates.
+ */
+export declare function createSubagentTool(args: CreateSubagentToolArgs): SubagentToolHandle;
+
+export declare interface CreateSubagentToolArgs {
+    /** Host directory mounted at /workspace inside the VM. */
+    mountPath: string;
+    /** pi auth directory the parent resolved. */
+    piAuthDir: string;
+    /** Resolved pi model handle — subagents share it. */
+    modelHandle: Model<Api>;
+    /** Agent name for telemetry. */
+    agentName: string;
+    /**
+     * Custom tools every subagent inherits (Gondolin-routed
+     * Read/Write/Edit/Bash + moltnet_* tools, etc). MUST NOT include
+     * the parent's submit-output tool, the parent's `subagent` tool,
+     * or any other parent-only artefact — the caller is responsible
+     * for filtering. The subagent appends its own submit tool.
+     */
+    inheritedCustomTools: ToolDefinition[];
+    /**
+     * The parent runtime instructor verbatim. Subagents prepend it to
+     * their own short "you are a subagent" preamble so the same
+     * invariants (gh auth, diary discipline, accountable commits)
+     * apply if the subagent takes those actions. The parent's task
+     * description dictates whether they should.
+     */
+    parentRuntimeInstructor: string;
+    parentTaskId: string;
+    parentTaskType: string;
+    parentAttemptN: number;
+    /**
+     * Parent task's cancel signal. When the daemon cancels the parent
+     * task (operator cancel or task-level `runningTimeoutSec` expiry),
+     * each in-flight subagent's inner `session.abort()` is invoked so
+     * it tears down promptly instead of running until its own LLM
+     * call resolves. Mirrors the existing `wireSessionAbort` pattern
+     * the parent session uses.
+     *
+     * Optional only because the test seam can omit it; production
+     * callers (executePiTask) pass `reporter.cancelSignal`.
+     */
+    parentCancelSignal?: AbortSignal;
+    /**
+     * Per-call fallback timeout. Defends against an inner session that
+     * ignores `abort()` for any reason (LLM provider stuck, tool call
+     * hanging on I/O, etc.). When the timeout fires, `session.abort()`
+     * is invoked and the tool returns `isError: true` with a
+     * `subagent_timed_out` reason the parent LLM can recover from.
+     *
+     * Default: 5 minutes. Set to `0` to disable (relying purely on
+     * parentCancelSignal). Negative values are treated as the default.
+     */
+    timeoutMs?: number;
+    /**
+     * Test seam. Production callers leave this undefined and get
+     * `buildAgentSession` from the factory module. Tests inject a mock
+     * that returns a stub session implementing only `prompt()` to
+     * exercise the tool's logic without booting a VM.
+     */
+    buildAgentSession?: (args: BuildAgentSessionArgs) => Promise<AgentSession>;
+}
+
 /**
  * Ensure a cached snapshot exists, building one if needed.
  * Returns the absolute path to the qcow2 checkpoint file.
@@ -300,6 +398,29 @@ export declare interface SandboxConfig {
 /** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
 export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
 
+export declare interface SubagentToolHandle {
+    /** ToolDefinition to register via `customTools` on the parent session. */
+    readonly tool: ToolDefinition;
+    /** How many times the parent LLM has called this tool. */
+    getCallCount: () => number;
+}
+
+/**
+ * Parameters shape the parent LLM sees when calling the subagent tool.
+ *
+ *   - `task`         — natural-language instructions for the subagent.
+ *                      The parent authors this per call. Must be
+ *                      non-empty.
+ *   - `output_schema` — name of a registered SubagentOutputContract.
+ *                      Resolved at call time; unknown names error.
+ */
+export declare const SubagentToolParameters: TObject<{
+    task: TString;
+    output_schema: TString;
+}>;
+
+export declare type SubagentToolParameters = Static<typeof SubagentToolParameters>;
+
 /**
  * The Task promise body.
  *

package/dist/index.js

@@ -8580,6 +8580,39 @@ function extractUsage(message) {
 	};
 }
 //#endregion
+//#region src/runtime/agent-session-factory.ts
+var NO_SKILLS = () => ({
+	skills: [],
+	diagnostics: []
+});
+/**
+* Construct an in-memory `AgentSession`. The caller is responsible for
+* eventually invoking `session.prompt(...)` and for tearing down — the
+* helper does no lifecycle management beyond construction.
+*/
+async function buildAgentSession(args) {
+	const piOtelExtension = createPiOtelExtension({
+		agentName: args.agentName,
+		spanAttributes: args.otelSpanAttrs
+	});
+	const resourceLoader = new DefaultResourceLoader({
+		cwd: args.mountPath,
+		agentDir: args.piAuthDir,
+		extensionFactories: [piOtelExtension],
+		appendSystemPrompt: args.appendSystemPrompt,
+		skillsOverride: args.skillsOverride ?? NO_SKILLS
+	});
+	await resourceLoader.reload();
+	return (await createAgentSession({
+		agentDir: args.piAuthDir,
+		cwd: args.mountPath,
+		model: args.modelHandle,
+		customTools: args.customTools,
+		sessionManager: SessionManager.inMemory(),
+		resourceLoader
+	})).session;
+}
+//#endregion
 //#region ../agent-runtime/src/context-bindings.ts
 var PROMPT_SEPARATOR = "\n\n---\n\n";
 /**
@@ -9440,6 +9473,15 @@ function validateTaskOutput(taskType, output, input) {
 function getTaskOutputSchema(taskType) {
 	return getTaskTypeEntry(taskType)?.outputSchema ?? null;
 }
+/**
+* Whether sessions running this task type should have the generic
+* `subagent` custom tool registered. Returns `false` for unknown task
+* types and for task types that didn't opt in. See `TaskTypeEntry`
+* for the design rationale.
+*/
+function taskTypeUsesSubagents(taskType) {
+	return getTaskTypeEntry(taskType)?.usesSubagents === true;
+}
 //#endregion
 //#region ../tasks/src/wire.ts
 /**
@@ -13935,6 +13977,25 @@ var require_multistream = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.pino = pino;
 })))();
 //#endregion
+//#region ../agent-runtime/src/subagent-output-contracts.ts
+var REGISTRY = /* @__PURE__ */ new Map();
+/**
+* Resolve a subagent output contract by name. Returns `null` for
+* unknown names — callers (the subagent custom tool) decide whether
+* that's a tool error the parent LLM can recover from or a hard fail.
+*/
+function getSubagentOutputContract(name) {
+	return REGISTRY.get(name) ?? null;
+}
+/**
+* List all registered contracts. Useful for diagnostics and for the
+* subagent tool's parameter description so a parent LLM can see what
+* contracts are available without enumerating them in its prompt.
+*/
+function listSubagentOutputContracts() {
+	return [...REGISTRY.values()];
+}
+//#endregion
 //#region src/runtime/inject-task-context.ts
 /**
 * Slice 1.5 of #943 — wire the agent-runtime resolver into the
@@ -14128,6 +14189,190 @@ function buildRuntimeInstructor(ctx) {
 	].join("\n");
 }
 //#endregion
+//#region src/runtime/subagent-tool.ts
+var SUBAGENT_SUBMIT_TOOL_NAME = "submit_subagent_output";
+/**
+* Parameters shape the parent LLM sees when calling the subagent tool.
+*
+*   - `task`         — natural-language instructions for the subagent.
+*                      The parent authors this per call. Must be
+*                      non-empty.
+*   - `output_schema` — name of a registered SubagentOutputContract.
+*                      Resolved at call time; unknown names error.
+*/
+var SubagentToolParameters = Type$1.Object({
+	task: Type$1.String({
+		minLength: 1,
+		description: "Natural-language instructions for the subagent. The subagent starts with a fresh conversation and a narrowed system prompt; this is the only context it has from you."
+	}),
+	output_schema: Type$1.String({
+		minLength: 1,
+		description: "Name of a registered subagent output contract. The subagent must submit a structured payload via `submit_subagent_output` matching this contract."
+	})
+}, { additionalProperties: false });
+var DEFAULT_SUBAGENT_TIMEOUT_MS = 300 * 1e3;
+/**
+* Build the subagent custom tool for a parent session. The handle
+* exposes the call counter so executors can emit summary telemetry
+* when the parent terminates.
+*/
+function createSubagentTool(args) {
+	const buildSession = args.buildAgentSession ?? buildAgentSession;
+	let callCount = 0;
+	return {
+		tool: defineTool({
+			name: "subagent",
+			label: "Delegate to subagent",
+			description: subagentToolDescription(),
+			parameters: SubagentToolParameters,
+			async execute(_id, params) {
+				if (!Value.Check(SubagentToolParameters, params)) return toolError(`subagent: invalid parameters: ${JSON.stringify([...Value.Errors(SubagentToolParameters, params)].slice(0, 3))}`);
+				const { task, output_schema } = params;
+				const contract = getSubagentOutputContract(output_schema);
+				if (!contract) return toolError(`subagent: unknown output_schema "${output_schema}". Registered contracts: [${listSubagentOutputContracts().map((c) => c.name).join(", ")}]`);
+				callCount += 1;
+				const callIndex = callCount;
+				let captured = null;
+				const submitTool = defineTool({
+					name: SUBAGENT_SUBMIT_TOOL_NAME,
+					label: `Submit ${output_schema}`,
+					description: `Submit your structured output for this subagent task. Call exactly once when done. Args MUST match the ${output_schema} contract; mismatches return a tool error you can recover from in the same session.`,
+					parameters: contract.parametersSchema,
+					async execute(_innerId, innerParams) {
+						if (!Value.Check(contract.parametersSchema, innerParams)) return toolError(`submit_subagent_output: schema validation failed: ${[...Value.Errors(contract.parametersSchema, innerParams)].slice(0, 3).map((e) => `${e.path}: ${e.message}`).join("; ")}. Re-call with a corrected payload.`);
+						captured = innerParams;
+						return {
+							content: [{
+								type: "text",
+								text: "Output captured. Subagent session will terminate; no further action needed."
+							}],
+							details: { captured: true },
+							terminate: true
+						};
+					}
+				});
+				const subagentInstructor = buildSubagentInstructor({
+					contractName: output_schema,
+					contractDescription: contract.description,
+					parentTaskId: args.parentTaskId,
+					callIndex
+				});
+				const session = await buildSession({
+					mountPath: args.mountPath,
+					piAuthDir: args.piAuthDir,
+					modelHandle: args.modelHandle,
+					agentName: args.agentName,
+					customTools: [...args.inheritedCustomTools, submitTool],
+					appendSystemPrompt: [args.parentRuntimeInstructor, subagentInstructor],
+					skillsOverride: () => ({
+						skills: [],
+						diagnostics: []
+					}),
+					otelSpanAttrs: {
+						"moltnet.task.id": args.parentTaskId,
+						"moltnet.task.type": args.parentTaskType,
+						"moltnet.task.attempt": args.parentAttemptN,
+						"moltnet.subagent.contract": output_schema,
+						"moltnet.subagent.index": callIndex
+					}
+				});
+				let abortReason = null;
+				let abortInvoked = false;
+				const fireAbort = (reason) => {
+					if (abortInvoked) return;
+					abortInvoked = true;
+					abortReason = reason;
+					session.abort().catch((err) => {
+						const message = err instanceof Error ? err.message : String(err);
+						process.stderr.write(`[subagent] inner session.abort() failed: ${message}\n`);
+					});
+				};
+				const cancelListener = args.parentCancelSignal ? (() => {
+					const signal = args.parentCancelSignal;
+					const listener = () => fireAbort("parent_cancelled");
+					if (signal.aborted) listener();
+					else signal.addEventListener("abort", listener, { once: true });
+					return () => signal.removeEventListener("abort", listener);
+				})() : null;
+				const timeoutMs = args.timeoutMs === void 0 || args.timeoutMs < 0 ? DEFAULT_SUBAGENT_TIMEOUT_MS : args.timeoutMs;
+				const timeoutHandle = timeoutMs > 0 ? setTimeout(() => fireAbort("subagent_timed_out"), timeoutMs) : null;
+				try {
+					await session.prompt(task);
+				} catch (err) {
+					return toolError(`subagent: inner session.prompt() threw: ${err instanceof Error ? err.message : String(err)}`);
+				} finally {
+					if (timeoutHandle) clearTimeout(timeoutHandle);
+					if (cancelListener) cancelListener();
+				}
+				if (abortReason !== null) return toolError(`subagent: ${abortReason === "subagent_timed_out" ? `subagent timed out after ${timeoutMs}ms` : "parent task was cancelled"}. The parent should fail this task or retry with a clearer scope.`);
+				if (captured === null) return toolError(`subagent: inner session ended without calling ${SUBAGENT_SUBMIT_TOOL_NAME}. The parent should retry with clearer instructions or fail the task.`);
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(captured)
+					}],
+					details: {
+						captured: true,
+						contract: output_schema,
+						callIndex
+					}
+				};
+			}
+		}),
+		getCallCount: () => callCount
+	};
+}
+function subagentToolDescription() {
+	return [
+		"Delegate a sub-task to a fresh subagent session with isolated context.",
+		"",
+		"The subagent starts with no conversation history and only the `task` ",
+		"string you provide as its instructions. It runs in the same VM with ",
+		"the same tools you have (Gondolin-routed Read/Write/Edit/Bash, ",
+		"moltnet_* tools), and is expected to call ",
+		`\`${SUBAGENT_SUBMIT_TOOL_NAME}\` with a payload matching the named `,
+		"contract before its session ends.",
+		"",
+		"On success, the tool result is the JSON-stringified subagent payload.",
+		"On failure (unknown contract, validation error, subagent did not ",
+		"submit) the tool returns isError:true with a recoverable message."
+	].join("\n");
+}
+function buildSubagentInstructor(args) {
+	return [
+		"# You are a subagent",
+		"",
+		`Parent task: \`${args.parentTaskId}\` (subagent call #${args.callIndex}).`,
+		"",
+		`Your assigned output contract is \`${args.contractName}\`:`,
+		`${args.contractDescription}`,
+		"",
+		"Rules for this session:",
+		"",
+		`- You MUST call \`${SUBAGENT_SUBMIT_TOOL_NAME}\` exactly once with a `,
+		"  payload matching the contract above. Your session terminates on ",
+		"  the valid call.",
+		"- The parent's message above is your task. Do not invent additional ",
+		"  steps the parent did not request.",
+		"- All MoltNet runtime invariants from the parent runtime instructor ",
+		"  apply (diary discipline, gh-auth pattern, etc.) IF you take any ",
+		"  action that would trigger them. Most subagents do not commit code ",
+		"  or open PRs — only do so if your task message explicitly requires it.",
+		"- You do NOT have access to the `subagent` tool. Do not attempt nested ",
+		"  delegation; do the work yourself."
+	].join("\n");
+}
+function toolError(text) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details: { captured: false },
+		isError: true
+	};
+}
+//#endregion
 //#region src/runtime/task-output.ts
 var METER_NAME = "@themoltnet/pi-extension/task-output";
 var parseResultCounter = null;
@@ -14439,6 +14684,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 	const taskTeamId = task.teamId ?? "";
 	let reporterOpen = false;
 	let session = null;
+	let subagentHandle = null;
 	const finalUsage = emptyUsage(opts.provider, opts.model);
 	let cancelListener = null;
 	const makeFailedOutput = (code, message, usage = finalUsage) => ({
@@ -14556,47 +14802,55 @@ async function executePiTask(claimedTask, reporter, opts) {
 			});
 			const piAuthDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
 			const modelHandle = getModel(opts.provider, opts.model);
-			const piOtelExtension = createPiOtelExtension({
-				agentName: opts.agentName,
-				spanAttributes: {
-					"moltnet.task.id": task.id,
-					"moltnet.task.attempt": attemptN,
-					"moltnet.task.type": task.taskType
-				}
-			});
-			const appendSystemPrompt = [buildRuntimeInstructor({
+			const runtimeInstructor = buildRuntimeInstructor({
 				taskId: task.id,
 				taskType: task.taskType,
 				attemptN,
 				diaryId,
 				agentName: opts.agentName,
 				correlationId: task.correlationId ?? null
-			})];
+			});
+			const appendSystemPrompt = [runtimeInstructor];
 			if (injectedContext.systemPromptPrefix) appendSystemPrompt.push(injectedContext.systemPromptPrefix);
 			const injectedSkills = injectedContext.skills;
-			const resourceLoader = new DefaultResourceLoader({
-				cwd: mountPath,
-				agentDir: piAuthDir,
-				extensionFactories: [piOtelExtension],
+			const parentSubagentTools = [];
+			if (taskTypeUsesSubagents(task.taskType)) {
+				subagentHandle = createSubagentTool({
+					mountPath,
+					piAuthDir,
+					modelHandle,
+					agentName: opts.agentName,
+					inheritedCustomTools: [...gondolinCustomTools, ...moltnetTools],
+					parentRuntimeInstructor: runtimeInstructor,
+					parentTaskId: task.id,
+					parentTaskType: task.taskType,
+					parentAttemptN: attemptN,
+					parentCancelSignal: reporter.cancelSignal
+				});
+				parentSubagentTools.push(subagentHandle.tool);
+			}
+			session = await buildAgentSession({
+				mountPath,
+				piAuthDir,
+				modelHandle,
+				agentName: opts.agentName,
+				customTools: [
+					...gondolinCustomTools,
+					...moltnetTools,
+					...submitTools,
+					...parentSubagentTools
+				],
 				appendSystemPrompt,
 				skillsOverride: () => ({
 					skills: injectedSkills,
 					diagnostics: []
-				})
+				}),
+				otelSpanAttrs: {
+					"moltnet.task.id": task.id,
+					"moltnet.task.attempt": attemptN,
+					"moltnet.task.type": task.taskType
+				}
 			});
-			await resourceLoader.reload();
-			session = (await createAgentSession({
-				agentDir: piAuthDir,
-				cwd: mountPath,
-				model: modelHandle,
-				customTools: [
-					...gondolinCustomTools,
-					...moltnetTools,
-					...submitTools
-				],
-				sessionManager: SessionManager.inMemory(),
-				resourceLoader
-			})).session;
 		} catch (err) {
 			const message = err instanceof Error ? err.message : String(err);
 			await emit("error", {
@@ -14667,6 +14921,10 @@ async function executePiTask(claimedTask, reporter, opts) {
 				phase: "session_prompt"
 			});
 		}
+		if (subagentHandle && subagentHandle.getCallCount() > 0) await emit("info", {
+			event: "subagent_summary",
+			callCount: subagentHandle.getCallCount()
+		});
 		await Promise.all(recordingPromise);
 		const cancelled = reporter.cancelSignal.aborted;
 		let parsedOutput = null;
@@ -15126,4 +15384,4 @@ function moltnetExtension(pi) {
 	registerMoltnetReflectCommand(pi, state);
 }
 //#endregion
-export { HOST_EXEC_DEFAULT_BASE_ENV, activateAgentEnv, createGondolinBashOps, createGondolinEditOps, createGondolinReadOps, createGondolinWriteOps, createMoltNetTools, createPiOtelExtension, createPiTaskExecutor, moltnetExtension as default, ensureSnapshot, executePiTask, findMainWorktree, injectTaskContext, loadCredentials, resumeVm, toGuestPath };
+export { HOST_EXEC_DEFAULT_BASE_ENV, activateAgentEnv, buildAgentSession, createGondolinBashOps, createGondolinEditOps, createGondolinReadOps, createGondolinWriteOps, createMoltNetTools, createPiOtelExtension, createPiTaskExecutor, createSubagentTool, moltnetExtension as default, ensureSnapshot, executePiTask, findMainWorktree, injectTaskContext, loadCredentials, resumeVm, toGuestPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-extension",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "MoltNet pi extension — sandboxed tool execution in Gondolin VMs with MoltNet identity and persistent memory",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "@earendil-works/gondolin": "^0.9.1",
     "@opentelemetry/api": "^1.9.0",
     "@sinclair/typebox": "^0.34.0",
-    "@themoltnet/agent-runtime": "0.12.0",
+    "@themoltnet/agent-runtime": "0.13.0",
     "@themoltnet/sdk": "0.100.0"
   },
   "peerDependencies": {