clinkx 0.2.0 → 0.2.2

package/clinkx-workflows/dist/clink-client.js

@@ -0,0 +1,216 @@
+/**
+ * Clink client wrapper for clinkx-workflows.
+ *
+ * Provides callClink() — the typed interface for calling the child's
+ * clink tool and parsing its response into output_text + debug_metadata.
+ *
+ * Key behaviors:
+ * - Always sets debug: true on internal calls
+ * - Parses MCP text content blocks robustly (no positional assumptions)
+ * - Strips host _meta.progressToken from child calls (progress isolation)
+ * - Maps child -32602 to InvalidCallError
+ * - Maps child isError: true to CallExecutionError
+ * - Only output_text is stored/threaded/hashed
+ */
+import { InvalidCallError, CallExecutionError } from "./errors.js";
+import { logger } from "./logger.js";
+import { basename } from "node:path";
+/**
+ * Build the tool arguments for a child clink call.
+ *
+ * Ensures debug: true is always set and strips any _meta.progressToken
+ * to prevent child from emitting progress to the host.
+ */
+export function buildCallArgs(input) {
+    // Clone to avoid mutating caller's input
+    const args = { ...input };
+    // Always enable debug for internal calls
+    args["debug"] = true;
+    // Strip host _meta.progressToken (1-11a: progress isolation)
+    if (args["_meta"] != null && typeof args["_meta"] === "object") {
+        const meta = { ...args["_meta"] };
+        delete meta["progressToken"];
+        // Only keep _meta if it still has keys
+        if (Object.keys(meta).length > 0) {
+            args["_meta"] = meta;
+        }
+        else {
+            delete args["_meta"];
+        }
+    }
+    return args;
+}
+/**
+ * Parse the MCP tool call result into output_text and debug_metadata.
+ *
+ * Does NOT assume positional ordering — scans all text content blocks
+ * and identifies the _debug block by JSON-parsing each one.
+ */
+export function parseCallResult(result) {
+    const textBlocks = [];
+    let debugMetadata = null;
+    if (result.content != null) {
+        for (const block of result.content) {
+            if (block.type === "text" && block.text != null) {
+                // Try to identify _debug block
+                const text = block.text.trim();
+                if (debugMetadata == null && text.startsWith("{")) {
+                    try {
+                        const parsed = JSON.parse(text);
+                        if ("_debug" in parsed && typeof parsed["_debug"] === "object") {
+                            debugMetadata = parsed["_debug"];
+                            continue; // Don't include _debug block in output_text
+                        }
+                    }
+                    catch {
+                        // Not JSON or not _debug — treat as output text
+                    }
+                }
+                textBlocks.push(block.text);
+            }
+        }
+    }
+    return {
+        outputText: textBlocks.join(""),
+        debugMetadata,
+    };
+}
+function sanitizeDebugMetadataForLog(debug) {
+    if (debug == null)
+        return null;
+    if (typeof debug["adapter_config_path"] !== "string")
+        return debug;
+    return {
+        ...debug,
+        adapter_config_path: basename(debug["adapter_config_path"]),
+    };
+}
+/**
+ * Call the child's clink tool and return parsed output.
+ *
+ * @param session - Active ClinkBackend
+ * @param input - Tool input arguments (ClinkInput shape)
+ * @param signal - Optional AbortSignal for cancellation
+ * @param context - Stage/call context for error attribution
+ * @returns Parsed clink call result
+ * @throws InvalidCallError on child -32602
+ * @throws CallExecutionError on child isError: true
+ */
+export async function callClink(session, input, signal, context, timeoutMs) {
+    const args = buildCallArgs(input);
+    const stageId = context?.stageId ?? "unknown";
+    const callId = context?.callId ?? "unknown";
+    let result;
+    try {
+        result = await session.callTool(args, signal != null || timeoutMs != null
+            ? {
+                ...(signal != null ? { signal } : {}),
+                ...(timeoutMs != null ? { timeoutMs } : {}),
+            }
+            : undefined);
+    }
+    catch (err) {
+        // Check for MCP -32602 (InvalidParams) error from child
+        if (isMcpInvalidParams(err)) {
+            throw new InvalidCallError(`Child rejected call as invalid: ${err instanceof Error ? err.message : String(err)}`, stageId, callId);
+        }
+        throw err;
+    }
+    // Map child isError: true to CallExecutionError
+    if (result.isError === true) {
+        const parsed = parseCallResult(result);
+        const failureClass = classifyFailure(parsed.debugMetadata);
+        const childDebugMetadata = extractChildFailureMetadata(parsed.debugMetadata);
+        // Fallback: if pipeline missed the panic class (e.g. wrapper formatting
+        // differences), detect the codex-local crash signature in output text.
+        let effectiveFailureClass = failureClass;
+        let effectiveChildDebugMetadata = childDebugMetadata;
+        if (failureClass === "permanent" && parsed.outputText != null) {
+            const codexLocalMatch = parsed.outputText.match(/\[codex-local\]:?\s*Local Codex process failed(?::\s*Process exited with code:\s*(\d+))?/);
+            if (codexLocalMatch != null) {
+                const exitCode = codexLocalMatch[1] != null ? Number(codexLocalMatch[1]) : null;
+                const synthesizedClass = exitCode === 101 ? "codex_local_rust_panic" : "codex_local_crash";
+                if (TRANSIENT_PANIC_CLASSES.has(synthesizedClass)) {
+                    effectiveFailureClass = "transient";
+                    logger.info({ stage_id: stageId, call_id: callId, synthesized_panic_class: synthesizedClass }, "reclassified failure as transient via output-text fallback");
+                    // Synthesize into childDebugMetadata (readonly fields — create new object)
+                    if (effectiveChildDebugMetadata != null) {
+                        effectiveChildDebugMetadata = { ...effectiveChildDebugMetadata, codex_panic_class: synthesizedClass };
+                    }
+                    else {
+                        effectiveChildDebugMetadata = { codex_panic_class: synthesizedClass };
+                    }
+                }
+            }
+        }
+        logger.warn({
+            stage_id: stageId,
+            call_id: callId,
+            failure_class: failureClass,
+            effective_failure_class: effectiveFailureClass,
+            debug: sanitizeDebugMetadataForLog(parsed.debugMetadata),
+        }, "child clink call returned isError");
+        throw new CallExecutionError(parsed.outputText || "Child clink call failed", stageId, callId, effectiveFailureClass, effectiveChildDebugMetadata);
+    }
+    return parseCallResult(result);
+}
+/**
+ * Panic classes confirmed as transient (retryable). Only classes with strong
+ * evidence of being transport-layer failures belong here. `codex_local_crash`
+ * is deliberately excluded — a generic wrapper exit may indicate a permanent
+ * failure (OOM, config error, sandbox violation).
+ */
+const TRANSIENT_PANIC_CLASSES = new Set([
+    "stdout_would_block",
+    "stdout_broken_pipe",
+    "stdout_write_failure",
+    "codex_local_rust_panic",
+]);
+/**
+ * Classify a child failure as transient or permanent based on _debug metadata.
+ */
+function classifyFailure(debug) {
+    if (debug == null)
+        return "permanent";
+    const reason = debug["termination_reason"];
+    if (reason === "wall" || reason === "idle")
+        return "transient";
+    const panicClass = debug["codex_panic_class"];
+    if (typeof panicClass === "string" && TRANSIENT_PANIC_CLASSES.has(panicClass)) {
+        return "transient";
+    }
+    const exitCode = debug["exit_code"];
+    if (exitCode === null || exitCode === undefined)
+        return "transient";
+    return "permanent";
+}
+/**
+ * Extract structured failure metadata from the child's _debug block.
+ */
+function extractChildFailureMetadata(debug) {
+    if (debug == null)
+        return undefined;
+    const meta = {
+        rejection_reason: typeof debug["rejection_reason"] === "string" ? debug["rejection_reason"] : undefined,
+        parse_status: typeof debug["parse_status"] === "string" ? debug["parse_status"] : undefined,
+        parse_source: typeof debug["parse_source"] === "string" ? debug["parse_source"] : undefined,
+        adapter_config_path: typeof debug["adapter_config_path"] === "string" ? debug["adapter_config_path"] : undefined,
+        exit_code: typeof debug["exit_code"] === "number" || debug["exit_code"] === null ? debug["exit_code"] : undefined,
+        codex_panic_class: typeof debug["codex_panic_class"] === "string" ? debug["codex_panic_class"] : undefined,
+    };
+    // Only return if at least one field is present
+    const hasContent = meta.rejection_reason != null || meta.parse_status != null ||
+        meta.parse_source != null || meta.adapter_config_path != null || meta.exit_code !== undefined ||
+        meta.codex_panic_class != null;
+    return hasContent ? meta : undefined;
+}
+/**
+ * Check if an error is an MCP -32602 (InvalidParams) error.
+ */
+function isMcpInvalidParams(err) {
+    if (err == null || typeof err !== "object")
+        return false;
+    const code = err["code"];
+    return code === -32602;
+}
+//# sourceMappingURL=clink-client.js.map

package/clinkx-workflows/dist/clink-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clink-client.js","sourceRoot":"","sources":["../src/clink-client.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,126 @@
+/**
+ * Environment variable definitions and defaults for clinkx-workflows.
+ *
+ * All workflow-server env vars use the CLINKX_WORKFLOWS_* prefix.
+ * Child env vars (CLINKX_*) are scrubbed from the child process environment
+ * and re-injected only with explicit workflow-owned values.
+ *
+ * ## Real vs Dead Knobs (child env)
+ *
+ * REAL controls (child env CAN control these):
+ * - CLINKX_MAX_CONCURRENT: fail-fast semaphore depth (concurrency.ts:3,25-29)
+ * - CLINKX_MAX_RESPONSE_CHARS: output truncation ceiling (pipeline.ts env fallback)
+ * - CLINKX_MAX_OUTPUT_BYTES: per-stream capture cap (runner.ts::createStreamCapture)
+ * - CLINKX_MAX_PROMPT_BYTES: pre-dispatch prompt ceiling (runner.ts)
+ * - CLINKX_CONFIG_PATH: adapter config path override
+ * - CLINKX_ALLOWED_ROOTS: comma-separated allowed path prefixes
+ * - CLINKX_LOG_LEVEL: pino log verbosity
+ *
+ * DEAD knobs (adapter JSON wins, env has no effect with current shipped adapters):
+ * - CLINKX_TIMEOUT_SECONDS: both shipped adapters set timeout_seconds in JSON
+ *   (codex.json:9 = 3600, claude.json:8 = 3600). Adapter config wins per runner.ts:156-159.
+ * - CLINKX_IDLE_TIMEOUT_SECONDS: both shipped adapters set idle_timeout_seconds in JSON.
+ *   Adapter config wins per runner.ts:164-167.
+ * - CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS: both shipped adapters set idle_timeout_startup_seconds.
+ *   Adapter config wins per runner.ts:168-171. Additionally, result_contract.enabled forces
+ *   both idle timers to 0 (runner.ts:163-170).
+ */
+/** Resolve workspace root: explicit env > process.cwd() with warning. */
+export declare function resolveWorkspaceRoot(): string;
+/** Whether workspace root was explicitly configured. */
+export declare function hasExplicitWorkspaceRoot(): boolean;
+/**
+ * Derive CLINKX_ALLOWED_ROOTS for the child process.
+ * Union of resolved workspace root + workflow state/artifact roots.
+ * Rejects filesystem root (/) as workspace root.
+ */
+export declare function deriveAllowedRoots(workspaceRoot: string, stateDir: string, artifactsDir: string): string;
+/** Command to spawn the owned ClinkX child. */
+export declare function getClinkxCmd(): string;
+/** Workflow definition directory. */
+export declare function getWorkflowsPath(): string;
+/** Prompt template root directory (resolved relative to package root). */
+export declare function getTemplatesPath(): string;
+/** Upper bound for concurrent calls within a parallel stage. */
+export declare function getMaxParallel(): number;
+/** Passed to child as CLINKX_MAX_CONCURRENT. */
+export declare function getChildMaxConcurrent(): number;
+/** Passed to child as CLINKX_MAX_RESPONSE_CHARS (200k to avoid silent context truncation). */
+export declare function getChildMaxResponseChars(): number;
+/** Passed to child as CLINKX_MAX_OUTPUT_BYTES. */
+export declare function getChildMaxOutputBytes(): number;
+/** Passed to child as CLINKX_MAX_PROMPT_BYTES. */
+export declare function getChildMaxPromptBytes(): number;
+/** Optional workflow-owned child adapter bundle path. */
+export declare function getChildConfigPath(): string | undefined;
+/**
+ * Default workflow-level timeout (seconds).
+ *
+ * This is the hard wall clock ceiling for an entire workflow run. The engine
+ * creates an AbortController with this deadline; when exceeded, remaining
+ * stages are aborted. Overridden by `settings.timeout_seconds` in the
+ * workflow definition.
+ *
+ * This is the workflow-server-level timeout (Layer 1 in the timeout ownership
+ * model). It is distinct from:
+ * - Per-call timeout_seconds in workflow definitions (Layer 2, upward extension only)
+ * - Child-side adapter timeouts in adapter JSON (Layer 3, adapter-owned)
+ *
+ * See engine.ts module comment for the full timeout ownership model.
+ */
+export declare function getWorkflowTimeout(): number;
+/** Pre-dispatch UTF-8 prompt/context ceiling (bytes). */
+export declare function getMaxPromptBytes(): number;
+/** Workflow server log level. */
+export declare function getLogLevel(): string;
+/** Persistent workflow state directory. */
+export declare function getStateDir(): string;
+/** Base directory containing persistent run state directories. */
+export declare function getRunsDir(): string;
+/** Persistent state directory for a specific run. */
+export declare function getRunStateDir(runId: string): string;
+/** Disposable per-run artifacts directory. */
+export declare function getArtifactsDir(): string;
+/**
+ * CLINKX_* env vars to scrub from child process environment before re-injection.
+ * All CLINKX_* vars are scrubbed; only explicit workflow-owned values are re-injected.
+ */
+export declare const CHILD_ENV_SCRUB_PREFIX = "CLINKX_";
+/**
+ * Config-discovery vars to also scrub (prevent child from inheriting parent's
+ * config resolution path, which would bypass workflow-owned adapter bundles).
+ */
+export declare const CHILD_ENV_SCRUB_EXTRA: readonly ["XDG_CONFIG_HOME"];
+/**
+ * Child env vars that are re-injected with workflow-owned values.
+ * Maps from workflow config key to child env var name.
+ */
+export declare const CHILD_ENV_REINJECT_MAP: {
+    readonly maxConcurrent: "CLINKX_MAX_CONCURRENT";
+    readonly maxResponseChars: "CLINKX_MAX_RESPONSE_CHARS";
+    readonly maxOutputBytes: "CLINKX_MAX_OUTPUT_BYTES";
+    readonly maxPromptBytes: "CLINKX_MAX_PROMPT_BYTES";
+    readonly configPath: "CLINKX_CONFIG_PATH";
+    readonly allowedRoots: "CLINKX_ALLOWED_ROOTS";
+    readonly logLevel: "CLINKX_LOG_LEVEL";
+};
+/**
+ * Baseline OS env vars that are NEVER scrubbed from child.
+ * ClinkX's internal env.ts::buildEnv handles delegate subprocess sanitization.
+ */
+export declare const CHILD_ENV_BASELINE: readonly ["PATH", "HOME", "USER", "LANG", "TMPDIR"];
+/**
+ * DEAD KNOBS: these env vars have no effect with current shipped adapters
+ * because adapter JSON config wins (runner.ts:156-171). Both shipped adapters
+ * set timeout_seconds in JSON (codex.json:9 = 3600, claude.json:8 = 3600).
+ *
+ * These are Layer 3 (child-side) timeout controls. The workflow engine does
+ * NOT attempt to control child-side timeouts via env vars. Instead, use
+ * CLINKX_WORKFLOWS_CHILD_CONFIG_PATH to point at a workflow-specific adapter
+ * bundle with the desired timeout floors.
+ *
+ * See engine.ts module comment for the full timeout ownership model.
+ *
+ * Do NOT set these in the child env — they create a false sense of control.
+ */
+export declare const DEAD_KNOBS: readonly ["CLINKX_TIMEOUT_SECONDS", "CLINKX_IDLE_TIMEOUT_SECONDS", "CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS"];

package/clinkx-workflows/dist/config.js

@@ -0,0 +1,226 @@
+/**
+ * Environment variable definitions and defaults for clinkx-workflows.
+ *
+ * All workflow-server env vars use the CLINKX_WORKFLOWS_* prefix.
+ * Child env vars (CLINKX_*) are scrubbed from the child process environment
+ * and re-injected only with explicit workflow-owned values.
+ *
+ * ## Real vs Dead Knobs (child env)
+ *
+ * REAL controls (child env CAN control these):
+ * - CLINKX_MAX_CONCURRENT: fail-fast semaphore depth (concurrency.ts:3,25-29)
+ * - CLINKX_MAX_RESPONSE_CHARS: output truncation ceiling (pipeline.ts env fallback)
+ * - CLINKX_MAX_OUTPUT_BYTES: per-stream capture cap (runner.ts::createStreamCapture)
+ * - CLINKX_MAX_PROMPT_BYTES: pre-dispatch prompt ceiling (runner.ts)
+ * - CLINKX_CONFIG_PATH: adapter config path override
+ * - CLINKX_ALLOWED_ROOTS: comma-separated allowed path prefixes
+ * - CLINKX_LOG_LEVEL: pino log verbosity
+ *
+ * DEAD knobs (adapter JSON wins, env has no effect with current shipped adapters):
+ * - CLINKX_TIMEOUT_SECONDS: both shipped adapters set timeout_seconds in JSON
+ *   (codex.json:9 = 3600, claude.json:8 = 3600). Adapter config wins per runner.ts:156-159.
+ * - CLINKX_IDLE_TIMEOUT_SECONDS: both shipped adapters set idle_timeout_seconds in JSON.
+ *   Adapter config wins per runner.ts:164-167.
+ * - CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS: both shipped adapters set idle_timeout_startup_seconds.
+ *   Adapter config wins per runner.ts:168-171. Additionally, result_contract.enabled forces
+ *   both idle timers to 0 (runner.ts:163-170).
+ */
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+// ---------------------------------------------------------------------------
+// Workflow server env vars (CLINKX_WORKFLOWS_*)
+// ---------------------------------------------------------------------------
+function envStr(key, fallback) {
+    const v = process.env[key];
+    return v != null && v !== "" ? v : fallback;
+}
+function envInt(key, fallback) {
+    const v = process.env[key];
+    if (v == null || v === "")
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Resolve workspace root: explicit env > process.cwd() with warning. */
+export function resolveWorkspaceRoot() {
+    const explicit = process.env["CLINKX_WORKFLOWS_WORKSPACE_ROOT"];
+    if (explicit != null && explicit !== "") {
+        try {
+            return realpathSync(resolve(explicit));
+        }
+        catch {
+            return resolve(explicit);
+        }
+    }
+    // Fallback with warning — caller should log this
+    return resolve(process.cwd());
+}
+/** Whether workspace root was explicitly configured. */
+export function hasExplicitWorkspaceRoot() {
+    const v = process.env["CLINKX_WORKFLOWS_WORKSPACE_ROOT"];
+    return v != null && v !== "";
+}
+/**
+ * Derive CLINKX_ALLOWED_ROOTS for the child process.
+ * Union of resolved workspace root + workflow state/artifact roots.
+ * Rejects filesystem root (/) as workspace root.
+ */
+export function deriveAllowedRoots(workspaceRoot, stateDir, artifactsDir) {
+    const roots = [workspaceRoot, stateDir, artifactsDir];
+    return roots.join(",");
+}
+// ---------------------------------------------------------------------------
+// Config accessors
+// ---------------------------------------------------------------------------
+/** Command to spawn the owned ClinkX child. */
+export function getClinkxCmd() {
+    return envStr("CLINKX_WORKFLOWS_CLINKX_CMD", "clinkx");
+}
+/**
+ * Resolve a path relative to the package root (two levels up from dist/src/).
+ * If the path is absolute, return as-is.
+ */
+function resolvePackageRelative(raw) {
+    if (raw.startsWith("/")) {
+        return raw;
+    }
+    const packageRoot = resolve(import.meta.dirname, "..");
+    return resolve(packageRoot, raw);
+}
+/** Workflow definition directory. */
+export function getWorkflowsPath() {
+    return envStr("CLINKX_WORKFLOWS_PATH", "workflows/");
+}
+/** Prompt template root directory (resolved relative to package root). */
+export function getTemplatesPath() {
+    return resolvePackageRelative(envStr("CLINKX_WORKFLOWS_TEMPLATES_PATH", "templates/"));
+}
+/** Upper bound for concurrent calls within a parallel stage. */
+export function getMaxParallel() {
+    return envInt("CLINKX_WORKFLOWS_MAX_PARALLEL", 5);
+}
+/** Passed to child as CLINKX_MAX_CONCURRENT. */
+export function getChildMaxConcurrent() {
+    return envInt("CLINKX_WORKFLOWS_CHILD_MAX_CONCURRENT", 5);
+}
+/** Passed to child as CLINKX_MAX_RESPONSE_CHARS (200k to avoid silent context truncation). */
+export function getChildMaxResponseChars() {
+    return envInt("CLINKX_WORKFLOWS_CHILD_MAX_RESPONSE_CHARS", 200_000);
+}
+/** Passed to child as CLINKX_MAX_OUTPUT_BYTES. */
+export function getChildMaxOutputBytes() {
+    return envInt("CLINKX_WORKFLOWS_CHILD_MAX_OUTPUT_BYTES", 10_485_760);
+}
+/** Passed to child as CLINKX_MAX_PROMPT_BYTES. */
+export function getChildMaxPromptBytes() {
+    return envInt("CLINKX_WORKFLOWS_CHILD_MAX_PROMPT_BYTES", 1_048_576);
+}
+/** Optional workflow-owned child adapter bundle path. */
+export function getChildConfigPath() {
+    const v = process.env["CLINKX_WORKFLOWS_CHILD_CONFIG_PATH"];
+    return v != null && v !== "" ? v : undefined;
+}
+/**
+ * Default workflow-level timeout (seconds).
+ *
+ * This is the hard wall clock ceiling for an entire workflow run. The engine
+ * creates an AbortController with this deadline; when exceeded, remaining
+ * stages are aborted. Overridden by `settings.timeout_seconds` in the
+ * workflow definition.
+ *
+ * This is the workflow-server-level timeout (Layer 1 in the timeout ownership
+ * model). It is distinct from:
+ * - Per-call timeout_seconds in workflow definitions (Layer 2, upward extension only)
+ * - Child-side adapter timeouts in adapter JSON (Layer 3, adapter-owned)
+ *
+ * See engine.ts module comment for the full timeout ownership model.
+ */
+export function getWorkflowTimeout() {
+    return envInt("CLINKX_WORKFLOWS_TIMEOUT_SECONDS", 1800);
+}
+/** Pre-dispatch UTF-8 prompt/context ceiling (bytes). */
+export function getMaxPromptBytes() {
+    return envInt("CLINKX_WORKFLOWS_MAX_PROMPT_BYTES", 900_000);
+}
+/** Workflow server log level. */
+export function getLogLevel() {
+    return envStr("CLINKX_WORKFLOWS_LOG_LEVEL", "info");
+}
+/** Persistent workflow state directory. */
+export function getStateDir() {
+    const xdgState = process.env["XDG_STATE_HOME"];
+    const defaultBase = xdgState != null && xdgState !== ""
+        ? xdgState
+        : `${process.env["HOME"] ?? "~"}/.local/state`;
+    return envStr("CLINKX_WORKFLOWS_STATE_DIR", `${defaultBase}/clinkx-workflows`);
+}
+/** Base directory containing persistent run state directories. */
+export function getRunsDir() {
+    return join(getStateDir(), "runs");
+}
+/** Persistent state directory for a specific run. */
+export function getRunStateDir(runId) {
+    return join(getRunsDir(), runId);
+}
+/** Disposable per-run artifacts directory. */
+export function getArtifactsDir() {
+    const tmpdir = process.env["TMPDIR"] ?? "/tmp";
+    return envStr("CLINKX_WORKFLOWS_ARTIFACTS_DIR", `${tmpdir}/clinkx-workflows/artifacts`);
+}
+// ---------------------------------------------------------------------------
+// Child env scrub/reinject constants
+// ---------------------------------------------------------------------------
+/**
+ * CLINKX_* env vars to scrub from child process environment before re-injection.
+ * All CLINKX_* vars are scrubbed; only explicit workflow-owned values are re-injected.
+ */
+export const CHILD_ENV_SCRUB_PREFIX = "CLINKX_";
+/**
+ * Config-discovery vars to also scrub (prevent child from inheriting parent's
+ * config resolution path, which would bypass workflow-owned adapter bundles).
+ */
+export const CHILD_ENV_SCRUB_EXTRA = ["XDG_CONFIG_HOME"];
+/**
+ * Child env vars that are re-injected with workflow-owned values.
+ * Maps from workflow config key to child env var name.
+ */
+export const CHILD_ENV_REINJECT_MAP = {
+    maxConcurrent: "CLINKX_MAX_CONCURRENT",
+    maxResponseChars: "CLINKX_MAX_RESPONSE_CHARS",
+    maxOutputBytes: "CLINKX_MAX_OUTPUT_BYTES",
+    maxPromptBytes: "CLINKX_MAX_PROMPT_BYTES",
+    configPath: "CLINKX_CONFIG_PATH",
+    allowedRoots: "CLINKX_ALLOWED_ROOTS",
+    logLevel: "CLINKX_LOG_LEVEL",
+};
+/**
+ * Baseline OS env vars that are NEVER scrubbed from child.
+ * ClinkX's internal env.ts::buildEnv handles delegate subprocess sanitization.
+ */
+export const CHILD_ENV_BASELINE = [
+    "PATH",
+    "HOME",
+    "USER",
+    "LANG",
+    "TMPDIR",
+];
+/**
+ * DEAD KNOBS: these env vars have no effect with current shipped adapters
+ * because adapter JSON config wins (runner.ts:156-171). Both shipped adapters
+ * set timeout_seconds in JSON (codex.json:9 = 3600, claude.json:8 = 3600).
+ *
+ * These are Layer 3 (child-side) timeout controls. The workflow engine does
+ * NOT attempt to control child-side timeouts via env vars. Instead, use
+ * CLINKX_WORKFLOWS_CHILD_CONFIG_PATH to point at a workflow-specific adapter
+ * bundle with the desired timeout floors.
+ *
+ * See engine.ts module comment for the full timeout ownership model.
+ *
+ * Do NOT set these in the child env — they create a false sense of control.
+ */
+export const DEAD_KNOBS = [
+    "CLINKX_TIMEOUT_SECONDS",
+    "CLINKX_IDLE_TIMEOUT_SECONDS",
+    "CLINKX_IDLE_TIMEOUT_STARTUP_SECONDS",
+];
+//# sourceMappingURL=config.js.map

package/clinkx-workflows/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/definition-normalizer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 type { WorkflowDefinition, Call } from "./schema.js";
+/** A call with prompt_template resolved to inlined text + hash. */
+export interface NormalizedCall extends Omit<Call, "prompt_template"> {
+    /** Always present after normalization — either original prompt or inlined template. */
+    readonly prompt: string;
+    /** Removed after normalization — replaced by inlined prompt. */
+    readonly prompt_template?: undefined;
+    /** Present only if the original call used prompt_template. */
+    readonly template_hash?: string | undefined;
+    /** Original template path, preserved for diagnostics. */
+    readonly template_path?: string | undefined;
+    /** Built-in reducer function ID. When set, this call runs a deterministic function instead of an LLM. */
+    readonly reducer?: string | undefined;
+    /** If true, upstream context artifacts are aliased to prevent identity leakage. */
+    readonly anonymize_context?: boolean | undefined;
+}
+export interface NormalizedStage {
+    readonly id: string;
+    readonly description?: string | undefined;
+    readonly parallel: boolean;
+    readonly retry: Call extends {
+        retry: infer R;
+    } ? R : {
+        readonly mode: "transport_only" | "all";
+        readonly max_retries: number;
+        readonly backoff_seconds: number;
+        readonly max_backoff_seconds: number;
+    };
+    readonly on_failure: "abort" | "continue";
+    readonly calls: readonly NormalizedCall[];
+}
+export interface NormalizedWorkflowDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly stages: readonly NormalizedStage[];
+    readonly variables: WorkflowDefinition["variables"];
+    readonly settings: WorkflowDefinition["settings"];
+}
+/**
+ * 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 declare function normalizeDefinition(definition: WorkflowDefinition, templates: ReadonlyMap<string, string>): NormalizedWorkflowDefinition;
+/**
+ * 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 declare function normalizeForSnapshot(definition: WorkflowDefinition, templates: ReadonlyMap<string, string>): NormalizedWorkflowDefinition;