clinkx 0.2.0 → 0.2.1

package/clinkx-workflows/dist/definition-normalizer.js

@@ -0,0 +1,75 @@
+/**
+ * Snapshot normalization for clinkx-workflows (2-10a).
+ *
+ * Normalizes a loaded workflow definition into snapshot-ready form:
+ * - Inlines template text (not just hashes) — hash-only snapshots can't reconstruct for resume
+ * - Includes template content hashes alongside inlined text
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a workflow definition by inlining all template text.
+ *
+ * @param definition - Parsed and validated workflow definition
+ * @param templates - Map of template path → template content (from resolveAllTemplates)
+ * @returns Normalized definition with all prompts inlined
+ */
+export function normalizeDefinition(definition, templates) {
+    const normalizedStages = definition.stages.map((stage) => ({
+        id: stage.id,
+        ...(stage.description != null ? { description: stage.description } : {}),
+        parallel: stage.parallel,
+        retry: stage.retry,
+        on_failure: stage.on_failure,
+        calls: stage.calls.map((call) => normalizeCall(call, templates)),
+    }));
+    return {
+        name: definition.name,
+        description: definition.description,
+        version: definition.version,
+        stages: normalizedStages,
+        variables: definition.variables,
+        settings: definition.settings,
+    };
+}
+/**
+ * Snapshot-facing alias used by the execution engine and future persistence work.
+ * The normalized definition is already snapshot-ready because template text is inlined.
+ */
+export function normalizeForSnapshot(definition, templates) {
+    return normalizeDefinition(definition, templates);
+}
+/**
+ * Normalize a single call by inlining template text if needed.
+ */
+function normalizeCall(call, templates) {
+    if (call.prompt != null) {
+        // Already has inline prompt — pass through, strip prompt_template
+        const { prompt_template: _, ...rest } = call;
+        return { ...rest, prompt: call.prompt };
+    }
+    // Must have prompt_template (XOR enforced by schema)
+    const templatePath = call.prompt_template;
+    const content = templates.get(templatePath);
+    if (content == null) {
+        throw new Error(`Template content not found for path "${templatePath}" ` +
+            `— resolveAllTemplates should have loaded this`);
+    }
+    const hash = hashContent(content);
+    const { prompt: _p, prompt_template: _t, ...rest } = call;
+    return {
+        ...rest,
+        prompt: content,
+        template_hash: hash,
+        template_path: templatePath,
+    };
+}
+/**
+ * Compute a SHA-256 hash of template content for snapshot fingerprinting.
+ */
+function hashContent(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+//# sourceMappingURL=definition-normalizer.js.map

package/clinkx-workflows/dist/definition-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-normalizer.js","sourceRoot":"","sources":["../src/definition-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8CzC,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAA8B,EAC9B,SAAsC;IAEtC,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACzD,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;KACjE,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,MAAM,EAAE,gBAAgB;QACxB,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,QAAQ,EAAE,UAAU,CAAC,QAAQ;KAC9B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAA8B,EAC9B,SAAsC;IAEtC,OAAO,mBAAmB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CACpB,IAAU,EACV,SAAsC;IAEtC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;QACxB,kEAAkE;QAClE,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;QAC7C,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAoB,CAAC;IAC5D,CAAC;IAED,qDAAqD;IACrD,MAAM,YAAY,GAAG,IAAI,CAAC,eAAgB,CAAC;IAC3C,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,wCAAwC,YAAY,IAAI;YACtD,+CAA+C,CAClD,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC1D,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,OAAO;QACf,aAAa,EAAE,IAAI;QACnB,aAAa,EAAE,YAAY;KACV,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC"}

package/clinkx-workflows/dist/engine.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Workflow execution engine for ordered linear stages.
+ *
+ * ## Timeout Ownership Model (3-8)
+ *
+ * Timeouts in clinkx-workflows operate at three distinct layers, each with
+ * clear ownership boundaries:
+ *
+ * ### Layer 1: Workflow-level deadline (engine-owned)
+ *
+ * The engine creates an AbortController with a deadline derived from
+ * `settings.timeout_seconds` (default: CLINKX_WORKFLOWS_TIMEOUT_SECONDS,
+ * 1800s). This is a hard wall clock ceiling for the entire workflow run.
+ * When exceeded, remaining stages are aborted and the run fails with
+ * a clear timeout error.
+ *
+ * Owner: WorkflowEngine.createDeadlineController()
+ * Config: CLINKX_WORKFLOWS_TIMEOUT_SECONDS (default: 1800)
+ * Scope: Entire workflow run
+ *
+ * ### Layer 2: Per-call parent-side timeout (engine-owned)
+ *
+ * Each tools/call RPC to the child has a parent-side timeout computed as:
+ *   max(call.timeout_seconds * 1000 + CALL_TIMEOUT_BUFFER_MS, DEFAULT_PARENT_CALL_TIMEOUT_MS)
+ *
+ * This prevents individual calls from blocking indefinitely. The buffer
+ * (CALL_TIMEOUT_BUFFER_MS = 5s) accounts for child-side teardown latency.
+ * DEFAULT_PARENT_CALL_TIMEOUT_MS (600s = 10min) is the floor — even calls
+ * without explicit timeout_seconds get a parent-side deadline.
+ *
+ * Owner: WorkflowEngine.invokeCall()
+ * Config: Per-call timeout_seconds in workflow definition
+ * Scope: Single tools/call RPC round-trip
+ *
+ * ### Layer 3: Child-side timeout (adapter-owned, NOT engine-controlled)
+ *
+ * The ClinkX child's own timeout behavior is controlled by adapter JSON
+ * config (codex.json:9, claude.json:8 — both set timeout_seconds: 3600).
+ * The env vars CLINKX_TIMEOUT_SECONDS, CLINKX_IDLE_TIMEOUT_SECONDS, and
+ * CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS are DEAD KNOBS with current shipped
+ * adapters — adapter JSON config wins (runner.ts:156-171).
+ *
+ * The workflow engine does NOT attempt to control child-side timeouts via
+ * env vars. Instead:
+ * - Per-call `timeout_seconds` in the workflow definition is passed as a
+ *   hidden field in the ClinkInput payload, which the child uses for
+ *   UPWARD EXTENSION ONLY (extends beyond adapter floor, never shortens).
+ * - If different child timeout/idle floors are needed, point the child at
+ *   a workflow-specific adapter bundle via CLINKX_WORKFLOWS_CHILD_CONFIG_PATH.
+ *
+ * Owner: Adapter JSON config in the child's config path
+ * Config: CLINKX_WORKFLOWS_CHILD_CONFIG_PATH for custom adapter bundles
+ * Scope: Single subprocess spawn within the child
+ *
+ * ### Interaction between layers
+ *
+ * The workflow deadline (L1) takes precedence: if it fires, all in-flight
+ * calls are cancelled regardless of their per-call timeouts (L2). The
+ * per-call timeout (L2) prevents any single call from consuming the entire
+ * workflow budget. The child-side timeout (L3) is independently enforced
+ * by the child and may fire before L2 — in that case the child returns
+ * isError: true with termination_reason: "wall" or "idle", which the
+ * workflow engine treats as a transient failure eligible for retry.
+ */
+import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+import { type ChildFailureMetadata } from "./errors.js";
+import { type FidelityReport } from "./fidelity.js";
+import type { CallState, FailureClass, RunStatus } from "./state-schema.js";
+import type { ClinkBackend } from "./backend.js";
+import type { ValidatorRegistry } from "./validators/index.js";
+import { type ArtifactRecord } from "./artifacts.js";
+export interface ExecutedCall {
+    readonly stageId: string;
+    readonly callId: string;
+    readonly ok: boolean;
+    readonly outputText?: string | undefined;
+    readonly error?: string | undefined;
+    readonly artifact?: ArtifactRecord | undefined;
+    readonly fidelity?: FidelityReport | undefined;
+}
+export interface ExecutedStage {
+    readonly stageId: string;
+    readonly ok: boolean;
+    readonly calls: readonly ExecutedCall[];
+    readonly aggregateArtifactPath?: string | undefined;
+}
+export interface WorkflowExecutionResult {
+    readonly outputText: string;
+    readonly stages: readonly ExecutedStage[];
+    readonly artifactsDir: string;
+}
+export interface EngineResumeState {
+    readonly completedCalls?: ReadonlyMap<string, ExecutedCall> | undefined;
+    readonly preparedInputs?: ReadonlyMap<string, Readonly<Record<string, unknown>>> | undefined;
+    readonly failedCalls?: ReadonlyMap<string, {
+        readonly stageId: string;
+        readonly callId: string;
+        readonly error: string;
+    }> | undefined;
+}
+type HookResult = Promise<void> | void;
+export interface EngineRunStateChange {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly state: RunStatus;
+    readonly startedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+    readonly error?: string | undefined;
+    readonly failureClass?: FailureClass | undefined;
+}
+export interface EngineCallPreparedEvent {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly stageId: string;
+    readonly callId: string;
+    readonly attempt: number;
+    readonly retryCount: number;
+    readonly contextProducing: boolean;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export interface EngineCallStateChange {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly stageId: string;
+    readonly callId: string;
+    readonly state: Exclude<CallState, "pending">;
+    readonly attempt: number;
+    readonly retryCount: number;
+    readonly startedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+    readonly durationMs?: number | undefined;
+    readonly outputText?: string | undefined;
+    readonly error?: string | undefined;
+    readonly failureClass?: FailureClass | undefined;
+    readonly fidelity?: FidelityReport | undefined;
+    readonly artifact?: ArtifactRecord | undefined;
+    readonly childDebugMetadata?: ChildFailureMetadata | undefined;
+}
+export interface EngineRetryEvent {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly stageId: string;
+    readonly callId: string;
+    readonly attempt: number;
+    readonly retryCount: number;
+    readonly nextRetryCount: number;
+    readonly delayMs: number;
+    readonly error: string;
+    readonly failureClass: FailureClass;
+}
+export interface EngineProgressEvent {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly scope: "run" | "stage" | "call";
+    readonly state: Exclude<CallState, "pending">;
+    readonly message: string;
+    readonly stageId?: string | undefined;
+    readonly stageDescription?: string | undefined;
+    readonly callId?: string | undefined;
+    readonly attempt?: number | undefined;
+    readonly retryCount?: number | undefined;
+}
+export interface EngineHooks {
+    readonly onRunStateChange?: ((event: EngineRunStateChange) => HookResult) | undefined;
+    readonly onCallPrepared?: ((event: EngineCallPreparedEvent) => HookResult) | undefined;
+    readonly onCallStateChange?: ((event: EngineCallStateChange) => HookResult) | undefined;
+    readonly onRetryScheduled?: ((event: EngineRetryEvent) => HookResult) | undefined;
+    readonly onProgress?: ((event: EngineProgressEvent) => HookResult) | undefined;
+}
+export interface WorkflowEngineOptions {
+    readonly definition: NormalizedWorkflowDefinition;
+    readonly session: ClinkBackend;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly validatorRegistry: ValidatorRegistry;
+    readonly runId: string;
+    readonly runDir: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly maxParallel?: number | undefined;
+    readonly childMaxConcurrent?: number | undefined;
+    readonly maxPromptBytes?: number | undefined;
+    readonly promptReserveBytes?: number | undefined;
+    readonly allowedRoots?: readonly string[] | undefined;
+    readonly hooks?: EngineHooks | undefined;
+    readonly resume?: EngineResumeState | undefined;
+}
+export declare class WorkflowEngine {
+    private readonly definition;
+    private readonly session;
+    private readonly variables;
+    private readonly validatorRegistry;
+    private readonly runId;
+    private readonly runDir;
+    private readonly signal;
+    private readonly queueDepth;
+    private readonly maxPromptBytes;
+    private readonly promptReserveBytes;
+    private readonly allowedRoots;
+    private readonly hooks;
+    private readonly resumeCompletedCalls;
+    private readonly resumePreparedInputs;
+    private readonly resumeFailedCalls;
+    private readonly contextProducingCalls;
+    private readonly artifactStore;
+    constructor(options: WorkflowEngineOptions);
+    execute(): Promise<WorkflowExecutionResult>;
+    private executeParallelStage;
+    private executeSequentialStage;
+    private executeSingleCall;
+    private invokeCall;
+    private maybeWriteArtifact;
+    private resolveDynamicPaths;
+    private createDeadlineController;
+    private throwIfAborted;
+    private validateFinalStage;
+    private validateAdvertisedCliNames;
+    private defaultAllowedRoots;
+    private buildCallInput;
+    private materializeUnexpectedFailure;
+    private emitRunStateChange;
+    private emitCallPrepared;
+    private emitCallStateChange;
+    private emitRetryScheduled;
+    private emitProgress;
+    private seedResumedArtifacts;
+    /**
+     * Pre-flight validation: check that all user-supplied file/image paths exist
+     * before any stage executes. Skips already-completed calls on resume.
+     *
+     * - ENOENT → collect as missing (fail-fast after checking all)
+     * - EACCES/EIO → warn but don't fail (NFS/FUSE transient)
+     * - context_from artifacts are NOT validated (engine-generated)
+     */
+    private validateInputPathsExist;
+}
+export {};