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

package/dist/src/paths.d.ts

@@ -1,11 +1,14 @@
 export declare function safePart(value: string): string;
-/**
- * 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.
- */
 export declare function canonicalPath(path: string): string;
+export declare function extensionIdentity(path: string): string;
 export declare function sameFilesystemPath(left: string, right: string): boolean;
+/**
+ * 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 declare function piResourcePath(path: string, cwd: string): string;
+/** Pi attributes a loaded resource to a contributed path by lexical containment of resolved paths, without following symlinks. */
+export declare function piResourceContains(root: string, path: string): boolean;
 export declare function workflowProjectSettingsPath(cwd: string): string;
 export declare function projectStorageKey(cwd: string): string;
 export declare function projectSessionsDirectory(cwd: string, home?: string): string;

package/dist/src/paths.js

@@ -1,26 +1,37 @@
 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) { return value.replace(/[^a-zA-Z0-9._-]/g, "_"); }
+export function canonicalPath(path) { const absolute = resolve(path); try {
+    return realpathSync(absolute);
+}
+catch {
+    return absolute;
+} }
+export function extensionIdentity(path) { return path.startsWith("builtin:") ? path : canonicalPath(path.startsWith("file:") ? fileURLToPath(path) : path); }
+export function sameFilesystemPath(left, right) { 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) {
-    const absolute = resolve(path);
-    try {
-        return realpathSync(absolute);
-    }
-    catch {
-        return absolute;
-    }
+export function piResourcePath(path, cwd) {
+    //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, path) {
+    const relativePath = relative(resolve(root), resolve(path));
+    return relativePath === "" || (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));
 }
-export function sameFilesystemPath(left, right) { return canonicalPath(left) === canonicalPath(right); }
 export function workflowProjectSettingsPath(cwd) { return join(cwd, ".pi", "pi-extensible-workflows", "settings.json"); }
 export function projectStorageKey(cwd) {
     const exact = resolve(cwd);

package/dist/src/persistence.d.ts

@@ -2,4 +2,5 @@ export { atomicJson, atomicWriteFile, json } from "./io.js";
 export { projectStorageKey, projectSessionsDirectory, runsDirectory, listPersistedSessionIds, structuralPath, } 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, WorktreeReference, BorrowedWorktreeBinding, isPersistedRun, } from "./decoders.js";

package/dist/src/persistence.js

@@ -2,4 +2,5 @@ export { atomicJson, atomicWriteFile, json } from "./io.js";
 export { projectStorageKey, projectSessionsDirectory, runsDirectory, listPersistedSessionIds, structuralPath, } from "./paths.js";
 export { hasLiveSessionLease, SessionLease, acquireSessionLease, listRunIds, processAlive } from "./session-lease.js";
 export { RunStore } from "./store.js";
+export { decodePreparedAgentConfiguration } from "./decoders.js";
 export { isPersistedRun, } from "./decoders.js";

package/dist/src/pi-runtime-runner.js

@@ -164,7 +164,7 @@ export class PiRuntimeAgentRunner {
         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;
@@ -423,6 +423,9 @@ export class PiRuntimeAgentRunner {
             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)

package/dist/src/registry.d.ts

@@ -1,4 +1,4 @@
-import type { AgentAttemptAction, JsonValue, RegisteredAgentSetupHook, WorkflowCatalog, WorkflowCatalogContext, WorkflowCatalogError, WorkflowCatalogFunction, WorkflowCatalogIndex, WorkflowCatalogModelAlias, WorkflowExtension, WorkflowExtensionSettings, WorkflowExtensionSettingsValidatorContext, WorkflowFunction, WorkflowFunctionContext, WorkflowFunctionSource, WorkflowJournal, WorkflowModelAlias, WorkflowModelAliasResolverContext, WorkflowRoleDirectoryRegistration } from "./types.js";
+import type { AgentAttemptAction, 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";
 export type SubagentStatusObserver = (status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>) => void;
 export declare class WorkflowRegistry {
@@ -8,6 +8,11 @@ export declare class WorkflowRegistry {
     setSubagentStatusObserver(observer: SubagentStatusObserver | undefined): void;
     observeSubagentStatus(status: Readonly<SubagentStatus>, request: Readonly<SubagentRunRequest>): void;
     register(extension: WorkflowExtension): void;
+    /** Every registration's headline and declared module provenance, for hosts that must prove which extension made it. */
+    registrations(): ReadonlyArray<Readonly<{
+        headline: string;
+        source?: string;
+    }>>;
     function(name: string): WorkflowFunction;
     functions(): Readonly<Record<string, WorkflowFunction>>;
     functionSources(): Readonly<Record<string, WorkflowFunctionSource>>;
@@ -19,10 +24,9 @@ export declare class WorkflowRegistry {
     }>>;
     validateExtensionSettings(settings: Readonly<WorkflowExtensionSettings> | undefined, context: WorkflowExtensionSettingsValidatorContext): void;
     invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
+    agentPreparationHooks(): readonly RegisteredAgentPreparationHook[];
     agentSetupHooks(): readonly RegisteredAgentSetupHook[];
     agentAttemptActions(): Readonly<Record<string, AgentAttemptAction>>;
-    roleDirectories(): readonly string[];
-    roleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
     modelAliases(): readonly {
         name: string;
         version: string;
@@ -31,7 +35,7 @@ export declare class WorkflowRegistry {
     }[];
     resolveModelAliases(context: Readonly<WorkflowModelAliasResolverContext>, shadowed?: ReadonlySet<string>): Promise<Readonly<Record<string, string>>>;
 }
-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">;
 export declare function resetWorkflowRegistry(): void;
 export declare function resetWorkflowRegistryIfIdle(): void;
 export declare function beginWorkflowExtensionLoading(): void;
@@ -43,6 +47,4 @@ export declare function workflowCatalogIndex(context?: WorkflowCatalogContext):
 export declare function workflowCatalogDetail(name: string, context?: WorkflowCatalogContext): WorkflowCatalogFunction | WorkflowCatalogModelAlias | WorkflowCatalogError;
 export declare function registeredWorkflowFunctions(): Readonly<Record<string, WorkflowFunction>>;
 export declare function registeredWorkflowFunctionSources(): Readonly<Record<string, WorkflowFunctionSource>>;
-export declare function registeredWorkflowRoleDirectories(): readonly string[];
-export declare function registeredWorkflowRoleDirectoryRegistrations(): readonly WorkflowRoleDirectoryRegistration[];
-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/dist/src/registry.js

@@ -1,50 +1,11 @@
-import { readFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Value } from "typebox/value";
 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._-]*$/;
-function normalizeRoleDirectory(value) {
-    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) {
-    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 = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-        return object(metadata) && isCorePackageName(metadata.name);
-    }
-    catch {
-        return false;
-    }
-}
 function catalogSchema(schema, at) {
     validateSchema(schema, at);
     return structuredClone(schema);
@@ -53,9 +14,9 @@ export class WorkflowRegistry {
     #extensions = new Set();
     #functionSources = new Map();
     #globals = new Map();
+    #preparationHooks = new Map();
     #hooks = new Map();
     #agentAttemptActions = new Map();
-    #roleDirectories = new Map();
     #modelAliases = new Map();
     #settingsValidators = new Set();
     #frozen = false;
@@ -69,10 +30,11 @@ export class WorkflowRegistry {
             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())
+        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;
@@ -85,12 +47,8 @@ export class WorkflowRegistry {
             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");
@@ -118,6 +76,14 @@ export class WorkflowRegistry {
             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}`);
@@ -132,18 +98,17 @@ export class WorkflowRegistry {
             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 } : {}) }));
         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))
@@ -151,6 +116,10 @@ export class WorkflowRegistry {
         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() {
+        return [...this.#extensions].map(({ headline, source }) => Object.freeze({ headline, ...(source === undefined ? {} : { source }) }));
+    }
     function(name) {
         if (!IDENTIFIER.test(name))
             fail("MISSING_WORKFLOW", `Registered functions require an unqualified name: ${name}`);
@@ -176,7 +145,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 };
@@ -246,7 +215,7 @@ export class WorkflowRegistry {
                 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)}`);
             }
         }
@@ -268,16 +237,11 @@ export class WorkflowRegistry {
         journal.put(path, stored);
         return structuredClone(stored);
     }
+    agentPreparationHooks() { return [...this.#preparationHooks.values()].sort(byPriorityThenName); }
     agentSetupHooks() {
         return [...this.#hooks.values()].sort(byPriorityThenName);
     }
     agentAttemptActions() { return Object.freeze(Object.fromEntries(this.#agentAttemptActions.entries())); }
-    roleDirectories() {
-        return [...this.#roleDirectories.keys()];
-    }
-    roleDirectoryRegistrations() {
-        return [...this.#roleDirectories.values()];
-    }
     modelAliases() { return [...this.#modelAliases.values()].sort((left, right) => left.name.localeCompare(right.name)); }
     async resolveModelAliases(context, shadowed = new Set()) {
         const resolved = {};
@@ -325,10 +289,10 @@ function createWorkflowRegistryApi(registry) {
         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() {
@@ -361,7 +325,9 @@ export function retainWorkflowRegistry() {
 }
 export function loadingRegistry() { return workflowRegistryHost().api; }
 beginWorkflowExtensionLoading();
-export function registerWorkflowExtension(extension) { loadingRegistry().register(extension); }
+export function registerWorkflowExtension(extension) {
+    loadingRegistry().register(extension);
+}
 export function workflowCatalog(context) { return loadingRegistry().catalog(context); }
 export function workflowCatalogIndex(context) { return loadingRegistry().catalogIndex(context); }
 export function workflowCatalogDetail(name, context) { return loadingRegistry().catalogDetail(name, context); }
@@ -370,11 +336,3 @@ export function registeredWorkflowFunctionSources() {
     const sources = loadingRegistry().functionSources;
     return typeof sources === "function" ? sources() : {};
 }
-export function registeredWorkflowRoleDirectories() {
-    const directories = loadingRegistry().roleDirectories;
-    return typeof directories === "function" ? directories() : [];
-}
-export function registeredWorkflowRoleDirectoryRegistrations() {
-    const registrations = loadingRegistry().roleDirectoryRegistrations;
-    return typeof registrations === "function" ? registrations() : [];
-}

package/dist/src/runtime/agent-runner.d.ts

@@ -109,6 +109,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/dist/src/script-tools.d.ts

@@ -0,0 +1,27 @@
+import type { ExtensionToolContext, ToolLoadout, ToolLoadoutChanges } from "@earendil-works/pi-coding-agent";
+import { type JsonValue } from "./types.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 declare function scriptToolExcluded(name: string): boolean;
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export declare function scriptToolIdentifier(name: string): string;
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export declare function scriptToolContext(ctx: unknown): ExtensionToolContext | undefined;
+export declare function scriptToolIdentifiers(context: ExtensionToolContext | undefined): string[];
+export declare function scriptTool(context: ExtensionToolContext, identifier: string): ScriptTool | undefined;
+/**
+ * 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 declare function scriptToolValue(tool: ScriptTool, outcome: ScriptToolOutcome): JsonValue;
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export declare function validateScriptToolReferences(script: string, context: ExtensionToolContext | undefined): void;
+/**
+ * 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 declare function prepareScriptToolLoadout(loadout: ToolLoadout): ToolLoadoutChanges | undefined;
+export {};

package/dist/src/script-tools.js

@@ -0,0 +1,87 @@
+import { WorkflowError } from "./types.js";
+import { errorText, jsonValue, object } from "./utils.js";
+import { RPC_LIMIT_BYTES } from "./execution.js";
+import { scriptToolReferences } from "./validation.js";
+/** 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) {
+    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) {
+    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) {
+    return object(ctx) && typeof ctx.executeTool === "function" && Array.isArray(ctx.tools) ? ctx : undefined;
+}
+export function scriptToolIdentifiers(context) {
+    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, identifier) {
+    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, outcome) {
+    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;
+    try {
+        value = JSON.parse(JSON.stringify(structured ?? text));
+    }
+    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, context) {
+    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) {
+    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) {
+    if (loadout.declared.some(({ name }) => name === "codemode"))
+        return undefined;
+    const callable = new Set(loadout.callable.map(({ name }) => name));
+    const descriptions = {};
+    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/dist/src/session-lease.d.ts

@@ -1,4 +1,4 @@
-export declare function processAlive(pid: number, startedAt?: number): Promise<boolean>;
+export declare function processAlive(pid: number, startedAt?: number, procRoot?: string): Promise<boolean>;
 export declare function hasLiveSessionLease(cwd: string, sessionId: string, home?: string): Promise<boolean>;
 export declare class SessionLease {
     #private;

package/dist/src/session-lease.js

@@ -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";
@@ -10,22 +11,55 @@ import { runsDirectory } from "./paths.js";
 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, startedAt) {
+const START_MARGIN_MS = 60_000;
+let clockTicks;
+function clockTickRate() {
+    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, procRoot) {
+    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, startedAt, procRoot = "/proc") {
     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;
-        }
+    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");
     }
     return true;
 }
@@ -98,7 +132,7 @@ export async function acquireSessionLease(cwd, sessionId, home = homedir()) {
     const path = join(directory, SESSION_OWNER_FILE);
     for (;;) {
         const token = randomUUID();
-        const owner = { pid: process.pid, token, startedAt: process.platform === "linux" ? (await stat(`/proc/${String(process.pid)}`)).ctimeMs : Date.now() };
+        const owner = { pid: process.pid, token, startedAt: Date.now() };
         try {
             const handle = await open(path, "wx", 0o600);
             try {

package/dist/src/settings.d.ts

@@ -1,13 +1,29 @@
-import type { AgentResourcePolicy, ContextFileScope, WorkflowExtensionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution } from "./types.js";
+import { type ToolAnnotations } from "@earendil-works/pi-coding-agent";
+import type { AgentResourcePolicy, AgentResourceSelectorSources, ContextFileScope, WorkflowExtensionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution } from "./types.js";
 export { workflowProjectSettingsPath } from "./paths.js";
 export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
 export declare function workflowSettingsPath(agentDir?: string): string;
 export declare function validateSelectorList(value: unknown, path: string, kind: "skills" | "extensions" | "tools", errorCode?: "INVALID_SETTINGS" | "INVALID_METADATA", normalizeExtensions?: boolean): readonly string[] | undefined;
-export declare function validateContextFileScopes(value: unknown, rolePath: string): readonly ContextFileScope[] | undefined;
+export declare function validateContextFileScopes(value: unknown, sourcePath: string): readonly ContextFileScope[] | undefined;
 export declare function validateWorkflowExtensionSettings(value: unknown, settingsPath: string, errorCode?: "INVALID_SETTINGS" | "INVALID_METADATA"): WorkflowExtensionSettings | undefined;
 export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+/**
+ * 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 declare function workflowToolExposure(name: string, codemodeTools: WorkflowSettings["codemodeTools"]): {
+    exposure?: "model-only";
+    annotations?: ToolAnnotations;
+};
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export declare function loadCodemodeToolsSetting(agentDir?: string): WorkflowSettings["codemodeTools"];
 export declare function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides>;
-export declare function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): WorkflowSettingsResolution;
+export declare function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): WorkflowSettingsResolution & {
+    selectorSources: AgentResourceSelectorSources;
+};
 export declare function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void;
 export declare function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): AgentResourcePolicy;
 export declare function saveModelAliases(path?: string, aliases?: Readonly<Record<string, string>>): void;
+export declare function canonicalExtensionSelector(selector: string, cwd: string): string;