@oai404iao/pi-subagent 0.2.0 → 0.4.0-alpha.0

package/src/schemas.ts

@@ -17,6 +17,15 @@ function agentNameParameter(agentNames?: readonly string[]) {
 function delegationFields(agentNames?: readonly string[]) {
 	return {
 		agent: agentNameParameter(agentNames),
+		task_name: Type.Optional(
+			Type.String({
+				description:
+					"Stable readable child path segment; lowercase letters, digits, hyphens, and underscores",
+				pattern: "^[a-z0-9][a-z0-9_-]{0,63}$",
+				minLength: 1,
+				maxLength: 64,
+			}),
+		),
 		description: Type.String({
 			description: "Short 3-5 word display label for the delegated task",
 			minLength: 1,
@@ -29,6 +38,27 @@ function delegationFields(agentNames?: readonly string[]) {
 	};
 }
 
+const ContextParameters = Type.Object(
+	{
+		mode: StringEnum(
+			["fresh", "all_completed", "last_n_completed"] as const,
+			{
+				description:
+					"Parent context inherited once when the child is created",
+			},
+		),
+		completed_turns: Type.Optional(
+			Type.Integer({
+				description:
+					"Number of completed parent turns for last_n_completed",
+				minimum: 1,
+				maximum: 100,
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 function forkDelegationFields(agentNames?: readonly string[]) {
 	return {
 		...delegationFields(agentNames),
@@ -45,10 +75,14 @@ function createDelegationParameters(
 	agentNames?: readonly string[],
 ) {
 	const fields = delegationFields(agentNames);
+	const contextualFields = {
+		...fields,
+		context: Type.Optional(ContextParameters),
+	};
 	return Type.Object(
 		enableRunInBackground
 			? {
-					...fields,
+					...contextualFields,
 					run_in_background: Type.Optional(
 						Type.Boolean({
 							description:
@@ -56,7 +90,7 @@ function createDelegationParameters(
 						}),
 					),
 				}
-			: fields,
+			: contextualFields,
 		{ additionalProperties: false },
 	);
 }
@@ -75,19 +109,56 @@ export function delegationParameters(
 	return createDelegationParameters(enableRunInBackground, agentNames);
 }
 
-export const ForkDelegationParameters = Type.Object(
-	forkDelegationFields(),
-	{ additionalProperties: false },
-);
+function createForkDelegationParameters(
+	enableRunInBackground: boolean,
+	agentNames?: readonly string[],
+) {
+	const fields = forkDelegationFields(agentNames);
+	return Type.Object(
+		enableRunInBackground
+			? {
+					...fields,
+					run_in_background: Type.Optional(
+						Type.Boolean({
+							description:
+								"Run as a continuable inherited-context background child. Fork remains foreground by default.",
+						}),
+					),
+				}
+			: fields,
+		{ additionalProperties: false },
+	);
+}
+
+export const ForegroundForkDelegationParameters =
+	createForkDelegationParameters(false);
+
+export const ForkDelegationParameters =
+	createForkDelegationParameters(true);
 
-export function forkDelegationParameters(agentNames?: readonly string[]) {
-	if (agentNames === undefined) return ForkDelegationParameters;
-	return Type.Object(forkDelegationFields(agentNames), { additionalProperties: false });
+export function forkDelegationParameters(
+	agentNames?: readonly string[],
+	enableRunInBackground = true,
+) {
+	if (agentNames === undefined) {
+		return enableRunInBackground
+			? ForkDelegationParameters
+			: ForegroundForkDelegationParameters;
+	}
+	return createForkDelegationParameters(
+		enableRunInBackground,
+		agentNames,
+	);
 }
 
 export const SendMessageParameters = Type.Object(
 	{
-		subagent_id: Type.String({ description: "Durable id of a direct continuable child", minLength: 1 }),
+		subagent_id: Type.String({
+			description:
+				"Readable absolute/relative task path or durable id of a direct continuable child",
+			minLength: 1,
+			maxLength: 4096,
+		}),
 		message: Type.String({
 			description: "Message to enqueue as the child's next FIFO turn",
 			minLength: 1,
@@ -96,11 +167,43 @@ export const SendMessageParameters = Type.Object(
 	{ additionalProperties: false },
 );
 
+export const FollowupTaskParameters = Type.Object(
+	{
+		subagent_id: Type.String({
+			description:
+				"Readable absolute/relative task path or durable id of a direct mailbox-v2 continuable child",
+			minLength: 1,
+			maxLength: 4096,
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+export const DEFAULT_WAIT_AGENT_TIMEOUT_MS = 30_000;
+export const MAX_WAIT_AGENT_TIMEOUT_MS = 120_000;
+
+export const WaitAgentParameters = Type.Object(
+	{
+		timeout_ms: Type.Optional(
+			Type.Integer({
+				description:
+					"Maximum event-driven wait in milliseconds before returning a timeout",
+				minimum: 0,
+				maximum: MAX_WAIT_AGENT_TIMEOUT_MS,
+				default: DEFAULT_WAIT_AGENT_TIMEOUT_MS,
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 export const InterruptParameters = Type.Object(
 	{
 		agent_id: Type.String({
-			description: "Id of a live child or deeper descendant whose current turn should stop",
+			description:
+				"Readable absolute/relative task path or durable id of a live descendant whose current turn should stop",
 			minLength: 1,
+			maxLength: 4096,
 		}),
 	},
 	{ additionalProperties: false },

package/src/task-path.ts

@@ -0,0 +1,188 @@
+import type {
+	SubagentDescriptor,
+	SubagentTask,
+} from "./types.ts";
+
+export const ROOT_TASK_PATH = "/root";
+export const LEGACY_TASK_NAMESPACE = ".legacy";
+export const MAX_TASK_NAME_LENGTH = 64;
+export const MAX_TASK_PATH_LENGTH = 4096;
+
+const TASK_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const AGENT_ID_PATTERN =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function pathSegments(path: string): string[] {
+	if (path.length > MAX_TASK_PATH_LENGTH) {
+		throw new Error(
+			`task path exceeds ${MAX_TASK_PATH_LENGTH} characters`,
+		);
+	}
+	if (!path.startsWith("/") || path.endsWith("/") || path.includes("//")) {
+		throw new Error(`task path must be a canonical absolute path under ${ROOT_TASK_PATH}`);
+	}
+	const segments = path.slice(1).split("/");
+	if (segments[0] !== "root") {
+		throw new Error(`task path must be rooted at ${ROOT_TASK_PATH}`);
+	}
+	return segments;
+}
+
+export function validateTaskName(value: string): string {
+	if (!TASK_NAME_PATTERN.test(value)) {
+		throw new Error(
+			"task_name must contain 1-64 lowercase ASCII letters, digits, hyphens, or underscores and start with a letter or digit",
+		);
+	}
+	if (value === "root" || value === LEGACY_TASK_NAMESPACE) {
+		throw new Error(`task_name "${value}" is reserved`);
+	}
+	return value;
+}
+
+export function validateTaskPath(path: string): string {
+	if (path === ROOT_TASK_PATH) return path;
+	const segments = pathSegments(path);
+	for (let index = 1; index < segments.length; index++) {
+		const segment = segments[index]!;
+		if (
+			index === 1
+			&& segment === LEGACY_TASK_NAMESPACE
+		) {
+			const legacyId = segments[index + 1];
+			if (!legacyId || !AGENT_ID_PATTERN.test(legacyId)) {
+				throw new Error(
+					`legacy task paths must use ${ROOT_TASK_PATH}/${LEGACY_TASK_NAMESPACE}/<agent-id>`,
+				);
+			}
+			index++;
+			continue;
+		}
+		validateTaskName(segment);
+	}
+	return path;
+}
+
+export function taskPath(parentPath: string, name: string): string {
+	validateTaskPath(parentPath);
+	validateTaskName(name);
+	const path = `${parentPath}/${name}`;
+	return validateTaskPath(path);
+}
+
+export function legacyTaskPath(agentId: string): string {
+	if (!AGENT_ID_PATTERN.test(agentId)) {
+		throw new Error("legacy task path requires a UUIDv7 agent id");
+	}
+	return `${ROOT_TASK_PATH}/${LEGACY_TASK_NAMESPACE}/${agentId}`;
+}
+
+export function descriptorTaskPath(
+	descriptor: SubagentDescriptor,
+): string {
+	return descriptor.version === 3
+		? descriptor.task.path
+		: legacyTaskPath(descriptor.agentId);
+}
+
+export function descriptorTask(
+	descriptor: SubagentDescriptor,
+): SubagentTask {
+	if (descriptor.version === 3) return { ...descriptor.task };
+	return {
+		name: descriptor.agentId,
+		path: legacyTaskPath(descriptor.agentId),
+	};
+}
+
+export function validateDescriptorTask(task: SubagentTask): SubagentTask {
+	const name = validateTaskName(task.name);
+	const path = validateTaskPath(task.path);
+	if (path === ROOT_TASK_PATH || path.split("/").at(-1) !== name) {
+		throw new Error("task.path must end with task.name");
+	}
+	return { name, path };
+}
+
+export function slugTaskName(value: string): string {
+	const normalized = value
+		.normalize("NFKD")
+		.replace(/\p{Mark}/gu, "")
+		.toLowerCase()
+		.replace(/[^a-z0-9_-]+/g, "-")
+		.replace(/[-_]{2,}/g, "-")
+		.replace(/^[-_]+|[-_]+$/g, "")
+		.slice(0, MAX_TASK_NAME_LENGTH)
+		.replace(/[-_]+$/g, "");
+	const candidate =
+		!normalized || normalized === "root" || normalized === LEGACY_TASK_NAMESPACE
+			? "task"
+			: normalized;
+	return validateTaskName(candidate);
+}
+
+export function numberedTaskName(base: string, ordinal: number): string {
+	validateTaskName(base);
+	if (!Number.isSafeInteger(ordinal) || ordinal < 2) {
+		throw new Error("task name ordinal must be an integer of at least 2");
+	}
+	const suffix = `-${ordinal}`;
+	const prefix = base
+		.slice(0, MAX_TASK_NAME_LENGTH - suffix.length)
+		.replace(/[-_]+$/g, "");
+	return validateTaskName(`${prefix || "task"}${suffix}`);
+}
+
+export function resolveTaskPath(
+	basePath: string,
+	reference: string,
+): string {
+	validateTaskPath(basePath);
+	if (!reference.trim() || reference !== reference.trim()) {
+		throw new Error("task path reference must be a non-empty trimmed string");
+	}
+	if (reference.length > MAX_TASK_PATH_LENGTH) {
+		throw new Error(
+			`task path reference exceeds ${MAX_TASK_PATH_LENGTH} characters`,
+		);
+	}
+	if (reference.includes("//") || (reference.length > 1 && reference.endsWith("/"))) {
+		throw new Error("task path reference contains an empty segment");
+	}
+
+	const absolute = reference.startsWith("/");
+	const segments = absolute ? ["root"] : pathSegments(basePath);
+	const input = absolute ? reference.slice(1).split("/") : reference.split("/");
+	if (absolute && input.shift() !== "root") {
+		throw new Error(`absolute task paths must be rooted at ${ROOT_TASK_PATH}`);
+	}
+	for (const segment of input) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") {
+			if (segments.length === 1) {
+				throw new Error(`task path reference cannot escape ${ROOT_TASK_PATH}`);
+			}
+			segments.pop();
+			continue;
+		}
+		if (segment === LEGACY_TASK_NAMESPACE) {
+			segments.push(segment);
+			continue;
+		}
+		if (
+			segments.at(-1) === LEGACY_TASK_NAMESPACE
+			&& AGENT_ID_PATTERN.test(segment)
+		) {
+			segments.push(segment);
+			continue;
+		}
+		validateTaskName(segment);
+		segments.push(segment);
+	}
+	const resolved = `/${segments.join("/")}`;
+	return validateTaskPath(resolved);
+}
+
+export function isAgentId(value: string): boolean {
+	return AGENT_ID_PATTERN.test(value);
+}

package/src/types.ts

@@ -2,20 +2,36 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 
 export type AgentScope = "user" | "project" | "both";
-export type AgentSource = "bundled" | "user" | "project";
+/** Sources that runtime discovery is allowed to activate. */
+export type AgentSource = "user" | "project";
+/** `bundled` is retained only for reading descriptors written by older releases. */
+export type AgentSnapshotSource = AgentSource | "bundled";
 export type ReportDelivery = "wakeup" | "quiet";
+export type BackgroundProtocol = "legacy" | "mailbox-v2";
 export type SubagentMode = "one-shot" | "continuable";
 export type SubagentProviderName = "spawn" | "fork";
 export type SubagentStopReason = "completed" | "aborted" | "error" | "max-tokens";
+export type ContextInheritance =
+	| { mode: "fresh" }
+	| { mode: "all_completed" }
+	| { mode: "last_n_completed"; completedTurns: number };
+
+export interface SubagentTask {
+	name: string;
+	path: string;
+}
 
 export interface SubagentSettings {
 	agentScope: AgentScope;
-	syncBundledAgents: boolean;
 	maxDepth: number;
 	enableRunInBackground: boolean;
 	defaultBackground: boolean;
+	maxConcurrentBackgroundRuns: number;
+	maxIdleRuntimes: number;
+	backgroundProtocol?: BackgroundProtocol;
 	reportDelivery: ReportDelivery;
 	inheritExtensions: boolean;
+	openAIIdentity: boolean;
 	maxOutputBytes: number;
 }
 
@@ -37,7 +53,7 @@ export interface AgentSnapshot {
 	model?: string;
 	thinking?: ThinkingLevel;
 	systemPrompt: string;
-	source: AgentSource;
+	source: AgentSnapshotSource;
 }
 
 export interface ResolvedModel {
@@ -47,21 +63,29 @@ export interface ResolvedModel {
 
 export interface SubagentRuntimeSnapshot {
 	agentScope: AgentScope;
-	syncBundledAgents: boolean;
 	maxDepth: number;
 	enableRunInBackground: boolean;
 	defaultBackground: boolean;
+	maxConcurrentBackgroundRuns: number;
+	maxIdleRuntimes: number;
+	backgroundProtocol: BackgroundProtocol;
 	reportDelivery: ReportDelivery;
 	inheritExtensions: boolean;
+	openAIIdentity: boolean;
 	maxOutputBytes: number;
 }
 
-export interface SubagentDescriptor {
-	version: 1;
+interface SubagentDescriptorBase {
 	mode: SubagentMode;
 	provider: SubagentProviderName;
 	label: string;
-	parentSessionId: string;
+	/** Durable pi-subagent control identity, independent of provider wire ids. */
+	agentId: string;
+	/** Durable control identity of the delegating pi-subagent. */
+	parentAgentId: string;
+	/** Pi session lookup key of the delegating agent; never used as a wire id. */
+	parentPiSessionId: string;
+	/** Path of the parent's session file at delegation time (attribute, not identity). */
 	parentSessionFile?: string;
 	depth: number;
 	cwd: string;
@@ -72,14 +96,32 @@ export interface SubagentDescriptor {
 	runtime: SubagentRuntimeSnapshot;
 }
 
+export interface SubagentDescriptorV2 extends SubagentDescriptorBase {
+	version: 2;
+}
+
+export interface SubagentDescriptorV3 extends SubagentDescriptorBase {
+	version: 3;
+	task: SubagentTask;
+	context: ContextInheritance;
+}
+
+export type SubagentDescriptor =
+	| SubagentDescriptorV2
+	| SubagentDescriptorV3;
+
 export interface SubagentUsage extends Usage {
 	turns: number;
 }
 
 export interface SubagentRunResult {
-	id: string;
+	agentId: string;
+	turnId: string;
+	piSessionId?: string;
 	sessionFile?: string;
 	output: string;
+	outputTruncated?: boolean;
+	omittedBytes?: number;
 	stopReason: SubagentStopReason;
 	usage: SubagentUsage;
 }
@@ -92,9 +134,13 @@ export interface TraceItem {
 
 export interface DelegationDetails {
 	kind: "delegation";
-	id: string;
+	agentId: string;
+	taskPath: string;
+	turnId?: string;
+	piSessionId?: string;
 	provider: SubagentProviderName;
 	mode: SubagentMode;
+	context: ContextInheritance;
 	agent: string;
 	label: string;
 	depth: number;
@@ -108,23 +154,35 @@ export interface DelegationDetails {
 
 export interface ControlDetails {
 	kind: "control";
-	action: "send" | "interrupt" | "list" | "report";
-	id?: string;
+	action: "send" | "followup" | "wait" | "interrupt" | "list" | "report";
+	agentId?: string;
+	taskPath?: string;
+	messageId?: string;
+	turnId?: string;
+	pendingMessages?: number;
+	claimedMessages?: number;
+	completionIds?: string[];
+	timedOut?: boolean;
+	unreadUpdates?: number;
 }
 
 export interface CatalogChild {
 	kind: "child";
-	id: string;
-	parentId: string;
+	agentId: string;
+	parentAgentId: string;
+	taskPath: string;
+	parentTaskPath: string;
 	depth: number;
 	descriptor: SubagentDescriptor;
 	sessionFile?: string;
 	status: "running" | "idle" | "ready";
+	pendingMessages: number;
+	unreadUpdates: number;
 }
 
 export interface CatalogDiagnostic {
 	kind: "diagnostic";
-	id: string;
+	piSessionId: string;
 	reason: "corrupt" | "unavailable";
 	sessionFile?: string;
 	parentSessionFile?: string;
@@ -135,7 +193,8 @@ export type CatalogEntry = CatalogChild | CatalogDiagnostic;
 
 export interface ParentMessageDetails {
 	kind: "report" | "settled";
-	childId: string;
+	childAgentId: string;
+	taskPath?: string;
 	label: string;
 	stopReason?: SubagentStopReason;
 	truncated?: boolean;