@marcoscale98/pi-extensible-workflows 5.17.0-fork.1 → 6.2.1-fork.1

package/src/index.ts

@@ -3,10 +3,9 @@ export * from "./package-identity.js";
 export { createToolTimingExtension, TOOL_TIMING_ENTRY_TYPE } from "./tool-timing.js";
 export type { ToolTimingEntry } from "./tool-timing.js";
 export * from "./utils.js";
-export { canonicalPath, sameFilesystemPath } from "./paths.js";
+export { canonicalPath, extensionIdentity, sameFilesystemPath } from "./paths.js";
 export * from "./budget.js";
 export * from "./validation.js";
-export * from "./roles.js";
 export * from "./registry.js";
 export * from "./execution.js";
 export * from "./host.js";

package/src/paths.ts

@@ -1,24 +1,33 @@
 import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, join, resolve } from "node:path";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { WorkflowError } from "./types.js";
 import { isNodeError } from "./utils.js";
 
 export function safePart(value: string): string { return value.replace(/[^a-zA-Z0-9._-]/g, "_"); }
 
+export function canonicalPath(path: string): string { const absolute = resolve(path); try { return realpathSync(absolute); } catch { return absolute; } }
+export function extensionIdentity(path: string): string { return path.startsWith("builtin:") ? path : canonicalPath(path.startsWith("file:") ? fileURLToPath(path) : path); }
+export function sameFilesystemPath(left: string, right: string): boolean { return canonicalPath(left) === canonicalPath(right); }
 /**
- * Resolves a path to its filesystem spelling, including symlink and platform aliases.
- * A missing path safely falls back to its absolute lexical spelling rather than
- * guessing at the identity of an object that does not exist.
+ * The path Pi's resource loader uses for a resource path an extension returns: trimmed, `~`, `~/` and `file://` expanded,
+ * relative to the loader cwd. Synthetic `<...>` and `builtin:` paths stay as they are.
  */
-export function canonicalPath(path: string): string {
-  const absolute = resolve(path);
-  try { return realpathSync(absolute); } catch { return absolute; }
+export function piResourcePath(path: string, cwd: string): string {
+  //NOTE: Pi also rewrites Windows shell paths and `~\` on win32; those forms are not mirrored here and fail closed.
+  if (path.startsWith("<") || path.startsWith("builtin:")) return path;
+  const trimmed = path.trim();
+  const expanded = trimmed === "~" ? homedir() : trimmed.startsWith("~/") ? join(homedir(), trimmed.slice(2)) : /^file:\/\//.test(trimmed) ? fileURLToPath(trimmed) : trimmed;
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+}
+/** Pi attributes a loaded resource to a contributed path by lexical containment of resolved paths, without following symlinks. */
+export function piResourceContains(root: string, path: string): boolean {
+  const relativePath = relative(resolve(root), resolve(path));
+  return relativePath === "" || (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));
 }
-
-export function sameFilesystemPath(left: string, right: string): boolean { return canonicalPath(left) === canonicalPath(right); }
 export function workflowProjectSettingsPath(cwd: string): string { return join(cwd, ".pi", "pi-extensible-workflows", "settings.json"); }
 
 export function projectStorageKey(cwd: string): string {

package/src/persistence.ts

@@ -4,6 +4,7 @@ export {
 } from "./paths.js";
 export { hasLiveSessionLease, SessionLease, acquireSessionLease, listRunIds, processAlive } from "./session-lease.js";
 export { RunStore } from "./store.js";
+export { decodePreparedAgentConfiguration } from "./decoders.js";
 export {
   EffectiveSystemPrompt, PersistedRun, RunSummaryAgent, RunSummaryArtifacts, RunSummary,
   CompletedOperation, AwaitingCheckpoint, PendingWorkflowDecision, PersistedOwnershipNode,

package/src/pi-runtime-runner.ts

@@ -172,7 +172,7 @@ export class PiRuntimeAgentRunner implements RuntimeAgentRunner {
     let structuredResult: RuntimeJsonValue | undefined;
     const resultTool = prepared.resultTool;
     if (!resultTool) throw new WorkflowError("INTERNAL_ERROR", "Workflow agent session is missing its workflow_result tool");
-    const preparedForSession = preparedForRuntimeRequest(prepared, request.customTools, request.signal, (value) => { structuredResult = value; }, resultTool);
+    const preparedForSession = Object.freeze({ ...preparedForRuntimeRequest(prepared, request.customTools, request.signal, (value) => { structuredResult = value; }, resultTool), ...(request.turnControl ? { turnControl: request.turnControl } : {}) });
     const callbacks = this.#options.callbacks;
     const handoff = this.#options.handoff;
     let adapter: PiRuntimeSessionAdapter | undefined;
@@ -364,6 +364,8 @@ export class PiRuntimeAgentRunner implements RuntimeAgentRunner {
       throwIfProgressFailed();
       beginTurn(false);
       throwIfTurnPolicyFailed();
+      // NOTE: A transport that already sent turnControl (Herdr, in its pane launch prompt) reports turnControlDelivered; steering its suspended local session would fail.
+      if (request.turnControl && !session.turnControlDelivered) await activeSession.steer(request.turnControl);
       await promptAndRecover(request.task, true);
       completeTurn(hasResult() || !hasToolCall(lastAssistant), false, true);
       if (turnPolicyFailure) throw turnPolicyFailure;

package/src/registry.ts

@@ -1,48 +1,16 @@
-import { readFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Value } from "typebox/value";
-import type { AgentAttemptAction, JsonSchema, JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowExtension, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowFunction, WorkflowFunctionContext, WorkflowFunctionSource, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext, WorkflowRoleDirectoryRegistration } from "./types.js";
+import type { AgentAttemptAction, JsonSchema, JsonValue, RegisteredAgentSetupHook, RegisteredAgentPreparationHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowExtension, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowFunction, WorkflowFunctionContext, WorkflowFunctionSource, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext } from "./types.js";
 import type { SubagentRunRequest, SubagentStatus } from "../subagents/src/contracts.js";
 import { byPriorityThenName, deepFreeze, errorCode, errorText, fail, jsonValue, MODEL_ALIAS_NAME, object, validWorkflowExtensionNamespace } from "./utils.js";
 import { loadSettings, resolveWorkflowSettings } from "./settings.js";
 import { validateSchema } from "./utils.js";
-import { canonicalPath } from "./paths.js";
-import { isCorePackageName } from "./package-identity.js";
 
-const RESERVED_GLOBALS = new Set(["agent", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+const RESERVED_GLOBALS = new Set(["agent", "shell", "tools", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 export type SubagentStatusObserver = (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void;
 
-function normalizeRoleDirectory(value: unknown): string {
-  try {
-    if (value instanceof URL) {
-      if (value.protocol !== "file:") fail("INVALID_METADATA", "Workflow role directories require file URLs or absolute filesystem paths");
-      return fileURLToPath(value);
-    }
-    if (typeof value === "string") {
-      if (value.startsWith("file:")) return fileURLToPath(value);
-      if (isAbsolute(value)) return value;
-    }
-  } catch (error) {
-    fail("INVALID_METADATA", `Invalid workflow role directory: ${errorText(error)}`);
-  }
-  fail("INVALID_METADATA", "Workflow role directories require file URLs or absolute filesystem paths");
-}
-function isBuiltinRoleDirectory(path: string): boolean {
-  const canonical = canonicalPath(path);
-  const starterDirectory = dirname(canonical);
-  if (basename(canonical) !== "roles" || basename(starterDirectory) !== "starter") return false;
-  const distributionDirectory = dirname(starterDirectory);
-  const packageRoot = basename(distributionDirectory) === "dist" ? dirname(distributionDirectory) : distributionDirectory;
-  try {
-    const metadata: unknown = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-    return object(metadata) && isCorePackageName(metadata.name);
-  } catch { return false; }
-}
-
 function catalogSchema(schema: unknown, at: string): JsonSchema {
   validateSchema(schema, at);
   return structuredClone(schema);
@@ -51,9 +19,9 @@ export class WorkflowRegistry {
   readonly #extensions = new Set<Readonly<WorkflowExtension>>();
   readonly #functionSources = new Map<string, WorkflowFunctionSource>();
   readonly #globals = new Map<string, string>();
+  readonly #preparationHooks = new Map<string, RegisteredAgentPreparationHook>();
   readonly #hooks = new Map<string, RegisteredAgentSetupHook>();
   readonly #agentAttemptActions = new Map<string, AgentAttemptAction>();
-  readonly #roleDirectories = new Map<string, WorkflowRoleDirectoryRegistration>();
   readonly #modelAliases = new Map<string, { name: string; version: string; headline: string; resolve: WorkflowModelAlias["resolve"] }>();
   readonly #settingsValidators = new Set<{ headline: string; validate: NonNullable<WorkflowExtension["validateSettings"]> }>();
   #frozen = false;
@@ -67,9 +35,10 @@ export class WorkflowRegistry {
   register(extension: WorkflowExtension): void {
     if (this.#frozen) fail("REGISTRY_FROZEN", "Workflow extension registration is closed after session_start");
     if (object(extension) && Object.prototype.hasOwnProperty.call(extension, "workflows")) fail("INVALID_METADATA", "Separate registered workflow definitions were removed; register a function with input and output schemas instead");
-    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "source", "dependencies", "validateSettings", "functions", "modelAliases", "agentSetupHooks", "agentAttemptActions", "roleDirectories"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version and non-empty headline");
+    if (!object(extension) || Object.keys(extension).some((key) => !["version", "headline", "description", "source", "dependencies", "validateSettings", "functions", "modelAliases", "agentPreparationHooks", "agentSetupHooks", "agentAttemptActions"].includes(key)) || typeof extension.version !== "string" || !SEMVER.test(extension.version) || typeof extension.headline !== "string" || !extension.headline.trim()) fail("INVALID_METADATA", "Workflow extensions require a semantic version and non-empty headline");
     const functions = extension.functions ?? {};
     const modelAliases = extension.modelAliases ?? {};
+    const agentPreparationHooks = extension.agentPreparationHooks ?? {};
     const agentSetupHooks = extension.agentSetupHooks ?? {};
     const agentAttemptActions = extension.agentAttemptActions ?? {};
     const source = extension.source;
@@ -79,10 +48,7 @@ export class WorkflowRegistry {
     if (validateSettings !== undefined && typeof validateSettings !== "function") fail("INVALID_METADATA", "Workflow extension validateSettings must be a function");
     if (source !== undefined && (typeof source !== "string" || !source.trim())) fail("INVALID_METADATA", "Workflow extension source must be a non-empty module URL");
     if (dependencyValues !== undefined && (!Array.isArray(dependencyValues) || dependencyValues.some((dependency) => typeof dependency !== "string" || dependency.trim() !== dependency || !PACKAGE_NAME.test(dependency)) || new Set(dependencyValues).size !== dependencyValues.length)) fail("INVALID_METADATA", "Workflow extension dependencies must be unique, non-empty package names");
-    const roleDirectoryValues = extension.roleDirectories === undefined ? [] : extension.roleDirectories;
-    if (!Array.isArray(roleDirectoryValues)) fail("INVALID_METADATA", "Workflow extension roleDirectories must be an array");
-    const roleDirectories = [...new Set(Array.from(roleDirectoryValues, (value) => normalizeRoleDirectory(value)))];
-    if (!object(functions) || !object(modelAliases) || !object(agentSetupHooks) || !object(agentAttemptActions) || (Object.keys(functions).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentSetupHooks).length === 0 && Object.keys(agentAttemptActions).length === 0 && roleDirectories.length === 0 && validateSettings === undefined)) fail("INVALID_METADATA", "Workflow extensions require functions, model aliases, agent setup hooks, agent attempt actions, role directories, or a settings validator");
+    if (!object(functions) || !object(modelAliases) || !object(agentPreparationHooks) || !object(agentSetupHooks) || !object(agentAttemptActions) || (Object.keys(functions).length === 0 && Object.keys(modelAliases).length === 0 && Object.keys(agentPreparationHooks).length === 0 && Object.keys(agentSetupHooks).length === 0 && Object.keys(agentAttemptActions).length === 0 && validateSettings === undefined)) fail("INVALID_METADATA", "Workflow extensions require functions, model aliases, agent preparation hooks, agent setup hooks, agent attempt actions, or a settings validator");
     const names = Object.keys(functions);
     if (new Set(names).size !== names.length) fail("GLOBAL_COLLISION", "Global name collision inside extension");
     for (const name of names) {
@@ -101,6 +67,11 @@ export class WorkflowRegistry {
       if (!object(alias) || Object.keys(alias).some((key) => key !== "resolve") || typeof alias.resolve !== "function") fail("INVALID_METADATA", `Invalid model alias resolver: ${name}`);
       if (this.#modelAliases.has(name)) fail("DUPLICATE_NAME", `Model alias already registered: ${name}`);
     }
+    for (const [name, hook] of Object.entries(agentPreparationHooks)) {
+      if (!IDENTIFIER.test(name) || !object(hook) || Object.keys(hook).some((key) => !["priority", "optionsSchema", "prepare"].includes(key)) || typeof hook.prepare !== "function" || hook.priority !== undefined && (typeof hook.priority !== "number" || !Number.isFinite(hook.priority))) fail("INVALID_METADATA", `Invalid agent preparation hook: ${name}`);
+      if (this.#preparationHooks.has(name)) fail("DUPLICATE_NAME", `Agent preparation hook already registered: ${name}`);
+      if (hook.optionsSchema !== undefined) validateSchema(hook.optionsSchema, `${name} options schema`);
+    }
     for (const [name, hook] of Object.entries(agentSetupHooks)) {
       if (!IDENTIFIER.test(name) || !object(hook) || Object.keys(hook).some((key) => !["priority", "setup"].includes(key)) || typeof hook.setup !== "function" || hook.priority !== undefined && (typeof hook.priority !== "number" || !Number.isFinite(hook.priority))) fail("INVALID_METADATA", `Invalid agent setup hook: ${name}`);
       if (this.#hooks.has(name)) fail("DUPLICATE_NAME", `Agent setup hook already registered: ${name}`);
@@ -110,17 +81,22 @@ export class WorkflowRegistry {
       if ((action.visibleStandalone !== undefined) !== (action.runStandalone !== undefined)) fail("INVALID_METADATA", `Standalone agent attempt actions require visibleStandalone and runStandalone: ${name}`);
       if (this.#agentAttemptActions.has(name)) fail("DUPLICATE_NAME", `Agent attempt action already registered: ${name}`);
     }
-    const stored = deepFreeze({ ...extension, functions, modelAliases, agentSetupHooks, agentAttemptActions, ...(roleDirectories.length ? { roleDirectories } : {}) });
+    const stored = deepFreeze({ ...extension, functions, modelAliases, agentPreparationHooks, agentSetupHooks, agentAttemptActions });
     if (source !== undefined) for (const name of names) this.#functionSources.set(name, Object.freeze({ module: source, export: "default", dependencies: Object.freeze([...dependencies]) }));
     this.#extensions.add(stored);
-    for (const directory of roleDirectories) if (!this.#roleDirectories.has(directory)) this.#roleDirectories.set(directory, deepFreeze({ path: directory, extension: { version: extension.version, headline: extension.headline }, ...(isBuiltinRoleDirectory(directory) ? { builtin: true as const } : {}) }));
     for (const name of names) this.#globals.set(name, name);
     for (const [name, alias] of Object.entries(modelAliases)) this.#modelAliases.set(name, { name, version: extension.version, headline: extension.headline, resolve: alias.resolve });
+    for (const [name, hook] of Object.entries(agentPreparationHooks)) this.#preparationHooks.set(name, { name, priority: hook.priority ?? 10, prepare: hook.prepare, ...(hook.optionsSchema === undefined ? {} : { optionsSchema: structuredClone(hook.optionsSchema) }), ...(source === undefined ? {} : { source }) });
     for (const [name, hook] of Object.entries(agentSetupHooks)) this.#hooks.set(name, { name, priority: hook.priority ?? 10, setup: hook.setup });
     for (const [name, action] of Object.entries(agentAttemptActions)) this.#agentAttemptActions.set(name, action);
     if (validateSettings !== undefined) this.#settingsValidators.add({ headline: extension.headline, validate: validateSettings });
   }
 
+  /** Every registration's headline and declared module provenance, for hosts that must prove which extension made it. */
+  registrations(): ReadonlyArray<Readonly<{ headline: string; source?: string }>> {
+    return [...this.#extensions].map(({ headline, source }) => Object.freeze({ headline, ...(source === undefined ? {} : { source }) }));
+  }
+
   function(name: string): WorkflowFunction {
     if (!IDENTIFIER.test(name)) fail("MISSING_WORKFLOW", `Registered functions require an unqualified name: ${name}`);
     const fn = [...this.#extensions].find((extension) => extension.functions?.[name])?.functions?.[name];
@@ -145,7 +121,7 @@ export class WorkflowRegistry {
     let source = "global settings";
     try {
       const resolved = context ? resolveWorkflowSettings(context.cwd, context.projectTrusted, context.globalSettingsPath) : undefined;
-      aliases = resolved?.effective.modelAliases ?? loadSettings().modelAliases;
+      aliases = resolved?.effective.modelAliases ?? (context ? loadSettings().modelAliases : resolveWorkflowSettings(process.cwd(), false).effective.modelAliases);
       if (resolved) { source = resolved.projectTrusted && [resolved.sources.modelAliases, resolved.sources.skills, resolved.sources.extensions, resolved.sources.tools].some((path) => path === resolved.projectSettingsPath) ? "trusted project settings" : "global settings"; settings = { concurrency: resolved.effective.concurrency, backgroundWidget: resolved.effective.backgroundWidget ?? true, modelAliases: resolved.effective.modelAliases ?? {}, skills: resolved.effective.skills ?? [], extensions: Array.isArray(resolved.effective.extensions) ? resolved.effective.extensions : [], tools: resolved.effective.tools ?? [], ...(resolved.effective.extensionSettings === undefined ? {} : { extensionSettings: resolved.effective.extensionSettings }), ...(resolved.effective.worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand: resolved.effective.worktreePostCreateCommand }), globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted: resolved.projectTrusted, sources: resolved.sources }; }
     } catch { aliases = undefined; }
     const staticEntries: WorkflowCatalogModelAlias[] = Object.keys(aliases ?? {}).map((name) => ({ name, kind: "static", provenance: source }));
@@ -197,7 +173,7 @@ export class WorkflowRegistry {
     for (const { headline, validate } of this.#settingsValidators) {
       try { validate(frozenSettings, Object.freeze({ ...context })); }
       catch (error) {
-        const location = context.source === "role" && context.role ? `role ${context.role}` : context.source;
+        const location = context.source;
         fail("INVALID_SETTINGS", `Invalid extension settings (${headline}; ${location}): ${errorText(error)}`);
       }
     }
@@ -217,16 +193,11 @@ export class WorkflowRegistry {
     return structuredClone(stored);
   }
 
+  agentPreparationHooks(): readonly RegisteredAgentPreparationHook[] { return [...this.#preparationHooks.values()].sort(byPriorityThenName); }
   agentSetupHooks(): readonly RegisteredAgentSetupHook[] {
     return [...this.#hooks.values()].sort(byPriorityThenName);
   }
   agentAttemptActions(): Readonly<Record<string, AgentAttemptAction>> { return Object.freeze(Object.fromEntries(this.#agentAttemptActions.entries())); }
-  roleDirectories(): readonly string[] {
-    return [...this.#roleDirectories.keys()];
-  }
-  roleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[] {
-    return [...this.#roleDirectories.values()];
-  }
   modelAliases(): readonly { name: string; version: string; headline: string; resolve: WorkflowModelAlias["resolve"] }[] { return [...this.#modelAliases.values()].sort((left, right) => left.name.localeCompare(right.name)); }
   async resolveModelAliases(context: Readonly<WorkflowModelAliasResolverContext>, shadowed: ReadonlySet<string> = new Set()): Promise<Readonly<Record<string, string>>> {
     const resolved: Record<string, string> = {};
@@ -247,7 +218,7 @@ export class WorkflowRegistry {
     return Object.freeze(resolved);
   }
 }
-export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "functionSources" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "validateExtensionSettings" | "modelAliases" | "resolveModelAliases" | "agentSetupHooks" | "agentAttemptActions" | "roleDirectories" | "roleDirectoryRegistrations" | "setSubagentStatusObserver" | "observeSubagentStatus">;
+export type WorkflowRegistryApi = Pick<WorkflowRegistry, "frozen" | "freeze" | "register" | "function" | "functions" | "functionSources" | "catalog" | "catalogIndex" | "catalogDetail" | "globals" | "invokeFunction" | "validateExtensionSettings" | "modelAliases" | "resolveModelAliases" | "agentPreparationHooks" | "agentSetupHooks" | "agentAttemptActions" | "setSubagentStatusObserver" | "observeSubagentStatus" | "registrations">;
 interface WorkflowRegistryHost { api: WorkflowRegistryApi; activeHosts: number }
 const WORKFLOW_REGISTRY_KEY = Symbol.for("pi-extensible-workflows.workflow-registry");
 const globalRegistry = globalThis as typeof globalThis & Record<symbol, WorkflowRegistryHost | undefined>;
@@ -269,10 +240,10 @@ function createWorkflowRegistryApi(registry: WorkflowRegistry): WorkflowRegistry
     validateExtensionSettings: (...args) => { registry.validateExtensionSettings(...args); },
     modelAliases: () => registry.modelAliases(),
     resolveModelAliases: (...args) => registry.resolveModelAliases(...args),
-    roleDirectories: () => registry.roleDirectories(),
-    roleDirectoryRegistrations: () => registry.roleDirectoryRegistrations(),
+    agentPreparationHooks: () => registry.agentPreparationHooks(),
     agentSetupHooks: () => registry.agentSetupHooks(),
     agentAttemptActions: () => registry.agentAttemptActions(),
+    registrations: () => registry.registrations(),
   };
 }
 function workflowRegistryHost(): WorkflowRegistryHost {
@@ -301,7 +272,9 @@ export function retainWorkflowRegistry(): () => void {
 }
 export function loadingRegistry(): WorkflowRegistryApi { return workflowRegistryHost().api; }
 beginWorkflowExtensionLoading();
-export function registerWorkflowExtension(extension: WorkflowExtension): void { loadingRegistry().register(extension); }
+export function registerWorkflowExtension(extension: WorkflowExtension): void {
+  loadingRegistry().register(extension);
+}
 export function workflowCatalog(context?: WorkflowCatalogContext): WorkflowCatalog { return loadingRegistry().catalog(context); }
 export function workflowCatalogIndex(context?: WorkflowCatalogContext): WorkflowCatalogIndex { return loadingRegistry().catalogIndex(context); }
 export function workflowCatalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError { return loadingRegistry().catalogDetail(name, context); }
@@ -310,13 +283,4 @@ export function registeredWorkflowFunctionSources(): Readonly<Record<string, Wor
   const sources = loadingRegistry().functionSources;
   return typeof sources === "function" ? sources() : {};
 }
-export function registeredWorkflowRoleDirectories(): readonly string[] {
-  const directories = loadingRegistry().roleDirectories;
-  return typeof directories === "function" ? directories() : [];
-}
-export function registeredWorkflowRoleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[] {
-  const registrations = loadingRegistry().roleDirectoryRegistrations;
-  return typeof registrations === "function" ? registrations() : [];
-}
-
-export type { WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogModelAlias, WorkflowCatalogSettings, WorkflowRoleDirectoryRegistration } from "./types.js";
+export type { WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogIndexFunction, WorkflowCatalogModelAlias, WorkflowCatalogSettings } from "./types.js";

package/src/runtime/agent-runner.ts

@@ -121,6 +121,8 @@ export interface RuntimeAgentRunRequest {
   readonly customTools: readonly RuntimeTool[];
   /** Explicit result schema; omitted agents use the default string workflow_result schema. */
   readonly resultSchema?: RuntimeJsonSchema;
+  /** Transient retry or budget text delivered as a separate steered message after the task, never inside it. */
+  readonly turnControl?: string;
   readonly run: RuntimeRunIdentity;
   readonly agent: RuntimeAgentIdentity;
   readonly signal: AbortSignal;

package/src/script-tools.ts

@@ -0,0 +1,76 @@
+import type { ExtensionToolContext, ToolLoadout, ToolLoadoutChanges } from "@earendil-works/pi-coding-agent";
+import { WorkflowError, type JsonValue } from "./types.js";
+import { errorText, jsonValue, object } from "./utils.js";
+import { RPC_LIMIT_BYTES } from "./execution.js";
+import { scriptToolReferences } from "./validation.js";
+
+type ScriptTool = ExtensionToolContext["tools"][number];
+type ScriptToolOutcome = Awaited<ReturnType<ExtensionToolContext["executeTool"]>>;
+
+/** Workflow and subagent tools stay out of scripts, so a run cannot launch or control runs. Codemode is model-only and never callable. */
+export function scriptToolExcluded(name: string): boolean {
+  return name === "workflow" || name.startsWith("workflow_") || name.startsWith("subagents_");
+}
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export function scriptToolIdentifier(name: string): string {
+  let identifier = "";
+  for (const char of name) identifier += (identifier === "" ? /^[A-Za-z_$]$/ : /^[A-Za-z0-9_$]$/).test(char) ? char : "_";
+  return identifier || "_";
+}
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export function scriptToolContext(ctx: unknown): ExtensionToolContext | undefined {
+  return object(ctx) && typeof ctx.executeTool === "function" && Array.isArray(ctx.tools) ? ctx as unknown as ExtensionToolContext : undefined;
+}
+export function scriptToolIdentifiers(context: ExtensionToolContext | undefined): string[] {
+  return (context?.tools ?? []).filter(({ name }) => !scriptToolExcluded(name)).map(({ name }) => scriptToolIdentifier(name));
+}
+// NOTE: a launch rejects identifiers that several tools share; a later tool set may still collide, and the first match wins.
+export function scriptTool(context: ExtensionToolContext, identifier: string): ScriptTool | undefined {
+  return context.tools.find(({ name }) => !scriptToolExcluded(name) && scriptToolIdentifier(name) === identifier);
+}
+/**
+ * What a script call resolves to, as in codemode: the structured content of a tool with an output
+ * schema, also for error results that carry one, otherwise its text; other failures throw. The value
+ * is normalized through JSON and size-checked before it is journaled, so a replay returns the same value.
+ */
+export function scriptToolValue(tool: ScriptTool, outcome: ScriptToolOutcome): JsonValue {
+  const structured = tool.outputSchema === undefined ? undefined : outcome.result.structuredContent;
+  const text = outcome.result.content.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+  if (structured === undefined && outcome.isError) throw new WorkflowError("TOOL_FAILED", `${tool.name}: ${text || "failed"}`);
+  let value: unknown;
+  try { value = JSON.parse(JSON.stringify(structured ?? text)) as unknown; } catch (error) { throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON: ${errorText(error)}`); }
+  if (!jsonValue(value)) throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON`);
+  if (Buffer.byteLength(JSON.stringify(value)) > RPC_LIMIT_BYTES) throw new WorkflowError("TOOL_FAILED", `${tool.name} returned more than the 10 MB workflow RPC limit`);
+  return value;
+}
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export function validateScriptToolReferences(script: string, context: ExtensionToolContext | undefined): void {
+  const references = scriptToolReferences(script);
+  if (!references?.length) return;
+  if (!context) throw new WorkflowError("UNKNOWN_TOOL", `Workflow scripts can call session tools only when launched by the workflow tool; this launch has none for ${references.map((name) => `tools.${name}`).join(", ")}`);
+  const identifiers = scriptToolIdentifiers(context);
+  const unknown = references.filter((name) => !identifiers.includes(name));
+  if (unknown.length) throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools this session cannot call: ${unknown.map((name) => `tools.${name}`).join(", ")}`);
+  const ambiguous = references.filter((name) => identifiers.indexOf(name) !== identifiers.lastIndexOf(name));
+  if (ambiguous.length) throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools whose names collide after normalization: ${ambiguous.map((name) => `tools.${name}`).join(", ")}`);
+}
+function describeScriptOutput(schema: unknown): string | undefined {
+  if (!object(schema) || schema.type !== "object" || !object(schema.properties)) return schema === undefined ? undefined : "a JSON value";
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  return `\`{ ${Object.keys(schema.properties).map((name) => required.has(name) ? name : `${name}?`).join(", ")} }\``;
+}
+/**
+ * Tells the model what `tools.<id>(args)` resolves to for declared tools with an output schema; the
+ * workflow description says that the others resolve to their text. With codemode active its own
+ * identical `Codemode:` lines say this, and pi keeps only one description per tool, so this defers.
+ */
+export function prepareScriptToolLoadout(loadout: ToolLoadout): ToolLoadoutChanges | undefined {
+  if (loadout.declared.some(({ name }) => name === "codemode")) return undefined;
+  const callable = new Set(loadout.callable.map(({ name }) => name));
+  const descriptions: Record<string, string> = {};
+  for (const tool of loadout.declared) {
+    const output = callable.has(tool.name) && !scriptToolExcluded(tool.name) ? describeScriptOutput(tool.outputSchema) : undefined;
+    if (output) descriptions[tool.name] = `${tool.description.trim()}\n\nWorkflow scripts: \`tools.${scriptToolIdentifier(tool.name)}(args)\` resolves to ${output}.`;
+  }
+  return { descriptions };
+}

package/src/session-lease.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { link, mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -12,12 +13,39 @@ const SESSION_OWNER_FILE = "owner.json";
 const SESSION_OWNER_WRITE_GRACE_MS = 30_000;
 const RUN_CREATE_TEMP = /^\.([a-zA-Z0-9._-]+)\.(\d+)\.[0-9a-f-]+\.tmp$/;
 
-export async function processAlive(pid: number, startedAt?: number): Promise<boolean> {
+const START_MARGIN_MS = 60_000;
+let clockTicks: number | undefined;
+
+function clockTickRate(): number {
+  if (clockTicks !== undefined) return clockTicks;
+  try {
+    const rate = Number(execFileSync("getconf", ["CLK_TCK"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+    clockTicks = Number.isInteger(rate) && rate > 0 ? rate : 100;
+  } catch { clockTicks = 100; }
+  return clockTicks;
+}
+
+// Process start in epoch ms from /proc/<pid>/stat field 22; undefined when unreadable or unparsable.
+async function linuxProcessStart(pid: number, procRoot: string): Promise<number | undefined> {
+  try {
+    const text = await readFile(join(procRoot, String(pid), "stat"), "utf8");
+    // Field 2 (command name) may contain spaces and parentheses, so count fields after the last ")".
+    const close = text.lastIndexOf(")");
+    const ticks = close < 0 ? Number.NaN : Number(text.slice(close + 2).split(" ")[19]);
+    const btime = /^btime (\d+)$/m.exec(await readFile(join(procRoot, "stat"), "utf8"))?.[1];
+    if (btime === undefined || !Number.isInteger(ticks) || ticks < 0) return undefined;
+    return Number(btime) * 1000 + (ticks / clockTickRate()) * 1000;
+  } catch { return undefined; }
+}
+
+// The /proc/<pid> ctime is not a start time: procfs rebuilds the inode after cache reclaim.
+// A live owner never starts after its stamp; a reused pid starts later.
+export async function processAlive(pid: number, startedAt?: number, procRoot = "/proc"): Promise<boolean> {
+  try { process.kill(pid, 0); } catch (error) { return !isNodeError(error, "ESRCH"); }
+  if (startedAt === undefined || process.platform !== "linux") return true;
+  const start = await linuxProcessStart(pid, procRoot);
+  if (start !== undefined) return start <= startedAt + START_MARGIN_MS;
   try { process.kill(pid, 0); } catch (error) { return !isNodeError(error, "ESRCH"); }
-  if (startedAt !== undefined && process.platform === "linux") {
-    try { if ((await stat(`/proc/${String(pid)}`)).ctimeMs > startedAt) return false; }
-    catch (error) { if (isNodeError(error, "ENOENT")) return false; }
-  }
   return true;
 }
 export async function hasLiveSessionLease(cwd: string, sessionId: string, home = homedir()): Promise<boolean> {
@@ -73,7 +101,7 @@ export async function acquireSessionLease(cwd: string, sessionId: string, home =
   const path = join(directory, SESSION_OWNER_FILE);
   for (;;) {
     const token = randomUUID();
-    const owner: SessionOwner = { pid: process.pid, token, startedAt: process.platform === "linux" ? (await stat(`/proc/${String(process.pid)}`)).ctimeMs : Date.now() };
+    const owner: SessionOwner = { pid: process.pid, token, startedAt: Date.now() };
     try {
       const handle = await open(path, "wx", 0o600);
       try { await handle.writeFile(`${JSON.stringify(owner)}\n`, "utf8"); } finally { await handle.close(); }