@narumitw/pi-subagents 2.1.3 → 3.0.0

package/src/blocking-status.ts

@@ -1,63 +0,0 @@
-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/cached-module-loader.ts

@@ -1,18 +0,0 @@
-export function cachedModuleLoader<Module>(load: () => Promise<Module>): () => Promise<Module> {
-	let pending: Promise<Module> | undefined;
-	return () => {
-		if (!pending) {
-			pending = load().catch((error) => {
-				pending = undefined;
-				throw error;
-			});
-		}
-		return pending;
-	};
-}
-
-export function throwIfAborted(signal: AbortSignal | undefined, message: string): void {
-	if (!signal?.aborted) return;
-	if (signal.reason instanceof Error) throw signal.reason;
-	throw new DOMException(message, "AbortError");
-}

package/src/capabilities.ts

@@ -1,145 +0,0 @@
-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

@@ -1,115 +0,0 @@
-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

@@ -1,107 +0,0 @@
-import { type AgentConfig, resolveAgentToolNames } from "./agents/types.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();
-}

package/src/child-peer-bridge.ts

@@ -1,124 +0,0 @@
-import net from "node:net";
-import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import { type ChildPeerClient, createChildPeerExtension } from "./child-peer-tools.js";
-import type { AgentMailboxMessage } from "./registry.js";
-
-const MAX_RESPONSE_BYTES = 64 * 1024;
-const REQUEST_TIMEOUT_MS = 2_000;
-
-const captured = captureBridgeEnvironment();
-
-const childPeerBridge: ExtensionFactory = captured
-	? createChildPeerExtension(createProcessPeerClient(captured))
-	: () => undefined;
-
-export default childPeerBridge;
-
-interface CapturedBridgeEnvironment {
-	host: "127.0.0.1";
-	port: number;
-	token: string;
-}
-
-export function captureBridgeEnvironment(): CapturedBridgeEnvironment | undefined {
-	const host = process.env.PI_SUBAGENT_PEER_HOST;
-	const rawPort = process.env.PI_SUBAGENT_PEER_PORT;
-	const token = process.env.PI_SUBAGENT_PEER_TOKEN;
-	delete process.env.PI_SUBAGENT_PEER_HOST;
-	delete process.env.PI_SUBAGENT_PEER_PORT;
-	delete process.env.PI_SUBAGENT_PEER_TOKEN;
-	if (!host && !rawPort && !token) return undefined;
-	const port = Number(rawPort);
-	if (host !== "127.0.0.1" || !Number.isSafeInteger(port) || port < 1 || port > 65_535 || !token) {
-		throw new Error("Invalid pi-subagents peer bridge environment");
-	}
-	return { host, port, token };
-}
-
-function createProcessPeerClient(environment: CapturedBridgeEnvironment): ChildPeerClient {
-	const request = async (input: Record<string, unknown>): Promise<Record<string, unknown>> => {
-		const response = await requestBridge(environment, { ...input, token: environment.token });
-		if (response.ok !== true) {
-			throw new Error(
-				typeof response.error === "string"
-					? response.error
-					: "Subagent peer bridge rejected the request",
-			);
-		}
-		return response;
-	};
-	return {
-		async send(target, message, deduplicationKey) {
-			const response = await request({
-				action: "send",
-				target,
-				message,
-				...(deduplicationKey ? { deduplicationKey } : {}),
-			});
-			if (!isMailboxMessage(response.message)) {
-				throw new Error("Subagent peer bridge returned an invalid message receipt");
-			}
-			return response.message;
-		},
-		async list() {
-			return (await request({ action: "list" })).peers ?? [];
-		},
-		async acknowledge(messageIds, completionIds) {
-			await request({ action: "acknowledge", messageIds, completionIds });
-		},
-	};
-}
-
-function requestBridge(
-	environment: CapturedBridgeEnvironment,
-	request: Record<string, unknown>,
-): Promise<Record<string, unknown>> {
-	return new Promise((resolve, reject) => {
-		const socket = net.createConnection({ host: environment.host, port: environment.port });
-		let response = Buffer.alloc(0);
-		let settled = false;
-		const finish = (error?: Error, value?: Record<string, unknown>) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			socket.destroy();
-			if (error) reject(error);
-			else resolve(value ?? {});
-		};
-		const timer = setTimeout(
-			() => finish(new Error("Subagent peer bridge request timed out")),
-			REQUEST_TIMEOUT_MS,
-		);
-		timer.unref();
-		socket.once("connect", () => socket.end(`${JSON.stringify(request)}\n`));
-		socket.on("data", (chunk: Buffer) => {
-			response = Buffer.concat([response, chunk]);
-			if (response.byteLength > MAX_RESPONSE_BYTES) {
-				finish(new Error("Subagent peer bridge response exceeded its size limit"));
-			}
-		});
-		socket.once("error", (error) => finish(error));
-		socket.once("close", () => {
-			if (settled) return;
-			try {
-				const parsed = JSON.parse(response.toString("utf8")) as unknown;
-				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
-				finish(undefined, parsed as Record<string, unknown>);
-			} catch {
-				finish(new Error("Subagent peer bridge returned malformed JSON"));
-			}
-		});
-	});
-}
-
-function isMailboxMessage(value: unknown): value is AgentMailboxMessage {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-	const message = value as Record<string, unknown>;
-	return (
-		typeof message.id === "string" &&
-		typeof message.senderId === "string" &&
-		typeof message.recipientId === "string" &&
-		typeof message.content === "string" &&
-		typeof message.createdAt === "number"
-	);
-}