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

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", "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 {
@@ -215,9 +216,11 @@ export interface WorkflowRetentionSettings {
     olderThanDays?: number;
     maxTerminalRuns?: number;
 }
+export type CodemodeToolsSetting = "all" | "read-only" | "none";
 export interface WorkflowSettings {
     concurrency: number;
     backgroundWidget?: boolean;
+    codemodeTools?: CodemodeToolsSetting;
     modelAliases?: Readonly<Record<string, string>>;
     skills?: readonly string[];
     extensions?: readonly string[];
@@ -226,7 +229,7 @@ export interface WorkflowSettings {
     retention?: Readonly<WorkflowRetentionSettings>;
     worktreePostCreateCommand?: readonly string[];
 }
-export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget">>;
+export type WorkflowSettingsOverrides = Partial<Omit<WorkflowSettings, "backgroundWidget" | "codemodeTools">>;
 export interface WorkflowSettingsSources {
     concurrency: string;
     modelAliases: string;
@@ -238,6 +241,7 @@ export interface WorkflowSettingsSources {
     worktreePostCreateCommand?: string;
 }
 export interface WorkflowSettingsResolution {
+    selectorSources?: AgentResourceSelectorSources;
     globalSettingsPath: string;
     projectSettingsPath: string;
     projectTrusted: boolean;
@@ -259,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;
@@ -279,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;
@@ -354,7 +361,6 @@ export interface AgentRecord {
     handle?: string;
     turn?: number;
     continuity?: AgentContinuity;
-    role?: string;
     requestedModel?: string;
     model: ModelSpec;
     tools: readonly string[];
@@ -403,6 +409,21 @@ export interface WorkflowPhaseShellActivity {
     active: number;
     startedAt: number;
 }
+/** A script call recorded for inspection. Tool payloads stay in the replay journal, not this record. Oversized shell inputs are JSON prefixes, with `inputBytes` their full size. */
+export interface WorkflowScriptCall {
+    kind: "shell" | "tool";
+    name: string;
+    path: string;
+    input?: JsonValue;
+    inputBytes?: number;
+    phase?: string;
+    startedAt: number;
+    finishedAt?: number;
+    error?: {
+        code: WorkflowErrorCode;
+        message?: string;
+    };
+}
 export interface RunRecord {
     id: string;
     workflowName: string;
@@ -419,6 +440,11 @@ export interface RunRecord {
     activeShells?: number;
     activeShellStartedAt?: number;
     activeShellsByPhase?: readonly WorkflowPhaseShellActivity[];
+    activeTools?: readonly {
+        name: string;
+        startedAt: number;
+    }[];
+    scriptCalls?: readonly WorkflowScriptCall[];
     error?: WorkflowErrorShape;
     failedAt?: string;
     budget?: WorkflowBudget;
@@ -428,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;
@@ -456,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;
@@ -476,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: {
@@ -487,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;
@@ -594,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>;
@@ -610,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;
@@ -639,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;
@@ -685,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>;
@@ -703,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>;
@@ -757,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;
@@ -773,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;
@@ -782,7 +865,6 @@ export interface WorkflowFailureAgent {
 export interface WorkflowSiblingAgent {
     id: string;
     label?: string;
-    role?: string;
     structuralPath: readonly string[];
 }
 export interface WorkflowFailureDiagnostics {
@@ -835,6 +917,11 @@ export interface ShellIdentity {
     occurrence: number;
     worktreeOwner?: string;
 }
+/** A script `tools.<id>(args)` call: the n-th call of that tool within one structural scope. */
+export interface ToolIdentity {
+    structuralPath: readonly string[];
+    occurrence: number;
+}
 export interface WorkflowBridge {
     agent?: (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
     shell?: (command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
@@ -846,6 +933,7 @@ export interface WorkflowBridge {
     }>>;
     phase?: (name: string) => void | Promise<void>;
     log?: (message: string) => void | Promise<void>;
+    tool?: (identifier: string, args: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: ToolIdentity) => Promise<JsonValue>;
 }
 export interface WorkflowExecution {
     result: Promise<JsonValue>;
@@ -865,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;
@@ -952,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",
-    "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+    "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>;
@@ -6,6 +7,8 @@ export declare class SerialLane {
 export declare function object(value: unknown): value is Record<string, unknown>;
 export declare function sanitizeDisplayText(value: string): string;
 export { object as isObject };
+/** A short digest of a JSON value that ignores object key order. */
+export declare function jsonDigest(value: JsonValue): string;
 export declare function jsonValue(value: unknown, seen?: Set<object>): value is JsonValue;
 export declare function jsonObject(value: unknown): value is Record<string, JsonValue>;
 export declare function mergeWorkflowExtensionSettings(...layers: readonly (Readonly<WorkflowExtensionSettings> | undefined)[]): Readonly<WorkflowExtensionSettings> | undefined;
@@ -45,6 +48,23 @@ export declare function validateModelAliases(value: unknown, settingsPath?: stri
 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 {
+        name: string;
+        exposure?: string;
+    }[];
+};
+/**
+ * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
+ * only codemode scripts call or tool_search loads, such as MCP tools with the default exposure.
+ * Agent sessions allow tools by name, so leaving these out would make them unreachable there.
+ */
+export declare function reachableTools(pi: ToolSource): string[];
+/** Provider of the virtual models that expose workflow model aliases in `/model`. */
+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 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;

package/dist/src/utils.js

@@ -1,5 +1,7 @@
-import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, THINKING_LEVELS, WorkflowError } from "./types.js";
+import { createHash } from "node:crypto";
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError } from "./types.js";
 import { Minimatch } from "minimatch";
+import { THINKING_LEVELS } from "./types.js";
 export class SerialLane {
     #tail = Promise.resolve();
     run(task) {
@@ -17,6 +19,17 @@ export function sanitizeDisplayText(value) { return value.replace(ANSI_ESCAPE_SE
 export { object as isObject };
 function isStringKey(key) { return typeof key === "string"; }
 function stringKeyValue(value, key) { return object(value) ? value[key] : undefined; }
+function sortedJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortedJson);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortedJson(value[key])]));
+}
+/** A short digest of a JSON value that ignores object key order. */
+export function jsonDigest(value) {
+    return createHash("sha256").update(JSON.stringify(sortedJson(value))).digest("hex").slice(0, 16);
+}
 export function jsonValue(value, seen = new Set()) {
     if (value === null || typeof value === "boolean" || typeof value === "string")
         return true;
@@ -91,13 +104,22 @@ export const WORKFLOW_EXTENSION_NAMESPACE = /^[A-Za-z][A-Za-z0-9_-]*$/;
 export function validWorkflowExtensionNamespace(value) { return WORKFLOW_EXTENSION_NAMESPACE.test(value) && value !== "__proto__" && value !== "constructor" && value !== "prototype"; }
 export function parseThinking(value) { return isThinkingLevel(value) ? value : undefined; }
 export function parseModelReference(value) {
-    const match = /^([^/:\s]+)\/([^:\s]+)(?::([^:\s]+))?$/.exec(value);
+    const match = /^([^/:\s]+)\/([^\s]+)$/.exec(value);
     if (!match?.[1] || !match[2])
         fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
-    const thinking = match[3];
-    if (thinking !== undefined && !isThinkingLevel(thinking))
-        fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
-    return { provider: match[1], model: match[2], ...(thinking !== undefined ? { thinking } : {}) };
+    // The model id is everything after the first slash, so namespaced ids such as
+    // `deepseek/deepseek-v4.1-flash:nitro` survive intact. Only a trailing segment
+    // that names a thinking level is one.
+    const reference = match[2];
+    const separator = reference.lastIndexOf(":");
+    const suffix = separator === -1 ? undefined : reference.slice(separator + 1);
+    if (suffix === "")
+        fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+    const thinking = suffix !== undefined && isThinkingLevel(suffix) ? suffix : undefined;
+    const model = thinking === undefined ? reference : reference.slice(0, separator);
+    if (model === "")
+        fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+    return { provider: match[1], model, ...(thinking === undefined ? {} : { thinking }) };
 }
 export function assertModelThinking(value, path = "model") {
     if (value.includes("/") && parseModelReference(value).thinking === undefined)
@@ -182,6 +204,24 @@ export function modelCapability(value, aliases, knownModels, settingsPath) {
     const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
     return `${parsed.provider}/${parsed.model}`;
 }
+/**
+ * Tools a session can reach, and so the ceiling for its agents: the declared tools plus the ones
+ * only codemode scripts call or tool_search loads, such as MCP tools with the default exposure.
+ * Agent sessions allow tools by name, so leaving these out would make them unreachable there.
+ */
+export function reachableTools(pi) {
+    const undeclared = pi.getAllTools?.().filter(({ exposure }) => exposure === "codemode" || exposure === "deferred").map(({ name }) => name) ?? [];
+    return [...new Set([...pi.getActiveTools(), ...undeclared])];
+}
+/** Provider of the virtual models that expose workflow model aliases in `/model`. */
+export 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 function physicalModel(spec, aliases = {}, knownModels, settingsPath) {
+    if (spec.provider !== VIRTUAL_MODEL_PROVIDER || !modelAliasName(spec.model, aliases))
+        return spec;
+    const target = resolveModelReference(spec.model, aliases, knownModels, settingsPath);
+    return spec.thinking === undefined ? target : { ...target, thinking: spec.thinking };
+}
 export function aliasDrift(previous, current) {
     return [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort().flatMap((name) => previous[name] === current[name] ? [] : [`${name}: ${previous[name] ?? "(missing)"} -> ${current[name] ?? "(missing)"}`]);
 }

package/dist/src/validation.d.ts

@@ -1,16 +1,27 @@
 import type { CheckpointInput, JsonValue, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, ValidatedWorkflowLaunch, WorkflowMetadata, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
 import type { WorkflowRegistryApi } from "./registry.js";
 export { validateSchema } from "./utils.js";
-export { loadAgentDefinitions, loadProjectAgentDefinitions, parseRoleMarkdown, workflowRoleDirectories } from "./roles.js";
-export type { WorkflowRoleDirectoryInput } from "./roles.js";
-export { DEFAULT_SETTINGS, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath } from "./settings.js";
+export { DEFAULT_SETTINGS, loadCodemodeToolsSetting, loadSettings, loadSettingsOverrides, resolveAgentResourcePolicy, resolveWorkflowSettings, saveModelAliases, validateContextFileScopes, validateModelAliasAvailability, validateSelectorList, validateWorkflowExtensionSettings, workflowProjectSettingsPath, workflowSettingsPath, workflowToolExposure } from "./settings.js";
 export declare function validateCheckpoint(value: unknown): CheckpointInput;
+/**
+ * The `tools.<id>` members a workflow script names statically. Any other use of `tools`, such as a
+ * local declaration that shadows the global or passing it around, makes the set unknowable: undefined.
+ */
+export declare function scriptToolReferences(script: string): string[] | undefined;
 export declare function instrumentWorkflow(script: string): string;
 export declare function workflowPrompt(template: string, values: Readonly<Record<string, JsonValue>>): string;
+export declare function isCoreAgentOption(key: string): boolean;
 export declare function validateAgentOptions(value: unknown): Readonly<Record<string, JsonValue>>;
 export declare function validateShellOptions(value: unknown): ShellOptions;
 export declare function validateShellCommand(value: unknown): string;
 export declare function inspectWorkflowScript(script: string): StaticWorkflowCall[];
+/**
+ * Distinct, completely static option objects of agent(...) and agent.create(...) calls, so launch can inspect them
+ * before any effect. Calls with any dynamic option stay runtime-checked, and so do handles whose sends may add options.
+ */
+export declare function staticAgentPreparationOptions(script: string, registered?: Readonly<Record<string, {
+    run: (...args: never[]) => unknown;
+}>>): Array<Readonly<Record<string, JsonValue>>>;
 export declare function preflight(script: string, capabilities: PreflightCapabilities, schemas?: readonly unknown[], metadata?: WorkflowMetadata, compatibility?: boolean): PreflightResult;
 export declare function validateWorkflowLaunch(params: WorkflowValidationParameters, context: WorkflowValidationContext, registry?: WorkflowRegistryApi): ValidatedWorkflowLaunch;
 export declare function validateWorkflowLaunchWithRegistry(params: WorkflowValidationParameters, context: WorkflowValidationContext, registry?: WorkflowRegistryApi): ValidatedWorkflowLaunch;