@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/auto-transport.ts

@@ -0,0 +1,114 @@
+import { discoverAgents, type SubagentSettings } from "./agents.js";
+import type { ManagedAgent, TurnOutcome } from "./registry.js";
+import { isWriteCapable } from "./stateful-safety.js";
+import type { SubagentTransport } from "./transport.js";
+import type {
+	EffectiveSubagentTransportKind,
+	TransportProgressCallback,
+} from "./transport-types.js";
+
+const BUILT_IN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"]);
+
+export interface AutoTransportOptions {
+	subprocess: SubagentTransport;
+	inProcess: SubagentTransport;
+	rpc: SubagentTransport;
+	getSettings?: () => SubagentSettings | undefined;
+}
+
+export interface AutoTransportSelection {
+	kind: EffectiveSubagentTransportKind;
+	reason: string;
+}
+
+export class AutoTransport implements SubagentTransport {
+	readonly kind = "auto" as const;
+	private readonly selections = new Map<string, AutoTransportSelection>();
+
+	constructor(private readonly options: AutoTransportOptions) {}
+
+	async runTurn(
+		agent: ManagedAgent,
+		task: string,
+		signal: AbortSignal,
+		onProgress?: TransportProgressCallback,
+	): Promise<TurnOutcome> {
+		const selection = this.selections.get(agent.id) ?? this.select(agent);
+		this.selections.set(agent.id, selection);
+		const transport = this.transport(selection.kind);
+		const outcome = await transport.runTurn(agent, task, signal, (progress) =>
+			onProgress?.({ ...progress, selectionReason: selection.reason }),
+		);
+		return {
+			...outcome,
+			telemetry: outcome.telemetry
+				? { ...outcome.telemetry, selectionReason: selection.reason }
+				: outcome.telemetry,
+		};
+	}
+
+	async release(agent: ManagedAgent): Promise<void> {
+		const selection = this.selections.get(agent.id);
+		this.selections.delete(agent.id);
+		if (selection) await this.transport(selection.kind).release?.(agent);
+	}
+
+	async shutdown(): Promise<void> {
+		this.selections.clear();
+		const transports = [this.options.subprocess, this.options.inProcess, this.options.rpc];
+		const results = await Promise.allSettled(transports.map((transport) => transport.shutdown?.()));
+		const failures = results.flatMap((result) =>
+			result.status === "rejected" ? [result.reason] : [],
+		);
+		if (failures.length > 0) {
+			throw new AggregateError(
+				failures,
+				`Failed to shut down ${failures.length} auto transport(s)`,
+			);
+		}
+	}
+
+	selectionFor(agentId: string): AutoTransportSelection | undefined {
+		const selection = this.selections.get(agentId);
+		return selection ? { ...selection } : undefined;
+	}
+
+	private select(agent: ManagedAgent): AutoTransportSelection {
+		const settings = this.options.getSettings?.();
+		const config = discoverAgents(agent.cwd, agent.agentScope ?? "user", settings).agents.find(
+			(candidate) => candidate.name === agent.agent,
+		);
+		if (!config) {
+			throw new Error(`Automatic transport cannot resolve subagent ${agent.agent}`);
+		}
+		const effectiveTools = agent.executionPlan?.effectiveTools ?? config.tools;
+		const unsupported = (effectiveTools ?? []).filter((tool) => !BUILT_IN_TOOL_NAMES.has(tool));
+		if (unsupported.length > 0) {
+			return {
+				kind: "subprocess",
+				reason: `extension/custom tools require subprocess: ${unsupported.join(", ")}`,
+			};
+		}
+		if (isWriteCapable(effectiveTools)) {
+			return {
+				kind: "rpc",
+				reason: "write-capable built-in tools use a persistent isolated process",
+			};
+		}
+		return {
+			kind: "in-process",
+			reason: "read-only built-in tools use the lowest-overhead public SDK session",
+		};
+	}
+
+	private transport(kind: EffectiveSubagentTransportKind): SubagentTransport {
+		switch (kind) {
+			case "subprocess":
+				return this.options.subprocess;
+			case "in-process":
+				return this.options.inProcess;
+			case "rpc":
+				return this.options.rpc;
+		}
+	}
+}

package/src/blocking-status.ts

@@ -0,0 +1,63 @@
+const STATUS_KEY = "subagents";
+const activeStatuses = new Map<string, string>();
+
+interface StatusContext {
+	ui: { setStatus: (key: string, value: string | undefined) => void };
+}
+
+export function startSubagentStatus(
+	ctx: StatusContext,
+	toolCallId: string,
+	status: string,
+): { update(status: string): void; clear(): void } {
+	let cleared = false;
+	const update = (nextStatus: string) => {
+		if (cleared) return;
+		activeStatuses.set(toolCallId, nextStatus);
+		publishSubagentStatus(ctx);
+	};
+	update(status);
+	return {
+		update,
+		clear() {
+			if (cleared) return;
+			cleared = true;
+			activeStatuses.delete(toolCallId);
+			publishSubagentStatus(ctx);
+		},
+	};
+}
+
+function publishSubagentStatus(ctx: StatusContext): void {
+	const statuses = [...activeStatuses.values()];
+	if (statuses.length === 0) {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		return;
+	}
+	const suffix = statuses.length > 1 ? ` +${statuses.length - 1}` : "";
+	ctx.ui.setStatus(STATUS_KEY, `${statuses[0]}${suffix}`);
+}
+
+export function singleStatus(agent: string): string {
+	return `${agent}`;
+}
+
+export function chainStatus(step: number, total: number, agent?: string): string {
+	return `chain ${step}/${total}${agent ? ` ${agent}` : ""}`;
+}
+
+export function parallelStatus(done: number, total: number, running: number): string {
+	return `parallel ${done}/${total} done${running > 0 ? ` ${running} running` : ""}`;
+}
+
+export function fanInStatus(agent: string): string {
+	return `fan-in ${agent}`;
+}
+
+export function panelReviewStatus(done: number, total: number, running: number): string {
+	return `panel review ${done}/${total}${running > 0 ? ` ${running} running` : ""}`;
+}
+
+export function panelSynthesisStatus(agent: string): string {
+	return `panel synthesis ${agent}`;
+}

package/src/capabilities.ts

@@ -0,0 +1,145 @@
+import type { SubagentResultFormat } from "./result-contract.js";
+import { SUBAGENT_RESULT_FORMATS } from "./result-contract.js";
+
+export const CAPABILITY_MANIFEST_VERSION = "pi-subagents:capabilities:v1" as const;
+export const CAPABILITY_MODALITIES = ["text", "image", "audio"] as const;
+export const FILESYSTEM_AUTHORITY = ["none", "read", "write"] as const;
+export const EXTERNAL_AUTHORITY = ["none", "required"] as const;
+export const CAPABILITY_HINTS = ["low", "medium", "high"] as const;
+export type CapabilityHint = (typeof CAPABILITY_HINTS)[number];
+
+const MAX_ITEMS = 50;
+const MAX_ITEM_LENGTH = 256;
+const MAX_LIMITATION_LENGTH = 1024;
+
+export interface AgentAuthorityManifest {
+	filesystem?: (typeof FILESYSTEM_AUTHORITY)[number];
+	network?: (typeof EXTERNAL_AUTHORITY)[number];
+	secrets?: (typeof EXTERNAL_AUTHORITY)[number];
+}
+
+export interface AgentCapabilityManifest {
+	version: typeof CAPABILITY_MANIFEST_VERSION;
+	capabilities: string[];
+	modalities: Array<(typeof CAPABILITY_MODALITIES)[number]>;
+	resultFormats: SubagentResultFormat[];
+	authority?: AgentAuthorityManifest;
+	verificationRoles: string[];
+	contextStrengths?: string[];
+	costHint?: CapabilityHint;
+	latencyHint?: CapabilityHint;
+	limitations: string[];
+}
+
+export function normalizeCapabilityManifest(value: unknown): AgentCapabilityManifest | undefined {
+	if (value === undefined) return undefined;
+	if (!isPlainObject(value) || value.version !== CAPABILITY_MANIFEST_VERSION) return undefined;
+	const capabilities = identifiers(value.capabilities, false);
+	const modalities = enumArray(value.modalities, CAPABILITY_MODALITIES);
+	const resultFormats = enumArray(value.resultFormats, SUBAGENT_RESULT_FORMATS);
+	const verificationRoles = identifiers(value.verificationRoles, false);
+	const contextStrengths =
+		value.contextStrengths === undefined ? undefined : identifiers(value.contextStrengths, false);
+	const costHint = optionalEnum(value.costHint, CAPABILITY_HINTS);
+	const latencyHint = optionalEnum(value.latencyHint, CAPABILITY_HINTS);
+	const limitations = strings(value.limitations, MAX_LIMITATION_LENGTH);
+	if (
+		!capabilities ||
+		!modalities ||
+		!resultFormats ||
+		!verificationRoles ||
+		(contextStrengths === undefined && value.contextStrengths !== undefined) ||
+		costHint === false ||
+		latencyHint === false ||
+		!limitations
+	) {
+		return undefined;
+	}
+	const authority = normalizeAuthority(value.authority);
+	if (authority === false) return undefined;
+	return {
+		version: CAPABILITY_MANIFEST_VERSION,
+		capabilities,
+		modalities,
+		resultFormats,
+		...(authority === undefined ? {} : { authority }),
+		verificationRoles,
+		...(contextStrengths === undefined ? {} : { contextStrengths }),
+		...(costHint === undefined ? {} : { costHint }),
+		...(latencyHint === undefined ? {} : { latencyHint }),
+		limitations,
+	};
+}
+
+export function projectCapabilityManifest(
+	manifest: AgentCapabilityManifest | undefined,
+): AgentCapabilityManifest | undefined {
+	return manifest ? structuredClone(manifest) : undefined;
+}
+
+function normalizeAuthority(value: unknown): AgentAuthorityManifest | undefined | false {
+	if (value === undefined) return undefined;
+	if (!isPlainObject(value)) return false;
+	const filesystem = optionalEnum(value.filesystem, FILESYSTEM_AUTHORITY);
+	const network = optionalEnum(value.network, EXTERNAL_AUTHORITY);
+	const secrets = optionalEnum(value.secrets, EXTERNAL_AUTHORITY);
+	if (filesystem === false || network === false || secrets === false) return false;
+	return {
+		...(filesystem === undefined ? {} : { filesystem }),
+		...(network === undefined ? {} : { network }),
+		...(secrets === undefined ? {} : { secrets }),
+	};
+}
+
+function identifiers(value: unknown, required: boolean): string[] | undefined {
+	if (value === undefined) return required ? undefined : [];
+	return strings(value, MAX_ITEM_LENGTH, /^[a-z0-9]+(?:-[a-z0-9]+)*$/u);
+}
+
+function strings(value: unknown, maxLength: number, pattern?: RegExp): string[] | undefined {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > MAX_ITEMS) return undefined;
+	const result: string[] = [];
+	const seen = new Set<string>();
+	for (const item of value) {
+		if (typeof item !== "string") return undefined;
+		const normalized = item.trim();
+		if (!normalized || normalized.length > maxLength || (pattern && !pattern.test(normalized))) {
+			return undefined;
+		}
+		if (seen.has(normalized)) continue;
+		seen.add(normalized);
+		result.push(normalized);
+	}
+	return result;
+}
+
+function enumArray<const T extends readonly string[]>(
+	value: unknown,
+	allowed: T,
+): Array<T[number]> | undefined {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || value.length > MAX_ITEMS) return undefined;
+	const result: Array<T[number]> = [];
+	const seen = new Set<string>();
+	for (const item of value) {
+		if (typeof item !== "string" || !allowed.includes(item)) return undefined;
+		if (seen.has(item)) continue;
+		seen.add(item);
+		result.push(item as T[number]);
+	}
+	return result;
+}
+
+function optionalEnum<const T extends readonly string[]>(
+	value: unknown,
+	allowed: T,
+): T[number] | undefined | false {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || !allowed.includes(value)) return false;
+	return value as T[number];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/capability-grant.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { type ExecutionPlan, isExecutionPlan } from "./execution-plan.js";
+
+export const CAPABILITY_GRANT_VERSION = "pi-subagents:capability-grant:v1" as const;
+
+export interface CapabilityGrant {
+	version: typeof CAPABILITY_GRANT_VERSION;
+	id: string;
+	executionPlanId: string;
+	taskGeneration: number;
+	effectiveTools?: string[];
+	issuedAt: number;
+	expiresAt: number;
+	state: "active" | "revoked";
+	revokedAt?: number;
+	revocationReason?: string;
+}
+
+function grantId(projection: {
+	executionPlanId: string;
+	taskGeneration: number;
+	effectiveTools?: string[];
+	issuedAt: number;
+	expiresAt: number;
+}): string {
+	return createHash("sha256").update(JSON.stringify(projection)).digest("hex");
+}
+
+export function issueCapabilityGrant(
+	plan: ExecutionPlan,
+	issuedAt: number,
+	lifetimeMs: number,
+): CapabilityGrant {
+	if (!Number.isFinite(issuedAt) || !Number.isFinite(lifetimeMs) || lifetimeMs <= 0) {
+		throw new Error("Capability grant requires finite issuance and lifetime bounds");
+	}
+	const expiresAt = issuedAt + lifetimeMs;
+	const projection = {
+		executionPlanId: plan.id,
+		taskGeneration: plan.taskGeneration,
+		effectiveTools: plan.effectiveTools,
+		issuedAt,
+		expiresAt,
+	};
+	return {
+		version: CAPABILITY_GRANT_VERSION,
+		id: grantId(projection),
+		...projection,
+		state: "active",
+	};
+}
+
+export function revokeCapabilityGrant(
+	grant: CapabilityGrant,
+	reason: string,
+	revokedAt: number,
+): CapabilityGrant {
+	if (grant.state === "revoked") throw new Error("Capability grant is already revoked");
+	grant.state = "revoked";
+	grant.revokedAt = revokedAt;
+	grant.revocationReason = reason.slice(0, 256);
+	return structuredClone(grant);
+}
+
+export function isCapabilityGrant(value: unknown): value is CapabilityGrant {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const grant = value as Partial<CapabilityGrant>;
+	const validShape =
+		grant.version === CAPABILITY_GRANT_VERSION &&
+		typeof grant.id === "string" &&
+		/^[a-f0-9]{64}$/u.test(grant.id) &&
+		typeof grant.executionPlanId === "string" &&
+		/^[a-f0-9]{64}$/u.test(grant.executionPlanId) &&
+		Number.isSafeInteger(grant.taskGeneration) &&
+		Number(grant.taskGeneration) >= 0 &&
+		Number.isFinite(grant.issuedAt) &&
+		Number.isFinite(grant.expiresAt) &&
+		Number(grant.expiresAt) >= Number(grant.issuedAt) &&
+		(grant.state === "active" || grant.state === "revoked") &&
+		(grant.state === "active"
+			? grant.revokedAt === undefined && grant.revocationReason === undefined
+			: Number.isFinite(grant.revokedAt) &&
+				typeof grant.revocationReason === "string" &&
+				grant.revocationReason.length > 0) &&
+		(grant.effectiveTools === undefined ||
+			(Array.isArray(grant.effectiveTools) &&
+				grant.effectiveTools.every((tool) => typeof tool === "string")));
+	if (!validShape) return false;
+	const validated = grant as CapabilityGrant;
+	const expectedId = grantId({
+		executionPlanId: validated.executionPlanId,
+		taskGeneration: validated.taskGeneration,
+		effectiveTools: validated.effectiveTools,
+		issuedAt: validated.issuedAt,
+		expiresAt: validated.expiresAt,
+	});
+	return validated.id === expectedId;
+}
+
+export function isCapabilityGrantActive(
+	grant: CapabilityGrant,
+	plan: ExecutionPlan,
+	now: number,
+): boolean {
+	return (
+		isCapabilityGrant(grant) &&
+		isExecutionPlan(plan) &&
+		grant.state === "active" &&
+		grant.executionPlanId === plan.id &&
+		grant.taskGeneration === plan.taskGeneration &&
+		JSON.stringify(grant.effectiveTools ?? null) === JSON.stringify(plan.effectiveTools ?? null) &&
+		now >= grant.issuedAt &&
+		now <= grant.expiresAt
+	);
+}

package/src/capability-router.ts

@@ -0,0 +1,107 @@
+import { type AgentConfig, resolveAgentToolNames } from "./agents.js";
+import type { CapabilityHint } from "./capabilities.js";
+
+export interface CapabilityRouteRequest {
+	agent?: string;
+	requiredCapabilities?: string[];
+	requiredTools?: string[];
+	requiredVerificationRole?: string;
+	requiredSideEffectClass?: string;
+	preferredCostHint?: CapabilityHint;
+	preferredLatencyHint?: CapabilityHint;
+}
+
+export interface CapabilityRouteDecision {
+	agent: AgentConfig;
+	eligibleAgents: string[];
+	requiredCapabilities: string[];
+}
+
+const HINT_RANK: Record<CapabilityHint, number> = { low: 0, medium: 1, high: 2 };
+
+export function routeByCapability(
+	agents: readonly AgentConfig[],
+	request: CapabilityRouteRequest,
+): CapabilityRouteDecision {
+	const requiredCapabilities = unique(request.requiredCapabilities ?? []);
+	const requiredTools = unique(request.requiredTools ?? []);
+	const eligible = agents.filter((agent) => {
+		const manifest = agent.capabilityManifest;
+		const effectiveTools = resolveAgentToolNames(agent.tools);
+		if (!manifest) {
+			return (
+				requiredCapabilities.length === 0 &&
+				requiredTools.every((tool) => effectiveTools.includes(tool)) &&
+				request.requiredVerificationRole === undefined &&
+				request.requiredSideEffectClass === undefined
+			);
+		}
+		const sideEffectAllowed =
+			request.requiredSideEffectClass !== "read-only" ||
+			manifest.authority?.filesystem === "read" ||
+			manifest.authority?.filesystem === "none";
+		return (
+			requiredCapabilities.every((capability) => manifest.capabilities.includes(capability)) &&
+			requiredTools.every((tool) => effectiveTools.includes(tool)) &&
+			(!request.requiredVerificationRole ||
+				manifest.verificationRoles.includes(request.requiredVerificationRole)) &&
+			sideEffectAllowed
+		);
+	});
+	if (request.agent) {
+		const named = agents.find((agent) => agent.name === request.agent);
+		if (!named) throw new Error(`Unknown subagent ${request.agent}`);
+		if (!eligible.includes(named)) {
+			throw new Error(
+				`Selected subagent ${request.agent} does not satisfy the required capability manifest`,
+			);
+		}
+		return {
+			agent: named,
+			eligibleAgents: eligible.map((agent) => agent.name).sort(),
+			requiredCapabilities,
+		};
+	}
+	if (eligible.length === 0) {
+		throw new Error(
+			`No capable agent satisfies: ${
+				[...requiredCapabilities, ...requiredTools.map((tool) => `tool:${tool}`)].join(", ") ||
+				"the requested side-effect class"
+			}`,
+		);
+	}
+	const ranked = [...eligible].sort((left, right) => {
+		const leftCost = hintDistance(
+			left.capabilityManifest?.costHint ?? "medium",
+			request.preferredCostHint,
+		);
+		const rightCost = hintDistance(
+			right.capabilityManifest?.costHint ?? "medium",
+			request.preferredCostHint,
+		);
+		const leftLatency = hintDistance(
+			left.capabilityManifest?.latencyHint ?? "medium",
+			request.preferredLatencyHint,
+		);
+		const rightLatency = hintDistance(
+			right.capabilityManifest?.latencyHint ?? "medium",
+			request.preferredLatencyHint,
+		);
+		return (
+			leftCost - rightCost || leftLatency - rightLatency || left.name.localeCompare(right.name)
+		);
+	});
+	return {
+		agent: ranked[0],
+		eligibleAgents: ranked.map((agent) => agent.name),
+		requiredCapabilities,
+	};
+}
+
+function hintDistance(actual: CapabilityHint, preferred: CapabilityHint | undefined): number {
+	return preferred ? Math.abs(HINT_RANK[actual] - HINT_RANK[preferred]) : HINT_RANK[actual];
+}
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values.map((value) => value.trim()).filter(Boolean))].sort();
+}