@oai404iao/pi-subagent 0.3.0 → 0.4.0

package/src/task-path.ts

@@ -0,0 +1,146 @@
+import type {
+	SubagentDescriptor,
+	SubagentTask,
+} from "./types.ts";
+
+export const ROOT_TASK_PATH = "/root";
+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") {
+		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++) {
+		validateTaskName(segments[index]!);
+	}
+	return path;
+}
+
+export function taskPath(parentPath: string, name: string): string {
+	validateTaskPath(parentPath);
+	validateTaskName(name);
+	const path = `${parentPath}/${name}`;
+	return validateTaskPath(path);
+}
+
+export function descriptorTaskPath(
+	descriptor: SubagentDescriptor,
+): string {
+	return descriptor.task.path;
+}
+
+export function descriptorTask(
+	descriptor: SubagentDescriptor,
+): SubagentTask {
+	return { ...descriptor.task };
+}
+
+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" ? "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;
+		}
+		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

@@ -1,20 +1,36 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 
+/** Current on-disk subagent descriptor version. */
+export const DESCRIPTOR_VERSION = 4;
+
 export type AgentScope = "user" | "project" | "both";
-export type AgentSource = "bundled" | "user" | "project";
-export type ReportDelivery = "wakeup" | "quiet";
+/** Sources that runtime discovery is allowed to activate. */
+export type AgentSource = "user" | "project";
+/**
+ * Single execution mode. `foreground` waits for every child's final answer;
+ * `background` starts durable mailbox children.
+ */
+export type RuntimeMode = "foreground" | "background";
 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;
-	reportDelivery: ReportDelivery;
+	runtimeMode: RuntimeMode;
+	maxConcurrentBackgroundRuns: number;
+	maxIdleRuntimes: number;
 	inheritExtensions: boolean;
 	openAIIdentity: boolean;
 	maxOutputBytes: number;
@@ -48,18 +64,16 @@ export interface ResolvedModel {
 
 export interface SubagentRuntimeSnapshot {
 	agentScope: AgentScope;
-	syncBundledAgents: boolean;
 	maxDepth: number;
-	enableRunInBackground: boolean;
-	defaultBackground: boolean;
-	reportDelivery: ReportDelivery;
+	runtimeMode: RuntimeMode;
+	maxConcurrentBackgroundRuns: number;
+	maxIdleRuntimes: number;
 	inheritExtensions: boolean;
 	openAIIdentity: boolean;
 	maxOutputBytes: number;
 }
 
-export interface SubagentDescriptor {
-	version: 2;
+interface SubagentDescriptorBase {
 	mode: SubagentMode;
 	provider: SubagentProviderName;
 	label: string;
@@ -80,15 +94,24 @@ export interface SubagentDescriptor {
 	runtime: SubagentRuntimeSnapshot;
 }
 
+export interface SubagentDescriptor extends SubagentDescriptorBase {
+	version: typeof DESCRIPTOR_VERSION;
+	task: SubagentTask;
+	context: ContextInheritance;
+}
+
 export interface SubagentUsage extends Usage {
 	turns: number;
 }
 
 export interface SubagentRunResult {
 	agentId: string;
+	turnId: string;
 	piSessionId?: string;
 	sessionFile?: string;
 	output: string;
+	outputTruncated?: boolean;
+	omittedBytes?: number;
 	stopReason: SubagentStopReason;
 	usage: SubagentUsage;
 }
@@ -102,9 +125,12 @@ export interface TraceItem {
 export interface DelegationDetails {
 	kind: "delegation";
 	agentId: string;
+	taskPath: string;
+	turnId?: string;
 	piSessionId?: string;
 	provider: SubagentProviderName;
 	mode: SubagentMode;
+	context: ContextInheritance;
 	agent: string;
 	label: string;
 	depth: number;
@@ -118,18 +144,30 @@ export interface DelegationDetails {
 
 export interface ControlDetails {
 	kind: "control";
-	action: "send" | "interrupt" | "list" | "report";
+	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";
 	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 {
@@ -144,10 +182,10 @@ export interface CatalogDiagnostic {
 export type CatalogEntry = CatalogChild | CatalogDiagnostic;
 
 export interface ParentMessageDetails {
-	kind: "report" | "settled";
+	kind: "report";
 	childAgentId: string;
+	taskPath?: string;
 	label: string;
-	stopReason?: SubagentStopReason;
 	truncated?: boolean;
 }