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

package/dist/src/paths.d.ts

@@ -1,13 +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;
-/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
 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,28 +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));
 }
-/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
-export function extensionIdentity(path) { return path.startsWith("builtin:") ? path : canonicalPath(path); }
-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", "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/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,10 +1,10 @@
 import { type ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import type { AgentResourcePolicy, ContextFileScope, WorkflowExtensionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution } from "./types.js";
+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>;
 /**
@@ -20,7 +20,10 @@ export declare function workflowToolExposure(name: string, codemodeTools: Workfl
 /** 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;