@narumitw/pi-subagents 2.1.4 → 3.0.0

package/src/consult-policy.ts

@@ -1,15 +0,0 @@
-export const READ_ONLY_CONSULT_TOOLS = ["read", "grep", "find", "ls"] as const;
-
-const READ_ONLY_CONSULT_TOOL_SET = new Set<string>(READ_ONLY_CONSULT_TOOLS);
-
-export function resolveConsultTools(tools: readonly string[] | undefined): string[] {
-	if (tools === undefined) return [...READ_ONLY_CONSULT_TOOLS];
-	const seen = new Set<string>();
-	const effective: string[] = [];
-	for (const tool of tools) {
-		if (!READ_ONLY_CONSULT_TOOL_SET.has(tool) || seen.has(tool)) continue;
-		seen.add(tool);
-		effective.push(tool);
-	}
-	return effective;
-}

package/src/consult-registration.ts

@@ -1,125 +0,0 @@
-import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { cachedModuleLoader, throwIfAborted } from "./cached-module-loader.js";
-import type { RegisterSubagentConsultOptions } from "./consult.js";
-import { renderConsultCall, renderConsultResult } from "./consult-render.js";
-import { type ConsultDetails, SubagentConsultParams } from "./consult-tool.js";
-
-interface ConsultExecutionModule {
-	executeSubagentConsult: typeof import("./consult.js").executeSubagentConsult;
-}
-
-export interface ConsultRegistrationDependencies {
-	loadExecution?: () => Promise<ConsultExecutionModule>;
-}
-
-export function registerSubagentConsult(
-	pi: ExtensionAPI,
-	options: RegisterSubagentConsultOptions,
-	dependencies: ConsultRegistrationDependencies = {},
-): void {
-	const loadExecution = cachedModuleLoader(
-		dependencies.loadExecution ?? (() => import("./consult.js")),
-	);
-	let generation = 0;
-	const active = new Set<AbortController>();
-	const activeWork = new Set<Promise<unknown>>();
-	const cancelActive = (reason: string) => {
-		generation++;
-		for (const controller of active) {
-			controller.abort(new DOMException(reason, "AbortError"));
-		}
-		active.clear();
-	};
-	const cancelAndWaitForWork = async (reason: string) => {
-		cancelActive(reason);
-		await Promise.allSettled([...activeWork]);
-	};
-	pi.on("session_start", () => cancelAndWaitForWork("Subagent consultation session replaced"));
-	pi.on("session_shutdown", () => cancelAndWaitForWork("Subagent consultation session shut down"));
-
-	const description =
-		"Run one ephemeral subagent synchronously under enforced read-only tool and resource policies and return its answer. The child can use only the effective subset of Pi's built-in read, grep, find, and ls tools. Shell commands, file writes, extension tools, detached lifecycle operations, and persistent agent state are disabled. The current working-directory policy, trusted-target resource policy, and available agent definitions are published in the pi-subagents session-guidance message. Allowed targets without effective trust inherit no target or project resources. This is not a filesystem sandbox.";
-	const definition: ToolDefinition<typeof SubagentConsultParams, ConsultDetails> = {
-		name: "subagent_consult",
-		label: "Consult Read-only Subagent",
-		description,
-		promptSnippet: "Consult one constrained read-only subagent and wait for its answer",
-		promptGuidelines: [
-			"Use subagent_consult only for bounded read-only evidence gathering when an independent perspective is worth making the main agent wait.",
-			"Keep ordinary planning and review in the main agent with applicable skills and deterministic checks; use subagent_consult only when synchronous read-only isolation adds concrete value.",
-			"Set subagent_consult timeoutMs to the shortest realistic work deadline for the task difficulty; split oversized consultations instead of extending the deadline merely to compensate for broad scope.",
-			"Implementation-shaped subagent_consult tasks remain read-only and can return only analysis or instructions.",
-		],
-		parameters: SubagentConsultParams,
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const ownerGeneration = generation;
-			const ownedController = new AbortController();
-			active.add(ownedController);
-			const combined = combineAbortSignals(signal, ownedController.signal);
-			const work = (async () => {
-				throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
-				let executionModule: ConsultExecutionModule;
-				try {
-					executionModule = await loadExecution();
-				} catch (error) {
-					throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
-					throw error;
-				}
-				throwIfAborted(combined.signal, "Subagent consultation loading was cancelled");
-				if (ownerGeneration !== generation) {
-					throw new DOMException("Subagent consultation owner was replaced", "AbortError");
-				}
-				return executionModule.executeSubagentConsult(
-					params,
-					combined.signal,
-					onUpdate,
-					ctx,
-					options,
-					() => ownerGeneration === generation,
-				);
-			})();
-			activeWork.add(work);
-			try {
-				return await work;
-			} finally {
-				combined.dispose();
-				active.delete(ownedController);
-				activeWork.delete(work);
-			}
-		},
-		renderCall(args, theme) {
-			return renderConsultCall(args, theme);
-		},
-		renderResult(result, renderOptions, theme, context) {
-			return renderConsultResult(result, renderOptions, theme, context);
-		},
-	};
-	pi.registerTool<typeof SubagentConsultParams, ConsultDetails>(definition);
-	pi.on("tool_result", (event) => {
-		if (event.toolName !== "subagent_consult") return;
-		if ((event.details as ConsultDetails | undefined)?.isError) return { isError: true };
-	});
-}
-
-function combineAbortSignals(
-	external: AbortSignal | undefined,
-	owned: AbortSignal,
-): { signal: AbortSignal; dispose(): void } {
-	if (!external) return { signal: owned, dispose() {} };
-	const controller = new AbortController();
-	const sources = [external, owned];
-	const listeners = sources.map((source) => {
-		const listener = () => {
-			if (!controller.signal.aborted) controller.abort(source.reason);
-		};
-		if (source.aborted) listener();
-		else source.addEventListener("abort", listener, { once: true });
-		return { source, listener };
-	});
-	return {
-		signal: controller.signal,
-		dispose() {
-			for (const { source, listener } of listeners) source.removeEventListener("abort", listener);
-		},
-	};
-}

package/src/consult-render.ts

@@ -1,194 +0,0 @@
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import {
-	getMarkdownTheme,
-	type Theme,
-	type ToolRenderResultOptions,
-} from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
-import type { ConsultDetails, SubagentConsultParams } from "./consult.js";
-import {
-	COLLAPSED_ANSWER_LINES,
-	COLLAPSED_LIST_LIMIT,
-	expansionHint,
-	previewLines,
-	projectRenderActivity,
-	type RenderStatus,
-	recordValue,
-	renderActivityLines,
-	renderFallbackResult,
-	safeBlock,
-	safeLine,
-	statusBadge,
-	stringValue,
-	type ToolRendererContext,
-	textResult,
-	toolHeader,
-} from "./render-common.js";
-import { formatUsageStats } from "./usage-format.js";
-
-export function renderConsultCall(args: Partial<SubagentConsultParams>, theme: Theme) {
-	const scope = args.agentScope ?? "user";
-	const text = [
-		toolHeader(theme, "subagent_consult", args.agent, [`[${scope}]`, "read-only"]),
-		`  ${theme.fg("dim", safeLine(args.task, "...", 2 * 1024))}`,
-	].join("\n");
-	return new Text(text, 0, 0);
-}
-
-export function renderConsultResult(
-	result: AgentToolResult<ConsultDetails>,
-	options: ToolRenderResultOptions,
-	theme: Theme,
-	context: ToolRendererContext<SubagentConsultParams>,
-) {
-	const details = recordValue(result.details);
-	if (!details || !recordValue(details.policy)) {
-		return renderFallbackResult(result, options, theme, context.isError);
-	}
-
-	const progress = recordValue(details.progress);
-	const child = recordValue(details.child);
-	const status = consultStatus(details, progress, options, context.isError);
-	const agent = safeLine(details.agent, safeLine(context.args?.agent, "subagent"), 256);
-	const source = safeLine(details.agentSource, "unknown", 128);
-	const usage = recordValue(progress?.usage ?? child?.usage);
-	const usageText = formatUnknownUsage(
-		usage,
-		stringValue(details.model) || undefined,
-		stringValue(details.thinkingLevel) || undefined,
-		stringValue(progress?.actualProvider ?? child?.actualProvider) || undefined,
-		stringValue(progress?.actualModel ?? child?.actualModel) || undefined,
-	);
-	const effectiveTools = stringList(recordValue(details.policy)?.effectiveTools);
-	const activity = projectRenderActivity(progress?.recentActivity);
-	const activityTotal = Math.max(
-		activity.length,
-		typeof progress?.recentActivityTotal === "number" ? progress.recentActivityTotal : 0,
-	);
-	const answer = safeBlock(textResult(result), "", 50 * 1024).trim();
-
-	if (options.expanded) {
-		const container = new Container();
-		container.addChild(
-			new Text(
-				`${statusBadge(theme, status)} · ${theme.fg("toolTitle", theme.bold(agent))}${theme.fg("muted", ` (${source})`)}`,
-				0,
-				0,
-			),
-		);
-		if (usageText) container.addChild(new Text(theme.fg("dim", usageText), 0, 0));
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
-		container.addChild(
-			new Text(theme.fg("dim", safeBlock(context.args?.task, "(unavailable)", 50 * 1024)), 0, 0),
-		);
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("muted", "─── Policy ───"), 0, 0));
-		container.addChild(new Text(theme.fg("dim", policySummary(details.policy)), 0, 0));
-		if (activity.length > 0) {
-			container.addChild(new Spacer(1));
-			container.addChild(new Text(theme.fg("muted", "─── Activity ───"), 0, 0));
-			container.addChild(
-				new Text(renderActivityLines(activity, theme, undefined, activityTotal), 0, 0),
-			);
-		}
-		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("muted", "─── Answer ───"), 0, 0));
-		if (answer) container.addChild(new Markdown(answer, 0, 0, getMarkdownTheme()));
-		else
-			container.addChild(
-				new Text(
-					theme.fg("muted", options.isPartial ? "(waiting for output)" : "(no output)"),
-					0,
-					0,
-				),
-			);
-		return container;
-	}
-
-	const lines = [
-		`${statusBadge(theme, status)} · ${theme.fg("toolTitle", theme.bold(agent))}${theme.fg("muted", ` (${source})`)}`,
-	];
-	if (usageText) lines.push(theme.fg("dim", usageText));
-	if (effectiveTools.length > 0 && options.isPartial) {
-		lines.push(theme.fg("dim", `tools: ${effectiveTools.join(", ")}`));
-	}
-	if (activity.length > 0) {
-		lines.push(renderActivityLines(activity, theme, COLLAPSED_LIST_LIMIT, activityTotal));
-	} else if (options.isPartial) {
-		lines.push(
-			theme.fg("muted", status === "starting" ? "(starting child)" : "(waiting for activity)"),
-		);
-	} else if (answer) {
-		lines.push(theme.fg("toolOutput", previewLines(answer, COLLAPSED_ANSWER_LINES)));
-	} else {
-		const error = safeBlock(child?.error, "", 2 * 1024).trim();
-		lines.push(theme.fg(status === "failed" ? "error" : "muted", error || "(no output)"));
-	}
-	if (!options.isPartial) lines.push(expansionHint());
-	return new Text(lines.filter(Boolean).join("\n"), 0, 0);
-}
-
-function consultStatus(
-	details: Record<string, unknown>,
-	progress: Record<string, unknown> | undefined,
-	options: ToolRenderResultOptions,
-	isError: boolean,
-): RenderStatus {
-	if (details.cancelled === true) return "cancelled";
-	if (isError || details.isError === true) {
-		const child = recordValue(details.child);
-		return child?.aborted === true && child?.timedOut !== true ? "cancelled" : "failed";
-	}
-	if (options.isPartial) return progress?.phase === "starting" ? "starting" : "running";
-	return "completed";
-}
-
-function stringList(value: unknown): string[] {
-	return Array.isArray(value)
-		? value.flatMap((item) => (typeof item === "string" ? [safeLine(item, "", 256)] : []))
-		: [];
-}
-
-function policySummary(value: unknown): string {
-	const policy = recordValue(value);
-	if (!policy) return "(unavailable)";
-	const resources = recordValue(policy.effectiveResources);
-	const tools = stringList(policy.effectiveTools);
-	return [
-		`tools: ${tools.length > 0 ? tools.join(", ") : "none"}`,
-		`resources: ${safeLine(resources?.policy ?? policy.requestedResources, "unknown", 256)}`,
-		`extensions: ${safeLine(policy.extensions, "unknown", 128)}`,
-		`session persistence: ${safeLine(policy.sessionPersistence, "unknown", 128)}`,
-		`retained agent: ${policy.retainedAgent === false ? "no" : "unknown"}`,
-	].join("\n");
-}
-
-function formatUnknownUsage(
-	value: Record<string, unknown> | undefined,
-	model?: string,
-	thinkingLevel?: string,
-	actualProvider?: string,
-	actualModel?: string,
-): string {
-	const usage = value ?? {};
-	return formatUsageStats(
-		{
-			input: safeNumber(usage.input),
-			output: safeNumber(usage.output),
-			cacheRead: safeNumber(usage.cacheRead),
-			cacheWrite: safeNumber(usage.cacheWrite),
-			cost: safeNumber(usage.cost),
-			contextTokens: safeNumber(usage.contextTokens),
-			turns: safeNumber(usage.turns),
-		},
-		model,
-		thinkingLevel as never,
-		actualProvider,
-		actualModel,
-	);
-}
-
-function safeNumber(value: unknown): number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
-}

package/src/consult-resources.ts

@@ -1,51 +0,0 @@
-import type { ConsultResourcePolicy } from "./agents/types.js";
-import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
-import { resolvePiPromptResources } from "./prompt-resources.js";
-import type { ChildLaunchPolicy } from "./runner-types.js";
-
-const MINIMAL_CONSULT_SYSTEM_PROMPT =
-	"You are a read-only consultation assistant. Analyze the delegated task using only executor-provided capabilities and return a grounded answer.";
-
-/**
- * Resolve Pi-owned prompt files without loading target settings, packages, or extensions.
- * The child still owns context-file, skill, and prompt-template loading according to this policy.
- */
-export async function resolveConsultResourceLaunchPolicy(
-	policy: ConsultResourcePolicy,
-	projectTrusted: boolean,
-	cwd: string,
-): Promise<ChildLaunchPolicy> {
-	if (policy === "none") {
-		return {
-			disableExtensions: true,
-			disableSkills: true,
-			disablePromptTemplates: true,
-			disableContextFiles: true,
-			projectTrust: false,
-			baseSystemPrompt: MINIMAL_CONSULT_SYSTEM_PROMPT,
-		};
-	}
-
-	const resources = await resolvePiPromptResources(cwd, projectTrusted);
-	const discoveredSystemPrompt = resources.systemPrompt;
-	const baseSystemPrompt = discoveredSystemPrompt
-		? truncateUtf8(discoveredSystemPrompt, DEFAULT_MAX_CONTEXT_BYTES).text
-		: undefined;
-	const appendSystemPromptPaths = resources.appendSystemPromptPaths;
-	const shared = {
-		disableExtensions: true,
-		disableContextFiles: !projectTrusted,
-		projectTrust: projectTrusted,
-		baseSystemPrompt,
-		appendSystemPromptPaths:
-			appendSystemPromptPaths.length > 0 ? appendSystemPromptPaths : undefined,
-	};
-	if (policy === "project-context") {
-		return {
-			...shared,
-			disableSkills: true,
-			disablePromptTemplates: true,
-		};
-	}
-	return shared;
-}

package/src/consult-tool.ts

@@ -1,95 +0,0 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import { type Static, Type } from "typebox";
-import type { AgentScope, ConsultResourcePolicy } from "./agents/types.js";
-import { THINKING_LEVELS } from "./agents/types.js";
-import { DEFAULT_MAX_CONTEXT_BYTES, MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
-
-const ConsultScopeSchema = StringEnum(["user", "project", "both"] as const, {
-	default: "user",
-	description: "Agent definition scope. Project scopes require a trusted project.",
-});
-const ConsultThinkingSchema = StringEnum(THINKING_LEVELS);
-
-export const SubagentConsultParams = Type.Object(
-	{
-		agent: Type.String({ minLength: 1 }),
-		task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
-		agentScope: Type.Optional(ConsultScopeSchema),
-		confirmProjectAgents: Type.Optional(Type.Boolean({ default: true })),
-		cwd: Type.Optional(Type.String({ minLength: 1 })),
-		timeoutMs: Type.Optional(
-			Type.Number({
-				minimum: 1,
-				maximum: MAX_SUBAGENT_TIMEOUT_MS,
-				description:
-					"Work deadline selected for the consultation difficulty. On expiry, Pi aborts the work and makes one separately bounded summary attempt.",
-			}),
-		),
-		thinkingLevel: Type.Optional(ConsultThinkingSchema),
-	},
-	{ additionalProperties: false },
-);
-
-export type SubagentConsultParams = Static<typeof SubagentConsultParams>;
-
-export interface ConsultProgressActivity {
-	type: "text" | "toolCall";
-	text?: string;
-	name?: "read" | "grep" | "find" | "ls";
-	args?: Record<string, string | number | boolean>;
-}
-
-export interface ConsultProgress {
-	phase: "starting" | "running";
-	recentActivity: ConsultProgressActivity[];
-	recentActivityTotal: number;
-	actualProvider?: string;
-	actualModel?: string;
-	usage: {
-		input: number;
-		output: number;
-		cacheRead: number;
-		cacheWrite: number;
-		cost: number;
-		contextTokens: number;
-		turns: number;
-	};
-}
-
-export interface ConsultDetails {
-	agent: string;
-	agentSource: string;
-	agentScope: AgentScope;
-	cwd: string;
-	model?: string;
-	thinkingLevel?: string;
-	timeoutMs: number;
-	policy: {
-		requestedTools: string[] | null;
-		effectiveTools: string[];
-		cwdBoundary: "current-workspace" | "external";
-		targetTrust: {
-			kind: string;
-			projectTrusted: boolean;
-			sourcePath?: string;
-			warning?: string;
-		};
-		requestedResources: ConsultResourcePolicy;
-		effectiveResources: {
-			policy: ConsultResourcePolicy;
-			projectResources: boolean;
-			contextFiles: boolean;
-			skills: boolean;
-			promptTemplates: boolean;
-		};
-		resourceDowngradeReason?: string;
-		extensions: "disabled";
-		sessionPersistence: "disabled";
-		retainedAgent: false;
-	};
-	child?: Record<string, unknown>;
-	progress?: ConsultProgress;
-	cancelled?: boolean;
-	isError?: boolean;
-	truncated?: boolean;
-}