@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/dist/builtin/subagents/src/runs/inprocess/control-registry.ts

@@ -0,0 +1,55 @@
+import type { ChildIdentity } from "@bastani/atomic-natives";
+import { createSubagentControl, type ParentContext, type SubagentControlRuntime } from "./runner.ts";
+
+/**
+ * Host-local registry for the Rust control planes owned by the current Atomic
+ * session. The native registry remains authoritative for child identity and
+ * status; this map only lets management actions find the corresponding
+ * in-process runtime without a file-backed run directory.
+ */
+const controls = new Map<string, SubagentControlRuntime>();
+
+export function registerSubagentControl(control: SubagentControlRuntime): void {
+	controls.set(control.parent.path, control);
+}
+
+export function getOrCreateSubagentControl(parent: ParentContext, sessionRoot: string): SubagentControlRuntime {
+	const existing = controls.get(parent.path);
+	// The control plane is parent-scoped. Parallel callers pass their per-child
+	// session directories here, but those storage paths must not split identity
+	// allocation across fresh native registries.
+	if (existing) return existing;
+	const control = createSubagentControl(parent, sessionRoot);
+	controls.set(parent.path, control);
+	return control;
+}
+
+export function unregisterSubagentControl(control: SubagentControlRuntime): void {
+	if (controls.get(control.parent.path) === control) controls.delete(control.parent.path);
+}
+
+export function findSubagentControl(id: string): SubagentControlRuntime | undefined {
+	const direct = controls.get(id);
+	if (direct) return direct;
+	for (const control of controls.values()) {
+		if (control.native.listChildren().some((child) => child.path === id)) return control;
+	}
+	return undefined;
+}
+
+export function listSubagentControls(): readonly SubagentControlRuntime[] {
+	return [...controls.values()];
+}
+
+export function findChildIdentity(
+	id: string,
+): { control: SubagentControlRuntime; identity: ChildIdentity } | undefined {
+	const control = findSubagentControl(id);
+	if (!control) return undefined;
+	const identity = control.native.listChildren().find((child) => child.path === id);
+	return identity ? { control, identity } : undefined;
+}
+
+export function clearSubagentControls(): void {
+	controls.clear();
+}

package/dist/builtin/subagents/src/runs/inprocess/control-status.ts

@@ -0,0 +1,106 @@
+import type { SubagentToolResult } from "../../shared/types.ts";
+import { findSubagentControl, listSubagentControls } from "./control-registry.ts";
+import type { ModelCandidate } from "./runner.ts";
+
+function canonicalChildren(control: NonNullable<ReturnType<typeof findSubagentControl>>) {
+	return [...control.listChildren()].sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function resumeTarget(control: NonNullable<ReturnType<typeof findSubagentControl>>, id: string) {
+	if (id !== control.parent.path) return control.findChild(id);
+	const children = canonicalChildren(control);
+	return children.find((child) => child.status === "interrupted") ?? children[0];
+}
+
+function childLines(control: ReturnType<typeof findSubagentControl>, id?: string): string[] {
+	if (!control) return [];
+	if (id) {
+		const child = control.findChild(id);
+		if (!child) return [];
+		const delivered = control.getDeliveredResult(id);
+		return [
+			`Child: ${child.path}`,
+			`Parent: ${child.parentPath}`,
+			`Task: ${child.taskName}`,
+			`Depth: ${child.depth}`,
+			`Status: ${child.status}`,
+			`Residency: ${child.loaded ? "loaded" : "cold"}`,
+			...(delivered?.sessionFile ? [`Session: ${delivered.sessionFile}`] : []),
+		];
+	}
+	return control
+		.listChildren()
+		.map((child) => `${child.path} — ${child.status} (${child.loaded ? "loaded" : "cold"})`);
+}
+
+export function inspectInProcessChildStatus(id?: string): SubagentToolResult | undefined {
+	if (id) {
+		const control = findSubagentControl(id);
+		if (!control) return undefined;
+		const text =
+			id === control.parent.path
+				? [`Parent: ${control.parent.path}`, ...childLines(control)].join("\n")
+				: childLines(control, id).join("\n");
+		if (!text) return undefined;
+		return {
+			content: [{ type: "text", text }],
+			details: { mode: "management", results: [] },
+		};
+	}
+	const lines = listSubagentControls().flatMap((control) => [
+		`Parent: ${control.parent.path}`,
+		...childLines(control),
+	]);
+	if (lines.length === 0) return undefined;
+	return {
+		content: [{ type: "text", text: lines.join("\n") }],
+		details: { mode: "management", results: [] },
+	};
+}
+
+export async function interruptInProcessChild(id: string): Promise<SubagentToolResult | undefined> {
+	const control = findSubagentControl(id);
+	if (!control) return undefined;
+	const identities = canonicalChildren(control);
+	const candidates = id === control.parent.path ? identities : identities.filter((child) => child.path === id);
+	for (const child of candidates) {
+		if (await control.interruptChild(child.path)) {
+			return {
+				content: [{ type: "text", text: `Interrupt requested for in-process child ${child.path}.` }],
+				details: { mode: "management", results: [] },
+			};
+		}
+	}
+	return {
+		content: [{ type: "text", text: `No running in-process child found for '${id}'.` }],
+		isError: true,
+		details: { mode: "management", results: [] },
+	};
+}
+
+export async function resumeInProcessChild(
+	id: string,
+	message: string,
+	candidate: ModelCandidate,
+): Promise<SubagentToolResult | undefined> {
+	const control = findSubagentControl(id);
+	if (!control) return undefined;
+	const target = resumeTarget(control, id);
+	if (!target) {
+		return {
+			content: [{ type: "text", text: `No in-process child found for '${id}'.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	const outcome = await control.resumeChild(target.path, message, candidate);
+	const selection =
+		id === control.parent.path && control.listChildren().length > 1
+			? `Bare run id resolved to ${target.path}; interrupted children are preferred, then canonical path order.\n\n`
+			: "";
+	return {
+		content: [{ type: "text", text: `${selection}${outcome.envelope}` }],
+		isError: outcome.status === "error" || outcome.status === "interrupted" ? true : undefined,
+		details: { mode: "management", results: [] },
+	};
+}

package/dist/builtin/subagents/src/runs/inprocess/index.ts

@@ -0,0 +1,50 @@
+export {
+	appendInProcessControlRequest,
+	appendInProcessControlResult,
+	appendInProcessNestedEvent,
+	clearInProcessNestedRouting,
+	hasInProcessNestedRoute,
+	interruptInProcessNestedAttempt,
+	readInProcessControlRequests,
+	readInProcessControlResults,
+	readInProcessNestedEvents,
+	registerInProcessNestedAttempt,
+	registerInProcessNestedRoute,
+	removeInProcessControlRequest,
+	resumeInProcessNestedAttempt,
+	subscribeInProcessControlRequests,
+	unregisterInProcessNestedRoute,
+} from "./nested-routing.ts";
+export type {
+	AdmissionRefusal,
+	AdmittedResult,
+	AttemptOutcome,
+	AttemptSignals,
+	AttemptStats,
+	ChildPolicy,
+	ChildSpec,
+	ChildStatus,
+	ContinuationReason,
+	InProcessControlRequest,
+	InProcessControlResult,
+	InProcessNestedAttemptHandle,
+	InProcessNestedResumeOutcome,
+	InProcessNestedRouteKey,
+	ModelCandidate,
+	ParentContext,
+	ResultEnvelope,
+	RunningAttempt,
+	TerminalStatus,
+	TerminationCauseName,
+} from "./runner.ts";
+export {
+	AdmittedChild,
+	admit_child_session,
+	continue_in_background,
+	createSubagentControl,
+	deliver_child_result,
+	reload_cold_child,
+	run_child_attempt,
+	SubagentControlRuntime,
+	terminate_child_attempt,
+} from "./runner.ts";

package/dist/builtin/subagents/src/runs/inprocess/nested-routing.ts

@@ -0,0 +1,218 @@
+/**
+ * In-process nested routing and control registry.
+ *
+ * Routes still expose the file-backed shape for compatibility with cold starts and
+ * older sessions, but a live host registers the same route here. Live children are
+ * addressed by their run id or canonical task path, so control never needs a
+ * request file, an inherited capability-token environment variable, or a poller.
+ */
+
+export interface InProcessNestedRouteKey {
+	readonly rootRunId: string;
+	readonly capabilityToken: string;
+}
+
+export interface InProcessControlRequest {
+	readonly type: "subagent.nested.control-request";
+	readonly rootRunId: string;
+	readonly capabilityToken: string;
+	readonly ts: number;
+	readonly requestId: string;
+	readonly targetRunId: string;
+	readonly action: "interrupt" | "resume";
+	readonly message?: string;
+	readonly filePath: string;
+}
+
+export interface InProcessControlResult {
+	readonly ts: number;
+	readonly requestId: string;
+	readonly targetRunId: string;
+	readonly ok: boolean;
+	readonly message: string;
+	readonly filePath?: string;
+}
+
+export interface InProcessNestedResumeOutcome {
+	readonly status: "ok" | "error" | "interrupted" | "continued";
+	readonly path: string;
+	readonly sessionFile?: string;
+	readonly envelope?: string;
+}
+
+export interface InProcessNestedAttemptHandle {
+	readonly runId: string;
+	readonly path: string;
+	readonly status: () => string;
+	readonly interrupt: () => Promise<void>;
+	readonly resume: (message: string) => Promise<InProcessNestedResumeOutcome>;
+}
+
+interface RouteState {
+	readonly key: InProcessNestedRouteKey;
+	readonly events: object[];
+	readonly controlRequests: Map<string, InProcessControlRequest>;
+	readonly controlResults: Map<string, InProcessControlResult>;
+	readonly listeners: Set<(request: InProcessControlRequest) => void | Promise<void>>;
+}
+
+const routeStates = new Map<string, RouteState>();
+const attemptHandles = new Map<string, Map<string, InProcessNestedAttemptHandle>>();
+
+function routeKey(route: InProcessNestedRouteKey): string {
+	return `${route.rootRunId}\u0000${route.capabilityToken}`;
+}
+
+function attemptKey(id: string): string {
+	return id.trim();
+}
+
+function stateFor(route: InProcessNestedRouteKey): RouteState | undefined {
+	return routeStates.get(routeKey(route));
+}
+
+export function registerInProcessNestedRoute(route: InProcessNestedRouteKey): void {
+	const key = routeKey(route);
+	if (!routeStates.has(key)) {
+		routeStates.set(key, {
+			key: { rootRunId: route.rootRunId, capabilityToken: route.capabilityToken },
+			events: [],
+			controlRequests: new Map(),
+			controlResults: new Map(),
+			listeners: new Set(),
+		});
+	}
+}
+
+export function unregisterInProcessNestedRoute(route: InProcessNestedRouteKey): void {
+	routeStates.delete(routeKey(route));
+}
+
+export function hasInProcessNestedRoute(route: InProcessNestedRouteKey): boolean {
+	return stateFor(route) !== undefined;
+}
+
+export function appendInProcessNestedEvent(route: InProcessNestedRouteKey, event: object): void {
+	const state = stateFor(route);
+	if (!state) return;
+	state.events.push(event);
+	if (state.events.length > 20_000) state.events.splice(0, state.events.length - 20_000);
+}
+
+export function readInProcessNestedEvents(route: InProcessNestedRouteKey): readonly object[] {
+	return stateFor(route)?.events ?? [];
+}
+
+export function appendInProcessControlRequest(route: InProcessNestedRouteKey, request: InProcessControlRequest): void {
+	const state = stateFor(route);
+	if (!state) return;
+	state.controlRequests.set(request.requestId, request);
+	for (const listener of state.listeners) queueMicrotask(() => void listener(request));
+}
+
+export function readInProcessControlRequests(route: InProcessNestedRouteKey): readonly InProcessControlRequest[] {
+	return stateFor(route) ? [...stateFor(route)!.controlRequests.values()] : [];
+}
+
+export function removeInProcessControlRequest(route: InProcessNestedRouteKey, requestId: string): void {
+	stateFor(route)?.controlRequests.delete(requestId);
+}
+
+export function appendInProcessControlResult(route: InProcessNestedRouteKey, result: InProcessControlResult): void {
+	const state = stateFor(route);
+	if (!state) return;
+	state.controlResults.set(result.requestId, result);
+}
+
+export function readInProcessControlResults(route: InProcessNestedRouteKey): readonly InProcessControlResult[] {
+	return stateFor(route) ? [...stateFor(route)!.controlResults.values()] : [];
+}
+
+export function subscribeInProcessControlRequests(
+	route: InProcessNestedRouteKey,
+	listener: (request: InProcessControlRequest) => void | Promise<void>,
+): (() => void) | undefined {
+	const state = stateFor(route);
+	if (!state) return undefined;
+	state.listeners.add(listener);
+	for (const request of state.controlRequests.values()) queueMicrotask(() => void listener(request));
+	return () => state.listeners.delete(listener);
+}
+
+export function registerInProcessNestedAttempt(handle: InProcessNestedAttemptHandle): () => void {
+	const key = attemptKey(handle.runId);
+	let handles = attemptHandles.get(key);
+	if (!handles) {
+		handles = new Map();
+		attemptHandles.set(key, handles);
+	}
+	handles.set(handle.path, handle);
+	const pathKey = attemptKey(handle.path);
+	if (pathKey !== key) {
+		let byPath = attemptHandles.get(pathKey);
+		if (!byPath) {
+			byPath = new Map();
+			attemptHandles.set(pathKey, byPath);
+		}
+		byPath.set(handle.path, handle);
+	}
+	return () => {
+		for (const lookupKey of [key, pathKey]) {
+			const current = attemptHandles.get(lookupKey);
+			if (!current || current.get(handle.path) !== handle) continue;
+			current.delete(handle.path);
+			if (current.size === 0) attemptHandles.delete(lookupKey);
+		}
+	};
+}
+
+function handlesFor(id: string): InProcessNestedAttemptHandle[] {
+	return [...(attemptHandles.get(attemptKey(id))?.values() ?? [])];
+}
+
+export interface InProcessNestedControlResult {
+	readonly ok: boolean;
+	readonly message: string;
+	readonly outcome?: InProcessNestedResumeOutcome;
+}
+
+export async function interruptInProcessNestedAttempt(
+	targetId: string,
+): Promise<InProcessNestedControlResult | undefined> {
+	const handles = handlesFor(targetId);
+	if (handles.length === 0) return undefined;
+	const active = handles.filter((handle) => handle.status() === "running" || handle.status() === "continued");
+	if (active.length === 0) {
+		return { ok: false, message: `Nested run ${targetId} has no active child attempt to interrupt.` };
+	}
+	await Promise.all(active.map((handle) => handle.interrupt()));
+	return { ok: true, message: `Interrupt requested for nested run ${targetId}.` };
+}
+
+export async function resumeInProcessNestedAttempt(
+	targetId: string,
+	message: string,
+): Promise<InProcessNestedControlResult | undefined> {
+	const handles = handlesFor(targetId);
+	if (handles.length === 0) return undefined;
+	const handle =
+		handles.find((candidate) => candidate.status() === "interrupted" || candidate.status() === "error") ?? handles[0];
+	if (!handle) return undefined;
+	if (handle.status() === "running" || handle.status() === "continued") {
+		return { ok: false, message: `Nested run ${targetId} is still running; resume is not required.` };
+	}
+	const outcome = await handle.resume(message);
+	return {
+		ok: outcome.status === "ok" || outcome.status === "continued",
+		message:
+			outcome.status === "ok"
+				? `Reloaded nested run ${targetId} through the in-process control plane.`
+				: `Nested run ${targetId} resume ended with status '${outcome.status}'.`,
+		outcome,
+	};
+}
+
+export function clearInProcessNestedRouting(): void {
+	routeStates.clear();
+	attemptHandles.clear();
+}

package/dist/builtin/subagents/src/runs/{shared/subagent-prompt-runtime.ts → inprocess/prompt-behavior.ts}

@@ -1,15 +1,4 @@
-import * as fs from "node:fs";
-import { createStructuredOutputTool, type ExtensionAPI, getEnvValue } from "@bastani/atomic";
-import type { JsonSchemaObject } from "../../shared/types.ts";
-import {
-	SUBAGENT_FANOUT_CHILD_ENV,
-	SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV,
-	SUBAGENT_INHERIT_SKILLS_ENV,
-	SUBAGENT_INTERCOM_SESSION_NAME_ENV,
-} from "./pi-args.ts";
-import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
-
-export { SUBAGENT_INTERCOM_SESSION_NAME_ENV } from "./pi-args.ts";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
 
 export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 	"You are a child subagent, not the parent orchestrator.",
@@ -42,19 +31,23 @@ const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instru
 const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
 const DATE_HEADER = "\nCurrent date:";
 
-function readBooleanEnv(name: string): boolean | undefined {
-	const value = getEnvValue(name);
-	if (value === undefined) return undefined;
-	return value !== "0";
+export interface ChildPromptPolicy {
+	readonly inheritProjectContext: boolean;
+	readonly inheritSkills: boolean;
+	readonly fanoutAuthorized: boolean;
+}
+
+export interface PromptRewriteOptions {
+	readonly inheritProjectContext: boolean;
+	readonly inheritSkills: boolean;
+	readonly fanoutChild?: boolean;
 }
 
 function findSectionEnd(prompt: string, startIndex: number, nextHeaders: string[]): number {
 	let endIndex = prompt.length;
 	for (const header of nextHeaders) {
 		const index = prompt.indexOf(header, startIndex);
-		if (index !== -1 && index < endIndex) {
-			endIndex = index;
-		}
+		if (index !== -1 && index < endIndex) endIndex = index;
 	}
 	return endIndex;
 }
@@ -89,17 +82,10 @@ function stripChildBoundaryInstructions(prompt: string): string {
 	return rewritten.replace(/^(?:[ \t]*\r?\n)+/, "");
 }
 
-export function rewriteSubagentPrompt(
-	prompt: string,
-	options: { inheritProjectContext: boolean; inheritSkills: boolean; fanoutChild?: boolean },
-): string {
+export function rewriteSubagentPrompt(prompt: string, options: PromptRewriteOptions): string {
 	let rewritten = prompt;
-	if (!options.inheritProjectContext) {
-		rewritten = stripProjectContext(rewritten);
-	}
-	if (!options.inheritSkills) {
-		rewritten = stripInheritedSkills(rewritten);
-	}
+	if (!options.inheritProjectContext) rewritten = stripProjectContext(rewritten);
+	if (!options.inheritSkills) rewritten = stripInheritedSkills(rewritten);
 	rewritten = stripSubagentOrchestrationSkill(rewritten);
 	rewritten = stripChildBoundaryInstructions(rewritten);
 	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
@@ -123,28 +109,28 @@ function isSubagentToolCallBlock(block: unknown): boolean {
 	return b?.type === "toolCall" && b.name === "subagent";
 }
 
-function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undefined {
+function stripAssistantSubagentToolCallBlocks<T>(message: T): T | undefined {
 	const m = message as { role?: string; content?: unknown };
 	if (m?.role !== "assistant" || !Array.isArray(m.content)) return message;
 	const filteredContent = m.content.filter((block) => !isSubagentToolCallBlock(block));
 	if (filteredContent.length === m.content.length) return message;
 	if (filteredContent.length === 0) return undefined;
-	return { ...m, content: filteredContent };
+	return { ...m, content: filteredContent } as T;
 }
 
-export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[] {
-	const preserveCurrentFanoutToolHistory = process.env[SUBAGENT_FANOUT_CHILD_ENV] === "1";
+/** Remove parent-only orchestration history while preserving it for an authorized fanout child. */
+export function stripParentOnlySubagentMessages<T>(messages: T[], preserveFanoutToolHistory = false): T[] {
 	let changed = false;
-	const filtered: unknown[] = [];
+	const filtered: T[] = [];
 	for (const message of messages) {
 		if (
 			isParentOnlySubagentMessage(message) ||
-			(!preserveCurrentFanoutToolHistory && isSubagentToolResultMessage(message))
+			(!preserveFanoutToolHistory && isSubagentToolResultMessage(message))
 		) {
 			changed = true;
 			continue;
 		}
-		const stripped = preserveCurrentFanoutToolHistory ? message : stripAssistantSubagentToolCallBlocks(message);
+		const stripped = preserveFanoutToolHistory ? message : stripAssistantSubagentToolCallBlocks(message);
 		if (stripped === undefined) {
 			changed = true;
 			continue;
@@ -155,44 +141,20 @@ export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[]
 	return changed ? filtered : messages;
 }
 
-export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
-	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
-	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
-	if (structuredOutputPath && structuredSchemaPath) {
-		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
-		pi.registerTool(
-			createStructuredOutputTool({
-				schema,
-				output: { outputPath: structuredOutputPath },
-			}),
-		);
-	}
-
-	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
-	onRuntimeEvent("context", (event) => {
-		const contextEvent = event as { messages?: unknown[] };
-		if (!Array.isArray(contextEvent.messages)) return undefined;
-		const messages = stripParentOnlySubagentMessages(contextEvent.messages);
-		if (messages === contextEvent.messages) return undefined;
-		return { messages };
-	});
-
-	pi.on("before_agent_start", async (event) => {
-		const intercomSessionName = getEnvValue(SUBAGENT_INTERCOM_SESSION_NAME_ENV)?.trim();
-		if (intercomSessionName && typeof pi.setSessionName === "function") {
-			pi.setSessionName(intercomSessionName);
-		}
+export interface InProcessChildPromptBehavior {
+	readonly systemPromptTransform: (prompt: string) => string;
+	readonly initialContextTransform: (messages: AgentMessage[]) => AgentMessage[];
+}
 
-		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
-		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
-		const fanoutChild = readBooleanEnv(SUBAGENT_FANOUT_CHILD_ENV);
-		if (inheritProjectContext === undefined && inheritSkills === undefined && fanoutChild === undefined) return;
-		const rewritten = rewriteSubagentPrompt(event.systemPrompt, {
-			inheritProjectContext: inheritProjectContext ?? true,
-			inheritSkills: inheritSkills ?? true,
-			fanoutChild: fanoutChild === true,
-		});
-		if (rewritten === event.systemPrompt) return;
-		return { systemPrompt: rewritten };
-	});
+/** Build the construction-time transforms for one admitted in-process child. */
+export function createInProcessChildPromptBehavior(policy: ChildPromptPolicy): InProcessChildPromptBehavior {
+	return {
+		systemPromptTransform: (prompt) =>
+			rewriteSubagentPrompt(prompt, {
+				inheritProjectContext: policy.inheritProjectContext,
+				inheritSkills: policy.inheritSkills,
+				fanoutChild: policy.fanoutAuthorized,
+			}),
+		initialContextTransform: (messages) => stripParentOnlySubagentMessages(messages, policy.fanoutAuthorized),
+	};
 }