@narumitw/pi-subagents 2.0.6 → 2.1.0

package/src/timeout-finalization.ts

@@ -1,7 +1,7 @@
 import { redactPrivateText } from "./context.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
 import { appendResultInstruction, type SubagentResultFormat } from "./result-contract.js";
-import type { RecentActivityItem } from "./runner.js";
+import type { RecentActivityItem } from "./runner-types.js";
 import {
 	formatTimeoutCheckpoint,
 	type TimeoutCheckpoint,

package/src/tool-schema-compatibility.ts

@@ -0,0 +1,73 @@
+import { type TObject, type TObjectOptions, type TProperties, type TSchema, Type } from "typebox";
+
+const LLAMA_CPP_MAX_REPETITION_THRESHOLD = 2_000;
+
+/**
+ * Remove large nested string repetitions that llama.cpp cannot compile into GBNF.
+ *
+ * Runtime normalization and validation continue to bound these inputs.
+ * See https://github.com/ggml-org/llama.cpp/issues/25746.
+ */
+export function grammarSafeToolObject<Properties extends TProperties>(
+	properties: Properties,
+	options?: TObjectOptions,
+): TObject<Properties> {
+	return makeGrammarSafeToolSchema(Type.Object(properties, options));
+}
+
+function makeGrammarSafeToolSchema<Schema extends TSchema>(schema: Schema): Schema {
+	return cloneSchema(schema, 0) as Schema;
+}
+
+function cloneSchema(schema: unknown, depth: number): unknown {
+	if (!isRecord(schema)) return schema;
+	const clone = cloneWithDescriptors(schema);
+	if (
+		depth > 1 &&
+		clone.type === "string" &&
+		typeof clone.maxLength === "number" &&
+		clone.maxLength >= LLAMA_CPP_MAX_REPETITION_THRESHOLD
+	) {
+		delete clone.maxLength;
+	}
+	if (isRecord(clone.properties)) {
+		clone.properties = mapSchemas(clone.properties, depth + 1);
+	}
+	if (clone.items !== undefined) {
+		clone.items = Array.isArray(clone.items)
+			? clone.items.map((item) => cloneSchema(item, depth + 1))
+			: cloneSchema(clone.items, depth + 1);
+	}
+	if (Array.isArray(clone.prefixItems)) {
+		clone.prefixItems = clone.prefixItems.map((item) => cloneSchema(item, depth + 1));
+	}
+	for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+		if (Array.isArray(clone[keyword])) {
+			clone[keyword] = clone[keyword].map((item) => cloneSchema(item, depth));
+		}
+	}
+	if (isRecord(clone.patternProperties)) {
+		clone.patternProperties = mapSchemas(clone.patternProperties, depth + 1);
+	}
+	if (isRecord(clone.additionalProperties)) {
+		clone.additionalProperties = cloneSchema(clone.additionalProperties, depth + 1);
+	}
+	return clone;
+}
+
+function mapSchemas(schemas: Record<string, unknown>, depth: number): Record<string, unknown> {
+	return Object.fromEntries(
+		Object.entries(schemas).map(([name, schema]) => [name, cloneSchema(schema, depth)]),
+	);
+}
+
+function cloneWithDescriptors(value: Record<string, unknown>): Record<string, unknown> {
+	return Object.defineProperties(
+		Object.create(Object.getPrototypeOf(value)),
+		Object.getOwnPropertyDescriptors(value),
+	) as Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/transport-types.ts

@@ -50,6 +50,12 @@ export interface TransportTelemetry {
 	model?: string;
 	thinkingLevel?: SubagentThinkingLevel;
 	usage?: TransportUsage;
+	budgetSource?: {
+		timeout: "runtime" | "explicit";
+		idleTimeout: "runtime" | "explicit";
+		turnLimit: "runtime" | "explicit";
+		toolCallLimit: "runtime" | "explicit";
+	};
 	failurePhase?: TransportProgressPhase;
 }
 

package/src/transport-ui.ts

@@ -11,25 +11,26 @@ const TRANSPORT_OPTIONS: Array<{
 }> = [
 	{
 		value: "subprocess",
-		label: "Fresh subprocess",
-		description: "Compatibility path with a fresh isolated Pi process for every turn.",
+		label: "Fresh process",
+		description:
+			"Start a separate Pi process for every turn. Most compatible, but slower for follow-ups.",
 	},
 	{
 		value: "in-process",
-		label: "In process",
+		label: "Inside Pi",
 		description:
-			"Lowest follow-up overhead for built-in tools, with shared memory and crash boundary.",
+			"Run built-in tools inside Pi for faster follow-ups. Shares Pi's memory and crash boundary.",
 	},
 	{
 		value: "rpc",
-		label: "Persistent RPC process",
-		description: "Retain native history in one isolated Pi process per active retained agent.",
+		label: "Persistent process (RPC)",
+		description:
+			"Keep one separate Pi process per background subagent so follow-ups preserve history.",
 	},
 	{
 		value: "auto",
-		label: "Automatic",
-		description:
-			"Read-only built-ins use in-process, write-capable built-ins use RPC, and custom tools use subprocess.",
+		label: "Automatic · Recommended",
+		description: "Let Pi choose a compatible method for each subagent and its tools.",
 	},
 ];
 
@@ -42,12 +43,15 @@ export function transportSettingsScreen(runtime: TransportUiRuntime) {
 	const current = runtime.getRuntimeStatus();
 	return {
 		kind: "actions" as const,
-		title: configured.error ? "Detached Transport · Read only" : "Detached Transport",
+		title: configured.error
+			? "Background Agent Transport · Read only"
+			: "Background Agent Transport",
 		lines: [
+			"Advanced: choose how Pi hosts background subagents.",
 			`Current session: ${transportLabel(current.transport)}`,
 			`Configured after reload: ${transportLabel(configured.value)} (${configured.source})`,
-			"Transport isolation is not a filesystem or network sandbox.",
-			"RPC v1 disables child extensions and supports built-in Pi tools only.",
+			"Separate processes do not restrict filesystem or network access.",
+			"Persistent process (RPC) supports built-in Pi tools and does not load child extensions.",
 			...(configured.error
 				? [
 						`Settings cannot be edited: ${safeTerminalText(configured.error)}`,
@@ -84,7 +88,7 @@ export async function applyTransportSetting(
 	const status = runtime.getRuntimeStatus();
 	if (status.retainedAgents > 0) {
 		ctx.ui.notify(
-			`Cannot change transport while ${status.retainedAgents} detached agent${status.retainedAgents === 1 ? " is" : "s are"} retained. Clear Current agents first.`,
+			`Cannot change transport while ${status.retainedAgents} subagent${status.retainedAgents === 1 ? " is" : "s are"} saved for follow-up. Clear Current subagents first.`,
 			"warning",
 		);
 		return { kind: "rejected" as const };
@@ -104,7 +108,7 @@ export async function applyTransportSetting(
 	}
 	if (runtime.getRuntimeStatus().retainedAgents > 0) {
 		ctx.ui.notify(
-			"Detached agents appeared while confirming; clear them before changing transport.",
+			"New subagents were saved for follow-up while confirming. Clear them before changing transport.",
 			"warning",
 		);
 		return { kind: "rejected" as const };
@@ -122,38 +126,6 @@ export async function applyTransportSetting(
 	}
 }
 
-export function responsivenessSetupScreen(runtime: TransportUiRuntime) {
-	const current = runtime.getRuntimeStatus();
-	const configured = inspectStatefulTransportSettings();
-	return {
-		kind: "actions" as const,
-		title: "Responsiveness Setup",
-		lines: [
-			`Current transport: ${transportLabel(current.transport)}`,
-			`Configured transport: ${transportLabel(configured.value)}`,
-			"Transport, completion delivery, and thinking defaults are separate explicit choices.",
-			"Use Automatic to reduce retained follow-up startup while keeping custom-tool compatibility.",
-		],
-		items: [
-			{
-				id: "auto",
-				label: "Preview Automatic transport",
-				description: "Choose a deterministic transport before each retained agent starts",
-				action: "set-transport" as const,
-			},
-			{ id: "transport", label: "Compare all transports", to: "transport" as const },
-			{
-				id: "completion",
-				label: "Completion delivery",
-				description: "Choose separately whether an idle root resumes for synthesis",
-				to: "settings" as const,
-			},
-			{ id: "back", label: "Back", action: "back" as const },
-		],
-		hint: "back" as const,
-	};
-}
-
 export function transportLabel(value: SubagentTransportKind): string {
 	return TRANSPORT_OPTIONS.find((option) => option.value === value)?.label ?? value;
 }

package/src/usage-recording-config.ts

@@ -0,0 +1,13 @@
+export const USAGE_RECORDING_DIRECTORY = "pi-subagents-usage";
+export const USAGE_RECORDING_RETENTION_DAYS = 30;
+export const USAGE_RECORDING_STUDY_ID = "pi-subagents-surface-v1";
+
+export interface SubagentUsageRecordingSettings {
+	enabled?: boolean;
+}
+
+export function resolveUsageRecordingEnabled(
+	settings: SubagentUsageRecordingSettings | undefined,
+): boolean {
+	return settings?.enabled === true;
+}

package/src/usage-recording-store.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const WRITER_PATTERN =
+	/^runtime-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.jsonl$/u;
+const MAX_EVENT_BYTES = 8 * 1024;
+const WRITE_TIMEOUT_MS = 2_000;
+
+export interface UsageEventStorePort {
+	readonly path: string;
+	append(event: unknown): Promise<void>;
+	prune(retentionDays: number): Promise<void>;
+	close(): Promise<void>;
+}
+
+export class UsageEventStore implements UsageEventStorePort {
+	readonly path: string;
+	private readonly writerPath: string;
+	private mutationTail: Promise<void> = Promise.resolve();
+	private readonly lifecycle = new AbortController();
+	private closed = false;
+
+	constructor(rootPath: string, options: { createId?: () => string; now?: () => number } = {}) {
+		this.path = rootPath;
+		this.createId = options.createId ?? randomUUID;
+		this.now = options.now ?? Date.now;
+		this.writerPath = path.join(rootPath, `runtime-${validId(this.createId())}.jsonl`);
+	}
+
+	private readonly createId: () => string;
+	private readonly now: () => number;
+
+	append(event: unknown): Promise<void> {
+		if (this.closed) return Promise.reject(new Error("Usage recording storage is closed."));
+		const frame = encodeEvent(event);
+		return this.enqueue(() =>
+			withTimeout(
+				(signal) => this.appendFrame(frame, signal),
+				this.lifecycle.signal,
+				WRITE_TIMEOUT_MS,
+				"Usage recording write timed out",
+			),
+		);
+	}
+
+	prune(retentionDays: number): Promise<void> {
+		if (this.closed) return Promise.reject(new Error("Usage recording storage is closed."));
+		return this.enqueue(() =>
+			withTimeout(
+				async (signal) => {
+					await ensurePrivateDirectory(this.path);
+					signal.throwIfAborted();
+					const cutoff = this.now() - retentionDays * 24 * 60 * 60 * 1000;
+					for (const entry of await readdir(this.path, { withFileTypes: true })) {
+						signal.throwIfAborted();
+						if (!entry.isFile() || !WRITER_PATTERN.test(entry.name)) continue;
+						const candidate = path.join(this.path, entry.name);
+						if (candidate === this.writerPath) continue;
+						let metadata: Awaited<ReturnType<typeof lstat>>;
+						try {
+							metadata = await lstat(candidate);
+						} catch (error) {
+							if (isNodeError(error) && error.code === "ENOENT") continue;
+							throw error;
+						}
+						if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.mtimeMs >= cutoff) {
+							continue;
+						}
+						await rm(candidate, { force: true });
+					}
+				},
+				this.lifecycle.signal,
+				WRITE_TIMEOUT_MS,
+				"Usage recording retention cleanup timed out",
+			),
+		);
+	}
+
+	async close(): Promise<void> {
+		if (this.closed) return;
+		this.closed = true;
+		this.lifecycle.abort(new DOMException("Usage recording storage closed", "AbortError"));
+		await this.mutationTail;
+	}
+
+	private enqueue(operation: () => Promise<void>): Promise<void> {
+		const result = this.mutationTail.then(operation);
+		this.mutationTail = result.catch(() => undefined);
+		return result;
+	}
+
+	private async appendFrame(frame: string, signal: AbortSignal): Promise<void> {
+		await ensurePrivateDirectory(this.path);
+		signal.throwIfAborted();
+		await assertOptionalPrivateRegularFile(this.writerPath);
+		signal.throwIfAborted();
+		await writeFile(this.writerPath, frame, {
+			encoding: "utf8",
+			flag: "a",
+			mode: 0o600,
+			signal,
+		});
+		if (process.platform !== "win32") await chmod(this.writerPath, 0o600);
+	}
+}
+
+export function encodeEvent(event: unknown): string {
+	const frame = `${JSON.stringify(event)}\n`;
+	if (Buffer.byteLength(frame) > MAX_EVENT_BYTES) {
+		throw new Error("Usage recording event exceeds the storage bound.");
+	}
+	return frame;
+}
+
+async function ensurePrivateDirectory(directoryPath: string): Promise<void> {
+	try {
+		const metadata = await lstat(directoryPath);
+		if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+			throw new Error("Usage recording storage must be a regular directory, not a link.");
+		}
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		await mkdir(directoryPath, { recursive: true, mode: 0o700 });
+		const metadata = await lstat(directoryPath);
+		if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+			throw new Error("Usage recording storage must be a regular directory, not a link.");
+		}
+	}
+	if (process.platform !== "win32") await chmod(directoryPath, 0o700);
+}
+
+async function assertOptionalPrivateRegularFile(filePath: string): Promise<void> {
+	try {
+		const metadata = await lstat(filePath);
+		if (!metadata.isFile() || metadata.isSymbolicLink()) {
+			throw new Error("Usage recording writers must be regular files, not links.");
+		}
+		if (process.platform !== "win32") await chmod(filePath, 0o600);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return;
+		throw error;
+	}
+}
+
+async function withTimeout<T>(
+	operation: (signal: AbortSignal) => Promise<T>,
+	lifecycleSignal: AbortSignal,
+	timeoutMs: number,
+	message: string,
+): Promise<T> {
+	lifecycleSignal.throwIfAborted();
+	const controller = new AbortController();
+	const abortLifecycle = () =>
+		controller.abort(
+			lifecycleSignal.reason ?? new DOMException("Usage recording storage closed", "AbortError"),
+		);
+	lifecycleSignal.addEventListener("abort", abortLifecycle, { once: true });
+	const timer = setTimeout(
+		() => controller.abort(new DOMException(message, "TimeoutError")),
+		timeoutMs,
+	);
+	try {
+		return await operation(controller.signal);
+	} catch (error) {
+		if (controller.signal.aborted) throw controller.signal.reason;
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		lifecycleSignal.removeEventListener("abort", abortLifecycle);
+	}
+}
+
+function validId(value: string): string {
+	if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value)) {
+		throw new Error("Usage recording storage received an invalid writer identity.");
+	}
+	return value;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}