@marcoscale98/pi-extensible-workflows 5.14.1-fork.1

package/subagents/src/contracts.ts

@@ -0,0 +1,176 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { WorkflowError } from "../../src/types.js";
+import type { AgentActivity, AgentAccounting, AgentAttemptSummary, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentToolCallProgress, AgentTransport, LiveSessionHandoff, PreparedAgentSession, WorkflowAgentSession, WorkflowAgentSessionReference } from "../../src/index.js";
+import { validateAgentOptions } from "../../src/validation.js";
+import type { Static } from "typebox";
+import { Value } from "typebox/value";
+import type { SubagentWorktreeAdapter } from "./worktree.js";
+
+export const SUBAGENTS_TOOL_NAMES = [
+  "subagents_run",
+  "subagents_inspect",
+  "subagents_steer",
+  "subagents_stop",
+  "subagents_retry",
+] as const;
+export const SUBAGENT_ATTEMPT_DETAILS_LIMIT = 1;
+export const SUBAGENT_MAX_RETRIES = 255;
+export const SUBAGENT_SYSTEM_PROMPT_LIMIT = 64 * 1024;
+
+const SUBAGENTS_MODE = Type.Union([
+  Type.Literal("background"),
+  Type.Literal("foreground"),
+], { description: "Launch mode; background is the default and foreground waits for the terminal envelope" });
+
+export const SUBAGENTS_RUN_PARAMETERS = Type.Object({
+  prompt: Type.String({ description: "Task for the subagent" }),
+  mode: Type.Optional(SUBAGENTS_MODE),
+  label: Type.Optional(Type.String({ description: "Optional display label for the subagent" })),
+  model: Type.Optional(Type.String({ description: "Optional model as provider/model:thinking or alias[:thinking]" })),
+  tools: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered tool selectors; candidates start enabled and !* restricts the set" })),
+  skills: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered skill selectors; candidates start enabled and !* restricts the set" })),
+  extensions: Type.Optional(Type.Array(Type.String(), { description: "Optional ordered extension selectors; candidates start enabled and !* restricts the set" })),
+  contextFiles: Type.Optional(Type.Array(Type.String(), { description: "Optional context-file scopes: global, project, cwd" })),
+  role: Type.Optional(Type.String({ description: "Workflow role name" })),
+  worktree: Type.Optional(Type.String({ description: "Optional named worktree; requires a clean working tree" })),
+  outputSchema: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Optional JSON schema for the result" })),
+  retries: Type.Optional(Type.Integer({ minimum: 0, maximum: SUBAGENT_MAX_RETRIES, description: "Optional retry count; at most 255 retries" })),
+  timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1, description: "Optional execution timeout in milliseconds" }), Type.Null()])),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_INSPECT_PARAMETERS = Type.Object({
+  id: Type.Optional(Type.String({ description: "Subagent ID; omit to list ordered run summaries" })),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_ID_PARAMETERS = Type.Object({
+  id: Type.String({ description: "Subagent ID" }),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_STEER_PARAMETERS = Type.Object({
+  id: Type.String({ description: "Subagent ID" }),
+  message: Type.String({ description: "Message to send to the running subagent" }),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_STOP_PARAMETERS = Type.Object({
+  id: Type.String({ description: "Subagent ID" }),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_RETRY_PARAMETERS = Type.Object({
+  id: Type.String({ description: "Failed or stopped subagent ID to retry" }),
+}, { additionalProperties: false });
+
+export const SUBAGENTS_TOOL_SCHEMAS = {
+  subagents_run: SUBAGENTS_RUN_PARAMETERS,
+  subagents_inspect: SUBAGENTS_INSPECT_PARAMETERS,
+  subagents_steer: SUBAGENTS_STEER_PARAMETERS,
+  subagents_stop: SUBAGENTS_STOP_PARAMETERS,
+  subagents_retry: SUBAGENTS_RETRY_PARAMETERS,
+} as const;
+
+export type SubagentRunRequest = Static<typeof SUBAGENTS_RUN_PARAMETERS>;
+export function normalizeSubagentRunRequest(value: unknown): SubagentRunRequest {
+  if (!Value.Check(SUBAGENTS_RUN_PARAMETERS, value)) throw new WorkflowError("INVALID_METADATA", "Invalid subagents_run parameters");
+  if (typeof value.worktree === "string" && !value.worktree.trim()) throw new WorkflowError("INVALID_METADATA", "worktree name must be a non-empty string");
+  const snapshot = structuredClone(value);
+  snapshot.mode ??= "background";
+  if (snapshot.worktree !== undefined) snapshot.worktree = snapshot.worktree.trim();
+  validateAgentOptions(snapshot);
+  return snapshot;
+}
+export type SubagentInspectRequest = Static<typeof SUBAGENTS_INSPECT_PARAMETERS>;
+export type SubagentIdRequest = Static<typeof SUBAGENTS_ID_PARAMETERS>;
+export type SubagentSteerRequest = Static<typeof SUBAGENTS_STEER_PARAMETERS>;
+export type SubagentProgress = {
+  readonly accounting: AgentAccounting;
+  readonly toolCalls: readonly AgentToolCallProgress[];
+  readonly state?: Omit<NonNullable<AgentProgress["state"]>, "systemPrompt">;
+  readonly activity?: AgentActivity;
+  readonly lastEventAt?: number;
+};
+export interface SubagentStatus {
+  readonly id: string;
+  readonly sessionId?: string;
+  readonly state: "running" | "completed" | "failed" | "stopped";
+  readonly startedAt?: number;
+  readonly finishedAt?: number;
+  readonly worktree?: { readonly path: string; readonly branch: string };
+  readonly error?: { readonly code: string; readonly message: string };
+  readonly progress?: SubagentProgress;
+  readonly attempts?: number;
+  readonly attemptDetails?: readonly AgentAttemptSummary[];
+}
+export interface SubagentNotification {
+  readonly id: string;
+  readonly label?: string;
+  readonly role?: string;
+  readonly state: "completed" | "failed";
+  readonly error?: { readonly code: string; readonly message: string };
+}
+export interface SubagentManagerContext {
+  readonly toolCallId: string;
+  readonly signal: AbortSignal | undefined;
+  readonly onUpdate: ((value: unknown) => void) | undefined;
+  readonly extensionContext: ExtensionContext;
+  readonly waitForForeground?: boolean;
+  readonly includeAttemptMetadata?: boolean;
+}
+export interface SubagentAttemptActionData {
+  readonly attempt: AgentAttemptSummary;
+  readonly session?: WorkflowAgentSessionReference;
+  readonly liveSession?: WorkflowAgentSession;
+  readonly prepared?: Readonly<PreparedAgentSession>;
+  readonly handoff?: LiveSessionHandoff;
+  readonly signal: AbortSignal;
+}
+
+export interface SubagentOwnerMarker {
+  readonly pid: number;
+  readonly processStart: number;
+  readonly sessionId: string;
+  readonly token: string;
+  readonly acquiredAt: number;
+}
+
+export interface SubagentLiveness {
+  readonly pid?: number;
+  readonly processStart?: number;
+  readonly sessionId?: string;
+  readonly token?: string;
+  readonly isLive?: (owner: Readonly<SubagentOwnerMarker>) => boolean | Promise<boolean>;
+}
+export interface SubagentExecutor {
+  execute(task: string, options: AgentExecutionOptions, signal?: AbortSignal, setSteer?: (handler: (message: string) => void | Promise<void>) => void): Promise<AgentExecutionResult>;
+}
+export interface SubagentManagerDependencies {
+  readonly getActiveTools?: () => readonly string[];
+  readonly agentDir?: string;
+  readonly storageDir?: string;
+  readonly transport?: AgentTransport;
+  readonly createExecutor?: (root: AgentExecutionRoot, transport: AgentTransport) => SubagentExecutor;
+  readonly worktreeAdapter?: SubagentWorktreeAdapter;
+  readonly liveness?: SubagentLiveness;
+  readonly notify?: (notification: Readonly<SubagentNotification>) => void | Promise<void>;
+  readonly onStatus?: (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void;
+  readonly onResourceWarning?: (message: string) => void;
+}
+export interface SubagentManager {
+  run(request: Readonly<SubagentRunRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  inspect(request: Readonly<SubagentInspectRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  steer(request: Readonly<SubagentSteerRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  stop(request: Readonly<SubagentIdRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  retry(request: Readonly<SubagentIdRequest>, context: Readonly<SubagentManagerContext>): Promise<unknown>;
+  getAttemptActionData?(id: string): Readonly<SubagentAttemptActionData> | undefined;
+  dispose?(): Promise<void>;
+}
+
+export interface SubagentsExtensionOptions {
+  readonly manager?: SubagentManager;
+  readonly clipboard?: (value: string) => Promise<void>;
+  readonly managerDependencies?: SubagentManagerDependencies;
+}
+
+export interface SubagentsExtension {
+  readonly manager: SubagentManager;
+  readonly tools: readonly ToolDefinition[];
+}

package/subagents/src/decode.ts

@@ -0,0 +1,158 @@
+import { finiteNumber, jsonValue, parseThinking } from "../../src/utils.js";
+import type { AgentAttemptSummary } from "../../src/types.js";
+import { SUBAGENT_ATTEMPT_DETAILS_LIMIT, type SubagentProgress, type SubagentStatus } from "./contracts.js";
+
+function objectValue(value: unknown): Record<string, unknown> | undefined { return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined; }
+function resourceSummaryValue(value: unknown): NonNullable<AgentAttemptSummary["setup"]["resourceSelectors"]> | undefined {
+  const record = objectValue(value);
+  const selectors = objectValue(record?.selectors);
+  const skills = stringArrayValue(record?.skills);
+  const extensions = stringArrayValue(record?.extensions);
+  const tools = stringArrayValue(record?.tools);
+  const selectorSkills = stringArrayValue(selectors?.skills);
+  const selectorExtensions = stringArrayValue(selectors?.extensions);
+  const selectorTools = stringArrayValue(selectors?.tools);
+  const unmatchedSkills = stringArrayValue(record?.unmatchedSkills);
+  const unmatchedExtensions = stringArrayValue(record?.unmatchedExtensions);
+  const unmatchedTools = stringArrayValue(record?.unmatchedTools);
+  if (!record || !selectors || !skills || !extensions || !tools || !selectorSkills || !selectorExtensions || !selectorTools || !unmatchedSkills || !unmatchedExtensions || !unmatchedTools) return undefined;
+  return { selectors: { skills: selectorSkills, extensions: selectorExtensions, tools: selectorTools }, skills, extensions, tools, unmatchedSkills, unmatchedExtensions, unmatchedTools };
+}
+function nonnegativeInteger(value: unknown): value is number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; }
+function stringArrayValue(value: unknown): readonly string[] | undefined { return Array.isArray(value) && value.length <= 256 && value.every((item) => typeof item === "string") ? value : undefined; }
+export function accountingValue(value: unknown): SubagentProgress["accounting"] | undefined {
+  const record = objectValue(value);
+  if (!record) return undefined;
+  const input = record.input;
+  const output = record.output;
+  const cacheRead = record.cacheRead;
+  const cacheWrite = record.cacheWrite;
+  const cost = record.cost;
+  if (!finiteNumber(input) || !finiteNumber(output) || !finiteNumber(cacheRead) || !finiteNumber(cacheWrite) || !finiteNumber(cost)) return undefined;
+  return { input, output, cacheRead, cacheWrite, cost };
+}
+export function legacyAccountingValue(record: Record<string, unknown>): SubagentProgress["accounting"] | undefined {
+  const accounting = accountingValue(record.accounting);
+  if (record.accounting !== undefined && !accounting) return undefined;
+  const usage = record.usage;
+  if (usage === undefined) return accounting;
+  const usageRecord = objectValue(usage);
+  const tokens = objectValue(usageRecord?.tokens);
+  if (!usageRecord || !tokens || !finiteNumber(tokens.input) || !finiteNumber(tokens.output) || !finiteNumber(tokens.cacheRead) || !finiteNumber(tokens.cacheWrite) || !finiteNumber(tokens.total) || !finiteNumber(usageRecord.cost)) return undefined;
+  return accounting ?? { input: tokens.input, output: tokens.output, cacheRead: tokens.cacheRead, cacheWrite: tokens.cacheWrite, cost: usageRecord.cost };
+}
+export function activityValue(value: unknown): NonNullable<SubagentProgress["activity"]> | undefined {
+  const record = objectValue(value);
+  return record && (record.kind === "reasoning" || record.kind === "tool" || record.kind === "text") && typeof record.text === "string" ? { kind: record.kind, text: record.text } : undefined;
+}
+function toolCallsValue(value: unknown): SubagentProgress["toolCalls"] | undefined {
+  if (!Array.isArray(value) || value.length > 256) return undefined;
+  const calls: SubagentProgress["toolCalls"][number][] = [];
+  for (const item of value) {
+    const record = objectValue(item);
+    if (!record || typeof record.id !== "string" || typeof record.name !== "string" || record.state !== "running" && record.state !== "completed" && record.state !== "failed") return undefined;
+    calls.push({ id: record.id, name: record.name, state: record.state });
+  }
+  return calls;
+}
+function sessionReferenceValue(value: unknown): AgentAttemptSummary["session"] | undefined {
+  const record = objectValue(value);
+  const transport = record?.transport;
+  const sessionId = record?.sessionId;
+  if (!record || typeof transport !== "string" || !transport.trim() || typeof sessionId !== "string" || !sessionId.trim()) return undefined;
+  return { transport, sessionId, ...(record.locator === undefined || !jsonValue(record.locator) ? {} : { locator: record.locator }) };
+}
+export function subagentErrorValue(value: unknown): { readonly code: string; readonly message: string } | undefined {
+  const record = objectValue(value);
+  return record && typeof record.code === "string" && typeof record.message === "string" ? { code: record.code, message: record.message } : undefined;
+}
+export function worktreeValue(value: unknown): { readonly path: string; readonly branch: string } | undefined {
+  const record = objectValue(value);
+  return record && typeof record.path === "string" && record.path.trim() && typeof record.branch === "string" && record.branch.trim() ? { path: record.path, branch: record.branch } : undefined;
+}
+function progressValue(value: unknown): SubagentProgress | undefined {
+  const record = objectValue(value);
+  if (!record) return undefined;
+  const accounting = accountingValue(record.accounting);
+  const toolCalls = toolCallsValue(record.toolCalls);
+  if (!accounting || !toolCalls) return undefined;
+  const activity = record.activity === undefined ? undefined : activityValue(record.activity);
+  if (record.activity !== undefined && activity === undefined) return undefined;
+  const rawState = record.state;
+  let state: SubagentProgress["state"];
+  if (rawState !== undefined) {
+    const stateRecord = objectValue(rawState);
+    const model = objectValue(stateRecord?.model);
+    const tools = stringArrayValue(stateRecord?.tools);
+    if (!stateRecord || !model || !tools || typeof model.provider !== "string" || typeof model.model !== "string") return undefined;
+    const thinking = parseThinking(model.thinking);
+    if (model.thinking !== undefined && thinking === undefined) return undefined;
+    state = { model: { provider: model.provider, model: model.model, ...(thinking === undefined ? {} : { thinking }) }, tools };
+  }
+  const lastEventAt = record.lastEventAt;
+  if (lastEventAt !== undefined && !nonnegativeInteger(lastEventAt)) return undefined;
+  return { accounting, toolCalls, ...(state === undefined ? {} : { state }), ...(activity === undefined ? {} : { activity }), ...(lastEventAt === undefined ? {} : { lastEventAt }) };
+}
+function legacyProgressValue(record: Record<string, unknown>): SubagentProgress | undefined {
+  const accounting = legacyAccountingValue(record);
+  const toolCalls = record.toolCalls === undefined ? [] : toolCallsValue(record.toolCalls);
+  if (!accounting || !toolCalls) return undefined;
+  const activity = record.activity === undefined ? undefined : activityValue(record.activity);
+  const lastEventAt = record.lastEventAt;
+  if (record.activity !== undefined && activity === undefined || lastEventAt !== undefined && !nonnegativeInteger(lastEventAt)) return undefined;
+  return { accounting, toolCalls, ...(activity === undefined ? {} : { activity }), ...(lastEventAt === undefined ? {} : { lastEventAt }) };
+}
+export function attemptValue(value: unknown): AgentAttemptSummary | undefined {
+  const record = objectValue(value);
+  const setup = objectValue(record?.setup);
+  const model = objectValue(setup?.model);
+  const hookNames = stringArrayValue(setup?.hookNames);
+  const tools = stringArrayValue(setup?.tools);
+  const resources = setup?.resourceSelectors === undefined ? undefined : resourceSummaryValue(setup.resourceSelectors);
+  const accounting = accountingValue(record?.accounting);
+  const session = record?.session === undefined ? undefined : sessionReferenceValue(record.session);
+  const error = record?.error === undefined ? undefined : subagentErrorValue(record.error);
+  const thinking = parseThinking(model?.thinking);
+  if (!record || !nonnegativeInteger(record.attempt) || record.attempt < 1 || typeof record.transport !== "string" || !record.transport.trim() || !setup || typeof setup.cwd !== "string" || !setup.cwd.trim() || !model || typeof model.provider !== "string" || !model.provider.trim() || typeof model.model !== "string" || !model.model.trim() || model.thinking !== undefined && thinking === undefined || !hookNames || !tools || setup.resourceSelectors !== undefined && resources === undefined || !accounting || record.session !== undefined && session === undefined || record.error !== undefined && error === undefined) return undefined;
+  return {
+    attempt: record.attempt,
+    transport: record.transport,
+    setup: { hookNames, model: { provider: model.provider, model: model.model, ...(thinking === undefined ? {} : { thinking }) }, tools, cwd: setup.cwd, ...(resources === undefined ? {} : { resourceSelectors: resources }) },
+    accounting,
+    ...(session === undefined ? {} : { session }),
+    ...(error === undefined ? {} : { error }),
+  };
+}
+export function statusValue(value: unknown): SubagentStatus | undefined {
+  const record = objectValue(value);
+  const id = record?.id;
+  const state = record?.state;
+  if (!record || typeof id !== "string" || !id || state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped") return undefined;
+  const startedAt = record.startedAt;
+  const finishedAt = record.finishedAt;
+  if (startedAt !== undefined && !nonnegativeInteger(startedAt) || finishedAt !== undefined && (!nonnegativeInteger(finishedAt) || typeof startedAt === "number" && finishedAt < startedAt)) return undefined;
+  const sessionId = record.sessionId;
+  if (sessionId !== undefined && (typeof sessionId !== "string" || !sessionId.trim())) return undefined;
+  const worktree = record.worktree === undefined ? undefined : worktreeValue(record.worktree);
+  if (record.worktree !== undefined && worktree === undefined) return undefined;
+  const error = record.error === undefined ? undefined : subagentErrorValue(record.error);
+  if (record.error !== undefined && error === undefined) return undefined;
+  const attempts = record.attempts;
+  if (attempts !== undefined && (!nonnegativeInteger(attempts) || attempts < 1)) return undefined;
+  const attemptDetails = record.attemptDetails === undefined ? undefined : Array.isArray(record.attemptDetails) ? record.attemptDetails.slice(-SUBAGENT_ATTEMPT_DETAILS_LIMIT).map(attemptValue) : undefined;
+  if (record.attemptDetails !== undefined && (!attemptDetails || attemptDetails.some((attempt): attempt is undefined => attempt === undefined))) return undefined;
+  const progress = record.progress === undefined ? legacyProgressValue(record) : progressValue(record.progress);
+  if (record.progress !== undefined && progress === undefined) return undefined;
+  return {
+    id,
+    ...(sessionId === undefined ? {} : { sessionId }),
+    state,
+    ...(startedAt === undefined ? {} : { startedAt }),
+    ...(finishedAt === undefined ? {} : { finishedAt }),
+    ...(worktree === undefined ? {} : { worktree }),
+    ...(error === undefined ? {} : { error }),
+    ...(attempts === undefined ? {} : { attempts }),
+    ...(attemptDetails === undefined ? {} : { attemptDetails: attemptDetails.filter((attempt): attempt is AgentAttemptSummary => attempt !== undefined) }),
+    ...(progress === undefined ? {} : { progress }),
+  };
+}

package/subagents/src/index.ts

@@ -0,0 +1,194 @@
+import { join } from "node:path";
+import { defineTool, getAgentDir, type AgentToolResult, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+import { WorkflowError, loadingRegistry } from "../../src/index.js";
+import { clearSubagentManager, setSubagentManager } from "../../src/subagent-manager-handle.js";
+import type { SubagentIdRequest, SubagentInspectRequest, SubagentManager, SubagentManagerContext, SubagentNotification, SubagentsExtension, SubagentsExtensionOptions, SubagentRunRequest, SubagentStatus, SubagentSteerRequest } from "./contracts.js";
+import { createSubagentManager } from "./manager.js";
+import { registerSubagentNavigator } from "./navigator.js";
+import { createSubagentBackgroundWidget, renderSubagentCall, renderSubagentControlCall, renderSubagentControlResult, renderSubagentInspectCall, renderSubagentInspectResult, renderSubagentResult } from "./view.js";
+import {
+  normalizeSubagentRunRequest,
+  SUBAGENTS_ID_PARAMETERS,
+  SUBAGENTS_INSPECT_PARAMETERS,
+  SUBAGENTS_RETRY_PARAMETERS,
+  SUBAGENTS_RUN_PARAMETERS,
+  SUBAGENTS_STEER_PARAMETERS,
+  SUBAGENTS_STOP_PARAMETERS,
+} from "./contracts.js";
+
+export * from "./contracts.js";
+export { attemptValue, statusValue, subagentErrorValue } from "./decode.js";
+export { createSubagentManager, createUnavailableSubagentManager } from "./manager.js";
+export { createRunStoreWorktreeAdapter, defaultWorktreeHome } from "./worktree.js";
+export type { SubagentWorktreeAdapter, SubagentWorktreeContext, SubagentWorktreeHandle, SubagentWorktreeRunStore } from "./worktree.js";
+
+type SubagentsExtensionAPI = Pick<ExtensionAPI, "registerTool"> & Partial<Pick<ExtensionAPI, "getActiveTools" | "on" | "sendMessage" | "registerCommand">>;
+
+function validateSubagentRunRequest(value: unknown): SubagentRunRequest {
+  return normalizeSubagentRunRequest(value);
+}
+
+function validateSubagentIdRequest(value: unknown, operation: string): SubagentIdRequest {
+  if (!Value.Check(SUBAGENTS_ID_PARAMETERS, value)) throw new WorkflowError("INVALID_METADATA", `Invalid ${operation} parameters`);
+  return value;
+}
+
+function validateSubagentInspectRequest(value: unknown): SubagentInspectRequest {
+  if (!Value.Check(SUBAGENTS_INSPECT_PARAMETERS, value)) throw new WorkflowError("INVALID_METADATA", "Invalid subagents_inspect parameters");
+  return value;
+}
+
+function validateSubagentSteerRequest(value: unknown): SubagentSteerRequest {
+  if (!Value.Check(SUBAGENTS_STEER_PARAMETERS, value)) throw new WorkflowError("INVALID_METADATA", "Invalid subagents_steer parameters");
+  return value;
+}
+
+function serialize(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    const serialized = JSON.stringify(value);
+    return typeof serialized === "string" ? serialized : String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function toolResult(value: unknown): AgentToolResult<unknown> {
+  return { content: [{ type: "text", text: serialize(value) }], details: value };
+}
+
+function managerContext(toolCallId: string, signal: AbortSignal | undefined, onUpdate: ((value: AgentToolResult<unknown>) => void) | undefined, context: ExtensionContext): SubagentManagerContext {
+  return {
+    toolCallId,
+    signal,
+    onUpdate: onUpdate === undefined ? undefined : (value) => { onUpdate(toolResult(value)); },
+    extensionContext: context,
+  };
+}
+export function createSubagentTools(manager: SubagentManager): readonly ToolDefinition[] {
+  return [
+    defineTool({
+      name: "subagents_run",
+      label: "Subagents Run",
+      description: "Start a durable subagent run. Background mode returns its ID immediately; foreground mode waits and returns the terminal value or error in this tool call. Use the ID with subagents_inspect, subagents_steer, subagents_stop, or subagents_retry.",
+      promptSnippet: "Run durable subagents in background by default; inspect, steer, stop, or retry them with the other subagents tools.",
+      promptGuidelines: [
+        "Runs are background by default; choose mode: \"foreground\" only when the terminal envelope is needed in this turn.",
+        "Do not poll a running ID; use subagents_inspect({ id }) when you need its current status or terminal result.",
+      ],
+      parameters: SUBAGENTS_RUN_PARAMETERS,
+      async execute(toolCallId, params, signal, onUpdate, context) {
+        return toolResult(await manager.run(validateSubagentRunRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
+      },
+      renderCall(args, _theme, context) { return renderSubagentCall(args, context); },
+      renderResult(result, options, theme, context) { return renderSubagentResult(result, options, theme, context); },
+    }),
+    defineTool({
+      name: "subagents_inspect",
+      label: "Subagents Inspect",
+      description: "Inspect durable subagent runs. Omit id for ordered run summaries, or provide id for detailed status, progress, activity, accounting, tool calls, timestamps, worktree metadata, and a terminal value or error when available.",
+      parameters: SUBAGENTS_INSPECT_PARAMETERS,
+      async execute(toolCallId, params, signal, onUpdate, context) {
+        return toolResult(await manager.inspect(validateSubagentInspectRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
+      },
+      renderCall(args, theme) { return renderSubagentInspectCall(args, theme); },
+      renderResult(result, options, theme, context) { return renderSubagentInspectResult(result, options, theme, context.args); },
+    }),
+    defineTool({
+      name: "subagents_steer",
+      label: "Subagents Steer",
+      description: "Send a message to a running subagent. The message is queued safely if its steering handler is not ready; settled runs cannot be steered.",
+      parameters: SUBAGENTS_STEER_PARAMETERS,
+      async execute(toolCallId, params, signal, onUpdate, context) {
+        return toolResult(await manager.steer(validateSubagentSteerRequest(params), managerContext(toolCallId, signal, onUpdate, context)));
+      },
+      renderCall(args, theme) { return renderSubagentControlCall("subagents_steer", args, theme); },
+      renderResult(result, _options, theme) { return renderSubagentControlResult(result, theme); },
+    }),
+    defineTool({
+      name: "subagents_stop",
+      label: "Subagents Stop",
+      description: "Stop one running subagent, abort its active session, persist state \"stopped\", and clean its worktree without affecting sibling runs.",
+      parameters: SUBAGENTS_STOP_PARAMETERS,
+      async execute(toolCallId, params, signal, onUpdate, context) {
+        return toolResult(await manager.stop(validateSubagentIdRequest(params, "subagents_stop"), managerContext(toolCallId, signal, onUpdate, context)));
+      },
+      renderCall(args, theme) { return renderSubagentControlCall("subagents_stop", args, theme); },
+      renderResult(result, _options, theme) { return renderSubagentControlResult(result, theme); },
+    }),
+    defineTool({
+      name: "subagents_retry",
+      label: "Subagents Retry",
+      description: "Start a fresh run from a failed or stopped subagent's persisted request. The new run gets a new ID and preserves its original background or foreground mode.",
+      parameters: SUBAGENTS_RETRY_PARAMETERS,
+      async execute(toolCallId, params, signal, onUpdate, context) {
+        return toolResult(await manager.retry(validateSubagentIdRequest(params, "subagents_retry"), managerContext(toolCallId, signal, onUpdate, context)));
+      },
+      renderCall(args, theme) { return renderSubagentControlCall("subagents_retry", args, theme); },
+      renderResult(result, options, theme, context) { return renderSubagentResult(result, options, theme, context); },
+    }),
+  ];
+}
+
+function notificationContent(notification: SubagentNotification): string {
+  const label = notification.label?.trim();
+  const role = notification.role?.trim() || "none";
+  const identity = label ? `${label} role=${role} (${notification.id})` : `${notification.id} role=${role}`;
+  if (notification.state === "completed") return `Subagent ${identity} completed. Inspect it with subagents_inspect({ id: "${notification.id}" }).`;
+  return `Subagent ${identity} failed: ${notification.error?.message ?? "unknown error"}. Inspect it with subagents_inspect({ id: "${notification.id}" }).`;
+}
+function managerDependencies(options: SubagentsExtensionOptions, activeTools: (() => readonly string[]) | undefined, notify: ((notification: SubagentNotification) => void | Promise<void>) | undefined, onStatus: ((status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void) | undefined, onResourceWarning?: (message: string) => void): SubagentsExtensionOptions["managerDependencies"] {
+  const dependencies = options.managerDependencies;
+  const next = {
+    ...(dependencies ?? {}),
+    ...(activeTools !== undefined && dependencies?.getActiveTools === undefined ? { getActiveTools: activeTools } : {}),
+    ...(notify !== undefined && dependencies?.notify === undefined ? { notify } : {}),
+    ...(onStatus !== undefined && dependencies?.onStatus === undefined ? { onStatus } : {}),
+    ...(onResourceWarning !== undefined && dependencies?.onResourceWarning === undefined ? { onResourceWarning } : {}),
+  };
+  return Object.keys(next).length === 0 ? dependencies : next;
+}
+function storageDirectory(options: SubagentsExtensionOptions): string {
+  const dependencies = options.managerDependencies;
+  return dependencies?.storageDir ?? join(dependencies?.agentDir ?? getAgentDir(), "subagents");
+}
+
+export function createSubagentsExtension(options: SubagentsExtensionOptions = {}, activeTools?: () => readonly string[], notify?: (notification: SubagentNotification) => void | Promise<void>, onStatus?: (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void, onResourceWarning?: (message: string) => void): SubagentsExtension {
+  const manager = options.manager ?? createSubagentManager(managerDependencies(options, activeTools, notify, onStatus, onResourceWarning));
+  const extension = { manager, tools: createSubagentTools(manager) };
+  return extension;
+}
+
+export function registerSubagentsExtension(pi: SubagentsExtensionAPI, options: SubagentsExtensionOptions = {}): SubagentsExtension {
+  const getActiveTools = pi.getActiveTools;
+  const activeTools = getActiveTools === undefined ? undefined : () => getActiveTools.call(pi);
+  const sendMessage = pi.sendMessage;
+  const notify = sendMessage === undefined ? undefined : (notification: SubagentNotification): void => {
+    sendMessage.call(pi, { customType: "subagents", content: notificationContent(notification), display: true, details: notification }, { deliverAs: "steer", triggerTurn: true });
+  };
+  const onResourceWarning = sendMessage === undefined ? undefined : (message: string): void => {
+    sendMessage.call(pi, { customType: "subagents", content: `Warning: ${message}`, display: true }, { deliverAs: "steer" });
+  };
+  const widget = createSubagentBackgroundWidget();
+  const extension = createSubagentsExtension(options, activeTools, notify, (status, request) => { widget.update(status, request); const registry = loadingRegistry(); if (typeof registry.observeSubagentStatus === "function") registry.observeSubagentStatus(status, request); }, onResourceWarning);
+  for (const tool of extension.tools) pi.registerTool(tool);
+  if (pi.registerCommand !== undefined) registerSubagentNavigator(pi.registerCommand.bind(pi), extension.manager, storageDirectory(options), options.clipboard);
+  if (pi.on !== undefined) {
+    setSubagentManager(extension.manager);
+    pi.on("session_start", (_event, context) => { widget.start(context); });
+    pi.on("session_shutdown", async () => {
+      try {
+        widget.dispose();
+        await extension.manager.dispose?.();
+      } finally {
+        clearSubagentManager(extension.manager);
+      }
+    });
+  }
+  return extension;
+}
+
+export default function extension(pi: ExtensionAPI, options: SubagentsExtensionOptions = {}): void {
+  registerSubagentsExtension(pi, options);
+}