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

package/src/settings.ts

@@ -0,0 +1,224 @@
+import { atomicWriteFile } from "./persistence.js";
+import { mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, type ToolAnnotations } from "@earendil-works/pi-coding-agent";
+import type { AgentResourcePolicy, AgentResourceSelectors, AgentResourceSelectorSet, ContextFileScope, JsonValue, WorkflowExtensionSettings, WorkflowRetentionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution, WorkflowSettingsSources } from "./types.js";
+import { isContextFileScope } from "./types.js";
+import { annotateModelAliasError, deepFreeze, errorText, fail, isNodeError, jsonValue, modelCapability, object, positiveInteger, resourcePatternHasMagic, unknownModel, validateModelAliases, validateResourcePattern, validWorkflowExtensionNamespace } from "./utils.js";
+import { canonicalPath, workflowProjectSettingsPath } from "./paths.js";
+export { workflowProjectSettingsPath } from "./paths.js";
+
+const ROLE_DIRECTORY = "pi-extensible-workflows";
+export const DEFAULT_SETTINGS: Readonly<WorkflowSettings> = Object.freeze({ concurrency: 8, backgroundWidget: true });
+export function workflowSettingsPath(agentDir = getAgentDir()): string { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
+function normalizedResourcePath(value: string, settingsPath: string): string {
+  // Built-in extensions are named `builtin:<name>`, not by a path.
+  if (value === "*" || value.startsWith("builtin:")) return value;
+  let expanded = value === "~" ? homedir() : value.startsWith("~/") || value.startsWith("~\\") ? join(homedir(), value.slice(2)) : value;
+  if (expanded.startsWith("file://")) expanded = fileURLToPath(expanded);
+  const resolved = resolve(dirname(settingsPath), expanded);
+  if (expanded === "**" || expanded.startsWith("**/") || expanded.startsWith("**\\")) return expanded;
+  if (resourcePatternHasMagic(expanded)) {
+    const magicIndex = resolved.search(/[*?\x5b\x5d{}()]/);
+    const separatorIndex = Math.max(resolved.lastIndexOf("/", magicIndex), resolved.lastIndexOf("\\", magicIndex));
+    const rootBoundary = separatorIndex === 0 || (separatorIndex === 2 && /^[A-Za-z]:[\\/]/.test(resolved));
+    const prefix = rootBoundary ? resolved.slice(0, separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(0, separatorIndex) : resolved;
+    const suffix = rootBoundary ? resolved.slice(separatorIndex + 1) : separatorIndex >= 0 ? resolved.slice(separatorIndex) : "";
+    return `${canonicalPath(prefix)}${suffix}`;
+  }
+  return canonicalPath(resolved);
+}
+export function validateSelectorList(value: unknown, path: string, kind: "skills" | "extensions" | "tools", errorCode: "INVALID_SETTINGS" | "INVALID_METADATA" = "INVALID_SETTINGS", normalizeExtensions = true): readonly string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) fail(errorCode, `${path}.${kind} must be an array`);
+  const normalized: string[] = [];
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string" || !entry.trim()) fail(errorCode, `${path}.${kind}[${String(index)}] must be a non-empty string`);
+    let selector = entry.trim();
+    if (kind === "extensions" && normalizeExtensions) {
+      const negated = selector.startsWith("!");
+      const body = negated ? selector.slice(1) : selector;
+      if (!body) fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid minimatch pattern: Empty minimatch pattern ${JSON.stringify(selector)}`);
+      try { selector = `${negated ? "!" : ""}${normalizedResourcePath(body, path)}`; } catch (error) { fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid path: ${errorText(error)}`); }
+    }
+    try { validateResourcePattern(selector); } catch (error) { fail(errorCode, `${path}.${kind}[${String(index)}] must be a valid minimatch pattern: ${errorText(error)}`); }
+    normalized.push(selector);
+  }
+  return Object.freeze(normalized);
+}
+function validateWorktreePostCreateCommand(value: unknown, settingsPath: string): readonly string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0) fail("INVALID_SETTINGS", `${settingsPath}.worktreePostCreateCommand must be a non-empty array`);
+  return Object.freeze(value.map((entry, index) => {
+    if (typeof entry !== "string" || !entry.trim()) fail("INVALID_SETTINGS", `${settingsPath}.worktreePostCreateCommand[${String(index)}] must be a non-empty string`);
+    return entry;
+  }));
+}
+function selectorsFromSettings(settings: Readonly<WorkflowSettings | WorkflowSettingsOverrides>): AgentResourceSelectors {
+  return {
+    ...(settings.skills === undefined ? {} : { skills: settings.skills }),
+    ...(settings.extensions === undefined ? {} : { extensions: settings.extensions }),
+    ...(settings.tools === undefined ? {} : { tools: settings.tools }),
+  };
+}
+function selectorSet(value: AgentResourceSelectors | undefined): AgentResourceSelectorSet { return { skills: [...(value?.skills ?? [])], extensions: [...(value?.extensions ?? [])], ...(value?.tools === undefined ? {} : { tools: [...value.tools] }) }; }
+export function validateContextFileScopes(value: unknown, rolePath: string): readonly ContextFileScope[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || !value.every(isContextFileScope)) fail("INVALID_METADATA", `${rolePath}.contextFiles must be an array containing only global, project, or cwd`);
+  return [...value];
+}
+export function validateWorkflowExtensionSettings(value: unknown, settingsPath: string, errorCode: "INVALID_SETTINGS" | "INVALID_METADATA" = "INVALID_SETTINGS"): WorkflowExtensionSettings | undefined {
+  if (value === undefined) return undefined;
+  const base = `${settingsPath}.extensionSettings`;
+  if (!object(value)) fail(errorCode, `${base} must be an object`);
+  const normalized: Record<string, JsonValue> = {};
+  for (const [namespace, raw] of Object.entries(value)) {
+    if (!validWorkflowExtensionNamespace(namespace)) fail(errorCode, `${base} contains an invalid namespace: ${namespace}`);
+    if (namespace === "herdr") {
+      if (!object(raw)) fail(errorCode, `${base}.herdr must be an object`);
+      if (Object.keys(raw).some((key) => key !== "enableFullyInspectableMode")) fail(errorCode, `${base}.herdr contains an unsupported setting`);
+      if (raw.enableFullyInspectableMode !== undefined && typeof raw.enableFullyInspectableMode !== "boolean") fail(errorCode, `${base}.herdr.enableFullyInspectableMode must be a boolean`);
+      normalized.herdr = Object.freeze({ ...(raw.enableFullyInspectableMode === undefined ? {} : { enableFullyInspectableMode: raw.enableFullyInspectableMode }) });
+      continue;
+    }
+    if (namespace === "trajectory") {
+      if (!object(raw)) fail(errorCode, `${base}.trajectory must be an object`);
+      if (Object.keys(raw).some((key) => key !== "port")) fail(errorCode, `${base}.trajectory contains an unsupported setting`);
+      if (raw.port !== undefined && (!positiveInteger(raw.port) || raw.port > 65535)) fail(errorCode, `${base}.trajectory.port must be an integer from 1 to 65535`);
+      normalized.trajectory = Object.freeze({ ...(raw.port === undefined ? {} : { port: raw.port }) });
+      continue;
+    }
+    if (!jsonValue(raw)) fail(errorCode, `${base}.${namespace} must be JSON-compatible`);
+    normalized[namespace] = structuredClone(raw);
+  }
+  return deepFreeze(normalized as WorkflowExtensionSettings);
+}
+function positiveRetentionInteger(value: unknown): value is number { return positiveInteger(value) && Number.isSafeInteger(value); }
+function validateRetention(value: unknown, settingsPath: string): Readonly<WorkflowRetentionSettings> | undefined {
+  if (value === undefined) return undefined;
+  const base = `${settingsPath}.retention`;
+  if (!object(value)) fail("INVALID_SETTINGS", `${base} must be an object`);
+  const unknown = Object.keys(value).find((key) => key !== "olderThanDays" && key !== "maxTerminalRuns");
+  if (unknown) fail("INVALID_SETTINGS", `Unknown retention setting at ${base}: ${unknown}`);
+  if (value.olderThanDays !== undefined && !positiveRetentionInteger(value.olderThanDays)) fail("INVALID_SETTINGS", `${base}.olderThanDays must be a positive integer`);
+  if (value.maxTerminalRuns !== undefined && !positiveRetentionInteger(value.maxTerminalRuns)) fail("INVALID_SETTINGS", `${base}.maxTerminalRuns must be a positive integer`);
+  return Object.freeze({ ...(value.olderThanDays === undefined ? {} : { olderThanDays: value.olderThanDays }), ...(value.maxTerminalRuns === undefined ? {} : { maxTerminalRuns: value.maxTerminalRuns }) });
+}
+function parseSettings(path: string, partial: false): Readonly<WorkflowSettings>;
+function parseSettings(path: string, partial: true): Readonly<WorkflowSettingsOverrides>;
+function parseSettings(path: string, partial: boolean): Readonly<WorkflowSettings | WorkflowSettingsOverrides> {
+  let parsed: unknown;
+  try { parsed = JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) {
+    if (isNodeError(error, "ENOENT")) return partial ? Object.freeze({}) : DEFAULT_SETTINGS;
+    fail("CONFIG_ERROR", `Invalid workflow settings JSON at ${path}: ${errorText(error)}`);
+  }
+  if (!object(parsed)) fail("INVALID_SETTINGS", `Workflow settings at ${path} must be an object`);
+  const allowed = new Set(["concurrency", "modelAliases", "skills", "extensions", "extensionSettings", "tools", "retention", "worktreePostCreateCommand", ...(partial ? [] : ["backgroundWidget", "codemodeTools"]) ]);
+  const unknown = Object.keys(parsed).find((key) => !allowed.has(key));
+  if (Object.prototype.hasOwnProperty.call(parsed, "disabledAgentResources")) fail("INVALID_SETTINGS", `disabledAgentResources is no longer supported; use skills, extensions, and tools selectors (settings: ${path})`);
+  if (unknown) fail("INVALID_SETTINGS", `Unknown workflow setting at ${path}: ${unknown}`);
+  const concurrency = parsed.concurrency === undefined ? (partial ? undefined : DEFAULT_SETTINGS.concurrency) : parsed.concurrency;
+  if (concurrency !== undefined && (!positiveInteger(concurrency) || concurrency > 16)) fail("INVALID_SETTINGS", `${path}.concurrency must be an integer from 1 to 16`);
+  const backgroundWidget = parsed.backgroundWidget === undefined ? (partial ? undefined : DEFAULT_SETTINGS.backgroundWidget) : parsed.backgroundWidget;
+  if (backgroundWidget !== undefined && typeof backgroundWidget !== "boolean") fail("INVALID_SETTINGS", `${path}.backgroundWidget must be a boolean`);
+  const codemodeTools = parsed.codemodeTools;
+  if (codemodeTools !== undefined && codemodeTools !== "all" && codemodeTools !== "read-only" && codemodeTools !== "none") fail("INVALID_SETTINGS", `${path}.codemodeTools must be "all", "read-only", or "none"`);
+  const modelAliases = parsed.modelAliases === undefined ? undefined : validateModelAliases(parsed.modelAliases, path);
+  const skills = validateSelectorList(parsed.skills, path, "skills");
+  const tools = validateSelectorList(parsed.tools, path, "tools");
+  const extensions = validateSelectorList(parsed.extensions, path, "extensions");
+  const extensionSettings = parsed.extensionSettings === undefined ? undefined : validateWorkflowExtensionSettings(parsed.extensionSettings, path, "INVALID_SETTINGS");
+  const retention = validateRetention(parsed.retention, path);
+  const worktreePostCreateCommand = validateWorktreePostCreateCommand(parsed.worktreePostCreateCommand, path);
+  return Object.freeze({
+    ...(concurrency === undefined ? {} : { concurrency }), ...(backgroundWidget === undefined ? {} : { backgroundWidget }), ...(codemodeTools === undefined ? {} : { codemodeTools }), ...(modelAliases === undefined ? {} : { modelAliases }),
+    ...(skills === undefined ? {} : { skills }), ...(extensions === undefined ? {} : { extensions }),
+    ...(extensionSettings === undefined ? {} : { extensionSettings }), ...(tools === undefined ? {} : { tools }), ...(retention === undefined ? {} : { retention }),
+    ...(worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand }),
+  });
+}
+export function loadSettings(path = workflowSettingsPath()): Readonly<WorkflowSettings> { return parseSettings(path, false); }
+const READ_ONLY_WORKFLOW_TOOLS: ReadonlySet<string> = new Set(["workflow_status", "workflow_catalog", "subagents_inspect"]);
+/**
+ * Exposure and annotations of a workflow or subagent tool. Under the global `codemodeTools` setting,
+ * `model-only` keeps the model's direct access and stops codemode scripts from calling the tool.
+ * Tools are registered once at load, so the setting is global and applies after a reload.
+ * Read-only tools carry `readOnlyHint` so permission extensions need not confirm them.
+ */
+export function workflowToolExposure(name: string, codemodeTools: WorkflowSettings["codemodeTools"]): { exposure?: "model-only"; annotations?: ToolAnnotations } {
+  const readOnly = READ_ONLY_WORKFLOW_TOOLS.has(name);
+  return { ...(codemodeTools === "none" || (codemodeTools === "read-only" && !readOnly) ? { exposure: "model-only" as const } : {}), ...(readOnly ? { annotations: { readOnlyHint: true } } : {}) };
+}
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export function loadCodemodeToolsSetting(agentDir?: string): WorkflowSettings["codemodeTools"] {
+  try { return loadSettings(workflowSettingsPath(agentDir)).codemodeTools; } catch { return undefined; }
+}
+export function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides> { return parseSettings(path, true); }
+export function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath = workflowSettingsPath()): WorkflowSettingsResolution {
+  const projectSettingsPath = workflowProjectSettingsPath(cwd);
+  const global = loadSettings(globalSettingsPath);
+  const project: Readonly<WorkflowSettingsOverrides> = projectTrusted ? loadSettingsOverrides(projectSettingsPath) : Object.freeze({});
+  const projectHas = (key: keyof WorkflowSettingsOverrides): boolean => Object.prototype.hasOwnProperty.call(project, key);
+  const sourceFor = (key: "skills" | "extensions" | "tools"): string => projectHas(key) ? projectSettingsPath : globalSettingsPath;
+  const globalSelectors = selectorsFromSettings(global);
+  const projectSelectors = selectorsFromSettings(project);
+  const effectiveSelectors = selectorSet({
+    skills: [...(globalSelectors.skills ?? []), ...(projectSelectors.skills ?? [])],
+    extensions: [...(globalSelectors.extensions ?? []), ...(projectSelectors.extensions ?? [])],
+    ...(globalSelectors.tools === undefined && projectSelectors.tools === undefined ? {} : { tools: [...(globalSelectors.tools ?? []), ...(projectSelectors.tools ?? [])] }),
+  });
+  const hasExtensionSelectors = global.extensions !== undefined || project.extensions !== undefined;
+  const extensionSettings = projectHas("extensionSettings") ? project.extensionSettings : global.extensionSettings;
+  const sources: WorkflowSettingsSources = {
+    concurrency: projectHas("concurrency") ? projectSettingsPath : globalSettingsPath,
+    modelAliases: projectHas("modelAliases") ? projectSettingsPath : globalSettingsPath,
+    skills: sourceFor("skills"), extensions: sourceFor("extensions"), tools: sourceFor("tools"),
+    ...(extensionSettings === undefined ? {} : { extensionSettings: projectHas("extensionSettings") ? projectSettingsPath : globalSettingsPath }),
+    ...(project.retention === undefined && global.retention === undefined ? {} : { retention: project.retention === undefined ? globalSettingsPath : projectSettingsPath }),
+    ...(projectHas("worktreePostCreateCommand") || global.worktreePostCreateCommand !== undefined ? { worktreePostCreateCommand: projectHas("worktreePostCreateCommand") ? projectSettingsPath : globalSettingsPath } : {}),
+  };
+  const effective = Object.freeze({
+    concurrency: project.concurrency ?? global.concurrency,
+    backgroundWidget: global.backgroundWidget ?? true,
+    ...(projectHas("modelAliases") ? { modelAliases: project.modelAliases } : global.modelAliases === undefined ? {} : { modelAliases: global.modelAliases }),
+    ...(effectiveSelectors.skills.length ? { skills: effectiveSelectors.skills } : global.skills !== undefined || project.skills !== undefined ? { skills: effectiveSelectors.skills } : {}),
+    ...(hasExtensionSelectors ? { extensions: effectiveSelectors.extensions } : {}),
+    ...(extensionSettings === undefined ? {} : { extensionSettings }),
+    ...(effectiveSelectors.tools?.length ? { tools: effectiveSelectors.tools } : global.tools !== undefined || project.tools !== undefined ? { tools: effectiveSelectors.tools } : {}),
+    ...((project.retention ?? global.retention) === undefined ? {} : { retention: project.retention ?? global.retention }),
+    ...(projectHas("worktreePostCreateCommand") ? { worktreePostCreateCommand: project.worktreePostCreateCommand } : global.worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand: global.worktreePostCreateCommand }),
+  });
+  return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, sources };
+}
+export function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void {
+  for (const name of names) {
+    try {
+      const target = modelCapability(name, aliases, knownModels, settingsPath);
+      if (!availableModels.has(target)) unknownModel(name, target, settingsPath);
+    } catch (error) { throw annotateModelAliasError(error, name); }
+  }
+}
+export function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath = workflowSettingsPath()): AgentResourcePolicy {
+  const resolved = resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath);
+  const global = selectorSet(selectorsFromSettings(resolved.global));
+  const project = selectorSet(selectorsFromSettings(resolved.project));
+  const effective = selectorSet(selectorsFromSettings(resolved.effective));
+  return { globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [], unmatchedTools: [], selectorSources: { global: selectorsFromSettings(resolved.global), project: selectorsFromSettings(resolved.project) } };
+}
+export function saveModelAliases(path = workflowSettingsPath(), aliases: Readonly<Record<string, string>> = {}): void {
+  const normalized = validateModelAliases(aliases, path);
+  let parsed: unknown = {};
+  try {
+    loadSettings(path);
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!isNodeError(error, "ENOENT")) throw error;
+  }
+  if (!object(parsed)) fail("INVALID_SETTINGS", `Workflow settings at ${path} must be an object`);
+  mkdirSync(dirname(path), { recursive: true });
+  atomicWriteFile(path, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, true);
+}
+

package/src/trajectory.ts

@@ -3,20 +3,30 @@ import { open, readFile, readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createReadToolDefinition, createWriteToolDefinition, DefaultPackageManager, getAgentDir, SettingsManager, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
-import { listRunIds, RunStore, type AwaitingCheckpoint, type EffectiveSystemPrompt, type PersistedRun } from "./persistence.js";
+import { listRunIds, RunStore, type AwaitingCheckpoint, type CompletedOperation, type EffectiveSystemPrompt, type PersistedRun } from "./persistence.js";
 import { navigatorAttentionSortByState } from "./host-view.js";
-import type { AgentAttemptSummary, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference } from "./types.js";
+import type { AgentAttemptSummary, AgentRecord, JsonValue, LaunchSnapshot, WorkflowAgentSessionReference, WorkflowErrorCode, WorkflowScriptCall } from "./types.js";
 import { normalizeSubagentRunRequest, type SubagentProgress, type SubagentRunRequest, type SubagentStatus } from "../subagents/src/contracts.js";
 import { statusValue, subagentErrorValue } from "../subagents/src/decode.js";
 import { isNodeError, jsonValue, object, resourcePatternHasMagic, selectResourcesByLayers } from "./utils.js";
 import type { TrajectoryAction, TrajectoryTarget } from "./trajectory-contracts.js";
 import { canonicalPath, sameFilesystemPath } from "./paths.js";
+import { TOOL_TIMING_ENTRY_TYPE } from "./tool-timing.js";
 
 export const TRAJECTORY_MAX_TRANSCRIPT_BYTES = 2 * 1024 * 1024;
 const TRAJECTORY_MAX_NON_TIMING_ENTRIES = 400;
 
+export type TrajectoryAgentOutput =
+  | { readonly status: "available"; readonly value: JsonValue; readonly bytes: number }
+  | { readonly status: "pending" }
+  | { readonly status: "failed" | "cancelled"; readonly code: string; readonly message: string }
+  | { readonly status: "truncated"; readonly kind: "result" | "failure"; readonly bytes: number; readonly path?: string }
+  | { readonly status: "unavailable" };
+export type TrajectoryAgent = AgentRecord & { readonly output: TrajectoryAgentOutput };
+export type TrajectoryScriptCall = WorkflowScriptCall & { readonly output: TrajectoryAgentOutput | { readonly status: "completed" } | { readonly status: "failed" | "cancelled"; readonly code: WorkflowErrorCode } };
+export type TrajectoryRunRecord = Omit<PersistedRun, "agents" | "scriptCalls"> & { readonly agents: readonly TrajectoryAgent[]; readonly scriptCalls?: readonly TrajectoryScriptCall[] };
 export type TrajectoryRun = {
-  run: PersistedRun;
+  run: TrajectoryRunRecord;
   snapshot: Readonly<LaunchSnapshot>;
   awaiting: readonly AwaitingCheckpoint[];
   createdAt?: string;
@@ -26,6 +36,31 @@ export type TrajectoryTranscriptStatus = "available" | "empty" | "missing" | "fa
 export type TrajectoryTranscriptMetadata = { readonly revision: number; readonly status: TrajectoryTranscriptStatus; readonly bytes?: number; readonly timing?: readonly unknown[]; };
 export type TrajectoryRunMetadata = Omit<TrajectoryRun, "transcripts"> & { transcripts: Readonly<Record<string, TrajectoryTranscriptMetadata>> };
 export type TrajectorySubagentArtifact = { readonly truncated: true; readonly path: string; readonly bytes: number };
+type SubagentOutputOptions = {
+  readonly state: SubagentStatus["state"];
+  readonly statusError: SubagentStatus["error"];
+  readonly attempt: AgentAttemptSummary | undefined;
+  readonly result: JsonValue | undefined;
+  readonly resultTruncated: boolean;
+  readonly resultPath: string;
+  readonly resultBytes: number | undefined;
+  readonly failure: { readonly code: string; readonly message: string } | undefined;
+  readonly failureTruncated: boolean;
+  readonly failurePath: string;
+  readonly failureBytes: number | undefined;
+};
+function subagentOutput(options: SubagentOutputOptions): TrajectoryAgentOutput {
+  if (options.resultTruncated) return { status: "truncated", kind: "result", path: options.resultPath, bytes: options.resultBytes ?? 0 };
+  if (options.result !== undefined) return { status: "available", value: options.result, bytes: serializedJsonBytes(options.result) };
+  if (options.failureTruncated) return { status: "truncated", kind: "failure", path: options.failurePath, bytes: options.failureBytes ?? 0 };
+  if (options.failure !== undefined) return { status: "failed", code: options.failure.code, message: options.failure.message };
+  if (options.state === "failed" || options.state === "stopped") {
+    const error = options.statusError ?? options.attempt?.error;
+    return { status: options.state === "stopped" ? "cancelled" : "failed", code: error?.code ?? (options.state === "stopped" ? "CANCELLED" : "AGENT_FAILED"), message: error?.message ?? `Subagent ${options.state}` };
+  }
+  if (options.state === "completed") return { status: "unavailable" };
+  return { status: "pending" };
+}
 export type TrajectorySubagent = {
   id: string;
   sessionId: string;
@@ -47,6 +82,7 @@ export type TrajectorySubagent = {
   attempt?: AgentAttemptSummary;
   result?: JsonValue | TrajectorySubagentArtifact;
   failure?: { readonly code: string; readonly message: string } | TrajectorySubagentArtifact;
+  output: TrajectoryAgentOutput;
   transcript: readonly unknown[];
 };
 export type TrajectorySubagentMetadata = Omit<TrajectorySubagent, "transcript"> & { transcript: TrajectoryTranscriptMetadata };
@@ -69,7 +105,6 @@ export type TrajectoryPublisherInput = {
   cwd: string;
   sessionId: string;
   port?: number;
-  themes: boolean;
   loadRuns: TrajectoryRunLoader;
   loadSubagents: TrajectorySubagentLoader;
   loadMetadata: TrajectoryPublisherMetadataLoader;
@@ -91,7 +126,7 @@ function transcriptToolCallId(value: unknown): string | undefined {
   for (const part of message.content) if (object(part) && typeof part.id === "string") return part.id;
   return undefined;
 }
-function isTimingTranscriptEntry(value: unknown): boolean { return object(value) && value.type === "custom" && value.customType === "pi-workflows:tool-timing"; }
+export function isTimingTranscriptEntry(value: unknown): boolean { return object(value) && value.type === "custom" && value.customType === TOOL_TIMING_ENTRY_TYPE; }
 function timingToolCallId(value: unknown): string | undefined {
   if (!object(value) || !isTimingTranscriptEntry(value) || !object(value.data)) return undefined;
   return typeof value.data.toolCallId === "string" ? value.data.toolCallId : undefined;
@@ -210,7 +245,8 @@ export function withPiToolDescriptionsForTools(tools: readonly string[], cwd: st
 function canonicalExtensionSelector(selector: string, base: string): string {
   const negated = selector.startsWith("!");
   const body = negated ? selector.slice(1) : selector;
-  if (body === "*" || body === "**" || body.startsWith("**/")) return selector;
+  // Built-in extensions are named `builtin:<name>`, not by a path.
+  if (body === "*" || body === "**" || body.startsWith("**/") || body.startsWith("builtin:")) return selector;
   const resolved = resolve(base, body);
   if (resourcePatternHasMagic(body)) return `${negated ? "!" : ""}${resolved}`;
   return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
@@ -277,11 +313,62 @@ function withoutAgentActivities(run: PersistedRun): PersistedRun {
   return agents.every((agent, index) => agent === run.agents[index]) ? run : { ...run, agents };
 }
 
+function serializedJsonBytes(value: JsonValue): number {
+  const serialized = JSON.stringify(value);
+  return Buffer.byteLength(serialized, "utf8");
+}
+function failedAgentOutput(agent: PersistedRun["agents"][number]): TrajectoryAgentOutput {
+  const error = [...(agent.attemptDetails ?? [])].reverse().find((attempt) => attempt.error)?.error;
+  const status = agent.state === "cancelled" ? "cancelled" : "failed";
+  return { status, code: error?.code ?? (status === "cancelled" ? "CANCELLED" : "AGENT_FAILED"), message: error?.message ?? `Agent ${agent.state}` };
+}
+function operationOutput(operation: CompletedOperation): TrajectoryAgentOutput {
+  const bytes = serializedJsonBytes(operation.value);
+  return bytes > DEFAULT_MAX_BYTES ? { status: "truncated", kind: "result", bytes } : { status: "available", value: operation.value, bytes };
+}
+function outputForCall(call: WorkflowScriptCall, operation: CompletedOperation | undefined): TrajectoryScriptCall["output"] {
+  if (operation !== undefined) return call.kind === "tool" ? { status: "completed" } : operationOutput(operation);
+  if (call.error) return { status: call.error.code === "CANCELLED" ? "cancelled" : "failed", code: call.error.code, ...(call.kind === "shell" ? { message: call.error.message ?? "Shell failed" } : {}) };
+  return call.finishedAt === undefined ? { status: "pending" } : { status: "unavailable" };
+}
+function outputForAgent(agent: PersistedRun["agents"][number], operation: CompletedOperation | undefined): TrajectoryAgentOutput {
+  if (operation !== undefined) return operationOutput(operation);
+  if (agent.state === "failed" || agent.state === "cancelled") return failedAgentOutput(agent);
+  if (agent.state === "completed") return { status: "unavailable" };
+  return { status: "pending" };
+}
+export function applyTrajectoryAgentOutputs(run: PersistedRun, operations: readonly CompletedOperation[]): TrajectoryRunRecord {
+  const byPath = new Map(operations.map((operation) => [operation.path, operation]));
+  const agents: readonly TrajectoryAgent[] = run.agents.map((agent) => ({ ...agent, output: outputForAgent(agent, agent.resultPath === undefined ? undefined : byPath.get(agent.resultPath)) }));
+  const scriptCalls = run.scriptCalls?.map((call): TrajectoryScriptCall => {
+    const recorded = { ...call, output: outputForCall(call, byPath.get(call.path)) };
+    if (call.kind === "tool") {
+      delete recorded.input;
+      delete recorded.inputBytes;
+      if (call.error) recorded.error = { code: call.error.code };
+    }
+    return recorded;
+  });
+  const rest: Omit<PersistedRun, "scriptCalls"> = run;
+  return { ...rest, agents, ...(scriptCalls === undefined ? {} : { scriptCalls }) };
+}
+function overlayTrajectoryRun(run: TrajectoryRunRecord, overlay: (run: PersistedRun) => PersistedRun): TrajectoryRunRecord {
+  const overlaid: Omit<PersistedRun, "scriptCalls"> = overlay(run);
+  const outputs = new Map(run.agents.map((agent) => [agent.id, agent.output]));
+  const agents: readonly TrajectoryAgent[] = overlaid.agents.map((agent) => {
+    const previous = outputs.get(agent.id);
+    const output = previous?.status === "available" || previous?.status === "truncated" ? previous : outputForAgent(agent, undefined);
+    return { ...agent, output };
+  });
+  return { ...overlaid, agents, ...(run.scriptCalls === undefined ? {} : { scriptCalls: run.scriptCalls }) };
+}
 async function loadTrajectoryRun(store: RunStore, includeTranscripts = true): Promise<TrajectoryRun> {
   const value = await store.load();
   const summary = await store.loadSummary().catch(() => undefined);
   const prompts = await store.systemPrompts().catch(() => []);
-  const run = withoutAgentActivities(await withResolvedResources(withPiToolDescriptions(applySystemPrompts(value.run, prompts)), store.cwd));
+  const prepared = withoutAgentActivities(await withResolvedResources(withPiToolDescriptions(applySystemPrompts(value.run, prompts)), store.cwd));
+  const operations = await store.replayableOperations().catch(() => []);
+  const run = applyTrajectoryAgentOutputs(prepared, operations);
   return { run, snapshot: value.snapshot, awaiting: await store.awaitingCheckpoints(), ...(summary?.createdAt === undefined ? {} : { createdAt: summary.createdAt }), transcripts: includeTranscripts ? await runTranscripts(run) : {} };
 }
 
@@ -290,7 +377,7 @@ export async function loadTrajectoryRuns(cwd: string, sessionId: string, home =
   for (const runId of await listRunIds(cwd, sessionId, home, false)) {
     try {
       const value = await loadTrajectoryRun(new RunStore(cwd, sessionId, runId, home));
-      loaded.push(overlay ? { ...value, run: overlay(value.run) } : value);
+      loaded.push(overlay ? { ...value, run: overlayTrajectoryRun(value.run, overlay) } : value);
     } catch { /* Ignore corrupt or concurrently removed runs. */ }
   }
   return loaded;
@@ -323,7 +410,7 @@ function createCachedRunLoader<Value extends { run: PersistedRun }, Signature>(c
           entry = { value, stateMtimeMs: (await fileMtime(join(store.directory, "state.json"))) ?? 0, journalMtimeMs: (await fileMtime(join(store.directory, "journal.json"))) ?? 0, transcripts };
           cache.set(runId, entry);
         }
-        loaded.push(overlay ? { ...entry.value, run: overlay(entry.value.run) } : entry.value);
+        loaded.push(overlay ? { ...entry.value, run: overlayTrajectoryRun(entry.value.run as TrajectoryRunRecord, overlay) } : entry.value);
       } catch { cache.delete(runId); /* Ignore corrupt or concurrently removed runs. */ }
     }
     return loaded;
@@ -490,6 +577,7 @@ async function loadTrajectorySubagent(directory: string, cwd: string, sessionId:
       ...(attempt === undefined ? {} : { attempt }),
       ...(result === undefined ? {} : { result }),
       ...(failure === undefined ? {} : { failure }),
+      output: subagentOutput({ state: status.state, statusError: status.error, attempt, result: resultValue === undefined ? undefined : boundedSubagentJson(resultValue), resultTruncated, resultPath, resultBytes, failure: failureValue === undefined ? undefined : subagentErrorValue(failureValue), failureTruncated, failurePath, failureBytes }),
     };
   } catch { return undefined; }
 }

package/src/types.ts

@@ -29,7 +29,7 @@ export const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
 export const ERROR_CODES = [
   "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
   "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID",
-  "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+  "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
   ] as const;
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -90,15 +90,16 @@ export interface WorkflowModelAliasResolverContext { cwd: string; projectTrusted
 export interface WorkflowModelAlias { resolve: (context: Readonly<WorkflowModelAliasResolverContext>) => string | Promise<string> }
 export interface WorkflowMetadata { name: string; description?: string }
 export interface HerdrExtensionSettings { enableFullyInspectableMode?: boolean }
-export interface TrajectoryExtensionSettings { port?: number; themes?: boolean }
+export interface TrajectoryExtensionSettings { port?: number }
 export interface WorkflowExtensionSettings { readonly [namespace: string]: JsonValue; readonly herdr?: Readonly<HerdrExtensionSettings>; readonly trajectory?: Readonly<TrajectoryExtensionSettings> }
 export type WorkflowExtensionSettingsSource = "global" | "project" | "role" | "effective";
 export interface WorkflowExtensionSettingsValidatorContext { source: WorkflowExtensionSettingsSource; cwd: string; projectTrusted: boolean; settingsPath?: string; role?: string }
 export type WorkflowExtensionSettingsValidator = (settings: Readonly<WorkflowExtensionSettings>, context: Readonly<WorkflowExtensionSettingsValidatorContext>) => void;
 export interface WorkflowSessionStartEvent { type: "session_start"; reason: "startup" | "reload" | "new" | "resume" | "fork"; previousSessionFile?: string; settings: Readonly<WorkflowExtensionSettings> }
 export interface WorkflowRetentionSettings { olderThanDays?: number; maxTerminalRuns?: number }
-export interface WorkflowSettings { concurrency: number; backgroundWidget?: boolean; modelAliases?: Readonly<Record<string, string>>; skills?: readonly string[]; extensions?: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
-export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget">>;
+export type CodemodeToolsSetting = "all" | "read-only" | "none";
+export interface WorkflowSettings { concurrency: number; backgroundWidget?: boolean; codemodeTools?: CodemodeToolsSetting; modelAliases?: Readonly<Record<string, string>>; skills?: readonly string[]; extensions?: readonly string[]; extensionSettings?: Readonly<WorkflowExtensionSettings>; tools?: readonly string[]; retention?: Readonly<WorkflowRetentionSettings>; worktreePostCreateCommand?: readonly string[] }
+export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget" | "codemodeTools">>;
 export interface WorkflowSettingsSources { concurrency: string; modelAliases: string; skills?: string; extensions?: string; tools?: string; extensionSettings?: string; retention?: string; worktreePostCreateCommand?: string }
 export interface WorkflowSettingsResolution { globalSettingsPath: string; projectSettingsPath: string; projectTrusted: boolean; global: Readonly<WorkflowSettings>; project: Readonly<WorkflowSettingsOverrides>; effective: Readonly<WorkflowSettings>; sources: Readonly<WorkflowSettingsSources> }
 export interface AgentResourceSelectors { skills?: readonly string[]; extensions?: readonly string[]; tools?: readonly string[] }
@@ -178,6 +179,8 @@ export interface WorkflowRunEvent { type: string; message: string; timestamp?: n
 export interface WorkflowRetryProvenance { sourceRunId: string; lineageRootRunId: string; completedPaths: readonly string[]; incompletePaths: readonly string[]; namedWorktrees: readonly string[] }
 export interface WorkflowPhaseRecord { phase: string; afterAgent: number }
 export interface WorkflowPhaseShellActivity { phaseIndex: number; active: number; startedAt: number }
+/** A script call recorded for inspection. Tool payloads stay in the replay journal, not this record. Oversized shell inputs are JSON prefixes, with `inputBytes` their full size. */
+export interface WorkflowScriptCall { kind: "shell" | "tool"; name: string; path: string; input?: JsonValue; inputBytes?: number; phase?: string; startedAt: number; finishedAt?: number; error?: { code: WorkflowErrorCode; message?: string } }
 export interface RunRecord {
   id: string;
   workflowName: string;
@@ -194,6 +197,8 @@ export interface RunRecord {
   activeShells?: number;
   activeShellStartedAt?: number;
   activeShellsByPhase?: readonly WorkflowPhaseShellActivity[];
+  activeTools?: readonly { name: string; startedAt: number }[]; // Script tool calls in flight: a live overlay for rendering, never persisted.
+  scriptCalls?: readonly WorkflowScriptCall[];
   error?: WorkflowErrorShape;
   failedAt?: string;
   budget?: WorkflowBudget;
@@ -356,7 +361,9 @@ export interface FunctionIdentity { path: string; structuralPath: readonly strin
 export type AgentContinuity = "fresh" | "continued";
 export interface AgentIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; parentBreadcrumb?: string; worktreeOwner?: string; handle?: string; turn?: number }
 export interface ShellIdentity { structuralPath: readonly string[]; callSite: string; occurrence: number; worktreeOwner?: string }
-export interface WorkflowBridge { agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>; shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>; checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>; function?: (name: string, input: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: FunctionIdentity) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; phase?: (name: string) => void | Promise<void>; log?: (message: string) => void | Promise<void> }
+/** A script `tools.<id>(args)` call: the n-th call of that tool within one structural scope. */
+export interface ToolIdentity { structuralPath: readonly string[]; occurrence: number }
+export interface WorkflowBridge { agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>; shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>; checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>; function?: (name: string, input: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: FunctionIdentity) => Promise<JsonValue>; worktree?: (owner: string, signal: AbortSignal) => Promise<Readonly<WorkflowWorktreeReference>>; functions?: Readonly<Record<string, { name: string }>>; phase?: (name: string) => void | Promise<void>; log?: (message: string) => void | Promise<void>; tool?: (identifier: string, args: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: ToolIdentity) => Promise<JsonValue> }
 export interface WorkflowExecution { result: Promise<JsonValue>; cancel: () => void }
 export interface StaticWorkflowScope { kind: "parallel" | "pipeline"; name: string | null; key: string | null }
 export type StaticWorkflowExecution = "parallel" | "sequential";

package/src/utils.ts

@@ -1,4 +1,5 @@
-import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
+import { createHash } from "node:crypto";
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
 import { Minimatch } from "minimatch";
 export class SerialLane {
   #tail: Promise<void> = Promise.resolve();
@@ -18,6 +19,15 @@ export function sanitizeDisplayText(value: string): string { return value.replac
 export { object as isObject };
 function isStringKey(key: PropertyKey): key is string { return typeof key === "string"; }
 function stringKeyValue(value: object, key: string): unknown { return object(value) ? value[key] : undefined; }
+function sortedJson(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) return value.map(sortedJson);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedJson(value[key] as JsonValue)]));
+}
+/** A short digest of a JSON value that ignores object key order. */
+export function jsonDigest(value: JsonValue): string {
+  return createHash("sha256").update(JSON.stringify(sortedJson(value))).digest("hex").slice(0, 16);
+}
 export function jsonValue(value: unknown, seen = new Set<object>()): value is JsonValue {
   if (value === null || typeof value === "boolean" || typeof value === "string") return true;
   if (typeof value === "number") return Number.isFinite(value);
@@ -153,6 +163,24 @@ export function resolveModelReference(value: string, aliases: Readonly<Record<st
   };
   return resolveReference(value, []);
 }
+type ToolSource = { getActiveTools(): string[]; getAllTools?(): readonly { name: string; exposure?: string }[] };
+/**
+ * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
+ * only codemode scripts call or tool_search loads, such as MCP tools with the default exposure.
+ * Agent sessions allow tools by name, so leaving these out would make them unreachable there.
+ */
+export function reachableTools(pi: ToolSource): string[] {
+  const undeclared = pi.getAllTools?.().filter(({ exposure }) => exposure === "codemode" || exposure === "deferred").map(({ name }) => name) ?? [];
+  return [...new Set([...pi.getActiveTools(), ...undeclared])];
+}
+/** Provider of the virtual models that expose workflow model aliases in `/model`. */
+export const VIRTUAL_MODEL_PROVIDER = "workflow";
+/** Child sessions do not load the workflow extension, so they receive the alias target instead of its virtual model. */
+export function physicalModel(spec: ModelSpec, aliases: Readonly<Record<string, string>> = {}, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec {
+  if (spec.provider !== VIRTUAL_MODEL_PROVIDER || !modelAliasName(spec.model, aliases)) return spec;
+  const target = resolveModelReference(spec.model, aliases, knownModels, settingsPath);
+  return spec.thinking === undefined ? target : { ...target, thinking: spec.thinking };
+}
 export function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string {
   const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
   return `${parsed.provider}/${parsed.model}`;
@@ -190,3 +218,10 @@ export function resourcePatternHasMagic(pattern: string): boolean { return /[*?\
 export function unmatchedResourcePatterns(patterns: readonly string[], resources: readonly string[]): string[] { return patterns.filter((pattern) => !resources.some((resource) => resourcePatternMatches(resource, pattern))); }
 export function createLaunchSnapshot(input: Omit<import("./types.js").LaunchSnapshot, "identityVersion"> & { identityVersion?: number }): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone({ ...input, identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION })); }
 export function loadLaunchSnapshot(input: import("./types.js").LaunchSnapshot): Readonly<import("./types.js").LaunchSnapshot> { return deepFreeze(structuredClone(input)); }
+
+export function validateSchema(schema: unknown, at = "schema"): asserts schema is JsonSchema {
+  if (!object(schema) || Object.getPrototypeOf(schema) !== Object.prototype || !jsonValue(schema)) fail("INVALID_SCHEMA", `${at} must be a plain JSON-compatible Schema object`);
+  if (typeof schema.type !== "string" && !Array.isArray(schema.type) && schema.$ref === undefined && schema.anyOf === undefined && schema.oneOf === undefined && schema.allOf === undefined && schema.const === undefined && schema.enum === undefined) fail("INVALID_SCHEMA", `${at} has no JSON Schema shape`);
+  if (schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some((key) => typeof key !== "string"))) fail("INVALID_SCHEMA", `${at}.required must be an array of strings`);
+  if (schema.properties !== undefined && !object(schema.properties)) fail("INVALID_SCHEMA", `${at}.properties must be an object`);
+}