@narumitw/pi-subagents 0.49.3 → 0.52.0

package/src/turn-budget.ts

@@ -0,0 +1,109 @@
+import { MAX_SUBAGENT_TIMEOUT_MS } from "./limits.js";
+import type { TurnTerminationReason } from "./timeout-checkpoint.js";
+
+export const MAX_SUBAGENT_TURNS = 1_000_000;
+export const MAX_SUBAGENT_TOOL_CALLS = 1_000_000;
+
+export interface TurnLimits {
+	idleTimeoutMs?: number;
+	maxTurns?: number;
+	maxToolCalls?: number;
+}
+
+export interface TurnBudgetStop {
+	reason: Extract<TurnTerminationReason, "idle_timeout" | "turn_limit" | "tool_call_limit">;
+	limit: number;
+}
+
+export interface TurnBudgetMonitorOptions extends TurnLimits {
+	onExceeded(stop: TurnBudgetStop): void;
+}
+
+const TERMINAL_STOP_REASONS = new Set(["stop", "length", "error", "aborted"]);
+
+export function validateTurnLimits(limits: TurnLimits): TurnLimits {
+	validateOptionalInteger("idleTimeoutMs", limits.idleTimeoutMs, MAX_SUBAGENT_TIMEOUT_MS);
+	validateOptionalInteger("maxTurns", limits.maxTurns, MAX_SUBAGENT_TURNS);
+	validateOptionalInteger("maxToolCalls", limits.maxToolCalls, MAX_SUBAGENT_TOOL_CALLS);
+	return { ...limits };
+}
+
+export class TurnBudgetMonitor {
+	private readonly limits: TurnLimits;
+	private readonly onExceeded: (stop: TurnBudgetStop) => void;
+	private idleTimer?: NodeJS.Timeout;
+	private assistantTurns = 0;
+	private toolCalls = 0;
+	private stopped = false;
+
+	constructor(options: TurnBudgetMonitorOptions) {
+		this.limits = validateTurnLimits({
+			idleTimeoutMs: options.idleTimeoutMs,
+			maxTurns: options.maxTurns,
+			maxToolCalls: options.maxToolCalls,
+		});
+		this.onExceeded = options.onExceeded;
+		this.resetIdleTimer();
+	}
+
+	recordActivity(): void {
+		if (this.stopped) return;
+		this.resetIdleTimer();
+	}
+
+	recordAssistantTurn(stopReason?: string): void {
+		if (this.stopped) return;
+		this.assistantTurns++;
+		this.recordActivity();
+		if (
+			this.limits.maxTurns !== undefined &&
+			this.assistantTurns >= this.limits.maxTurns &&
+			!TERMINAL_STOP_REASONS.has(stopReason ?? "")
+		) {
+			this.exceed({ reason: "turn_limit", limit: this.limits.maxTurns });
+		}
+	}
+
+	recordToolCalls(count = 1): void {
+		if (this.stopped || count < 1) return;
+		this.toolCalls += count;
+		if (this.limits.maxToolCalls !== undefined && this.toolCalls > this.limits.maxToolCalls) {
+			this.exceed({ reason: "tool_call_limit", limit: this.limits.maxToolCalls });
+		}
+	}
+
+	dispose(): void {
+		this.stopped = true;
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = undefined;
+	}
+
+	private resetIdleTimer(): void {
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		const idleTimeoutMs = this.limits.idleTimeoutMs;
+		if (idleTimeoutMs === undefined || this.stopped) {
+			this.idleTimer = undefined;
+			return;
+		}
+		this.idleTimer = setTimeout(
+			() => this.exceed({ reason: "idle_timeout", limit: idleTimeoutMs }),
+			idleTimeoutMs,
+		);
+		this.idleTimer.unref?.();
+	}
+
+	private exceed(stop: TurnBudgetStop): void {
+		if (this.stopped) return;
+		this.stopped = true;
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = undefined;
+		this.onExceeded(stop);
+	}
+}
+
+function validateOptionalInteger(name: string, value: number | undefined, maximum: number): void {
+	if (value === undefined) return;
+	if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+		throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+	}
+}

package/src/verification-policy.ts

@@ -0,0 +1,67 @@
+import type { DelegationContract } from "./delegation-contract.js";
+
+export interface VerificationRiskInput {
+	contract?: DelegationContract;
+	integrationOwner: boolean;
+	requiredCapabilities: string[];
+}
+
+export interface WorkflowVerificationTaskProjection {
+	id: string;
+	agent: string;
+	dependsOn?: readonly string[];
+	verifierFor?: string;
+	resultFormat?: string;
+}
+
+export function requiresIndependentVerification(input: VerificationRiskInput): boolean {
+	return (
+		input.contract?.admission?.verificationRequired === true ||
+		input.requiredCapabilities.some((capability) =>
+			["security-review", "security-implementation", "security-baseline"].includes(capability),
+		) ||
+		(input.integrationOwner && input.contract?.sideEffectPolicy !== "read-only")
+	);
+}
+
+export function validateWorkflowVerificationGraph(
+	tasks: readonly WorkflowVerificationTaskProjection[],
+	requiredTargetIds: ReadonlySet<string>,
+): void {
+	const byId = new Map(tasks.map((task) => [task.id, task]));
+	const verifierByTarget = new Map<string, WorkflowVerificationTaskProjection[]>();
+	for (const task of tasks) {
+		if (!task.verifierFor) continue;
+		const target = byId.get(task.verifierFor);
+		if (!target) throw new Error(`Workflow verifier ${task.id} targets a missing task`);
+		if (target.verifierFor) {
+			throw new Error(`Workflow verifier ${task.id} cannot verify another verifier`);
+		}
+		if (target.resultFormat !== "structured-v2") {
+			throw new Error(`Workflow verification target ${target.id} must request structured-v2`);
+		}
+		if (task.dependsOn?.length !== 1 || task.dependsOn[0] !== target.id) {
+			throw new Error(`Workflow verifier ${task.id} must depend directly and only on ${target.id}`);
+		}
+		if (task.agent === target.agent) {
+			throw new Error(`Workflow verifier ${task.id} must use a distinct agent`);
+		}
+		if (task.resultFormat !== "structured-v2") {
+			throw new Error(`Workflow verifier ${task.id} must request structured-v2`);
+		}
+		const entries = verifierByTarget.get(target.id) ?? [];
+		entries.push(task);
+		verifierByTarget.set(target.id, entries);
+	}
+	for (const targetId of requiredTargetIds) {
+		const verifiers = verifierByTarget.get(targetId) ?? [];
+		if (verifiers.length !== 1) {
+			throw new Error(`Workflow task ${targetId} requires exactly one independent verifier`);
+		}
+	}
+	for (const [targetId, verifiers] of verifierByTarget) {
+		if (verifiers.length !== 1) {
+			throw new Error(`Workflow task ${targetId} must have exactly one verifier`);
+		}
+	}
+}