pi-subagents 0.34.0 → 0.35.0

package/src/agents/frontmatter.ts

@@ -5,6 +5,57 @@ function escapeRegex(s: string): string {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Fold a YAML folded block scalar while preserving more-indented lines and
+ * every blank-line separator. Trailing whitespace is trimmed.
+ */
+function foldBlock(block: string): string {
+	let folded = "";
+	let hasContent = false;
+	let previousIsMoreIndented = false;
+	let blankLines = 0;
+
+	for (const line of block.split("\n")) {
+		const current = line.trimEnd();
+		if (current.trim() === "") {
+			if (hasContent) blankLines++;
+			continue;
+		}
+
+		const currentIsMoreIndented = current.length > current.trimStart().length;
+		if (hasContent) {
+			if (blankLines > 0) {
+				folded += "\n".repeat(blankLines + (previousIsMoreIndented || currentIsMoreIndented ? 1 : 0));
+			} else {
+				folded += previousIsMoreIndented || currentIsMoreIndented ? "\n" : " ";
+			}
+		}
+		folded += current;
+		hasContent = true;
+		previousIsMoreIndented = currentIsMoreIndented;
+		blankLines = 0;
+	}
+
+	return folded.trim();
+}
+
+/**
+ * Normalize a simple-scalar frontmatter list from comma-separated or block-list syntax.
+ * Only the standard `- item` marker is removed; ordinary hyphenated values stay intact.
+ */
+export function parseFrontmatterList(raw: string | undefined): string[] | undefined {
+	if (raw === undefined) return undefined;
+	return raw
+		.split("\n")
+		.flatMap((line) => {
+			const value = line.trim();
+			const listItem = value.match(/^-\s+(.+)$/);
+			return (listItem?.[1] ?? value).split(",");
+		})
+		.map((value) => value.trim())
+		.filter(Boolean);
+}
+
 /**
  * Parse YAML frontmatter from agent/chain files.
  * Handles both flat (key: value) and nested block (key: \n  sub: val) values.
@@ -31,12 +82,13 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 	let currentKey: string | null = null;
 	let currentBlockLines: string[] | null = null;
 	let currentIndent: number | null = null;
+	let currentFolded = false;
 
 	for (const line of lines) {
 		const indent = line.search(/\S|$/); // position of first non-whitespace char
 		const trimmed = line.trim();
 
-		if (currentKey !== null && currentBlockLines !== null && indent > (currentIndent ?? 0)) {
+		if (currentKey !== null && currentBlockLines !== null && (indent > (currentIndent ?? 0) || (currentFolded && trimmed === ""))) {
 			// This line is part of the current block value
 			currentBlockLines.push(line);
 			continue;
@@ -47,29 +99,31 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 			// Strip the common leading whitespace from the block so the
 			// serializer can add its own indentation level.
 			const rawBlock = currentBlockLines.join("\n");
-			const leadingSpaces = rawBlock.match(/^([ \t]+)/m);
-			const prefix = leadingSpaces?.[1] ?? "";
+			const leadingSpaces = rawBlock.match(/^[ \t]+(?=\S)/m);
+			const prefix = leadingSpaces?.[0] ?? "";
 			const stripped = prefix
 				? rawBlock.replace(new RegExp(`^${escapeRegex(prefix)}`, "gm"), "").replace(/^\n/, "")
 				: rawBlock;
-			frontmatter[currentKey] = stripped;
+			frontmatter[currentKey] = currentFolded ? foldBlock(stripped) : stripped;
 			currentKey = null;
 			currentBlockLines = null;
 			currentIndent = null;
+			currentFolded = false;
 		}
 
 		const match = line.match(/^([\w-]+):\s*(.*)$/);
 		if (match) {
-			let value = match[2].trim();
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
+			const rawValue = match[2].trim();
+			const isQuoted = (rawValue.startsWith('"') && rawValue.endsWith('"')) || (rawValue.startsWith("'") && rawValue.endsWith("'"));
+			const value = isQuoted ? rawValue.slice(1, -1) : rawValue;
+			const isFolded = !isQuoted && (rawValue === ">" || rawValue === ">-");
 
-			if (value === "") {
-				// Key with empty value — might start a block; defer storing until we see indent
+			if (value === "" || isFolded) {
+				// Key with empty value or folded block indicator — defer storing until we see indent
 				currentKey = match[1];
 				currentBlockLines = [];
 				currentIndent = indent;
+				currentFolded = isFolded;
 			} else {
 				// Simple key: value
 				frontmatter[match[1]] = value;
@@ -81,12 +135,12 @@ export function parseFrontmatter(content: string): { frontmatter: Record<string,
 	// Flush final block value
 	if (currentKey !== null && currentBlockLines !== null) {
 		const rawBlock = currentBlockLines.join("\n");
-		const leadingSpaces = rawBlock.match(/^([ \t]+)/m);
-		const prefix = leadingSpaces?.[1] ?? "";
+		const leadingSpaces = rawBlock.match(/^[ \t]+(?=\S)/m);
+		const prefix = leadingSpaces?.[0] ?? "";
 		const stripped = prefix
 			? rawBlock.replace(new RegExp(`^${escapeRegex(prefix)}`, "gm"), "").replace(/^\n/, "")
 			: rawBlock;
-		frontmatter[currentKey] = stripped;
+		frontmatter[currentKey] = currentFolded ? foldBlock(stripped) : stripped;
 	}
 
 	return { frontmatter, body };

package/src/agents/skills.ts

@@ -122,6 +122,8 @@ function extractSkillPathsFromPackageRoot(packageRoot: string, source: SkillSour
 let cachedGlobalNpmRoot: string | null = null;
 
 function getGlobalNpmRoot(): string | null {
+	const offline = process.env.PI_OFFLINE?.toLowerCase();
+	if (offline === "1" || offline === "true" || offline === "yes") return null;
 	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
 	try {
 		cachedGlobalNpmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
@@ -608,9 +610,22 @@ function readSkill(
 export function resolveSkills(
 	skillNames: string[],
 	cwd: string,
+	localSkillPaths?: string[],
+	localBaseDir?: string,
 ): { resolved: ResolvedSkill[]; missing: string[] } {
 	const resolved: ResolvedSkill[] = [];
 	const missing: string[] = [];
+	const localByName = new Map<string, CachedSkillEntry>();
+	if (localSkillPaths?.length) {
+		const agentDir = getAgentDir();
+		const localEntries = collectFilesystemSkills(cwd, agentDir, localSkillPaths.map((entry) => ({
+			path: path.resolve(localBaseDir ?? cwd, entry),
+			source: "unknown" as const,
+		})));
+		for (const entry of localEntries) {
+			if (!localByName.has(entry.name)) localByName.set(entry.name, entry);
+		}
+	}
 
 	for (const name of skillNames) {
 		const trimmed = name.trim();
@@ -620,18 +635,14 @@ export function resolveSkills(
 			continue;
 		}
 
-		const location = resolveSkillPath(trimmed, cwd);
-		if (!location) {
-			missing.push(trimmed);
-			continue;
-		}
-
-		const skill = readSkill(trimmed, location.path, location.source);
-		if (skill) {
-			resolved.push(skill);
-		} else {
-			missing.push(trimmed);
+		const local = localByName.get(trimmed);
+		let skill = local ? readSkill(trimmed, local.filePath, local.source) : undefined;
+		if (!skill) {
+			const location = resolveSkillPath(trimmed, cwd);
+			if (location) skill = readSkill(trimmed, location.path, location.source);
 		}
+		if (skill) resolved.push(skill);
+		else missing.push(trimmed);
 	}
 
 	return { resolved, missing };
@@ -641,8 +652,10 @@ export function resolveSkillsWithFallback(
 	skillNames: string[],
 	primaryCwd: string,
 	fallbackCwd?: string,
+	localSkillPaths?: string[],
+	localBaseDir?: string,
 ): { resolved: ResolvedSkill[]; missing: string[] } {
-	const primary = resolveSkills(skillNames, primaryCwd);
+	const primary = resolveSkills(skillNames, primaryCwd, localSkillPaths, localBaseDir);
 	if (!fallbackCwd || primary.missing.length === 0) return primary;
 	if (path.resolve(primaryCwd) === path.resolve(fallbackCwd)) return primary;
 

package/src/api/background-work.ts

@@ -0,0 +1,197 @@
+export const BACKGROUND_WORK_PROTOCOL_VERSION = 1;
+export const BACKGROUND_WORK_REGISTRY_KEY = "pi-subagents.background-work.v1";
+
+const MAX_PROVIDER_NAME_LENGTH = 128;
+const MAX_PROVIDERS = 100;
+const MAX_ITEM_ID_LENGTH = 256;
+const MAX_SESSION_ID_LENGTH = 256;
+const MAX_WAKE_CHANNEL_LENGTH = 256;
+const MAX_ITEMS_PER_PROVIDER = 10_000;
+
+export interface BackgroundWorkItem {
+	id: string;
+	sessionId: string;
+}
+
+export interface BackgroundWorkReconcileContext {
+	sessionId: string;
+	nowMs: number;
+}
+
+export interface BackgroundWorkProvider {
+	name: string;
+	listActiveWork(): readonly BackgroundWorkItem[];
+	wakeChannels?: readonly string[];
+	reconcile?(context: BackgroundWorkReconcileContext): void;
+}
+
+export interface RegisteredBackgroundWorkItem extends BackgroundWorkItem {
+	provider: string;
+}
+
+export interface BackgroundWorkSnapshot {
+	providers: readonly string[];
+	items: readonly RegisteredBackgroundWorkItem[];
+}
+
+interface BackgroundWorkRegistry {
+	version: typeof BACKGROUND_WORK_PROTOCOL_VERSION;
+	providers: Map<string, BackgroundWorkProvider>;
+}
+
+function registry(): BackgroundWorkRegistry {
+	const key = Symbol.for(BACKGROUND_WORK_REGISTRY_KEY);
+	const globalObject = globalThis as Record<PropertyKey, unknown>;
+	const existing = globalObject[key];
+	if (existing === undefined) {
+		const created: BackgroundWorkRegistry = {
+			version: BACKGROUND_WORK_PROTOCOL_VERSION,
+			providers: new Map(),
+		};
+		globalObject[key] = created;
+		return created;
+	}
+	if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+		throw new Error(`Malformed background-work registry at Symbol.for("${BACKGROUND_WORK_REGISTRY_KEY}").`);
+	}
+	const candidate = existing as Partial<BackgroundWorkRegistry>;
+	if (candidate.version !== BACKGROUND_WORK_PROTOCOL_VERSION || !(candidate.providers instanceof Map)) {
+		throw new Error(`Unsupported background-work registry at Symbol.for("${BACKGROUND_WORK_REGISTRY_KEY}").`);
+	}
+	return candidate as BackgroundWorkRegistry;
+}
+
+function validateString(value: unknown, field: string, maxLength: number): string {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+		throw new Error(`${field} must be a non-empty string without leading or trailing whitespace.`);
+	}
+	if (value.length > maxLength) throw new Error(`${field} must be at most ${maxLength} characters.`);
+	if (value.includes("\0")) throw new Error(`${field} must not contain NUL characters.`);
+	return value;
+}
+
+function validateProvider(value: unknown): BackgroundWorkProvider {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("Background-work provider must be an object.");
+	}
+	const provider = value as Record<string, unknown>;
+	const unknownFields = Object.keys(provider).filter((key) => !["name", "listActiveWork", "wakeChannels", "reconcile"].includes(key));
+	if (unknownFields.length > 0) throw new Error(`Background-work provider has unknown fields: ${unknownFields.join(", ")}.`);
+	const name = validateString(provider.name, "Background-work provider name", MAX_PROVIDER_NAME_LENGTH);
+	if (typeof provider.listActiveWork !== "function") {
+		throw new Error(`Background-work provider '${name}' must expose listActiveWork().`);
+	}
+	if (provider.reconcile !== undefined && typeof provider.reconcile !== "function") {
+		throw new Error(`Background-work provider '${name}' reconcile must be a function when provided.`);
+	}
+	if (provider.wakeChannels !== undefined) {
+		if (!Array.isArray(provider.wakeChannels)) {
+			throw new Error(`Background-work provider '${name}' wakeChannels must be an array when provided.`);
+		}
+		const channels = provider.wakeChannels.map((channel, index) =>
+			validateString(channel, `Background-work provider '${name}' wakeChannels[${index}]`, MAX_WAKE_CHANNEL_LENGTH));
+		if (new Set(channels).size !== channels.length) {
+			throw new Error(`Background-work provider '${name}' wakeChannels must not contain duplicates.`);
+		}
+	}
+	return value as BackgroundWorkProvider;
+}
+
+function validateItem(provider: string, value: unknown, index: number): BackgroundWorkItem {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`Background-work provider '${provider}' item ${index} must be an object.`);
+	}
+	const item = value as Record<string, unknown>;
+	const unknownFields = Object.keys(item).filter((key) => key !== "id" && key !== "sessionId");
+	if (unknownFields.length > 0) {
+		throw new Error(`Background-work provider '${provider}' item ${index} has unknown fields: ${unknownFields.join(", ")}.`);
+	}
+	return {
+		id: validateString(item.id, `Background-work provider '${provider}' item ${index} id`, MAX_ITEM_ID_LENGTH),
+		sessionId: validateString(item.sessionId, `Background-work provider '${provider}' item ${index} sessionId`, MAX_SESSION_ID_LENGTH),
+	};
+}
+
+/**
+ * Register or replace one process-local background-work provider. The returned
+ * disposer only removes this exact registration, so an old extension reload
+ * cannot unregister its replacement.
+ */
+export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider): () => void {
+	const validated = validateProvider(provider);
+	const current = registry();
+	if (!current.providers.has(validated.name) && current.providers.size >= MAX_PROVIDERS) {
+		throw new Error(`Background-work registry supports at most ${MAX_PROVIDERS} providers.`);
+	}
+	current.providers.set(validated.name, validated);
+	return () => {
+		if (current.providers.get(validated.name) === validated) current.providers.delete(validated.name);
+	};
+}
+
+export function listBackgroundWorkProviders(): readonly BackgroundWorkProvider[] {
+	const current = registry();
+	if (current.providers.size > MAX_PROVIDERS) throw new Error(`Background-work registry contains more than ${MAX_PROVIDERS} providers.`);
+	const providers: BackgroundWorkProvider[] = [];
+	for (const [key, value] of current.providers) {
+		const provider = validateProvider(value);
+		if (key !== provider.name) throw new Error(`Background-work registry key '${key}' does not match provider name '${provider.name}'.`);
+		providers.push(provider);
+	}
+	return providers;
+}
+
+/** Read validated provider wake channels without reconciling or listing work. */
+export function listBackgroundWorkWakeChannels(): readonly string[] {
+	const channels = new Set<string>();
+	for (const provider of listBackgroundWorkProviders()) {
+		for (const channel of provider.wakeChannels ?? []) channels.add(channel);
+	}
+	return [...channels];
+}
+
+/** Reconcile and snapshot active provider work owned by one exact Pi session. */
+export function snapshotBackgroundWork(sessionId: string, nowMs = Date.now()): BackgroundWorkSnapshot {
+	validateString(sessionId, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH);
+	const providers = listBackgroundWorkProviders();
+	const items: RegisteredBackgroundWorkItem[] = [];
+	const identities = new Set<string>();
+	for (const provider of providers) {
+		try {
+			provider.reconcile?.({ sessionId, nowMs });
+		} catch (error) {
+			throw new Error(
+				`Background-work provider '${provider.name}' reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
+				{ cause: error },
+			);
+		}
+		let active: readonly BackgroundWorkItem[];
+		try {
+			active = provider.listActiveWork();
+		} catch (error) {
+			throw new Error(
+				`Background-work provider '${provider.name}' listActiveWork failed: ${error instanceof Error ? error.message : String(error)}`,
+				{ cause: error },
+			);
+		}
+		if (!Array.isArray(active)) {
+			throw new Error(`Background-work provider '${provider.name}' listActiveWork() must return an array.`);
+		}
+		if (active.length > MAX_ITEMS_PER_PROVIDER) {
+			throw new Error(`Background-work provider '${provider.name}' returned ${active.length} items; maximum is ${MAX_ITEMS_PER_PROVIDER}.`);
+		}
+		active.forEach((value, index) => {
+			const item = validateItem(provider.name, value, index);
+			const identity = `${provider.name}\0${item.sessionId}\0${item.id}`;
+			if (identities.has(identity)) {
+				throw new Error(`Background-work provider '${provider.name}' returned duplicate item '${item.id}' for session '${item.sessionId}'.`);
+			}
+			identities.add(identity);
+			if (item.sessionId === sessionId) items.push({ provider: provider.name, ...item });
+		});
+	}
+	return {
+		providers: providers.map((provider) => provider.name),
+		items,
+	};
+}

package/src/api/delegation.ts

@@ -0,0 +1,158 @@
+export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
+
+// This is the established extension-to-extension transport. The public API
+// intentionally reuses it instead of adding a second event protocol.
+export const SUBAGENT_DELEGATION_REQUEST_EVENT = "prompt-template:subagent:request";
+export const SUBAGENT_DELEGATION_STARTED_EVENT = "prompt-template:subagent:started";
+export const SUBAGENT_DELEGATION_UPDATE_EVENT = "prompt-template:subagent:update";
+export const SUBAGENT_DELEGATION_RESPONSE_EVENT = "prompt-template:subagent:response";
+export const SUBAGENT_DELEGATION_CANCEL_EVENT = "prompt-template:subagent:cancel";
+
+export interface SubagentDelegationTurnBudget {
+	maxTurns: number;
+	graceTurns?: number;
+}
+
+export interface SubagentDelegationToolBudget {
+	soft?: number;
+	hard: number;
+	block?: string[] | "*";
+}
+
+export type SubagentDelegationAcceptanceEvidence =
+	| "changed-files"
+	| "tests-added"
+	| "commands-run"
+	| "validation-output"
+	| "residual-risks"
+	| "no-staged-files"
+	| "diff-summary"
+	| "review-findings"
+	| "manual-notes";
+
+export interface SubagentDelegationAcceptanceCriterion {
+	id: string;
+	must: string;
+	evidence?: SubagentDelegationAcceptanceEvidence[];
+	severity?: "required" | "recommended";
+}
+
+export interface SubagentDelegationAcceptanceVerifyCommand {
+	id: string;
+	command: string;
+	timeoutMs?: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	allowFailure?: boolean;
+}
+
+export interface SubagentDelegationAcceptanceReview {
+	agent?: string;
+	focus?: string;
+	required?: boolean;
+}
+
+interface SubagentDelegationAcceptanceFields {
+	criteria?: Array<string | SubagentDelegationAcceptanceCriterion>;
+	evidence?: SubagentDelegationAcceptanceEvidence[];
+	verify?: SubagentDelegationAcceptanceVerifyCommand[];
+	review?: SubagentDelegationAcceptanceReview | false;
+	stopRules?: string[];
+}
+
+export type SubagentDelegationAcceptanceConfig = SubagentDelegationAcceptanceFields & (
+	| { level: "none"; reason: string }
+	| { level?: "auto" | "attested" | "checked" | "verified"; reason?: string }
+);
+
+export type SubagentDelegationAcceptance =
+	| "auto"
+	| "attested"
+	| "checked"
+	| "verified"
+	| false
+	| SubagentDelegationAcceptanceConfig;
+
+export interface SubagentDelegationRequest {
+	version: typeof SUBAGENT_DELEGATION_PROTOCOL_VERSION;
+	requestId: string;
+	agent: string;
+	task: string;
+	context: "fresh" | "fork";
+	cwd: string;
+	model?: string;
+	timeoutMs?: number;
+	turnBudget?: SubagentDelegationTurnBudget;
+	toolBudget?: SubagentDelegationToolBudget;
+	skill?: string | string[] | boolean;
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	acceptance?: SubagentDelegationAcceptance;
+	artifacts?: boolean;
+}
+
+export interface SubagentDelegationStarted {
+	version: typeof SUBAGENT_DELEGATION_PROTOCOL_VERSION;
+	requestId: string;
+}
+
+export interface SubagentDelegationUpdate extends SubagentDelegationStarted {
+	currentTool?: string;
+	currentToolArgs?: string;
+	recentOutput?: string;
+	recentOutputLines?: string[];
+	recentTools?: Array<{ tool: string; args: string }>;
+	model?: string;
+	toolCount?: number;
+	durationMs?: number;
+	tokens?: number;
+}
+
+export type SubagentDelegationStatus =
+	| "completed"
+	| "failed"
+	| "timed_out"
+	| "cancelled"
+	| "interrupted"
+	| "turn_budget_exhausted"
+	| "tool_budget_exhausted"
+	| "acceptance_failed"
+	| "invalid_request"
+	| "unavailable_context";
+
+export type SubagentDelegationAcceptanceStatus =
+	| "pending"
+	| "not-required"
+	| "claimed"
+	| "attested"
+	| "checked"
+	| "verified"
+	| "reviewed"
+	| "accepted"
+	| "rejected";
+
+export interface SubagentDelegationAcceptanceResult {
+	status: SubagentDelegationAcceptanceStatus;
+	explicit: boolean;
+}
+
+export interface SubagentDelegationResponse extends SubagentDelegationStarted {
+	status: SubagentDelegationStatus;
+	error?: string;
+	runId?: string;
+	childIndex?: number;
+	agent?: string;
+	model?: string;
+	exitCode?: number;
+	output?: string;
+	outputPath?: string;
+	sessionFile?: string;
+	acceptance?: SubagentDelegationAcceptanceResult;
+	turns?: number;
+	toolCount?: number;
+	durationMs?: number;
+	tokens?: number;
+	warnings?: string[];
+}
+
+export interface SubagentDelegationCancel extends SubagentDelegationStarted {}