pi-extensible-workflows 0.3.2 → 1.0.0

package/dist/src/doctor.d.ts

@@ -1,4 +1,4 @@
-import { type WorkflowScriptDefinition, type WorkflowSettings } from "./index.js";
+import { type AgentResourcePolicy, type WorkflowScriptDefinition, type WorkflowSettings } from "./index.js";
 export type DoctorSeverity = "error" | "warning";
 export interface DoctorDiagnostic {
     severity: DoctorSeverity;
@@ -34,6 +34,8 @@ export interface DoctorPiState {
         path?: string;
         message: string;
     }[];
+    extensions?: readonly string[];
+    skills?: readonly string[];
     workflows: Readonly<Record<string, WorkflowScriptDefinition>>;
 }
 export interface DoctorReport {
@@ -45,6 +47,7 @@ export interface DoctorReport {
     activeTools: readonly string[];
     roles: readonly DoctorRole[];
     workflows: readonly DoctorWorkflow[];
+    resourcePolicy: AgentResourcePolicy;
     diagnostics: readonly DoctorDiagnostic[];
 }
 export interface DoctorOptions {

package/dist/src/doctor.js

@@ -2,7 +2,7 @@ import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { ModelRuntime, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_SETTINGS, loadSettings, parseModelReference, parseRoleMarkdown, preflight, registeredWorkflowDefinitions, workflowRoleDirectories, workflowSettingsPath, WorkflowError, } from "./index.js";
+import { DEFAULT_SETTINGS, loadSettings, parseModelReference, resolveAgentResourcePolicy, resolveModelReference, parseRoleMarkdown, preflight, registeredWorkflowDefinitions, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, WorkflowError, } from "./index.js";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
 function canonical(path) {
     const absolute = resolve(path);
@@ -65,7 +65,7 @@ async function discoverPi(cwd, agentDir) {
             agentDir,
             settingsManager,
             modelRuntime,
-            resourceLoaderOptions: { noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true },
+            resourceLoaderOptions: { noPromptTemplates: true, noThemes: true, noContextFiles: true },
             resourceLoaderReloadOptions: { resolveProjectTrust: async () => trusted },
         });
         const allModels = services.modelRuntime.getModels();
@@ -76,11 +76,14 @@ async function discoverPi(cwd, agentDir) {
         const { session } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(), model });
         const activeTools = session.agent.state.tools.map(({ name }) => name).filter((name) => name !== "workflow" && name !== "workflow_respond" && name !== "workflow_catalog");
         const extensions = services.resourceLoader.getExtensions();
+        const skills = services.resourceLoader.getSkills().skills;
         return {
             trust: { required, trusted, source },
             activeTools,
             knownModels: allModels.map(({ provider, id }) => `${provider}/${id}`),
             availableModels: availableModels.map(({ provider, id }) => `${provider}/${id}`),
+            extensions: extensions.extensions.map(({ resolvedPath }) => resolvedPath),
+            skills: skills.map(({ name }) => name),
             extensionErrors: [
                 ...extensions.errors.map(({ path, error }) => ({ path, message: error })),
                 ...services.diagnostics.filter(({ type }) => type === "error").map(({ message }) => ({ message })),
@@ -112,9 +115,13 @@ function roleFilesFrom(dirs) {
 function diagnostic(severity, code, message, source, hint) {
     return { severity, code, message, ...(source ? { source } : {}), ...(hint ? { hint } : {}) };
 }
-function validateModel(value, known, available, source, diagnostics) {
+function emptyResourcePolicy(globalSettingsPath, cwd, projectTrusted) {
+    const empty = { skills: [], extensions: [] };
+    return { globalSettingsPath, projectSettingsPath: workflowProjectSettingsPath(cwd), projectTrusted, global: empty, project: empty, effective: empty, unmatchedSkills: [], unmatchedExtensions: [] };
+}
+function validateModel(value, known, available, source, diagnostics, aliases, settingsPath) {
     try {
-        const parsed = parseModelReference(value);
+        const parsed = resolveModelReference(value, aliases, known, settingsPath);
         const name = `${parsed.provider}/${parsed.model}`;
         if (!known.has(name) || !available.has(name))
             diagnostics.push(diagnostic("warning", "MODEL_UNAVAILABLE", `Model is valid-shaped but unavailable: ${name}`, source));
@@ -123,10 +130,10 @@ function validateModel(value, known, available, source, diagnostics) {
         diagnostics.push(diagnostic("error", "MODEL_INVALID", error.message, source, error.message.includes("thinking") ? THINKING_HINT : "Use provider/model or provider/model:thinking."));
     }
 }
-function inspectRole(path, activeTools, knownModels, availableModels, diagnostics) {
+function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath) {
     let definition;
     try {
-        definition = parseRoleMarkdown(readFileSync(path, "utf8"), true);
+        definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
     }
     catch (error) {
         diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", error.message, path, "Fix the role YAML frontmatter."));
@@ -140,7 +147,7 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
     if (/{{\s*[^{}]+\s*}}/.test(body))
         diagnostics.push(diagnostic("warning", "ROLE_PLACEHOLDER", "Role body contains an unsupported placeholder-looking token", path));
     if (definition.model)
-        validateModel(definition.model, knownModels, availableModels, path, diagnostics);
+        validateModel(definition.model, knownModels, availableModels, path, diagnostics, aliases, settingsPath);
     for (const tool of definition.tools ?? [])
         if (!activeTools.has(tool))
             diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Active tools or enable its Pi extension."));
@@ -149,6 +156,14 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
 class DoctorModelSet extends Set {
     has(value) { parseModelReference(value); return true; }
 }
+function matchResourcePolicy(policy, pi) {
+    const extensions = new Set((pi.extensions ?? []).map(canonical));
+    const skills = new Set(pi.skills ?? []);
+    return { ...policy, unmatchedSkills: policy.effective.skills.filter((name) => !skills.has(name)), unmatchedExtensions: policy.effective.extensions.filter((path) => !extensions.has(canonical(path))) };
+}
+function resourcePolicySource(policy, kind, selector) {
+    return policy.project[kind].includes(selector) && !policy.global[kind].includes(selector) ? policy.projectSettingsPath : policy.globalSettingsPath;
+}
 export async function doctor(options = {}) {
     const cwd = canonical(options.cwd ?? process.cwd());
     const agentDir = canonical(options.agentDir ?? getAgentDir());
@@ -175,9 +190,24 @@ export async function doctor(options = {}) {
         diagnostics.push(diagnostic("warning", "PROJECT_UNTRUSTED", "Pi project resources are inactive because the project is not trusted", cwd, "Open this project in Pi, choose Trust, then rerun doctor."));
     for (const error of pi.extensionErrors)
         diagnostics.push(diagnostic("error", "EXTENSION_LOAD", error.message, error.path, "Fix or disable the failing Pi extension."));
+    let resourcePolicy;
+    try {
+        resourcePolicy = matchResourcePolicy(resolveAgentResourcePolicy(cwd, pi.trust.trusted, settingsPath), pi);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!diagnostics.some(({ code, source }) => code === "SETTINGS_INVALID" && source === settingsPath))
+            diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, message.includes(".json") ? message.match(/(?:settings: )?([^ )]+\.json)/)?.[1] : undefined, "Fix or remove the invalid workflow settings file."));
+        resourcePolicy = emptyResourcePolicy(settingsPath, cwd, pi.trust.trusted);
+    }
+    for (const skill of resourcePolicy.unmatchedSkills)
+        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled skill selector currently matches no discovered skill: ${skill}`, `${resourcePolicySource(resourcePolicy, "skills", skill)}.disabledAgentResources.skills`));
+    for (const extension of resourcePolicy.unmatchedExtensions)
+        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled extension selector currently matches no discovered extension source: ${extension}`, `${resourcePolicySource(resourcePolicy, "extensions", extension)}.disabledAgentResources.extensions`));
     const activeTools = new Set(pi.activeTools);
     const knownModels = new Set(pi.knownModels);
     const availableModels = new Set(pi.availableModels);
+    const aliases = settings.modelAliases ?? {};
     const roles = [];
     const definitions = new Map();
     const globalPaths = new Map();
@@ -186,7 +216,7 @@ export async function doctor(options = {}) {
         const name = basename(path, ".md");
         roles.push({ name, path, scope: "global", active: true });
         globalPaths.set(name, path);
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics);
+        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
         if (definition)
             definitions.set(name, definition);
     }
@@ -204,7 +234,7 @@ export async function doctor(options = {}) {
                 global.overriddenBy = path;
             }
         }
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics);
+        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
         if (definition)
             definitions.set(name, definition);
         else
@@ -218,6 +248,9 @@ export async function doctor(options = {}) {
                 models: new DoctorModelSet(pi.knownModels),
                 tools: activeTools,
                 agentTypes: new Set(definitions.keys()),
+                modelAliases: aliases,
+                knownModels,
+                settingsPath,
             }, [], { name, description: workflow.description });
             for (const model of checked.referenced.models)
                 if (!knownModels.has(model) || !availableModels.has(model))
@@ -233,7 +266,7 @@ export async function doctor(options = {}) {
     const severityOrder = { error: 0, warning: 1 };
     diagnostics.sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity] || (left.source ?? "").localeCompare(right.source ?? "") || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
     roles.sort((left, right) => left.name.localeCompare(right.name) || left.scope.localeCompare(right.scope));
-    return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, workflows, diagnostics };
+    return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, workflows, resourcePolicy, diagnostics };
 }
 function count(report, severity) { return report.diagnostics.filter((item) => item.severity === severity).length; }
 export function doctorExitCode(report) { return count(report, "error") > 0 ? 1 : 0; }
@@ -245,11 +278,23 @@ export function formatDoctorReport(report) {
         `- CWD: \`${report.cwd}\``,
         `- Agent dir: \`${report.agentDir}\``,
         `- Workflow settings: \`${report.settingsPath}\``,
-        `- Limits: concurrency=${String(report.settings.concurrency)}, maxAgentLaunches=${String(report.settings.maxAgentLaunches)}`,
+        `- Limits: concurrency=${String(report.settings.concurrency)}`,
         "",
         "## Trust/resources",
         `- [${report.trust.trusted ? "ok" : "warning"}] ${report.trust.source}`,
         "",
+        "## Agent resource exclusions",
+        `- Global settings: \`${report.resourcePolicy.globalSettingsPath}\``,
+        `- Global skills: ${report.resourcePolicy.global.skills.join(", ") || "(none)"}`,
+        `- Global extensions: ${report.resourcePolicy.global.extensions.join(", ") || "(none)"}`,
+        `- Project settings: \`${report.resourcePolicy.projectSettingsPath}\` (${report.resourcePolicy.projectTrusted ? "trusted" : "ignored: project untrusted"})`,
+        `- Project skills: ${report.resourcePolicy.project.skills.join(", ") || "(none)"}`,
+        `- Project extensions: ${report.resourcePolicy.project.extensions.join(", ") || "(none)"}`,
+        `- Effective skills: ${report.resourcePolicy.effective.skills.join(", ") || "(none)"}`,
+        `- Effective extensions: ${report.resourcePolicy.effective.extensions.join(", ") || "(none)"}`,
+        `- Unmatched skills: ${report.resourcePolicy.unmatchedSkills.join(", ") || "(none)"}`,
+        `- Unmatched extensions: ${report.resourcePolicy.unmatchedExtensions.join(", ") || "(none)"}`,
+        "",
         "## Active tools",
         ...(report.activeTools.length ? report.activeTools.map((tool) => `- \`${tool}\``) : ["- None resolved"]),
         "",

package/dist/src/index.d.ts

@@ -1,13 +1,23 @@
 import { Type } from "@earendil-works/pi-ai";
 import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { type AgentActivity, type AgentAttempt, type AgentDefinition, type SessionFactory } from "./agent-execution.js";
+import { type AgentActivity, type AgentAccounting, type AgentAttempt, type AgentBudgetHooks, type AgentDefinition, type AgentSetupHook, type RegisteredAgentSetupHook, type SessionFactory } from "./agent-execution.js";
 import { RunStore } from "./persistence.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
-export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted"];
+export declare const RUN_STATES: readonly ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
 export declare const AGENT_STATES: readonly ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
 export declare const WORKFLOW_ASYNC_STARTED_EVENT = "workflow:async-started";
 export declare const WORKFLOW_ASYNC_COMPLETE_EVENT = "workflow:async-complete";
-export declare const ERROR_CODES: readonly ["INVALID_SETTINGS", "INVALID_SYNTAX", "INVALID_METADATA", "DUPLICATE_NAME", "INVALID_SCHEMA", "UNKNOWN_MODEL", "UNKNOWN_TOOL", "UNKNOWN_AGENT_TYPE", "RUN_LIMIT_EXCEEDED", "RUN_OWNED", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "INTERNAL_ERROR"];
+export declare const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
+export declare const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
+export declare const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
+export declare const WORKFLOW_RUN_COMPLETED_EVENT = "workflow:run-completed";
+export declare const WORKFLOW_RUN_FAILED_EVENT = "workflow:run-failed";
+export declare const WORKFLOW_AGENT_STATE_CHANGED_EVENT = "workflow:agent-state-changed";
+export declare const WORKFLOW_PHASE_CHANGED_EVENT = "workflow:phase-changed";
+export declare const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpoint-state-changed";
+export declare const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
+export declare const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
+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", "REGISTRY_FROZEN", "GLOBAL_COLLISION", "MISSING_WORKFLOW", "RPC_LIMIT_EXCEEDED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID", "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR"];
 export type RunState = (typeof RUN_STATES)[number];
 export type AgentState = (typeof AGENT_STATES)[number];
 export type WorkflowErrorCode = (typeof ERROR_CODES)[number];
@@ -17,10 +27,100 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
 export type JsonSchema = {
     [key: string]: JsonValue;
 };
+export type BudgetDimension = "tokens" | "costUsd" | "durationMs" | "agentLaunches";
+export interface BudgetLimits {
+    soft?: number;
+    hard?: number;
+}
+export type WorkflowBudget = Partial<Record<BudgetDimension, BudgetLimits>>;
+export type WorkflowBudgetPatch = Partial<Record<BudgetDimension, BudgetLimits | {
+    soft?: number | null;
+    hard?: number | null;
+} | null>>;
+export interface WorkflowBudgetUsage {
+    tokens: number;
+    costUsd: number;
+    durationMs: number;
+    agentLaunches: number;
+}
+export type BudgetEventType = "soft_crossed" | "hard_overrun" | "hard_exhausted" | "adjustment_requested" | "adjustment_approved" | "adjustment_rejected";
+export interface BudgetEvent {
+    type: BudgetEventType;
+    budgetVersion: number;
+    dimensions: readonly BudgetDimension[];
+    usage: WorkflowBudgetUsage;
+    limits: WorkflowBudget;
+    at: number;
+    proposalId?: string;
+    previous?: WorkflowBudget;
+    proposed?: WorkflowBudget;
+}
+export interface BudgetApprovalRequest {
+    kind: "budget";
+    proposalId: string;
+    runId: string;
+    consumed: WorkflowBudgetUsage;
+    previous: WorkflowBudget;
+    proposed: WorkflowBudget;
+    budgetVersion: number;
+}
 export interface WorkflowErrorShape {
     code: WorkflowErrorCode;
     message: string;
 }
+export interface WorkflowEventBase {
+    runId: string;
+    sessionId: string;
+    workflowName: string;
+    cwd: string;
+    runDirectory: string;
+    timestamp: number;
+}
+export type WorkflowRunStartedEvent = WorkflowEventBase;
+export type WorkflowRunResumedEvent = WorkflowEventBase;
+export interface WorkflowRunStateChangedEvent extends WorkflowEventBase {
+    previousState: RunState;
+    state: RunState;
+    reason?: string;
+    errorCode?: WorkflowErrorCode;
+}
+export interface WorkflowRunCompletedEvent extends WorkflowEventBase {
+    resultPath: string;
+}
+export interface WorkflowRunFailedEvent extends WorkflowEventBase {
+    error: WorkflowErrorShape;
+}
+export interface WorkflowAgentStateChangedEvent extends WorkflowEventBase {
+    agentId: string;
+    displayLabel: string;
+    role?: string;
+    structuralPath: readonly string[];
+    parentId?: string;
+    parentBreadcrumb?: string;
+    worktreeOwner?: string;
+    previousState?: AgentState;
+    state: AgentState;
+    attempt: number;
+}
+export interface WorkflowPhaseChangedEvent extends WorkflowEventBase {
+    previousPhase?: string;
+    phase: string;
+}
+export type WorkflowCheckpointState = "awaiting" | "approved" | "rejected";
+export interface WorkflowCheckpointStateChangedEvent extends WorkflowEventBase {
+    name: string;
+    state: WorkflowCheckpointState;
+}
+export interface WorkflowBudgetEvent extends WorkflowEventBase {
+    type: BudgetEventType;
+    budgetVersion: number;
+    dimensions: readonly BudgetDimension[];
+    usage: WorkflowBudgetUsage;
+    limits: WorkflowBudget;
+    proposalId?: string;
+    previous?: WorkflowBudget;
+    proposed?: WorkflowBudget;
+}
 export interface ModelSpec {
     provider: string;
     model: string;
@@ -32,7 +132,34 @@ export interface WorkflowMetadata {
 }
 export interface WorkflowSettings {
     concurrency: number;
-    maxAgentLaunches: number;
+    modelAliases?: Readonly<Record<string, string>>;
+    disabledAgentResources?: Readonly<AgentResourceExclusions>;
+}
+export interface AgentResourceExclusions {
+    skills: readonly string[];
+    extensions: readonly string[];
+}
+export interface AgentResourcePolicy {
+    globalSettingsPath: string;
+    projectSettingsPath: string;
+    projectTrusted: boolean;
+    global: AgentResourceExclusions;
+    project: AgentResourceExclusions;
+    effective: AgentResourceExclusions;
+    unmatchedSkills: string[];
+    unmatchedExtensions: string[];
+}
+export interface AgentSetupSummary {
+    hookNames: readonly string[];
+    model: ModelSpec;
+    tools: readonly string[];
+    cwd: string;
+    disabledAgentResources?: {
+        skills: readonly string[];
+        extensions: readonly string[];
+        unmatchedSkills: readonly string[];
+        unmatchedExtensions: readonly string[];
+    };
 }
 export interface AgentAttemptSummary {
     attempt: number;
@@ -49,6 +176,13 @@ export interface AgentAttemptSummary {
         cacheWrite: number;
         cost: number;
     };
+    setup?: AgentSetupSummary;
+}
+export interface WorkflowWorktreeCreatedEvent extends WorkflowEventBase {
+    owner: string;
+    branch: string;
+    path: string;
+    base: string;
 }
 export interface AgentRecord {
     id: string;
@@ -57,8 +191,11 @@ export interface AgentRecord {
     path: string;
     state: AgentState;
     parentId?: string;
+    structuralPath?: readonly string[];
     parentBreadcrumb?: string;
+    worktreeOwner?: string;
     role?: string;
+    requestedModel?: string;
     model: ModelSpec;
     tools: readonly string[];
     attempts: number;
@@ -77,6 +214,10 @@ export interface AgentRecord {
     }[];
     activity?: AgentActivity | undefined;
 }
+export interface WorkflowRunEvent {
+    type: "warning";
+    message: string;
+}
 export interface RunRecord {
     id: string;
     workflowName: string;
@@ -86,13 +227,22 @@ export interface RunRecord {
     phase?: string;
     agents: readonly AgentRecord[];
     error?: WorkflowErrorShape;
+    budget?: WorkflowBudget;
+    budgetVersion?: number;
+    usage?: WorkflowBudgetUsage;
+    budgetEvents?: readonly BudgetEvent[];
+    events?: readonly WorkflowRunEvent[];
 }
+export declare const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 3;
 export interface LaunchSnapshot {
     identityVersion?: number;
     script: string;
     args: JsonValue;
     metadata: WorkflowMetadata;
     settings: WorkflowSettings;
+    budget?: WorkflowBudget;
+    settingsPath?: string;
+    modelAliases?: Readonly<Record<string, string>>;
     models: readonly string[];
     tools: readonly string[];
     agentTypes: readonly string[];
@@ -104,6 +254,10 @@ export interface PreflightCapabilities {
     models: ReadonlySet<string>;
     tools: ReadonlySet<string>;
     agentTypes: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    knownModels?: ReadonlySet<string>;
+    settingsPath?: string;
+    skipModelAvailability?: boolean;
 }
 export interface PreflightResult {
     metadata: WorkflowMetadata;
@@ -153,13 +307,13 @@ export interface WorkflowScriptDefinition {
     script: string;
 }
 export interface WorkflowExtension {
-    namespace: string;
     version: string;
     headline: string;
     description: string;
     functions?: Readonly<Record<string, WorkflowFunction>>;
     variables?: Readonly<Record<string, WorkflowVariable>>;
     workflows?: Readonly<Record<string, WorkflowScriptDefinition>>;
+    agentSetupHooks?: Readonly<Record<string, AgentSetupHook>>;
 }
 export interface WorkflowJournal {
     get(path: string): JsonValue | undefined;
@@ -173,7 +327,7 @@ export declare function formatWorkflowFailure(error: unknown): string;
 export declare class RunLifecycle {
     #private;
     private readonly changed?;
-    constructor(state?: RunState, changed?: ((state: RunState) => void | Promise<void>) | undefined);
+    constructor(state?: RunState, changed?: ((state: RunState, previousState: RunState, reason?: string) => void | Promise<void>) | undefined);
     get state(): RunState;
     enter(): Promise<void>;
     leave(): Promise<void>;
@@ -182,10 +336,43 @@ export declare class RunLifecycle {
     pause(): Promise<void>;
     resume(): Promise<void>;
     providerPause(): Promise<void>;
-    terminal(state: "completed" | "failed" | "stopped" | "interrupted"): Promise<void>;
+    terminal(state: "completed" | "failed" | "stopped" | "interrupted" | "budget_exhausted", reason?: string): Promise<void>;
 }
 export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
+export declare function validateBudget(value: unknown): WorkflowBudget | undefined;
+export declare function validateBudgetPatch(value: unknown): WorkflowBudgetPatch;
+export declare class WorkflowBudgetRuntime {
+    #private;
+    readonly budget: WorkflowBudget | undefined;
+    readonly version: number;
+    constructor(budget: WorkflowBudget | undefined, version?: number, usage?: Partial<WorkflowBudgetUsage>, events?: readonly BudgetEvent[], options?: {
+        now?: () => number;
+        onChange?: () => void;
+        active?: boolean;
+    });
+    get usage(): WorkflowBudgetUsage;
+    get events(): readonly BudgetEvent[];
+    get hardExhausted(): boolean;
+    checkAgentLaunch(): void;
+    beforeAttempt(): void;
+    beforeTurn(): void;
+    afterTurn(accounting: AgentAccounting, final: boolean): void;
+    instruction(agentId?: string): string | undefined;
+    forAgent(agentId: string): AgentBudgetHooks;
+    transition(state: RunState): void;
+    recordEvent(event: BudgetEvent): void;
+    snapshot(): {
+        usage: WorkflowBudgetUsage;
+        budgetEvents: readonly BudgetEvent[];
+    };
+}
+export declare function mergeBudget(budget: WorkflowBudget | undefined, patch: WorkflowBudgetPatch): WorkflowBudget | undefined;
+export declare function budgetRelaxed(previous: WorkflowBudget | undefined, next: WorkflowBudget | undefined): boolean;
+export declare function exhaustedBudgetDimensions(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): BudgetDimension[];
+export declare function resumeBudgetAllowed(budget: WorkflowBudget | undefined, usage: WorkflowBudgetUsage): boolean;
 export declare function parseModelReference(value: string): ModelSpec;
+export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
+export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
 export interface CheckpointInput {
     name: string;
     prompt: string;
@@ -193,8 +380,12 @@ export interface CheckpointInput {
 }
 export declare function validateCheckpoint(value: unknown): CheckpointInput;
 export declare function workflowSettingsPath(agentDir?: string): string;
+export declare function workflowProjectSettingsPath(cwd: string): string;
+export declare function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions;
 export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
-export declare function parseRoleMarkdown(content: string, strict?: boolean): AgentDefinition;
+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 parseRoleMarkdown(content: string, strict?: boolean, rolePath?: string): AgentDefinition;
 export declare function workflowRoleDirectories(agentDir?: string): readonly string[];
 export declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean): Readonly<Record<string, AgentDefinition>>;
 export type StaticWorkflowExecution = "parallel" | "sequential";
@@ -204,7 +395,7 @@ export interface StaticWorkflowScope {
     key: string | null;
 }
 export interface StaticWorkflowCall {
-    kind: "agent" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
+    kind: "agent" | "conversation" | "parallel" | "pipeline" | "checkpoint" | "phase" | "withWorktree";
     start: number;
     end: number;
     name: string | null;
@@ -222,7 +413,6 @@ export interface StaticWorkflowCall {
 export declare function inspectWorkflowScript(script: string): StaticWorkflowCall[];
 export interface WorkflowCatalogFunction {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -232,7 +422,6 @@ export interface WorkflowCatalogFunction {
 }
 export interface WorkflowCatalogVariable {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -241,7 +430,6 @@ export interface WorkflowCatalogVariable {
 }
 export interface WorkflowCatalogWorkflow {
     name: string;
-    namespace: string;
     version: string;
     headline: string;
     extensionDescription: string;
@@ -251,6 +439,7 @@ export interface WorkflowCatalog {
     functions: readonly WorkflowCatalogFunction[];
     variables: readonly WorkflowCatalogVariable[];
     workflows: readonly WorkflowCatalogWorkflow[];
+    modelAliases?: Readonly<Record<string, string>>;
 }
 export declare class WorkflowRegistry {
     #private;
@@ -261,15 +450,14 @@ export declare class WorkflowRegistry {
     workflows(): Readonly<Record<string, WorkflowScriptDefinition>>;
     catalog(): WorkflowCatalog;
     globals(): Readonly<Record<string, {
-        namespace: string;
         name: string;
     }>>;
-    invokeFunction(namespace: string, name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
+    invokeFunction(name: string, input: unknown, context: Readonly<WorkflowFunctionContext>, path: string, journal: WorkflowJournal): Promise<JsonValue>;
     variables(): readonly {
-        namespace: string;
         name: string;
         variable: WorkflowVariable;
     }[];
+    agentSetupHooks(): readonly RegisteredAgentSetupHook[];
 }
 export declare function registerWorkflowExtension(extension: WorkflowExtension): void;
 export declare function workflowCatalog(): WorkflowCatalog;
@@ -291,7 +479,7 @@ export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     args: Type.TOptional<Type.TUnknown>;
     foreground: Type.TOptional<Type.TBoolean>;
     concurrency: Type.TOptional<Type.TInteger>;
-    maxAgentLaunches: Type.TOptional<Type.TInteger>;
+    budget: Type.TOptional<Type.TUnknown>;
 }>;
 export declare function preflight(script: string, capabilities: PreflightCapabilities, schemas?: readonly unknown[], metadata?: WorkflowMetadata): PreflightResult;
 export interface WorkflowValidationParameters {
@@ -305,6 +493,9 @@ export interface WorkflowValidationContext {
     projectTrusted: boolean;
     availableModels: ReadonlySet<string>;
     rootTools: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    knownModels?: ReadonlySet<string>;
+    settingsPath?: string;
 }
 export interface ValidatedWorkflowLaunch {
     script: string;
@@ -327,13 +518,16 @@ export interface AgentIdentity {
     occurrence: number;
     parentBreadcrumb?: string;
     worktreeOwner?: string;
+    conversation?: {
+        name: string;
+        turn: number;
+    };
 }
 export interface WorkflowBridge {
     agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
     checkpoint?: (input: Readonly<Record<string, JsonValue>>, signal: AbortSignal) => boolean | Promise<boolean>;
-    function?: (namespace: string, name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string) => Promise<JsonValue>;
+    function?: (name: string, input: Readonly<Record<string, JsonValue>>, path: string, signal: AbortSignal, worktreeOwner?: string, structuralPath?: readonly string[]) => Promise<JsonValue>;
     functions?: Readonly<Record<string, {
-        namespace: string;
         name: string;
     }>>;
     variables?: Readonly<Record<string, JsonValue>>;
@@ -345,18 +539,19 @@ export interface WorkflowExecution {
     cancel: () => void;
 }
 export declare function runWorkflow(script: string, args?: JsonValue, bridge?: WorkflowBridge, signal?: AbortSignal): WorkflowExecution;
-export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile">): Promise<void>;
+export declare function persistActiveAgentAttempt(store: RunStore, id: string, active: Pick<AgentAttempt, "attempt" | "sessionId" | "sessionFile" | "setup">): Promise<void>;
 export declare function persistAgentAttempts(store: RunStore, id: string, attempts: readonly AgentAttempt[]): Promise<void>;
 export declare function formatWorkflowProgress(run: PersistedRun, spinner?: string): string;
+export declare function formatBudgetStatus(run: Pick<PersistedRun, "budget" | "budgetVersion" | "usage" | "budgetEvents">): string[];
 export declare function formatNavigatorDashboard(run: PersistedRun, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
 export declare function formatNavigatorRun(loaded: {
     run: PersistedRun;
     snapshot: Readonly<LaunchSnapshot>;
-}, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
+}, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string;
 export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory): void;
 export { acquireSessionLease, projectStorageKey, RunStore, runsDirectory, SessionLease, structuralPath } from "./persistence.js";
-export type { AwaitingCheckpoint, CompletedOperation, NativeSessionReference, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
+export type { AwaitingCheckpoint, CompletedOperation, ConversationHead, NativeSessionReference, PendingWorkflowDecision, PersistedConversation, PersistedOwnershipNode, PersistedRun, WorktreeReference } from "./persistence.js";
 export { FairAgentScheduler, WorkflowAgentExecutor } from "./agent-execution.js";
-export type { AgentAccounting, AgentAttempt, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentToolCallProgress } from "./agent-execution.js";
+export type { AgentAccounting, AgentAttempt, AgentBudgetHooks, AgentDefinition, AgentExecutionOptions, AgentExecutionResult, AgentExecutionRoot, AgentProgress, AgentSetup, AgentSetupContext, AgentSetupHook, AgentToolCallProgress, RegisteredAgentSetupHook, SessionInput } from "./agent-execution.js";
 export { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 export type { DoctorDiagnostic, DoctorOptions, DoctorPiState, DoctorReport, DoctorRole, DoctorSeverity, DoctorTrust, DoctorWorkflow } from "./doctor.js";