pi-extensible-workflows 2.0.0 → 3.0.0

package/dist/src/utils.js

@@ -0,0 +1,128 @@
+import { ERROR_CODES, LAUNCH_SNAPSHOT_IDENTITY_VERSION, WorkflowError } from "./types.js";
+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 } : {}) };
+}
+function aliasError(message, settingsPath) { fail("CONFIG_ERROR", `${message} (settings: ${settingsPath})`); }
+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);
+        if (typeof target !== "string" || !target.trim())
+            aliasError(`Invalid model alias target for ${name}`, settingsPath);
+        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);
+        }
+    }
+    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)"}`]);
+}
+export function mergeAgentResourceExclusions(...values) { return { skills: [...new Set(values.flatMap((value) => value?.skills ?? []))], extensions: [...new Set(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,24 @@
+import type { AgentDefinition, AgentResourcePolicy, CheckpointInput, JsonSchema, JsonValue, LaunchSnapshot, PreflightCapabilities, PreflightResult, ShellOptions, StaticWorkflowCall, ValidatedWorkflowLaunch, WorkflowMetadata, WorkflowSettings, 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 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 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";