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

package/dist/src/settings.js

@@ -1,16 +1,18 @@
 import { atomicWriteFile } from "./persistence.js";
 import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { isContextFileScope } from "./types.js";
-import { annotateModelAliasError, deepFreeze, errorText, fail, isNodeError, jsonValue, modelCapability, object, positiveInteger, resourcePatternHasMagic, unknownModel, validateModelAliases, validateResourcePattern, validWorkflowExtensionNamespace } from "./utils.js";
 import { canonicalPath, workflowProjectSettingsPath } from "./paths.js";
 export { workflowProjectSettingsPath } from "./paths.js";
-const ROLE_DIRECTORY = "pi-extensible-workflows";
+import { isContextFileScope } from "./types.js";
+import { annotateModelAliasError, deepFreeze, errorText, fail, isNodeError, modelCapability, object, positiveInteger, unknownModel, validateModelAliases } from "./utils.js";
+import { jsonValue, resourcePatternHasMagic, validateResourcePattern, validWorkflowExtensionNamespace } from "./utils.js";
+const WORKFLOW_DIRECTORY = "pi-extensible-workflows";
 export const DEFAULT_SETTINGS = Object.freeze({ concurrency: 8, backgroundWidget: true });
-export function workflowSettingsPath(agentDir = getAgentDir()) { return join(agentDir, ROLE_DIRECTORY, "settings.json"); }
+export function workflowSettingsPath(agentDir = getAgentDir()) { return join(agentDir, WORKFLOW_DIRECTORY, "settings.json"); }
 function normalizedResourcePath(value, settingsPath) {
     // Built-in extensions are named `builtin:<name>`, not by a path.
     if (value === "*" || value.startsWith("builtin:"))
@@ -82,23 +84,25 @@ function selectorsFromSettings(settings) {
     };
 }
 function selectorSet(value) { return { skills: [...(value?.skills ?? [])], extensions: [...(value?.extensions ?? [])], ...(value?.tools === undefined ? {} : { tools: [...value.tools] }) }; }
-export function validateContextFileScopes(value, rolePath) {
+export function validateContextFileScopes(value, sourcePath) {
     if (value === undefined)
         return undefined;
     if (!Array.isArray(value) || !value.every(isContextFileScope))
-        fail("INVALID_METADATA", `${rolePath}.contextFiles must be an array containing only global, project, or cwd`);
+        fail("INVALID_METADATA", `${sourcePath}.contextFiles must be an array containing only global, project, or cwd`);
     return [...value];
 }
 export function validateWorkflowExtensionSettings(value, settingsPath, errorCode = "INVALID_SETTINGS") {
     if (value === undefined)
         return undefined;
+    if (!object(value) || !jsonValue(value))
+        fail(errorCode, `${settingsPath}.extensionSettings must be a JSON object`);
+    for (const namespace of Object.keys(value))
+        if (!validWorkflowExtensionNamespace(namespace))
+            fail(errorCode, `${settingsPath}.extensionSettings contains an invalid namespace: ${namespace}`);
+    const generic = value;
     const base = `${settingsPath}.extensionSettings`;
-    if (!object(value))
-        fail(errorCode, `${base} must be an object`);
     const normalized = {};
-    for (const [namespace, raw] of Object.entries(value)) {
-        if (!validWorkflowExtensionNamespace(namespace))
-            fail(errorCode, `${base} contains an invalid namespace: ${namespace}`);
+    for (const [namespace, raw] of Object.entries(generic)) {
         if (namespace === "herdr") {
             if (!object(raw))
                 fail(errorCode, `${base}.herdr must be an object`);
@@ -119,8 +123,6 @@ export function validateWorkflowExtensionSettings(value, settingsPath, errorCode
             normalized.trajectory = Object.freeze({ ...(raw.port === undefined ? {} : { port: raw.port }) });
             continue;
         }
-        if (!jsonValue(raw))
-            fail(errorCode, `${base}.${namespace} must be JSON-compatible`);
         normalized[namespace] = structuredClone(raw);
     }
     return deepFreeze(normalized);
@@ -206,39 +208,22 @@ export function loadCodemodeToolsSetting(agentDir) {
 export function loadSettingsOverrides(path) { return parseSettings(path, true); }
 export function resolveWorkflowSettings(cwd, projectTrusted, globalSettingsPath = workflowSettingsPath()) {
     const projectSettingsPath = workflowProjectSettingsPath(cwd);
-    const global = loadSettings(globalSettingsPath);
-    const project = projectTrusted ? loadSettingsOverrides(projectSettingsPath) : Object.freeze({});
-    const projectHas = (key) => Object.prototype.hasOwnProperty.call(project, key);
-    const sourceFor = (key) => projectHas(key) ? projectSettingsPath : globalSettingsPath;
-    const globalSelectors = selectorsFromSettings(global);
-    const projectSelectors = selectorsFromSettings(project);
-    const effectiveSelectors = selectorSet({
-        skills: [...(globalSelectors.skills ?? []), ...(projectSelectors.skills ?? [])],
-        extensions: [...(globalSelectors.extensions ?? []), ...(projectSelectors.extensions ?? [])],
-        ...(globalSelectors.tools === undefined && projectSelectors.tools === undefined ? {} : { tools: [...(globalSelectors.tools ?? []), ...(projectSelectors.tools ?? [])] }),
-    });
-    const hasExtensionSelectors = global.extensions !== undefined || project.extensions !== undefined;
-    const extensionSettings = projectHas("extensionSettings") ? project.extensionSettings : global.extensionSettings;
-    const sources = {
-        concurrency: projectHas("concurrency") ? projectSettingsPath : globalSettingsPath,
-        modelAliases: projectHas("modelAliases") ? projectSettingsPath : globalSettingsPath,
-        skills: sourceFor("skills"), extensions: sourceFor("extensions"), tools: sourceFor("tools"),
-        ...(extensionSettings === undefined ? {} : { extensionSettings: projectHas("extensionSettings") ? projectSettingsPath : globalSettingsPath }),
-        ...(project.retention === undefined && global.retention === undefined ? {} : { retention: project.retention === undefined ? globalSettingsPath : projectSettingsPath }),
-        ...(projectHas("worktreePostCreateCommand") || global.worktreePostCreateCommand !== undefined ? { worktreePostCreateCommand: projectHas("worktreePostCreateCommand") ? projectSettingsPath : globalSettingsPath } : {}),
-    };
+    const consumerGlobal = loadSettings(globalSettingsPath);
+    const consumerProject = projectTrusted ? loadSettingsOverrides(projectSettingsPath) : Object.freeze({});
+    const global = consumerGlobal;
+    const project = consumerProject;
+    const selectorSources = { global: selectorsFromSettings(global), project: selectorsFromSettings(project) };
     const effective = Object.freeze({
-        concurrency: project.concurrency ?? global.concurrency,
-        backgroundWidget: global.backgroundWidget ?? true,
-        ...(projectHas("modelAliases") ? { modelAliases: project.modelAliases } : global.modelAliases === undefined ? {} : { modelAliases: global.modelAliases }),
-        ...(effectiveSelectors.skills.length ? { skills: effectiveSelectors.skills } : global.skills !== undefined || project.skills !== undefined ? { skills: effectiveSelectors.skills } : {}),
-        ...(hasExtensionSelectors ? { extensions: effectiveSelectors.extensions } : {}),
-        ...(extensionSettings === undefined ? {} : { extensionSettings }),
-        ...(effectiveSelectors.tools?.length ? { tools: effectiveSelectors.tools } : global.tools !== undefined || project.tools !== undefined ? { tools: effectiveSelectors.tools } : {}),
-        ...((project.retention ?? global.retention) === undefined ? {} : { retention: project.retention ?? global.retention }),
-        ...(projectHas("worktreePostCreateCommand") ? { worktreePostCreateCommand: project.worktreePostCreateCommand } : global.worktreePostCreateCommand === undefined ? {} : { worktreePostCreateCommand: global.worktreePostCreateCommand }),
+        ...global, ...project,
+        skills: [...(global.skills ?? []), ...(project.skills ?? [])],
+        extensions: [...(global.extensions ?? []), ...(project.extensions ?? [])],
+        ...(global.tools === undefined && project.tools === undefined ? {} : { tools: [...(global.tools ?? []), ...(project.tools ?? [])] }),
     });
-    return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, sources };
+    const sources = { concurrency: project.concurrency === undefined ? globalSettingsPath : projectSettingsPath, modelAliases: project.modelAliases === undefined ? globalSettingsPath : projectSettingsPath };
+    for (const key of ["skills", "extensions", "tools", "extensionSettings", "retention", "worktreePostCreateCommand"])
+        if (effective[key] !== undefined)
+            sources[key] = project[key] === undefined ? globalSettingsPath : projectSettingsPath;
+    return { globalSettingsPath, projectSettingsPath, projectTrusted, global, project, effective, sources, selectorSources };
 }
 export function validateModelAliasAvailability(aliases, names, availableModels, knownModels, settingsPath) {
     for (const name of names) {
@@ -257,7 +242,7 @@ export function resolveAgentResourcePolicy(cwd, projectTrusted, globalSettingsPa
     const global = selectorSet(selectorsFromSettings(resolved.global));
     const project = selectorSet(selectorsFromSettings(resolved.project));
     const effective = selectorSet(selectorsFromSettings(resolved.effective));
-    return { globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [], unmatchedTools: [], selectorSources: { global: selectorsFromSettings(resolved.global), project: selectorsFromSettings(resolved.project) } };
+    return { globalSettingsPath: resolved.globalSettingsPath, projectSettingsPath: resolved.projectSettingsPath, projectTrusted, global, project, effective, unmatchedSkills: [], unmatchedExtensions: [], unmatchedTools: [], selectorSources: resolved.selectorSources };
 }
 export function saveModelAliases(path = workflowSettingsPath(), aliases = {}) {
     const normalized = validateModelAliases(aliases, path);
@@ -275,3 +260,7 @@ export function saveModelAliases(path = workflowSettingsPath(), aliases = {}) {
     mkdirSync(dirname(path), { recursive: true });
     atomicWriteFile(path, `${JSON.stringify({ ...parsed, modelAliases: normalized }, null, 2)}\n`, true);
 }
+export function canonicalExtensionSelector(selector, cwd) {
+    const negated = selector.startsWith("!");
+    return `${negated ? "!" : ""}${normalizedResourcePath(negated ? selector.slice(1) : selector, join(cwd, "settings.json"))}`;
+}

package/dist/src/store.d.ts

@@ -1,4 +1,4 @@
-import { type JsonValue, type LaunchSnapshot, type WorkflowRunEvent } from "./types.js";
+import { type PreparedAgentConfiguration, type JsonValue, type LaunchSnapshot, type WorkflowLaunchMode, type WorkflowRunEvent } from "./types.js";
 import { type AwaitingCheckpoint, type BorrowedWorktreeBinding, type CompletedOperation, type EffectiveSystemPrompt, type PendingWorkflowDecision, type PersistedOwnershipNode, type PersistedRun, type RunSummary, type WorktreeReference } from "./decoders.js";
 export declare class RunStore {
     #private;
@@ -28,6 +28,8 @@ export declare class RunStore {
     loadSummary(): Promise<RunSummary>;
     saveState(run: PersistedRun): Promise<void>;
     updateState(update: (run: PersistedRun) => PersistedRun | Promise<PersistedRun>): Promise<PersistedRun>;
+    saveAgentConfiguration(key: string, configuration: PreparedAgentConfiguration): Promise<void>;
+    setLaunchMode(launchMode: WorkflowLaunchMode): Promise<void>;
     saveSnapshot(snapshot: Readonly<LaunchSnapshot>): Promise<void>;
     appendEvent(event: WorkflowRunEvent): Promise<void>;
     saveOwnership(nodes: readonly PersistedOwnershipNode[]): Promise<void>;

package/dist/src/store.js

@@ -24,7 +24,7 @@ function summaryFromRun(run, directory, journal, previous, fallbackCreatedAt, no
     const failedAt = run.failedAt ?? run.error?.failedAt;
     const replayablePaths = [...new Set([...(run.retry?.completedPaths ?? []), ...Object.keys(journal.completed)])];
     const incompletePaths = [...new Set([...(run.retry?.incompletePaths ?? []), ...(failedAt ? [failedAt] : [])])];
-    return { schemaVersion: 1, runId: run.id, sessionId: run.sessionId, workflowName: run.workflowName, state: run.state, createdAt, updatedAt: now, ...(previous?.terminalAt || HARD_TERMINAL_RUN_STATES.has(run.state) ? { terminalAt: previous?.terminalAt ?? now } : {}), usage: budgetUsage(run.usage), agents: run.agents.map(({ id, name, label, state, role, attempts }) => ({ id, name, ...(label ? { label } : {}), state, ...(role ? { role } : {}), attempts })), ...(run.error ? { error: run.error } : {}), ...(failedAt ? { failedAt } : {}), replayablePaths, incompletePaths, artifacts: summaryArtifacts(directory) };
+    return { schemaVersion: 1, runId: run.id, sessionId: run.sessionId, workflowName: run.workflowName, state: run.state, createdAt, updatedAt: now, ...(previous?.terminalAt || HARD_TERMINAL_RUN_STATES.has(run.state) ? { terminalAt: previous?.terminalAt ?? now } : {}), usage: budgetUsage(run.usage), agents: run.agents.map(({ id, name, label, state, attempts }) => ({ id, name, ...(label ? { label } : {}), state, attempts })), ...(run.error ? { error: run.error } : {}), ...(failedAt ? { failedAt } : {}), replayablePaths, incompletePaths, artifacts: summaryArtifacts(directory) };
 }
 function systemPromptStoragePath(directory) { return join(directory, SYSTEM_PROMPT_STORAGE); }
 function systemPromptRecordsPath(directory) { return join(systemPromptStoragePath(directory), SYSTEM_PROMPT_RECORDS); }
@@ -171,6 +171,22 @@ export class RunStore {
         });
         return write;
     }
+    async saveAgentConfiguration(key, configuration) {
+        await this.launchSnapshotLane.run(async () => {
+            const snapshot = decodeLaunchSnapshot(await json(join(this.directory, "snapshot.json")));
+            if (!snapshot)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
+            await atomicJson(join(this.directory, "snapshot.json"), { ...snapshot, agentConfigurations: { ...snapshot.agentConfigurations, [key]: configuration } });
+        });
+    }
+    async setLaunchMode(launchMode) {
+        await this.launchSnapshotLane.run(async () => {
+            const snapshot = decodeLaunchSnapshot(await json(join(this.directory, "snapshot.json")));
+            if (!snapshot)
+                throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
+            await atomicJson(join(this.directory, "snapshot.json"), { ...snapshot, launchMode });
+        });
+    }
     async saveSnapshot(snapshot) {
         const write = this.launchSnapshotLane.run(() => atomicJson(join(this.directory, "snapshot.json"), snapshot));
         await write;

package/dist/src/trajectory.d.ts

@@ -63,7 +63,6 @@ export type TrajectorySubagent = {
     sessionId: string;
     cwd: string;
     label?: string;
-    role?: string;
     mode: "background" | "foreground";
     state: SubagentStatus["state"];
     startedAt?: number;

package/dist/src/trajectory.js

@@ -238,8 +238,8 @@ async function resolveResourceInspection(inspection, cwd, selectorCwd = cwd) {
         return inspection;
     }
     const sources = inspection.selectorSources ?? { global: inspection.selectors, project: {} };
-    const skills = inspection.skills.length ? inspection.skills : selectResourcesByLayers([sources.global.skills, sources.project.skills, sources.role?.skills, sources.call?.skills], discovered.skills);
-    const extensions = inspection.extensions.length ? inspection.extensions : selectResourcesByLayers([sources.global.extensions, sources.project.extensions, sources.role?.extensions, sources.call?.extensions].map((layer) => layer?.map((selector) => canonicalExtensionSelector(selector, selectorCwd))), discovered.extensions);
+    const skills = inspection.skills.length ? inspection.skills : selectResourcesByLayers([sources.global.skills, sources.project.skills, sources.call?.skills], discovered.skills);
+    const extensions = inspection.extensions.length ? inspection.extensions : selectResourcesByLayers([sources.global.extensions, sources.project.extensions, sources.call?.extensions].map((layer) => layer?.map((selector) => canonicalExtensionSelector(selector, selectorCwd))), discovered.extensions);
     return skills === inspection.skills && extensions === inspection.extensions ? inspection : { ...inspection, skills, extensions };
 }
 export async function withResolvedAttemptResources(attempt, cwd) {
@@ -577,7 +577,6 @@ async function loadTrajectorySubagent(directory, cwd, sessionId, includeTranscri
         return {
             id, sessionId, cwd, mode: request.mode ?? "background", state: status.state, request, tools, transcript,
             ...(request.label === undefined ? {} : { label: request.label }),
-            ...(request.role === undefined ? {} : { role: request.role }),
             ...(status.startedAt === undefined ? {} : { startedAt: status.startedAt }),
             ...(status.finishedAt === undefined ? {} : { finishedAt: status.finishedAt }),
             ...(status.attempts === undefined ? {} : { attempts: status.attempts }),

package/dist/src/types.d.ts

@@ -23,9 +23,12 @@ export declare const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpo
 export declare const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
 export declare const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 export declare const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
-export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID", "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
+export declare const ERROR_CODES: readonly ["CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT", "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID", "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
 export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export declare const CONTEXT_FILE_SCOPES: readonly ["global", "project", "cwd"];
+export type ContextFileScope = (typeof CONTEXT_FILE_SCOPES)[number];
+export declare function isContextFileScope(value: unknown): value is ContextFileScope;
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -34,15 +37,15 @@ export type JsonSchema = {
     [key: string]: JsonValue;
 };
 type WorkflowSchema = JsonSchema | TSchema;
-export declare function roleNameOf(value: unknown): string | undefined;
 export interface AgentOptions<Schema extends TSchema = never> {
     label?: string;
     model?: string;
     tools?: string[];
+    /** Exact tool names removed after preparation hooks; never widens the parent ceiling. */
+    excludeTools?: string[];
     skills?: string[];
     extensions?: string[];
     contextFiles?: ContextFileScope[];
-    role?: string;
     outputSchema?: JsonSchema | Schema;
     retries?: number;
     timeoutMs?: number | null;
@@ -137,7 +140,6 @@ export interface WorkflowRunFailedEvent extends WorkflowEventBase {
 export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase {
     agentId: string;
     displayLabel: string;
-    role?: string;
     structuralPath: readonly string[];
     parentId?: string;
     parentBreadcrumb?: string;
@@ -196,13 +198,12 @@ export interface WorkflowExtensionSettings {
     readonly herdr?: Readonly<HerdrExtensionSettings>;
     readonly trajectory?: Readonly<TrajectoryExtensionSettings>;
 }
-export type WorkflowExtensionSettingsSource = "global" | "project" | "role" | "effective";
+export type WorkflowExtensionSettingsSource = "global" | "project" | "effective";
 export interface WorkflowExtensionSettingsValidatorContext {
     source: WorkflowExtensionSettingsSource;
     cwd: string;
     projectTrusted: boolean;
     settingsPath?: string;
-    role?: string;
 }
 export type WorkflowExtensionSettingsValidator = (settings: Readonly<WorkflowExtensionSettings>, context: Readonly<WorkflowExtensionSettingsValidatorContext>) => void;
 export interface WorkflowSessionStartEvent {
@@ -240,6 +241,7 @@ export interface WorkflowSettingsSources {
     worktreePostCreateCommand?: string;
 }
 export interface WorkflowSettingsResolution {
+    selectorSources?: AgentResourceSelectorSources;
     globalSettingsPath: string;
     projectSettingsPath: string;
     projectTrusted: boolean;
@@ -261,13 +263,14 @@ export interface AgentResourceSelectorSet {
 export interface AgentResourceSelectorSources {
     global: AgentResourceSelectors;
     project: AgentResourceSelectors;
-    role?: AgentResourceSelectors;
     call?: AgentResourceSelectors;
 }
-export declare const CONTEXT_FILE_SCOPES: readonly ["global", "project", "cwd"];
-export type ContextFileScope = (typeof CONTEXT_FILE_SCOPES)[number];
-export declare function isContextFileScope(value: unknown): value is ContextFileScope;
 export interface AgentResourcePolicy {
+    capabilities?: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
     globalSettingsPath: string;
     projectSettingsPath: string;
     projectTrusted: boolean;
@@ -281,6 +284,8 @@ export interface AgentResourcePolicy {
     unmatchedExtensions: readonly string[];
     unmatchedTools?: readonly string[];
     selectorSources: AgentResourceSelectorSources;
+    /** Skills loaded by the parent session; ceiling for skills that extensions contribute through resources_discover. Absent for top-level agents. */
+    parentSkills?: readonly string[];
 }
 export interface AgentResourceInspection {
     selectors: AgentResourceSelectorSet;
@@ -356,7 +361,6 @@ export interface AgentRecord {
     handle?: string;
     turn?: number;
     continuity?: AgentContinuity;
-    role?: string;
     requestedModel?: string;
     model: ModelSpec;
     tools: readonly string[];
@@ -450,22 +454,10 @@ export interface RunRecord {
     events?: readonly WorkflowRunEvent[];
     delivery?: WorkflowRunDelivery;
 }
-export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 6;
 export type WorkflowLaunchMode = "foreground" | "background";
-export interface AgentDefinition {
-    prompt?: string;
-    description?: string;
-    model?: string;
-    thinking?: NonNullable<ModelSpec["thinking"]>;
-    tools?: readonly string[];
-    skills?: readonly string[];
-    extensions?: readonly string[];
-    overrideSystemPrompt?: boolean;
-    contextFiles?: readonly ContextFileScope[];
-    extensionSettings?: Readonly<WorkflowExtensionSettings>;
-}
 export interface LaunchSnapshot {
-    identityVersion?: number;
+    identityVersion: number;
     launchMode?: WorkflowLaunchMode;
     script: string;
     args: JsonValue;
@@ -478,15 +470,12 @@ export interface LaunchSnapshot {
     phases?: readonly string[];
     models: readonly string[];
     tools: readonly string[];
-    agentTypes: readonly string[];
-    roles?: Readonly<Record<string, AgentDefinition>>;
-    projectRoles?: readonly string[];
+    agentConfigurations: Readonly<Record<string, PreparedAgentConfiguration>>;
     schemas: readonly JsonSchema[];
 }
 export interface PreflightCapabilities {
     models: ReadonlySet<string>;
     tools: ReadonlySet<string>;
-    agentTypes: ReadonlySet<string>;
     modelAliases?: Readonly<Record<string, string>>;
     knownModels?: ReadonlySet<string>;
     settingsPath?: string;
@@ -498,10 +487,22 @@ export interface PreflightResult {
         phases: readonly string[];
         models: readonly string[];
         tools: readonly string[];
-        agentTypes: readonly string[];
     };
     schemas: readonly JsonSchema[];
-    dynamicAgentRoles: boolean;
+}
+export interface AgentHandleSendOptions<Schema extends TSchema = never> {
+    outputSchema?: JsonSchema | Schema;
+    timeoutMs?: number | null;
+}
+/** A persistent agent: each send continues the transcript of the previous completed turn. Sends must be awaited one at a time, in the scope that created the handle. */
+export interface AgentHandle {
+    readonly name: string;
+    send: {
+        <Schema extends TSchema>(prompt: string, options: Readonly<AgentHandleSendOptions<Schema> & {
+            outputSchema: Schema;
+        }>): Promise<Static<Schema>>;
+        (prompt: string, options?: Readonly<AgentHandleSendOptions>): Promise<JsonValue>;
+    };
 }
 export interface WorkflowOrchestrationContext {
     agent: {
@@ -509,6 +510,9 @@ export interface WorkflowOrchestrationContext {
             outputSchema: Schema;
         }>): Promise<Static<Schema>>;
         (prompt: string, options?: Readonly<AgentOptions>): Promise<JsonValue>;
+        create: (options: Readonly<AgentOptions & {
+            name: string;
+        }>) => AgentHandle;
     };
     shell: (command: string, options?: ShellOptions) => Promise<ShellResult>;
     prompt: (template: string, values: Readonly<Record<string, JsonValue>>) => string;
@@ -616,6 +620,8 @@ export interface WorkflowAgentSession {
     getState(): Readonly<WorkflowAgentSessionState>;
     getSessionStats(): WorkflowAgentSessionStats;
     getLastAssistant(): WorkflowAgentMessage | undefined;
+    /** Set by a transport that already delivered `PreparedAgentSession.turnControl` itself; otherwise the runner steers it before the first prompt. */
+    readonly turnControlDelivered?: boolean;
     subscribe(listener: (event: WorkflowAgentSessionEvent) => void): () => void;
     subscribeAsync?(listener: (event: WorkflowAgentSessionEvent) => void | Promise<void>): () => void;
     prompt(text: string): Promise<WorkflowAgentTurnResult>;
@@ -632,7 +638,8 @@ export interface WorkflowAgentSession {
 type SessionTools = NonNullable<CreateAgentSessionOptions["tools"]>;
 type SessionCustomTools = NonNullable<CreateAgentSessionOptions["customTools"]>;
 export interface SessionInput {
-    cwd: string;
+    /** Read-only: setup hooks cannot move an agent, because Pi derives trust, settings and `.pi` resources from cwd. */
+    readonly cwd: string;
     model: ModelSpec;
     tools: SessionTools;
     sessionLabel: string;
@@ -661,6 +668,8 @@ export interface PreparedAgentSession {
     readonly sessionLabel: string;
     readonly sessionPath?: string;
     readonly initialPrompt?: string;
+    /** Dynamic per-attempt control text (retry state, budget). The runner steers it before the first prompt unless the session reports `turnControlDelivered`. */
+    readonly turnControl?: string;
     readonly agentDir?: string;
     readonly customTools?: readonly ToolDefinition[];
     readonly resultTool?: ToolDefinition;
@@ -707,6 +716,64 @@ export interface AgentSetupContext {
     readonly mode?: AgentInspectionMode;
     readonly settings: Readonly<WorkflowExtensionSettings>;
 }
+export interface AgentPreparation {
+    label?: string;
+    model?: string;
+    tools: string[];
+    skills: string[];
+    extensions: string[];
+    contextFiles?: ContextFileScope[];
+    systemPrompt?: string;
+    systemPromptAppend: string;
+    settings: WorkflowExtensionSettings;
+}
+export interface AgentPreparationContext {
+    readonly options: Readonly<AgentOptions>;
+    readonly cwd: string;
+    /** Launch project root that owns project configuration; differs from `cwd` inside worktree scopes. Optional for older hosts. */
+    readonly projectCwd?: string;
+    readonly agentDir: string;
+    readonly projectTrusted: boolean;
+    /** `dynamicModelAliasNames` lists the `modelAliases` entries resolved by extensions rather than read from static settings. */
+    readonly defaults: Readonly<{
+        model: ModelSpec;
+        modelAliases: Readonly<Record<string, string>>;
+        dynamicModelAliasNames?: readonly string[];
+        selectorSources: AgentResourceSelectorSources;
+        settings: Readonly<WorkflowExtensionSettings>;
+    }>;
+    readonly capabilities: Readonly<{
+        tools: readonly string[];
+        skills: readonly string[];
+        extensions: readonly string[];
+    }>;
+    readonly knownModels: ReadonlySet<string>;
+    readonly availableModels: ReadonlySet<string>;
+    readonly signal: AbortSignal;
+    readonly mode: AgentInspectionMode;
+}
+export interface AgentPreparationHook {
+    priority?: number;
+    optionsSchema?: JsonSchema;
+    prepare: (configuration: AgentPreparation, context: Readonly<AgentPreparationContext>) => void | Promise<void>;
+}
+/** `source` is the registering extension's module provenance, when it declared one. */
+export interface RegisteredAgentPreparationHook {
+    name: string;
+    priority: number;
+    optionsSchema?: JsonSchema;
+    source?: string;
+    prepare: AgentPreparationHook["prepare"];
+}
+/**
+ * `excludeTools` holds the exact tool names the agent and its ancestors excluded, frozen with the configuration so setup and
+ * children apply them even when re-evaluated options change. It is absent only in configurations prepared before it existed, which cannot resume.
+ */
+export interface PreparedAgentConfiguration extends Omit<AgentPreparation, "model"> {
+    model: ModelSpec;
+    projectTrusted: boolean;
+    excludeTools?: string[];
+}
 export interface AgentSetupHook {
     priority?: number;
     setup: (agent: AgentSetup, context: Readonly<AgentSetupContext>) => void | Promise<void>;
@@ -725,11 +792,6 @@ export interface WorkflowFunctionSource {
     readonly export: string;
     readonly dependencies: readonly string[];
 }
-export interface WorkflowRoleDirectoryRegistration {
-    path: string;
-    extension: WorkflowExtensionMetadata;
-    readonly builtin?: true;
-}
 export interface AgentAttemptActionUi {
     notify(message: string, level?: "info" | "warning" | "error"): void;
     confirm(title: string, message: string): Promise<boolean>;
@@ -779,9 +841,9 @@ export interface WorkflowExtension extends WorkflowExtensionMetadata {
     validateSettings?: WorkflowExtensionSettingsValidator;
     functions?: Readonly<Record<string, WorkflowFunction>>;
     modelAliases?: Readonly<Record<string, WorkflowModelAlias>>;
+    agentPreparationHooks?: Readonly<Record<string, AgentPreparationHook>>;
     agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
     agentAttemptActions?: Readonly<Record<string, AgentAttemptAction>>;
-    roleDirectories?: readonly (string | URL)[];
 }
 export interface WorkflowJournal {
     get(path: string): JsonValue | undefined;
@@ -795,7 +857,6 @@ export declare class WorkflowError extends Error {
 export interface WorkflowFailureAgent {
     id: string;
     label?: string;
-    role?: string;
     structuralPath: readonly string[];
     attempt: number;
     transport?: string;
@@ -804,7 +865,6 @@ export interface WorkflowFailureAgent {
 export interface WorkflowSiblingAgent {
     id: string;
     label?: string;
-    role?: string;
     structuralPath: readonly string[];
 }
 export interface WorkflowFailureDiagnostics {
@@ -893,7 +953,6 @@ export interface StaticWorkflowCall {
     prompt: string | null;
     model: string | null;
     label?: string | null;
-    role: string | null;
     retries?: number | null;
     outputSchema?: JsonSchema | null;
     options?: Readonly<Record<string, JsonValue>> | null;
@@ -980,8 +1039,5 @@ export interface WorkflowValidationContext {
 export interface ValidatedWorkflowLaunch {
     script: string;
     checked: PreflightResult;
-    agentDefinitions: Readonly<Record<string, AgentDefinition>>;
-    projectAgentDefinitions: Readonly<Record<string, AgentDefinition>>;
-    roleNames: readonly string[];
 }
 export {};

package/dist/src/types.js

@@ -17,18 +17,15 @@ export const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
 export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
 export const WORKFLOW_BLOCKED_EVENT = "workflow:blocked";
 export const ERROR_CODES = [
-    "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE",
+    "CONFIG_ERROR", "INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT",
     "RUN_OWNED", "RUN_NOT_FOUND", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "AGENT_RESULT_COLLECTED", "RESULT_INVALID",
     "TOOL_FAILED", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
 ];
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-export function roleNameOf(value) {
-    return typeof value === "string" ? value : undefined;
-}
-export const BUDGET_DIMENSIONS = ["tokens", "costUsd", "durationMs", "agentLaunches"];
-export const BUDGET_EVENT_TYPES = ["soft_crossed", "hard_overrun", "hard_exhausted", "adjustment_requested", "adjustment_approved", "adjustment_rejected"];
 export const CONTEXT_FILE_SCOPES = ["global", "project", "cwd"];
 export function isContextFileScope(value) { return CONTEXT_FILE_SCOPES.some((scope) => scope === value); }
+export const BUDGET_DIMENSIONS = ["tokens", "costUsd", "durationMs", "agentLaunches"];
+export const BUDGET_EVENT_TYPES = ["soft_crossed", "hard_overrun", "hard_exhausted", "adjustment_requested", "adjustment_approved", "adjustment_rejected"];
 export const WORKFLOW_AGENT_STALL_THRESHOLD_MS = 10 * 60 * 1000;
 export function zeroAccounting() { return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 }; }
 export function addAccounting(left, right) { return { input: left.input + right.input, output: left.output + right.output, cacheRead: left.cacheRead + right.cacheRead, cacheWrite: left.cacheWrite + right.cacheWrite, cost: left.cost + right.cost }; }
@@ -38,7 +35,7 @@ export function sumAccounting(values) {
         total = addAccounting(total, value);
     return total;
 }
-export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 6;
 export function defineWorkflowFunction(workflowFunction) { return workflowFunction; }
 // The brand keeps instanceof working across the bundled extension entries, which each inline their own copy of this class.
 const WORKFLOW_ERROR_BRAND = Symbol.for("pi-extensible-workflows.workflow-error");

package/dist/src/utils.d.ts

@@ -1,4 +1,5 @@
-import { WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type ThinkingLevel, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
+import { WorkflowError, type JsonSchema, type JsonValue, type ModelSpec, type WorkflowErrorCode, type WorkflowExtensionSettings } from "./types.js";
+import { type ThinkingLevel } from "./types.js";
 export declare class SerialLane {
     #private;
     run<T>(task: () => Promise<T>): Promise<T>;
@@ -46,6 +47,7 @@ export declare function modelAliasName(value: string, aliases: Readonly<Record<s
 export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
 export declare function unknownModel(value: string, target: string | undefined, settingsPath?: string): never;
 export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
+export declare function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string;
 type ToolSource = {
     getActiveTools(): string[];
     getAllTools?(): readonly {
@@ -63,7 +65,6 @@ export declare function reachableTools(pi: ToolSource): string[];
 export declare const VIRTUAL_MODEL_PROVIDER = "workflow";
 /** Child sessions do not load the workflow extension, so they receive the alias target instead of its virtual model. */
 export declare function physicalModel(spec: ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
-export declare function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string;
 export declare function aliasDrift(previous: Readonly<Record<string, string>>, current: Readonly<Record<string, string>>): string[];
 export declare function validateResourcePattern(pattern: string): void;
 export declare function resourcePatternMatches(resource: string, pattern: string): boolean;