pi-extensible-workflows 2.0.0 → 3.1.0

package/dist/src/types.js

@@ -0,0 +1,27 @@
+export const RUN_STATES = ["queued", "running", "pausing", "paused", "awaiting_input", "completed", "failed", "stopped", "interrupted", "budget_exhausted"];
+export const AGENT_STATES = ["queued", "running", "waiting_for_child", "paused", "retrying", "completed", "failed", "cancelled"];
+export const WORKFLOW_CALL_KINDS = ["agent", "parallel", "pipeline", "checkpoint", "phase", "withWorktree", "shell"];
+export const WORKFLOW_RUN_STARTED_EVENT = "workflow:run-started";
+export const WORKFLOW_RUN_RESUMED_EVENT = "workflow:run-resumed";
+export const WORKFLOW_RUN_STATE_CHANGED_EVENT = "workflow:run-state-changed";
+export const WORKFLOW_RUN_COMPLETED_EVENT = "workflow:run-completed";
+export const WORKFLOW_RUN_FAILED_EVENT = "workflow:run-failed";
+export const WORKFLOW_AGENT_STATE_CHANGED_EVENT = "workflow:agent-state-changed";
+export const WORKFLOW_PHASE_CHANGED_EVENT = "workflow:phase-changed";
+export const WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT = "workflow:checkpoint-state-changed";
+export const WORKFLOW_BUDGET_EVENT = "workflow:budget-event";
+export const WORKFLOW_WORKTREE_CREATED_EVENT = "workflow:worktree-created";
+export const ERROR_CODES = [
+    "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", "SHELL_FAILED", "AGENT_TIMEOUT", "AGENT_FAILED", "RESULT_INVALID",
+    "CANCELLED", "WORKER_UNRESPONSIVE", "WORKTREE_FAILED", "RESUME_INCOMPATIBLE", "BUDGET_EXHAUSTED", "INTERNAL_ERROR",
+];
+export const LAUNCH_SNAPSHOT_IDENTITY_VERSION = 5;
+export class WorkflowError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "WorkflowError";
+    }
+}

package/dist/src/utils.d.ts

@@ -0,0 +1,32 @@
+import { WorkflowError, type AgentResourceExclusions, type JsonValue, type ModelSpec, type WorkflowErrorCode } from "./types.js";
+export declare function object(value: unknown): value is Record<string, unknown>;
+export { object as isObject };
+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 positiveInteger(value: unknown): value is number;
+export declare function deepFreeze<T>(value: T): T;
+export declare function errorText(error: unknown): string;
+export declare function errorCode(error: unknown): WorkflowErrorCode | undefined;
+export declare function markWorkflowAuthored(error: WorkflowError, authored?: boolean): WorkflowError;
+export declare function isWorkflowAuthored(error: unknown): boolean;
+export declare function asWorkflowError(error: unknown): WorkflowError;
+export declare function fail(code: WorkflowErrorCode, message: string): never;
+export declare function parseThinking(value: unknown): ModelSpec["thinking"] | undefined;
+export declare function parseModelReference(value: string): ModelSpec;
+export declare function annotateModelAliasError(error: unknown, name: string): unknown;
+export declare function modelAliasErrorName(error: unknown): string | undefined;
+export declare function modelAliasName(value: string, aliases: Readonly<Record<string, string>>): string | undefined;
+export declare function validateModelAliases(value: unknown, settingsPath?: string): Readonly<Record<string, string>>;
+export declare function unknownModel(value: string, target: string | undefined, settingsPath?: string): never;
+export declare function resolveModelReference(value: string, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): ModelSpec;
+export declare function modelCapability(value: string | ModelSpec, aliases?: Readonly<Record<string, string>>, knownModels?: ReadonlySet<string>, settingsPath?: string): string;
+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;
+export declare function disabledResources(patterns: readonly string[], resources: readonly string[]): string[];
+export declare function unmatchedResourcePatterns(patterns: readonly string[], resources: readonly string[]): string[];
+export declare function mergeAgentResourceExclusions(...values: (AgentResourceExclusions | undefined)[]): AgentResourceExclusions;
+export declare function createLaunchSnapshot(input: Omit<import("./types.js").LaunchSnapshot, "identityVersion"> & {
+    identityVersion?: number;
+}): Readonly<import("./types.js").LaunchSnapshot>;
+export declare function loadLaunchSnapshot(input: import("./types.js").LaunchSnapshot): Readonly<import("./types.js").LaunchSnapshot>;

package/dist/src/utils.js

@@ -0,0 +1,168 @@
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError } from "./types.js";
+import { Minimatch } from "minimatch";
+export function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+export { object as isObject };
+export function jsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || seen.has(value))
+        return false;
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+        return false;
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string"))
+        return false;
+    seen.add(value);
+    const valid = (Array.isArray(value) ? Array.from(value) : keys.map((key) => value[key])).every((item) => jsonValue(item, seen));
+    seen.delete(value);
+    return valid;
+}
+export function jsonObject(value) { return jsonValue(value) && object(value); }
+export function positiveInteger(value) { return Number.isInteger(value) && value > 0; }
+export function deepFreeze(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+export function errorText(error) { return error && typeof error === "object" && typeof error.message === "string" ? error.message : error instanceof Error ? error.message : String(error); }
+export function errorCode(error) {
+    if (error instanceof WorkflowError)
+        return ERROR_CODES.includes(error.code) ? error.code : undefined;
+    if (!error || typeof error !== "object")
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" && ERROR_CODES.includes(code) ? code : undefined;
+}
+const WORKFLOW_AUTHORED_ERROR = Symbol("workflowAuthoredError");
+export function markWorkflowAuthored(error, authored = false) {
+    if (authored)
+        Object.defineProperty(error, WORKFLOW_AUTHORED_ERROR, { value: true });
+    return error;
+}
+export function isWorkflowAuthored(error) { return Boolean(error && typeof error === "object" && WORKFLOW_AUTHORED_ERROR in error); }
+export function asWorkflowError(error) {
+    const code = errorCode(error);
+    return markWorkflowAuthored(error instanceof WorkflowError && code ? error : new WorkflowError(code ?? "INTERNAL_ERROR", errorText(error)), isWorkflowAuthored(error) || !code);
+}
+export function fail(code, message) { throw new WorkflowError(code, message); }
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+const MODEL_ALIAS_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export function parseThinking(value) { return typeof value === "string" && THINKING_LEVELS.includes(value) ? value : undefined; }
+export function parseModelReference(value) {
+    const match = /^([^/:\s]+)\/([^:\s]+)(?::([^:\s]+))?$/.exec(value);
+    if (!match?.[1] || !match[2])
+        fail("UNKNOWN_MODEL", `Invalid model spec: ${value}`);
+    const thinking = match[3];
+    if (thinking && !THINKING_LEVELS.includes(thinking))
+        fail("UNKNOWN_MODEL", `Invalid thinking level: ${thinking}`);
+    return { provider: match[1], model: match[2], ...(thinking ? { thinking: thinking } : {}) };
+}
+const MODEL_ALIAS_ERROR_NAME = Symbol("modelAliasErrorName");
+function aliasError(message, settingsPath, name) {
+    const error = new WorkflowError("CONFIG_ERROR", `${message} (settings: ${settingsPath})`);
+    if (name)
+        Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+    throw error;
+}
+export function annotateModelAliasError(error, name) {
+    if (error instanceof WorkflowError)
+        Object.defineProperty(error, MODEL_ALIAS_ERROR_NAME, { value: name, configurable: true });
+    return error;
+}
+export function modelAliasErrorName(error) {
+    return error instanceof WorkflowError ? error[MODEL_ALIAS_ERROR_NAME] : undefined;
+}
+export function modelAliasName(value, aliases) {
+    const name = /^([^/:\s]+)(?::[^:\s]+)?$/.exec(value)?.[1];
+    return name && Object.prototype.hasOwnProperty.call(aliases, name) ? name : undefined;
+}
+export function validateModelAliases(value, settingsPath = "workflow settings") {
+    if (!object(value))
+        aliasError("modelAliases must be an object", settingsPath);
+    const aliases = {};
+    for (const [name, target] of Object.entries(value)) {
+        if (!MODEL_ALIAS_NAME.test(name))
+            aliasError(`Invalid model alias name: ${name}`, settingsPath, name);
+        if (typeof target !== "string" || !target.trim())
+            aliasError(`Invalid model alias target for ${name}`, settingsPath, name);
+        aliases[name] = target;
+    }
+    for (const name of Object.keys(aliases)) {
+        try {
+            resolveModelReference(name, aliases);
+        }
+        catch (error) {
+            aliasError(`Invalid model alias target for ${name}: ${errorText(error)}`, settingsPath, name);
+        }
+    }
+    return Object.freeze(aliases);
+}
+export function unknownModel(value, target, settingsPath) {
+    const resolved = target ? ` resolved to ${target}` : "";
+    const path = settingsPath ? ` (settings: ${settingsPath})` : "";
+    fail("UNKNOWN_MODEL", `Unknown model${target ? " alias" : ""} ${value}${resolved}${path}`);
+}
+export function resolveModelReference(value, aliases = {}, knownModels, settingsPath) {
+    const resolveReference = (reference, chain) => {
+        if (reference.includes("/"))
+            return parseModelReference(reference);
+        const match = /^([^:\s]+)(?::([^:\s]+))?$/.exec(reference);
+        const thinking = match?.[2];
+        if (!match?.[1] || thinking && !THINKING_LEVELS.includes(thinking))
+            unknownModel(reference, undefined, settingsPath);
+        const alias = modelAliasName(reference, aliases);
+        if (alias) {
+            if (chain.includes(alias))
+                fail("UNKNOWN_MODEL", `Circular model alias: ${[...chain, alias].join(" -> ")}${settingsPath ? ` (settings: ${settingsPath})` : ""}`);
+            const parsed = resolveReference(aliases[alias], [...chain, alias]);
+            return thinking ? { ...parsed, thinking: thinking } : parsed;
+        }
+        const candidates = [...(knownModels ?? [])].filter((model) => model.slice(model.indexOf("/") + 1) === match[1]);
+        if (candidates.length === 1) {
+            const parsed = parseModelReference(candidates[0]);
+            return thinking ? { ...parsed, thinking: thinking } : parsed;
+        }
+        unknownModel(reference, undefined, settingsPath);
+    };
+    return resolveReference(value, []);
+}
+export function modelCapability(value, aliases, knownModels, settingsPath) {
+    const parsed = typeof value === "string" ? resolveModelReference(value, aliases, knownModels, settingsPath) : value;
+    return `${parsed.provider}/${parsed.model}`;
+}
+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)"}`]);
+}
+const RESOURCE_PATTERN_OPTIONS = { dot: true, nonegate: true, nocomment: true };
+function resourcePatternBody(pattern) { return pattern.startsWith("!") ? pattern.slice(1) : pattern; }
+function resourcePatternPath(value) { return value.replaceAll("\\", "/"); }
+export function validateResourcePattern(pattern) {
+    const body = resourcePatternBody(pattern);
+    if (!body)
+        throw new Error(`Empty minimatch pattern ${JSON.stringify(pattern)}`);
+    const matcher = new Minimatch(resourcePatternPath(body), RESOURCE_PATTERN_OPTIONS);
+    if (matcher.makeRe() === false)
+        throw new Error(`Invalid minimatch pattern ${JSON.stringify(pattern)}`);
+}
+export function resourcePatternMatches(resource, pattern) { return new Minimatch(resourcePatternPath(resourcePatternBody(pattern)), RESOURCE_PATTERN_OPTIONS).match(resourcePatternPath(resource)); }
+export function disabledResources(patterns, resources) {
+    const disabled = new Set();
+    for (const resource of resources) {
+        let excluded = false;
+        for (const pattern of patterns)
+            if (resourcePatternMatches(resource, pattern))
+                excluded = !pattern.startsWith("!");
+        if (excluded)
+            disabled.add(resource);
+    }
+    return [...disabled];
+}
+export function unmatchedResourcePatterns(patterns, resources) { return patterns.filter((pattern) => !resources.some((resource) => resourcePatternMatches(resource, pattern))); }
+export function mergeAgentResourceExclusions(...values) { return { skills: values.flatMap((value) => value?.skills ?? []), extensions: values.flatMap((value) => value?.extensions ?? []) }; }
+export function createLaunchSnapshot(input) { return deepFreeze(structuredClone({ ...input, launchKind: input.launchKind ?? (input.functionName ? "function" : "inline"), identityVersion: input.identityVersion ?? LAUNCH_SNAPSHOT_IDENTITY_VERSION })); }
+export function loadLaunchSnapshot(input) { return deepFreeze(structuredClone(input)); }

package/dist/src/validation.d.ts

@@ -0,0 +1,28 @@
+import type { AgentDefinition, AgentResourcePolicy, CheckpointInput, JsonSchema, JsonValue, LaunchSnapshot, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, ValidatedWorkflowLaunch, WorkflowMetadata, WorkflowRoleDirectoryRegistration, WorkflowSettings, WorkflowSettingsOverrides, WorkflowSettingsResolution, WorkflowValidationContext, WorkflowValidationParameters } from "./types.js";
+import type { WorkflowRegistryApi } from "./registry.js";
+export declare const DEFAULT_SETTINGS: Readonly<WorkflowSettings>;
+export declare function validateCheckpoint(value: unknown): CheckpointInput;
+export declare function workflowSettingsPath(agentDir?: string): string;
+export declare function workflowProjectSettingsPath(cwd: string): string;
+export declare function loadSettings(path?: string): Readonly<WorkflowSettings>;
+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;
+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 declare function loadAgentDefinitions(cwd: string, agentDir?: string, projectTrusted?: boolean, extensionRoleDirectories?: readonly WorkflowRoleDirectoryInput[]): Readonly<Record<string, AgentDefinition>>;
+export declare function instrumentWorkflow(script: string): string;
+export declare function workflowPrompt(template: string, values: Readonly<Record<string, JsonValue>>): string;
+export declare function validateSchema(schema: unknown, at?: string): asserts schema is JsonSchema;
+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[];
+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;
+export declare function launchScriptForSnapshot(snapshot: Readonly<LaunchSnapshot>, registry: WorkflowRegistryApi): string;
+export { createLaunchSnapshot, loadLaunchSnapshot } from "./utils.js";