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

package/dist/src/paths.d.ts

@@ -5,6 +5,8 @@ export declare function safePart(value: string): string;
  * guessing at the identity of an object that does not exist.
  */
 export declare function canonicalPath(path: string): string;
+/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
+export declare function extensionIdentity(path: string): string;
 export declare function sameFilesystemPath(left: string, right: string): boolean;
 export declare function workflowProjectSettingsPath(cwd: string): string;
 export declare function projectStorageKey(cwd: string): string;

package/dist/src/paths.js

@@ -20,6 +20,8 @@ export function canonicalPath(path) {
         return absolute;
     }
 }
+/** Pi names built-in extensions `builtin:<name>` instead of by a path; other extensions are files. */
+export function extensionIdentity(path) { return path.startsWith("builtin:") ? path : canonicalPath(path); }
 export function sameFilesystemPath(left, right) { return canonicalPath(left) === canonicalPath(right); }
 export function workflowProjectSettingsPath(cwd) { return join(cwd, ".pi", "pi-extensible-workflows", "settings.json"); }
 export function projectStorageKey(cwd) {

package/dist/src/registry.js

@@ -3,10 +3,11 @@ import { basename, dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Value } from "typebox/value";
 import { byPriorityThenName, deepFreeze, errorCode, errorText, fail, jsonValue, MODEL_ALIAS_NAME, object, validWorkflowExtensionNamespace } from "./utils.js";
-import { loadSettings, resolveWorkflowSettings, validateSchema } from "./validation.js";
+import { loadSettings, resolveWorkflowSettings } from "./settings.js";
+import { validateSchema } from "./utils.js";
 import { canonicalPath } from "./paths.js";
 import { isCorePackageName } from "./package-identity.js";
-const RESERVED_GLOBALS = new Set(["agent", "shell", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
+const RESERVED_GLOBALS = new Set(["agent", "shell", "tools", "prompt", "checkpoint", "parallel", "pipeline", "phase", "withWorktree", "log", "args", "Promise", "JSON", "Math", "Date", "eval", "Function", "WebAssembly", "process", "require", "module", "exports", "console", "fetch", "XMLHttpRequest", "WebSocket", "performance", "crypto", "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Intl", "SharedArrayBuffer", "Atomics", "globalThis", "global", "undefined", "NaN", "Infinity", "extensions", "workflow_catalog"]);
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;

package/dist/src/roles.d.ts

@@ -0,0 +1,70 @@
+import type { AgentDefinition, AgentResourceSelectorSources, ContextFileScope, ModelSpec, WorkflowExtensionSettings, WorkflowRoleDirectoryRegistration } from "./types.js";
+export declare function parseRoleMarkdown(content: string, strict?: boolean, rolePath?: string): AgentDefinition;
+export declare function workflowRoleDirectories(agentDir?: string): readonly string[];
+export type WorkflowRoleDirectoryInput = string | WorkflowRoleDirectoryRegistration;
+export interface RoleDiscoveryOptions {
+    cwd: string;
+    agentDir?: string;
+    projectTrusted?: boolean;
+    extensionRoleDirectories?: readonly WorkflowRoleDirectoryInput[];
+}
+export interface RoleResourceCandidates {
+    skills?: readonly string[];
+    extensions?: readonly string[];
+    tools?: readonly string[];
+}
+export interface RoleResolutionOptions extends RoleDiscoveryOptions {
+    definition?: AgentDefinition;
+    definitions?: Readonly<Record<string, AgentDefinition>>;
+    model?: string;
+    modelOverride?: ModelSpec;
+    rootModel?: ModelSpec;
+    rootTools?: ReadonlySet<string> | readonly string[];
+    inheritedTools?: readonly string[];
+    availableModels?: ReadonlySet<string>;
+    knownModels?: ReadonlySet<string>;
+    modelAliases?: Readonly<Record<string, string>>;
+    blockedAliases?: ReadonlySet<string>;
+    blockedAliasTargets?: Readonly<Record<string, string>>;
+    settingsPath?: string;
+    selectorSources?: AgentResourceSelectorSources;
+    resources?: RoleResourceCandidates;
+    tools?: readonly string[];
+    skills?: readonly string[];
+    extensions?: readonly string[];
+    contextFiles?: readonly ContextFileScope[];
+    effectiveTools?: readonly string[];
+}
+export interface ResolvedRole {
+    name?: string;
+    definition?: AgentDefinition;
+    model?: ModelSpec;
+    requestedModel?: string;
+    tools?: readonly string[];
+    prompt: string;
+    overrideSystemPrompt: boolean;
+    systemPrompt: {
+        mode: "override" | "append";
+        text: string;
+    };
+    contextFiles?: readonly ContextFileScope[];
+    extensionSettings?: Readonly<WorkflowExtensionSettings>;
+    selectorSources: AgentResourceSelectorSources;
+    selectorLayers: {
+        skills: readonly (readonly string[] | undefined)[];
+        extensions: readonly (readonly string[] | undefined)[];
+        tools: readonly (readonly string[] | undefined)[];
+    };
+    selectedSkills?: readonly string[];
+    selectedExtensions?: readonly string[];
+    unmatchedSkills?: readonly string[];
+    unmatchedExtensions?: readonly string[];
+    unmatchedTools?: readonly string[];
+}
+export declare function loadProjectAgentDefinitions(cwd: string): Readonly<Record<string, AgentDefinition>>;
+export declare function discoverRoles(input: RoleDiscoveryOptions): Readonly<Record<string, AgentDefinition>>;
+export declare function loadRole(name: string, input: RoleDiscoveryOptions): AgentDefinition;
+export declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean, extensionRoleDirectories?: readonly WorkflowRoleDirectoryInput[]): Readonly<Record<string, AgentDefinition>>;
+export declare function canonicalExtensionSelector(selector: string, base?: string): string;
+/** Without a supplied root/tool/resource boundary, this API reports selector layers but does not infer available resources; tools and model remain undefined when no candidates are supplied. When selector sources are supplied, model aliases default to none and blocked aliases are not applied unless provided. */
+export declare function resolveRole(name: string | undefined, options: RoleResolutionOptions): ResolvedRole;

package/dist/src/roles.js

@@ -0,0 +1,326 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { registeredWorkflowRoleDirectoryRegistrations } from "./registry.js";
+import { resolveWorkflowSettings, validateContextFileScopes, validateSelectorList, validateWorkflowExtensionSettings, workflowSettingsPath } from "./settings.js";
+import { assertModelThinking, deepFreeze, object, errorText, fail, isNodeError, modelAliasName, modelCapability, resourcePatternHasMagic, resolveModelReference, selectResourcesByLayers, unmatchedResourcePatterns } from "./utils.js";
+import { canonicalPath, extensionIdentity } from "./paths.js";
+const ROLE_DIRECTORY = "pi-extensible-workflows";
+// Preserve the role-file base when a discovered definition is resolved again through the public API.
+const roleDefinitionPaths = new WeakMap();
+export function parseRoleMarkdown(content, strict = false, rolePath) {
+    if (!strict) {
+        if (!content.startsWith("---\n"))
+            return { prompt: content };
+        const end = content.indexOf("\n---", 4);
+        if (end < 0)
+            return { prompt: content };
+        const meta = {};
+        for (const line of content.slice(4, end).split("\n")) {
+            const match = /^(model|tools|skills|extensions|description|overrideSystemPrompt|override_system_prompt|is_system_prompt|contextFiles|extensionSettings|disabledAgentResources|thinking)\s*:\s*(.+)$/.exec(line.trim());
+            if (match?.[1] === "disabledAgentResources")
+                fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
+            if (match?.[1] === "thinking")
+                fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
+            if (match?.[1] && match[2])
+                meta[match[1]] = match[2].trim();
+        }
+        const unquote = (v) => v.replace(/^['"]|['"]$/g, "");
+        const parseList = (value) => value === undefined ? undefined : value.replace(/^\[|\]$/g, "").split(",").map((entry) => unquote(entry.trim())).filter(Boolean);
+        const tools = parseList(meta.tools);
+        const skills = parseList(meta.skills);
+        const extensions = parseList(meta.extensions);
+        let extensionSettings;
+        if (meta.extensionSettings !== undefined) {
+            try {
+                extensionSettings = JSON.parse(meta.extensionSettings);
+            }
+            catch (error) {
+                fail("INVALID_METADATA", `Invalid role extensionSettings: ${errorText(error)}`);
+            }
+        }
+        const rolePathValue = rolePath ?? "<role>";
+        const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA");
+        const definition = { prompt: content.slice(end + 4).replace(/^\n/, "") };
+        if (meta.model) {
+            const model = unquote(meta.model);
+            assertModelThinking(model, "Role model");
+            definition.model = model;
+        }
+        if (meta.description)
+            definition.description = unquote(meta.description);
+        if (tools)
+            definition.tools = tools;
+        if (skills)
+            definition.skills = skills;
+        if (extensions)
+            definition.extensions = extensions;
+        if (normalizedExtensionSettings !== undefined)
+            definition.extensionSettings = normalizedExtensionSettings;
+        const overrideSystemPrompt = meta.overrideSystemPrompt ?? meta.override_system_prompt ?? meta.is_system_prompt;
+        const contextFiles = meta.contextFiles ? meta.contextFiles.replace(/^\[|\]$/g, "").split(",").map((scope) => unquote(scope.trim())).filter(Boolean) : undefined;
+        const normalizedContextFiles = validateContextFileScopes(contextFiles, "role");
+        if (overrideSystemPrompt)
+            definition.overrideSystemPrompt = overrideSystemPrompt === "true";
+        if (normalizedContextFiles)
+            definition.contextFiles = normalizedContextFiles;
+        return definition;
+    }
+    const normalized = content.replace(/\r\n?/g, "\n");
+    if (normalized.startsWith("---\n") && normalized.indexOf("\n---", 3) < 0)
+        fail("INVALID_METADATA", "Role frontmatter is missing its closing delimiter");
+    let parsed;
+    try {
+        parsed = parseFrontmatter(content);
+    }
+    catch (error) {
+        fail("INVALID_METADATA", `Invalid role frontmatter: ${errorText(error)}`);
+    }
+    if (!object(parsed.frontmatter))
+        fail("INVALID_METADATA", "Role frontmatter must be an object");
+    const { model, tools, skills, extensions, extensionSettings, description, contextFiles } = parsed.frontmatter;
+    if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "disabledAgentResources"))
+        fail("INVALID_METADATA", "disabledAgentResources is no longer supported; use skills, extensions, and tools selectors");
+    if (Object.prototype.hasOwnProperty.call(parsed.frontmatter, "thinking"))
+        fail("INVALID_METADATA", "Role thinking is not supported; put it on model as provider/model:thinking");
+    const overrideSystemPrompt = parsed.frontmatter.overrideSystemPrompt ?? parsed.frontmatter.override_system_prompt ?? parsed.frontmatter.is_system_prompt;
+    if (model !== undefined && (typeof model !== "string" || model.trim() === ""))
+        fail("INVALID_METADATA", "Role model must be a non-empty string");
+    if (description !== undefined && (typeof description !== "string" || description.trim() === "" || description.length > 1024 || /[\r\n]/.test(description)))
+        fail("INVALID_METADATA", "Role description must be a non-empty single-line string of at most 1024 characters");
+    if (overrideSystemPrompt !== undefined && typeof overrideSystemPrompt !== "boolean")
+        fail("INVALID_METADATA", "Role overrideSystemPrompt must be a boolean");
+    const normalizedContextFiles = validateContextFileScopes(contextFiles, rolePath ?? "<role>");
+    const rolePathValue = rolePath ?? "<role>";
+    const normalizedTools = validateSelectorList(tools, rolePathValue, "tools", "INVALID_METADATA");
+    const normalizedSkills = validateSelectorList(skills, rolePathValue, "skills", "INVALID_METADATA");
+    const normalizedExtensions = validateSelectorList(extensions, rolePathValue, "extensions", "INVALID_METADATA");
+    const normalizedExtensionSettings = validateWorkflowExtensionSettings(extensionSettings, rolePathValue, "INVALID_METADATA");
+    const normalizedDescription = typeof description === "string" ? description.trim() : undefined;
+    const normalizedModel = typeof model === "string" ? model.trim() : undefined;
+    if (normalizedModel !== undefined)
+        assertModelThinking(normalizedModel, "Role model");
+    const definition = { prompt: parsed.body };
+    if (normalizedDescription !== undefined)
+        definition.description = normalizedDescription;
+    if (normalizedModel !== undefined)
+        definition.model = normalizedModel;
+    if (normalizedTools !== undefined)
+        definition.tools = normalizedTools;
+    if (normalizedSkills !== undefined)
+        definition.skills = normalizedSkills;
+    if (normalizedExtensions !== undefined)
+        definition.extensions = normalizedExtensions;
+    if (normalizedExtensionSettings !== undefined)
+        definition.extensionSettings = normalizedExtensionSettings;
+    if (typeof overrideSystemPrompt === "boolean")
+        definition.overrideSystemPrompt = overrideSystemPrompt;
+    if (normalizedContextFiles !== undefined)
+        definition.contextFiles = normalizedContextFiles;
+    return definition;
+}
+export function workflowRoleDirectories(agentDir = getAgentDir()) {
+    return [join(agentDir, ROLE_DIRECTORY, "roles")];
+}
+function projectRoleDirectories(root) {
+    return [join(root, ROLE_DIRECTORY, "roles")];
+}
+function roleDirectorySources(dirs) {
+    const seen = new Set();
+    return dirs.flatMap((value) => {
+        const source = typeof value === "string" ? { path: value } : { path: value.path, extension: value.extension, ...(value.builtin === true ? { builtin: true } : {}) };
+        if (seen.has(source.path))
+            return [];
+        seen.add(source.path);
+        return [source];
+    });
+}
+function roleDirectoryLabel(source, extension = true) {
+    return source.extension ? `Extension "${source.extension.headline}" (${source.extension.version})` : extension ? "Registered workflow extension" : "Standard workflow";
+}
+function isRoleFile(dir, entry) {
+    if (extname(entry.name) !== ".md")
+        return false;
+    if (entry.isFile())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return statSync(join(dir, entry.name)).isFile();
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function scanRoleFiles(dirs, extension) {
+    const files = [];
+    for (const source of roleDirectorySources(dirs)) {
+        let entries;
+        try {
+            entries = readdirSync(source.path, { withFileTypes: true });
+        }
+        catch (error) {
+            if (!extension && isNodeError(error, "ENOENT"))
+                continue;
+            fail("INVALID_METADATA", `${roleDirectoryLabel(source, extension)} role directory "${source.path}" could not be scanned: ${errorText(error)}`);
+        }
+        for (const entry of entries)
+            if (isRoleFile(source.path, entry))
+                files.push({ name: basename(entry.name, ".md"), path: join(source.path, entry.name), source });
+    }
+    return files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
+}
+function roleEntries(dirs, extension) {
+    const files = scanRoleFiles(dirs, extension);
+    const starterFiles = files.filter(({ source }) => source.builtin === true);
+    const regularFiles = files.filter(({ source }) => source.builtin !== true);
+    if (extension) {
+        const byName = new Map();
+        for (const file of regularFiles)
+            byName.set(file.name, [...(byName.get(file.name) ?? []), file]);
+        for (const [name, matches] of byName)
+            if (matches.length > 1)
+                fail("INVALID_METADATA", `Duplicate extension role "${name}": ${matches.map(({ path, source }) => `${roleDirectoryLabel(source)} role directory "${source.path}" (${path})`).join("; ")}`);
+    }
+    const read = (roleFiles) => Object.fromEntries(roleFiles.map(({ name, path, source }) => {
+        try {
+            const definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
+            roleDefinitionPaths.set(definition, path);
+            return [name, { name, path, source, definition }];
+        }
+        catch (error) {
+            if (extension)
+                fail("INVALID_METADATA", `${roleDirectoryLabel(source)} role directory "${source.path}" contains invalid role "${name}" at "${path}": ${errorText(error)}`);
+            throw error;
+        }
+    }));
+    return extension ? { ...read(starterFiles), ...read(regularFiles) } : read(files);
+}
+function discoveryInput(input) {
+    return { cwd: input.cwd, agentDir: input.agentDir ?? getAgentDir(), projectTrusted: input.projectTrusted ?? true, extensionRoleDirectories: input.extensionRoleDirectories ?? registeredWorkflowRoleDirectoryRegistrations() };
+}
+function discoveredRoleEntries(input) {
+    const resolved = discoveryInput(input);
+    return {
+        ...roleEntries(resolved.extensionRoleDirectories, true),
+        ...roleEntries(workflowRoleDirectories(resolved.agentDir), false),
+        ...(resolved.projectTrusted ? roleEntries(projectRoleDirectories(join(resolved.cwd, ".pi")), false) : {}),
+    };
+}
+export function loadProjectAgentDefinitions(cwd) {
+    return deepFreeze(Object.fromEntries(Object.entries(roleEntries(projectRoleDirectories(join(cwd, ".pi")), false)).map(([name, entry]) => [name, entry.definition])));
+}
+export function discoverRoles(input) {
+    return deepFreeze(Object.fromEntries(Object.entries(discoveredRoleEntries(input)).map(([name, entry]) => [name, entry.definition])));
+}
+export function loadRole(name, input) {
+    const entry = discoveredRoleEntries(input)[name];
+    if (!entry)
+        fail("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${name}`);
+    return entry.definition;
+}
+export function loadAgentDefinitions(cwd, agentDir = getAgentDir(), projectTrusted = true, extensionRoleDirectories = registeredWorkflowRoleDirectoryRegistrations()) {
+    return discoverRoles({ cwd, agentDir, projectTrusted, extensionRoleDirectories });
+}
+export function canonicalExtensionSelector(selector, base = process.cwd()) {
+    const negated = selector.startsWith("!");
+    const body = negated ? selector.slice(1) : selector;
+    // Built-in extensions are named `builtin:<name>`, not by a path.
+    if (body === "*" || body === "**" || body.startsWith("**/") || body.startsWith("builtin:"))
+        return selector;
+    const resolved = resolve(base, body);
+    if (resourcePatternHasMagic(body))
+        return `${negated ? "!" : ""}${resolved}`;
+    return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
+}
+function selectorsFromSettings(settings) {
+    return { ...(settings.skills === undefined ? {} : { skills: settings.skills }), ...(settings.extensions === undefined ? {} : { extensions: settings.extensions }), ...(settings.tools === undefined ? {} : { tools: settings.tools }) };
+}
+function rootToolNames(value) {
+    return value === undefined ? undefined : value instanceof Set ? [...value] : [...value];
+}
+function roleDefinitionFor(name, options) {
+    if (name === undefined)
+        return {};
+    if (options.definition !== undefined) {
+        const path = roleDefinitionPaths.get(options.definition);
+        return { definition: options.definition, ...(path === undefined ? {} : { path }) };
+    }
+    if (options.definitions?.[name] !== undefined) {
+        const definition = options.definitions[name];
+        const path = roleDefinitionPaths.get(definition);
+        return { definition, ...(path === undefined ? {} : { path }) };
+    }
+    const entries = discoveredRoleEntries(options);
+    const entry = entries[name];
+    if (!entry)
+        fail("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${name}`);
+    return entry;
+}
+/** Without a supplied root/tool/resource boundary, this API reports selector layers but does not infer available resources; tools and model remain undefined when no candidates are supplied. When selector sources are supplied, model aliases default to none and blocked aliases are not applied unless provided. */
+export function resolveRole(name, options) {
+    const { definition, path } = roleDefinitionFor(name, options);
+    const settings = options.selectorSources === undefined ? resolveWorkflowSettings(options.cwd, options.projectTrusted ?? true, options.settingsPath ?? workflowSettingsPath(options.agentDir ?? getAgentDir())) : undefined;
+    const baseSources = options.selectorSources ?? { global: selectorsFromSettings(settings?.global ?? {}), project: selectorsFromSettings(settings?.project ?? {}) };
+    const canonicalSources = (sources) => ({
+        ...sources,
+        global: { ...sources.global, ...(sources.global.extensions === undefined ? {} : { extensions: sources.global.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) },
+        project: { ...sources.project, ...(sources.project.extensions === undefined ? {} : { extensions: sources.project.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) },
+        ...(sources.role === undefined ? {} : { role: { ...sources.role, ...(sources.role.extensions === undefined ? {} : { extensions: sources.role.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) } }),
+        ...(sources.call === undefined ? {} : { call: { ...sources.call, ...(sources.call.extensions === undefined ? {} : { extensions: sources.call.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }) } }),
+    });
+    const roleLayer = definition?.skills !== undefined || definition?.extensions !== undefined || definition?.tools !== undefined ? { ...(definition.skills === undefined ? {} : { skills: definition.skills }), ...(definition.extensions === undefined ? {} : { extensions: definition.extensions.map((selector) => canonicalExtensionSelector(selector, path ? dirname(path) : options.cwd)) }), ...(definition.tools === undefined ? {} : { tools: definition.tools }) } : baseSources.role;
+    const callLayer = options.skills !== undefined || options.extensions !== undefined || options.tools !== undefined ? { ...(options.skills === undefined ? {} : { skills: options.skills }), ...(options.extensions === undefined ? {} : { extensions: options.extensions.map((selector) => canonicalExtensionSelector(selector, options.cwd)) }), ...(options.tools === undefined ? {} : { tools: options.tools }) } : baseSources.call;
+    const selectorSources = canonicalSources({ global: baseSources.global, project: baseSources.project, ...(roleLayer === undefined ? {} : { role: roleLayer }), ...(callLayer === undefined ? {} : { call: callLayer }) });
+    const callSelectors = selectorSources.call;
+    const roleSelectors = selectorSources.role;
+    const selectorLayers = {
+        skills: [selectorSources.global.skills, selectorSources.project.skills, roleSelectors?.skills, callSelectors?.skills],
+        extensions: [selectorSources.global.extensions, selectorSources.project.extensions, roleSelectors?.extensions, callSelectors?.extensions],
+        tools: [selectorSources.global.tools, selectorSources.project.tools, roleSelectors?.tools, callSelectors?.tools],
+    };
+    const resources = options.resources ?? {};
+    const candidateTools = options.inheritedTools ?? rootToolNames(options.rootTools) ?? resources.tools;
+    const tools = options.effectiveTools ?? (candidateTools === undefined ? undefined : selectResourcesByLayers(selectorLayers.tools, candidateTools));
+    const rootTools = rootToolNames(options.rootTools);
+    if (rootTools !== undefined) {
+        const outsideEffectiveTool = options.effectiveTools?.find((tool) => !candidateTools?.includes(tool));
+        if (outsideEffectiveTool)
+            fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideEffectiveTool}`);
+        const outsideCallTool = (options.tools ?? []).find((tool) => !tool.startsWith("!") && !resourcePatternHasMagic(tool) && !candidateTools?.includes(tool));
+        if (outsideCallTool)
+            fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideCallTool}`);
+        const outsideRootTool = tools?.find((tool) => !rootTools.includes(tool));
+        if (outsideRootTool)
+            fail("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideRootTool}`);
+    }
+    const selectedSkills = resources.skills === undefined ? undefined : selectResourcesByLayers(selectorLayers.skills, resources.skills);
+    const extensionResources = resources.extensions?.map((extension) => extensionIdentity(extension));
+    const selectedExtensions = extensionResources === undefined ? undefined : selectResourcesByLayers(selectorLayers.extensions, extensionResources);
+    const unmatchedSkills = resources.skills === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.skills.flatMap((layer) => layer ?? []), resources.skills);
+    const unmatchedExtensions = extensionResources === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.extensions.flatMap((layer) => layer ?? []), extensionResources);
+    const unmatchedTools = candidateTools === undefined ? undefined : unmatchedResourcePatterns(selectorLayers.tools.flatMap((layer) => layer ?? []), candidateTools);
+    const aliases = options.modelAliases ?? settings?.effective.modelAliases ?? {};
+    const requestedModel = options.model ?? (definition?.model && definition.thinking && !definition.model.includes(":") ? `${definition.model}:${definition.thinking}` : definition?.model);
+    const blockedAlias = requestedModel?.split(":", 1)[0];
+    if (requestedModel !== undefined && blockedAlias && options.blockedAliases?.has(blockedAlias) && !modelAliasName(requestedModel, aliases)) {
+        const target = options.blockedAliasTargets?.[blockedAlias];
+        fail("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${options.settingsPath ? ` (settings: ${options.settingsPath})` : ""}`);
+    }
+    let model = options.modelOverride;
+    if (model === undefined && requestedModel !== undefined) {
+        assertModelThinking(requestedModel);
+        model = resolveModelReference(requestedModel, aliases, options.knownModels ?? options.availableModels, options.settingsPath ?? settings?.sources.modelAliases);
+    }
+    if (model === undefined)
+        model = options.rootModel;
+    const availableModels = options.knownModels ?? options.availableModels ?? (options.rootModel === undefined ? undefined : new Set([modelCapability(options.rootModel)]));
+    if (model !== undefined && availableModels !== undefined && !availableModels.has(modelCapability(model)))
+        fail("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${options.settingsPath ? ` (settings: ${options.settingsPath})` : ""}`);
+    const prompt = definition?.prompt ?? "";
+    const overrideSystemPrompt = definition?.overrideSystemPrompt === true;
+    const contextFiles = options.contextFiles ?? definition?.contextFiles;
+    return { ...(name === undefined ? {} : { name }), ...(definition === undefined ? {} : { definition }), ...(model === undefined ? {} : { model }), ...(modelAliasName(requestedModel ?? "", aliases) && requestedModel ? { requestedModel } : {}), ...(tools === undefined ? {} : { tools }), prompt, overrideSystemPrompt, systemPrompt: { mode: overrideSystemPrompt ? "override" : "append", text: prompt }, ...(contextFiles === undefined ? {} : { contextFiles: [...contextFiles] }), ...(definition?.extensionSettings === undefined ? {} : { extensionSettings: definition.extensionSettings }), selectorSources, selectorLayers, ...(selectedSkills === undefined ? {} : { selectedSkills }), ...(selectedExtensions === undefined ? {} : { selectedExtensions }), ...(unmatchedSkills === undefined ? {} : { unmatchedSkills }), ...(unmatchedExtensions === undefined ? {} : { unmatchedExtensions }), ...(unmatchedTools === undefined ? {} : { unmatchedTools }) };
+}

package/dist/src/script-tools.d.ts

@@ -0,0 +1,27 @@
+import type { ExtensionToolContext, ToolLoadout, ToolLoadoutChanges } from "@earendil-works/pi-coding-agent";
+import { type JsonValue } from "./types.js";
+type ScriptTool = ExtensionToolContext["tools"][number];
+type ScriptToolOutcome = Awaited<ReturnType<ExtensionToolContext["executeTool"]>>;
+/** Workflow and subagent tools stay out of scripts, so a run cannot launch or control runs. Codemode is model-only and never callable. */
+export declare function scriptToolExcluded(name: string): boolean;
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export declare function scriptToolIdentifier(name: string): string;
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export declare function scriptToolContext(ctx: unknown): ExtensionToolContext | undefined;
+export declare function scriptToolIdentifiers(context: ExtensionToolContext | undefined): string[];
+export declare function scriptTool(context: ExtensionToolContext, identifier: string): ScriptTool | undefined;
+/**
+ * What a script call resolves to, as in codemode: the structured content of a tool with an output
+ * schema, also for error results that carry one, otherwise its text; other failures throw. The value
+ * is normalized through JSON and size-checked before it is journaled, so a replay returns the same value.
+ */
+export declare function scriptToolValue(tool: ScriptTool, outcome: ScriptToolOutcome): JsonValue;
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export declare function validateScriptToolReferences(script: string, context: ExtensionToolContext | undefined): void;
+/**
+ * Tells the model what `tools.<id>(args)` resolves to for declared tools with an output schema; the
+ * workflow description says that the others resolve to their text. With codemode active its own
+ * identical `Codemode:` lines say this, and pi keeps only one description per tool, so this defers.
+ */
+export declare function prepareScriptToolLoadout(loadout: ToolLoadout): ToolLoadoutChanges | undefined;
+export {};

package/dist/src/script-tools.js

@@ -0,0 +1,87 @@
+import { WorkflowError } from "./types.js";
+import { errorText, jsonValue, object } from "./utils.js";
+import { RPC_LIMIT_BYTES } from "./execution.js";
+import { scriptToolReferences } from "./validation.js";
+/** Workflow and subagent tools stay out of scripts, so a run cannot launch or control runs. Codemode is model-only and never callable. */
+export function scriptToolExcluded(name) {
+    return name === "workflow" || name.startsWith("workflow_") || name.startsWith("subagents_");
+}
+/** The identifier scripts use for a tool, the same as Pi codemode's, so its `tools.<id>(args)` lines apply to workflow scripts. */
+export function scriptToolIdentifier(name) {
+    let identifier = "";
+    for (const char of name)
+        identifier += (identifier === "" ? /^[A-Za-z_$]$/ : /^[A-Za-z0-9_$]$/).test(char) ? char : "_";
+    return identifier || "_";
+}
+/** The context of a Pi tool call, whose `executeTool()` runs session tools; absent for commands, session events, and headless launches. */
+export function scriptToolContext(ctx) {
+    return object(ctx) && typeof ctx.executeTool === "function" && Array.isArray(ctx.tools) ? ctx : undefined;
+}
+export function scriptToolIdentifiers(context) {
+    return (context?.tools ?? []).filter(({ name }) => !scriptToolExcluded(name)).map(({ name }) => scriptToolIdentifier(name));
+}
+// NOTE: a launch rejects identifiers that several tools share; a later tool set may still collide, and the first match wins.
+export function scriptTool(context, identifier) {
+    return context.tools.find(({ name }) => !scriptToolExcluded(name) && scriptToolIdentifier(name) === identifier);
+}
+/**
+ * What a script call resolves to, as in codemode: the structured content of a tool with an output
+ * schema, also for error results that carry one, otherwise its text; other failures throw. The value
+ * is normalized through JSON and size-checked before it is journaled, so a replay returns the same value.
+ */
+export function scriptToolValue(tool, outcome) {
+    const structured = tool.outputSchema === undefined ? undefined : outcome.result.structuredContent;
+    const text = outcome.result.content.flatMap((item) => item.type === "text" ? [item.text] : []).join("\n");
+    if (structured === undefined && outcome.isError)
+        throw new WorkflowError("TOOL_FAILED", `${tool.name}: ${text || "failed"}`);
+    let value;
+    try {
+        value = JSON.parse(JSON.stringify(structured ?? text));
+    }
+    catch (error) {
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON: ${errorText(error)}`);
+    }
+    if (!jsonValue(value))
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned a result that is not JSON`);
+    if (Buffer.byteLength(JSON.stringify(value)) > RPC_LIMIT_BYTES)
+        throw new WorkflowError("TOOL_FAILED", `${tool.name} returned more than the 10 MB workflow RPC limit`);
+    return value;
+}
+/** Fails a launch whose script names a tool this session cannot call, before any agent runs. */
+export function validateScriptToolReferences(script, context) {
+    const references = scriptToolReferences(script);
+    if (!references?.length)
+        return;
+    if (!context)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow scripts can call session tools only when launched by the workflow tool; this launch has none for ${references.map((name) => `tools.${name}`).join(", ")}`);
+    const identifiers = scriptToolIdentifiers(context);
+    const unknown = references.filter((name) => !identifiers.includes(name));
+    if (unknown.length)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools this session cannot call: ${unknown.map((name) => `tools.${name}`).join(", ")}`);
+    const ambiguous = references.filter((name) => identifiers.indexOf(name) !== identifiers.lastIndexOf(name));
+    if (ambiguous.length)
+        throw new WorkflowError("UNKNOWN_TOOL", `Workflow script calls tools whose names collide after normalization: ${ambiguous.map((name) => `tools.${name}`).join(", ")}`);
+}
+function describeScriptOutput(schema) {
+    if (!object(schema) || schema.type !== "object" || !object(schema.properties))
+        return schema === undefined ? undefined : "a JSON value";
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return `\`{ ${Object.keys(schema.properties).map((name) => required.has(name) ? name : `${name}?`).join(", ")} }\``;
+}
+/**
+ * Tells the model what `tools.<id>(args)` resolves to for declared tools with an output schema; the
+ * workflow description says that the others resolve to their text. With codemode active its own
+ * identical `Codemode:` lines say this, and pi keeps only one description per tool, so this defers.
+ */
+export function prepareScriptToolLoadout(loadout) {
+    if (loadout.declared.some(({ name }) => name === "codemode"))
+        return undefined;
+    const callable = new Set(loadout.callable.map(({ name }) => name));
+    const descriptions = {};
+    for (const tool of loadout.declared) {
+        const output = callable.has(tool.name) && !scriptToolExcluded(tool.name) ? describeScriptOutput(tool.outputSchema) : undefined;
+        if (output)
+            descriptions[tool.name] = `${tool.description.trim()}\n\nWorkflow scripts: \`tools.${scriptToolIdentifier(tool.name)}(args)\` resolves to ${output}.`;
+    }
+    return { descriptions };
+}

package/dist/src/settings.d.ts

@@ -0,0 +1,26 @@
+import { type ToolAnnotations } from "@earendil-works/pi-coding-agent";
+import type { AgentResourcePolicy, ContextFileScope, WorkflowExtensionSettings, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution } from "./types.js";
+export { workflowProjectSettingsPath } from "./paths.js";
+export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
+export declare function workflowSettingsPath(agentDir?: string): string;
+export declare function validateSelectorList(value: unknown, path: string, kind: "skills" | "extensions" | "tools", errorCode?: "INVALID_SETTINGS" | "INVALID_METADATA", normalizeExtensions?: boolean): readonly string[] | undefined;
+export declare function validateContextFileScopes(value: unknown, rolePath: string): readonly ContextFileScope[] | undefined;
+export declare function validateWorkflowExtensionSettings(value: unknown, settingsPath: string, errorCode?: "INVALID_SETTINGS" | "INVALID_METADATA"): WorkflowExtensionSettings | undefined;
+export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+/**
+ * Exposure and annotations of a workflow or subagent tool. Under the global `codemodeTools` setting,
+ * `model-only` keeps the model's direct access and stops codemode scripts from calling the tool.
+ * Tools are registered once at load, so the setting is global and applies after a reload.
+ * Read-only tools carry `readOnlyHint` so permission extensions need not confirm them.
+ */
+export declare function workflowToolExposure(name: string, codemodeTools: WorkflowSettings["codemodeTools"]): {
+    exposure?: "model-only";
+    annotations?: ToolAnnotations;
+};
+/** The `codemodeTools` setting at load time. Invalid settings keep the default; launches report them. */
+export declare function loadCodemodeToolsSetting(agentDir?: string): WorkflowSettings["codemodeTools"];
+export declare function loadSettingsOverrides(path: string): Readonly<WorkflowSettingsOverrides>;
+export declare function resolveWorkflowSettings(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): WorkflowSettingsResolution;
+export declare function validateModelAliasAvailability(aliases: Readonly<Record<string, string>>, names: readonly string[], availableModels: ReadonlySet<string>, knownModels: ReadonlySet<string>, settingsPath?: string): void;
+export declare function resolveAgentResourcePolicy(cwd: string, projectTrusted: boolean, globalSettingsPath?: string): AgentResourcePolicy;
+export declare function saveModelAliases(path?: string, aliases?: Readonly<Record<string, string>>): void;