@narumitw/pi-subagents 2.1.3 → 3.0.0

package/src/rpc-turn-capture.ts

@@ -1,217 +0,0 @@
-import { DEFAULT_MAX_OUTPUT_BYTES, truncateUtf8 } from "./limits.js";
-import { boundedPrivateText } from "./safe-text.js";
-import { journalMessages, TimeoutProgressJournal } from "./timeout-checkpoint.js";
-import { emptyTransportUsage, type TransportUsage } from "./transport-types.js";
-import type { TurnBudgetMonitor } from "./turn-budget.js";
-
-export interface RpcTurnCapture {
-	output: string;
-	partial: string;
-	stopReason?: string;
-	error?: string;
-	provider?: string;
-	model?: string;
-	usage: TransportUsage;
-	inFlightUsage?: TransportUsage;
-	firstActivityAt?: number;
-	journal: TimeoutProgressJournal;
-}
-
-export function createRpcTurnCapture(): RpcTurnCapture {
-	return {
-		output: "",
-		partial: "",
-		usage: emptyTransportUsage(),
-		journal: new TimeoutProgressJournal(),
-	};
-}
-
-export function captureRpcEvent(event: unknown, capture: RpcTurnCapture): boolean {
-	if (!isRecord(event)) return false;
-	const previousUsage = snapshotRpcUsage(capture);
-	if (event.type === "tool_execution_start") {
-		capture.journal.recordToolCall(
-			typeof event.toolCallId === "string" ? event.toolCallId : "",
-			typeof event.toolName === "string" ? event.toolName : "tool",
-			isRecord(event.args) ? event.args : {},
-		);
-	}
-	if (event.type === "tool_execution_end") {
-		const result = isRecord(event.result) ? event.result : {};
-		capture.journal.recordToolResult(
-			typeof event.toolCallId === "string" ? event.toolCallId : "",
-			typeof event.toolName === "string" ? event.toolName : "tool",
-			{ content: result.content, isError: event.isError },
-		);
-	}
-	if (event.type === "message_start" && isRecord(event.message)) {
-		if (event.message.role === "assistant") commitRpcInFlightUsage(capture);
-	}
-	if (event.type === "message_update") {
-		const usage = normalizeUsage(event.usage);
-		if (usage) capture.inFlightUsage = usage;
-		const delta = event.assistantMessageEvent;
-		if (isRecord(delta) && delta.type === "text_delta" && typeof delta.delta === "string") {
-			capture.partial = truncateUtf8(
-				`${capture.partial}${delta.delta}`,
-				DEFAULT_MAX_OUTPUT_BYTES,
-			).text;
-		}
-	}
-	if (event.type === "message_end" && isRecord(event.message)) {
-		const candidate = event.message;
-		if (candidate.role !== "toolResult") journalMessages(capture.journal, [candidate]);
-		if (candidate.role === "assistant") captureAssistantEnd(candidate, capture);
-	}
-	return !sameUsage(previousUsage, snapshotRpcUsage(capture));
-}
-
-export function snapshotRpcUsage(capture: RpcTurnCapture): TransportUsage {
-	const usage = { ...capture.usage };
-	if (capture.inFlightUsage) addUsage(usage, capture.inFlightUsage);
-	return usage;
-}
-
-export function commitRpcInFlightUsage(capture: RpcTurnCapture): boolean {
-	if (!capture.inFlightUsage) return false;
-	addUsage(capture.usage, capture.inFlightUsage);
-	capture.inFlightUsage = undefined;
-	return true;
-}
-
-function captureAssistantEnd(candidate: Record<string, unknown>, capture: RpcTurnCapture): void {
-	capture.output = truncateUtf8(
-		assistantText(candidate.content) || capture.partial,
-		DEFAULT_MAX_OUTPUT_BYTES,
-	).text;
-	capture.partial = capture.output;
-	capture.stopReason = typeof candidate.stopReason === "string" ? candidate.stopReason : undefined;
-	capture.error =
-		typeof candidate.errorMessage === "string"
-			? boundedPrivateText(candidate.errorMessage, 4 * 1024)
-			: undefined;
-	capture.provider =
-		typeof candidate.provider === "string"
-			? boundedPrivateText(candidate.provider, 256)
-			: undefined;
-	const responseModel =
-		typeof candidate.responseModel === "string"
-			? candidate.responseModel
-			: typeof candidate.model === "string"
-				? candidate.model
-				: undefined;
-	capture.model = responseModel ? boundedPrivateText(responseModel, 256) : undefined;
-	const finalUsage = normalizeUsage(candidate.usage);
-	const completedUsage = finalUsage ?? capture.inFlightUsage;
-	if (completedUsage) addUsage(capture.usage, completedUsage);
-	capture.inFlightUsage = undefined;
-	capture.usage.turns = addUsageValue(capture.usage.turns, 1);
-}
-
-export function observeRpcBudgetEvent(event: unknown, monitor: TurnBudgetMonitor): void {
-	if (!isRecord(event)) return;
-	if (event.type === "tool_execution_end") monitor.recordActivity();
-	if (event.type !== "message_end" || !isRecord(event.message)) return;
-	const message = event.message;
-	if (message.role === "toolResult") {
-		monitor.recordActivity();
-		return;
-	}
-	if (message.role !== "assistant") return;
-	monitor.recordToolCalls(assistantToolCallCount(message.content));
-	monitor.recordAssistantTurn(
-		typeof message.stopReason === "string" ? message.stopReason : undefined,
-	);
-}
-
-function assistantToolCallCount(content: unknown): number {
-	if (!Array.isArray(content)) return 0;
-	return content.filter((part) => isRecord(part) && part.type === "toolCall").length;
-}
-
-function normalizeUsage(value: unknown): TransportUsage | undefined {
-	if (!isRecord(value)) return undefined;
-	const input = safeNonNegative(value.input);
-	const output = safeNonNegative(value.output);
-	const cacheRead = safeNonNegative(value.cacheRead);
-	const cacheWrite = safeNonNegative(value.cacheWrite);
-	const reportedTotal = safeNonNegative(value.totalTokens);
-	const cost = isRecord(value.cost) ? safeNonNegative(value.cost.total) : undefined;
-	if (
-		input === undefined &&
-		output === undefined &&
-		cacheRead === undefined &&
-		cacheWrite === undefined &&
-		reportedTotal === undefined &&
-		cost === undefined
-	) {
-		return undefined;
-	}
-	const components = [input, output, cacheRead, cacheWrite].reduce<number>(
-		(total, current) => addUsageValue(total, current ?? 0),
-		0,
-	);
-	return {
-		input: input ?? 0,
-		output: output ?? 0,
-		cacheRead: cacheRead ?? 0,
-		cacheWrite: cacheWrite ?? 0,
-		totalTokens: reportedTotal ?? components,
-		cost: cost ?? 0,
-		turns: 0,
-	};
-}
-
-function addUsage(target: TransportUsage, value: TransportUsage): void {
-	for (const key of [
-		"input",
-		"output",
-		"cacheRead",
-		"cacheWrite",
-		"totalTokens",
-		"cost",
-		"turns",
-	] as const) {
-		target[key] = addUsageValue(target[key], value[key]);
-	}
-}
-
-function addUsageValue(current: number, addition: number): number {
-	return Math.min(Number.MAX_SAFE_INTEGER, current + addition);
-}
-
-function safeNonNegative(value: unknown): number | undefined {
-	return typeof value === "number" &&
-		Number.isFinite(value) &&
-		value >= 0 &&
-		value <= Number.MAX_SAFE_INTEGER
-		? value
-		: undefined;
-}
-
-function sameUsage(left: TransportUsage, right: TransportUsage): boolean {
-	return (
-		left.input === right.input &&
-		left.output === right.output &&
-		left.cacheRead === right.cacheRead &&
-		left.cacheWrite === right.cacheWrite &&
-		left.totalTokens === right.totalTokens &&
-		left.cost === right.cost &&
-		left.turns === right.turns
-	);
-}
-
-function assistantText(value: unknown): string {
-	if (typeof value === "string") return value;
-	if (!Array.isArray(value)) return "";
-	return value
-		.flatMap((part) => {
-			if (!isRecord(part)) return [];
-			return part.type === "text" && typeof part.text === "string" ? [part.text] : [];
-		})
-		.join("\n");
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

package/src/runner-outcome.ts

@@ -1,31 +0,0 @@
-import {
-	formatResultFailure as formatBaseResultFailure,
-	getResultFinalOutput as getBaseResultFinalOutput,
-	isResultError as isBaseResultError,
-} from "./runner-result.js";
-import type { SingleResult } from "./runner-types.js";
-
-export function getResultFinalOutput(result: SingleResult): string {
-	return getBaseResultFinalOutput(result);
-}
-
-export function isResultError(result: SingleResult): boolean {
-	return (
-		isBaseResultError(result) ||
-		result.resultContractInvalid === true ||
-		(result.outcome !== undefined &&
-			result.outcome.status !== "completed" &&
-			result.outcome.status !== "partial")
-	);
-}
-
-export function formatResultFailure(result: SingleResult): string {
-	const contractError = result.resultContractInvalid
-		? `Subagent returned an invalid ${result.resultFormat ?? "structured"} result contract`
-		: result.outcome && !["completed", "partial"].includes(result.outcome.status)
-			? `Subagent outcome ${result.outcome.status}${result.outcome.reasonCode ? ` (${result.outcome.reasonCode})` : ""}; recovery: ${result.outcome.recoveryActions.join(", ") || "none"}`
-			: undefined;
-	return contractError
-		? formatBaseResultFailure({ ...result, errorMessage: contractError })
-		: formatBaseResultFailure(result);
-}

package/src/runner-result.ts

@@ -1,55 +0,0 @@
-import type { Message } from "@earendil-works/pi-ai";
-import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
-import type { SingleResult } from "./runner-types.js";
-import { formatTimeoutCheckpoint } from "./timeout-checkpoint.js";
-
-export function getFinalOutput(messages: Message[]): string {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const msg = messages[i];
-		if (msg?.role === "assistant") {
-			const text = msg.content
-				.filter((part) => part.type === "text")
-				.map((part) => part.text)
-				.join("\n");
-			if (text) return text;
-		}
-	}
-	return "";
-}
-
-export function getResultFinalOutput(result: SingleResult): string {
-	return result.finalOutput ?? getFinalOutput(result.messages);
-}
-
-export function isResultError(result: SingleResult): boolean {
-	return (
-		(result.exitCode !== 0 && result.exitCode !== -1) ||
-		result.timedOut === true ||
-		result.stopReason === "timeout" ||
-		result.stopReason === "error" ||
-		result.stopReason === "aborted"
-	);
-}
-
-export function formatResultFailure(result: SingleResult): string {
-	const error = result.errorMessage || result.stderr.trim();
-	const output = getResultFinalOutput(result);
-	const sections = [error];
-	if (result.timeoutSummary) sections.push(`Timed-out work summary:\n${result.timeoutSummary}`);
-	else if (output) sections.push(`Partial output:\n${output}`);
-	if (result.partialOutput && result.partialOutput !== output) {
-		sections.push(`Partial output before finalization:\n${result.partialOutput}`);
-	}
-	if (result.termination && !result.timeoutSummary) {
-		sections.push(
-			`Termination checkpoint:\n${formatTimeoutCheckpoint(result.termination.checkpoint)}`,
-		);
-	}
-	if (result.timeoutSummaryError) {
-		sections.push(`Summary finalization failed: ${result.timeoutSummaryError}`);
-	}
-	return truncateUtf8(
-		sections.filter(Boolean).join("\n\n") || "(no output)",
-		DEFAULT_MAX_CONTEXT_BYTES,
-	).text;
-}

package/src/runner-types.ts

@@ -1,102 +0,0 @@
-import type { Message } from "@earendil-works/pi-ai";
-import type { AgentSource, SubagentThinkingLevel } from "./agents/types.js";
-import type { CapabilityGrant } from "./capability-grant.js";
-import type { TargetPolicyAudit } from "./cwd-policy.js";
-import type { DelegationContract } from "./delegation-contract.js";
-import type { ExecutionPlan } from "./execution-plan.js";
-import type { ClassifiedSubagentOutcome } from "./outcome.js";
-import type { AnyStructuredSubagentResult, SubagentResultFormat } from "./result-contract.js";
-import type { UsageStats } from "./runner-usage.js";
-import type { TurnTerminationReport } from "./timeout-checkpoint.js";
-import type { TurnLimits } from "./turn-budget.js";
-
-export type RecentActivityItem =
-	| { type: "text"; text: string }
-	| { type: "toolCall"; name: string; args: Record<string, unknown> };
-
-export interface SingleResult {
-	agent: string;
-	agentSource: AgentSource | "unknown";
-	task: string;
-	exitCode: number;
-	messages: Message[];
-	stderr: string;
-	usage: UsageStats;
-	model?: string;
-	actualProvider?: string;
-	actualModel?: string;
-	recentActivity?: RecentActivityItem[];
-	recentActivityTotal?: number;
-	thinkingLevel?: SubagentThinkingLevel;
-	stopReason?: string;
-	errorMessage?: string;
-	step?: number;
-	finalOutput?: string;
-	partialOutput?: string;
-	timeoutSummary?: string;
-	timeoutSummaryError?: string;
-	termination?: TurnTerminationReport;
-	timedOut?: boolean;
-	timeoutMs?: number;
-	aborted?: boolean;
-	truncated?: boolean;
-	malformedEvents?: number;
-	launchFailed?: boolean;
-	processStarted?: boolean;
-	target?: TargetPolicyAudit;
-	policy?: {
-		inherited: string[];
-		overridden: string[];
-		unsupported: string[];
-	};
-	contract?: DelegationContract;
-	resultFormat?: SubagentResultFormat;
-	structuredResult?: AnyStructuredSubagentResult;
-	resultContractInvalid?: boolean;
-	outcome?: ClassifiedSubagentOutcome;
-	attemptCount?: number;
-	hedged?: boolean;
-	executionPlan?: ExecutionPlan;
-	capabilityGrant?: CapabilityGrant;
-}
-
-export interface ChildLaunchPolicy {
-	tools?: string[];
-	disableExtensions?: boolean;
-	disableSkills?: boolean;
-	disablePromptTemplates?: boolean;
-	disableContextFiles?: boolean;
-	projectTrust?: boolean;
-	baseSystemPrompt?: string;
-	appendSystemPromptPaths?: string[];
-	/** Package-owned explicit child extensions loaded even when unrelated extensions are disabled. */
-	extensionPaths?: string[];
-	/** Package-owned tools added to the child allowlist without changing delegated execution tools. */
-	additionalTools?: string[];
-	/** Ephemeral child-process environment consumed and cleared by a package-owned bridge. */
-	env?: NodeJS.ProcessEnv;
-	/** Internal timeout recovery control; omitted means enabled. */
-	finalizeOnTimeout?: boolean;
-	/** Internal hard deadline for the summary attempt. */
-	timeoutFinalizationMs?: number;
-	/** Optional stateful result contract retained during timeout finalization. */
-	timeoutResultFormat?: SubagentResultFormat;
-	/** Optional non-wall-clock limits for this turn. */
-	turnLimits?: TurnLimits;
-	/** Override the timeout reason when an orchestration deadline caps this child. */
-	workTimeoutReason?: "work_timeout" | "orchestration_timeout";
-	/** Public limit value reported when the effective child timeout is only the remaining budget. */
-	workTimeoutReportLimit?: number;
-	/** Absolute blocking-workflow deadline that also caps model finalization. */
-	orchestrationDeadlineAt?: number;
-	/** Completion contract requested for this turn. */
-	resultFormat?: SubagentResultFormat;
-	/** Normalized request contract retained in result details. */
-	contract?: DelegationContract;
-	/** Original task summary shown in result details when the executed prompt has contract metadata. */
-	displayTask?: string;
-	/** Immutable audit or enforcement decision made before launch. */
-	executionPlan?: ExecutionPlan;
-	/** Executor-owned authority lifetime bound to the accepted plan generation. */
-	capabilityGrant?: CapabilityGrant;
-}

package/src/runner-usage.ts

@@ -1,48 +0,0 @@
-export interface UsageStats {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	cost: number;
-	costInput?: number;
-	costOutput?: number;
-	costCacheRead?: number;
-	costCacheWrite?: number;
-	totalTokens?: number;
-	contextTokens: number;
-	turns: number;
-}
-
-const MAX_USAGE_VALUE = Number.MAX_SAFE_INTEGER;
-
-export function protocolUsageCount(value: unknown): number {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
-}
-
-export function protocolUsageCost(value: unknown): number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0
-		? Math.min(value, MAX_USAGE_VALUE)
-		: 0;
-}
-
-export function addUsageValue(current: number, addition: number): number {
-	return Math.min(MAX_USAGE_VALUE, current + addition);
-}
-
-export function mergeUsageStats(target: UsageStats, addition: UsageStats): void {
-	for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"] as const) {
-		target[key] = addUsageValue(target[key], addition[key]);
-	}
-	for (const key of [
-		"costInput",
-		"costOutput",
-		"costCacheRead",
-		"costCacheWrite",
-		"totalTokens",
-	] as const) {
-		if (addition[key] !== undefined) {
-			target[key] = addUsageValue(target[key] ?? 0, addition[key]);
-		}
-	}
-	target.contextTokens = addition.contextTokens || target.contextTokens;
-}