clinkx 0.2.0 → 0.2.2

package/clinkx-workflows/dist/transport.js

@@ -0,0 +1,249 @@
+/**
+ * ClinkSession — per-run MCP client transport to a ClinkX child process.
+ *
+ * Spawns ClinkX over STDIO, performs MCP initialize handshake,
+ * verifies clink tool availability, and provides callTool/terminate.
+ *
+ * The SDK's Client.request() already:
+ * - Supports timeout via RequestOptions.timeout (ms)
+ * - Sends notifications/cancelled on AbortSignal abort
+ * So we get 1-7a (deadlines) and 1-8a/b (cancellation) from the SDK.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { logger } from "./logger.js";
+import { buildChildEnv } from "./child-env.js";
+import { getClinkxCmd, resolveWorkspaceRoot, deriveAllowedRoots, getStateDir, getArtifactsDir, } from "./config.js";
+import { CallExecutionError } from "./errors.js";
+/** Default deadline for initialize + tools/list handshake (ms). */
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000;
+/** Default deadline for tools/call RPCs (ms). */
+const DEFAULT_CALL_TIMEOUT_MS = 600_000;
+/**
+ * Per-run MCP session to a ClinkX child process.
+ *
+ * Lifecycle: create → connect() → callTool() ... → terminate()
+ */
+export class ClinkSession {
+    client = null;
+    transport = null;
+    terminated = false;
+    childExitedUnexpectedly = false;
+    /** Cached cli_name values from tools/list. */
+    cliNames = [];
+    /** Cached role union from tools/list. */
+    roleNames = [];
+    runId;
+    command;
+    args;
+    envOverrides;
+    handshakeTimeoutMs;
+    callTimeoutMs;
+    onChildDeath;
+    constructor(options) {
+        this.runId = options.runId;
+        this.command = options.command ?? getClinkxCmd();
+        this.args = options.args ?? [];
+        this.envOverrides = options.envOverrides ?? {};
+        this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+        this.callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+        this.onChildDeath = options.onChildDeath;
+    }
+    /**
+     * Spawn child, perform MCP handshake, verify clink tool.
+     * Throws on failure (handshake timeout, missing clink tool, etc.).
+     */
+    async connect() {
+        const workspaceRoot = resolveWorkspaceRoot();
+        const stateDir = getStateDir();
+        const artifactsDir = getArtifactsDir();
+        const allowedRoots = deriveAllowedRoots(workspaceRoot, stateDir, artifactsDir);
+        const childEnv = buildChildEnv({
+            allowedRoots,
+            ...this.envOverrides,
+        });
+        const transportArgs = [...this.args];
+        this.transport = new StdioClientTransport({
+            command: this.command,
+            args: transportArgs,
+            env: childEnv,
+            cwd: workspaceRoot,
+            stderr: "pipe",
+        });
+        // Capture child stderr and re-log with prefix
+        this.setupStderrCapture();
+        // Monitor for unexpected child death
+        this.setupChildDeathHandler();
+        this.client = new Client({ name: "clinkx-workflows", version: "0.1.0" }, { capabilities: {} });
+        // Connect performs MCP initialize handshake with enforced timeout
+        const connectPromise = this.client.connect(this.transport);
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                reject(new Error(`Handshake timeout: child did not complete MCP initialize within ${String(this.handshakeTimeoutMs)}ms. ` +
+                    `Check that "${this.command}" is a valid MCP server command.`));
+            }, this.handshakeTimeoutMs);
+        });
+        try {
+            await Promise.race([connectPromise, timeoutPromise]);
+        }
+        catch (err) {
+            // Force-terminate on timeout or connect error
+            this.terminated = true;
+            try {
+                if (this.client != null) {
+                    await this.client.close();
+                    this.client = null;
+                }
+            }
+            catch { /* best-effort cleanup */ }
+            try {
+                if (this.transport != null) {
+                    await this.transport.close();
+                    this.transport = null;
+                }
+            }
+            catch { /* best-effort cleanup */ }
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`ClinkSession connect failed for run ${this.runId}: ${msg}`);
+        }
+        finally {
+            if (timeoutHandle != null) {
+                clearTimeout(timeoutHandle);
+            }
+        }
+        logger.info({ run_id: this.runId, server: this.client.getServerVersion() }, "child MCP handshake complete");
+        // tools/list — verify clink tool exists
+        const toolsResult = await this.client.listTools(undefined, {
+            timeout: this.handshakeTimeoutMs,
+        });
+        const clinkTool = toolsResult.tools.find((t) => t.name === "clink");
+        if (clinkTool == null) {
+            await this.terminate();
+            throw new Error(`ClinkSession: child does not expose "clink" tool. ` +
+                `Available: ${toolsResult.tools.map((t) => t.name).join(", ") || "(none)"}`);
+        }
+        // Cache cli_name enum values if advertised
+        const props = clinkTool.inputSchema.properties;
+        if (props?.["cli_name"]?.["enum"] != null) {
+            const names = props["cli_name"]["enum"];
+            if (Array.isArray(names)) {
+                this.cliNames.push(...names.filter((n) => typeof n === "string"));
+            }
+        }
+        // Cache role enum values if advertised
+        if (props?.["role"]?.["enum"] != null) {
+            const roles = props["role"]["enum"];
+            if (Array.isArray(roles)) {
+                this.roleNames.push(...roles.filter((r) => typeof r === "string"));
+            }
+        }
+        logger.info({
+            run_id: this.runId,
+            cli_names: this.cliNames,
+            role_names: this.roleNames,
+        }, "child clink tool verified");
+    }
+    /**
+     * Call the child's clink tool.
+     *
+     * @param args - Tool arguments (ClinkInput shape)
+     * @param options - Optional signal and timeout override
+     * @returns Tool call result
+     */
+    async callTool(args, options) {
+        if (this.terminated) {
+            throw new Error("ClinkSession: already terminated");
+        }
+        if (this.client == null) {
+            throw new Error("ClinkSession: not connected");
+        }
+        if (this.childExitedUnexpectedly) {
+            throw new CallExecutionError(`Child process died unexpectedly during run ${this.runId}`, "transport", "child_death", "transient");
+        }
+        const result = await this.client.callTool({ name: "clink", arguments: args }, undefined, {
+            timeout: options?.timeoutMs ?? this.callTimeoutMs,
+            ...(options?.signal != null ? { signal: options.signal } : {}),
+        });
+        return result;
+    }
+    /**
+     * Terminate the child session cleanly.
+     */
+    async terminate() {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        try {
+            if (this.client != null) {
+                await this.client.close();
+                this.client = null;
+            }
+        }
+        catch (err) {
+            logger.warn({ run_id: this.runId, err: err instanceof Error ? err.message : String(err) }, "error during child session close");
+        }
+        this.transport = null;
+        logger.info({ run_id: this.runId }, "child session terminated");
+    }
+    /**
+     * Whether the session has been terminated.
+     */
+    get isTerminated() {
+        return this.terminated;
+    }
+    /**
+     * Whether the child died unexpectedly.
+     */
+    get hasChildDied() {
+        return this.childExitedUnexpectedly;
+    }
+    /**
+     * Set up stderr capture from the child process.
+     * Prefix each line with [child:<run_id>] and re-log via parent pino.
+     */
+    setupStderrCapture() {
+        if (this.transport == null)
+            return;
+        const stderrStream = this.transport.stderr;
+        if (stderrStream == null)
+            return;
+        const prefix = `[child:${this.runId}]`;
+        let buffer = "";
+        stderrStream.on("data", (chunk) => {
+            buffer += chunk.toString("utf-8");
+            const lines = buffer.split("\n");
+            // Keep incomplete last line in buffer
+            buffer = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.trim().length > 0) {
+                    logger.debug({ run_id: this.runId }, "%s %s", prefix, line);
+                }
+            }
+        });
+        stderrStream.on("end", () => {
+            if (buffer.trim().length > 0) {
+                logger.debug({ run_id: this.runId }, "%s %s", prefix, buffer);
+            }
+        });
+    }
+    /**
+     * Monitor for unexpected child death (1-9a).
+     * On unexpected death mid-run, mark as transient failure.
+     */
+    setupChildDeathHandler() {
+        if (this.transport == null)
+            return;
+        // The SDK's StdioClientTransport fires onclose when the child exits
+        const originalOnclose = this.transport.onclose;
+        this.transport.onclose = () => {
+            if (!this.terminated) {
+                this.childExitedUnexpectedly = true;
+                logger.error({ run_id: this.runId }, "child process died unexpectedly");
+                this.onChildDeath?.(null, null);
+            }
+            originalOnclose?.();
+        };
+    }
+}
+//# sourceMappingURL=transport.js.map

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

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

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

@@ -0,0 +1,137 @@
+/**
+ * Core workflow type definitions for clinkx-workflows.
+ *
+ * v1 execution model: ORDERED LINEAR STAGES ONLY.
+ * - No DAGs, no depends_on, no topological sort.
+ * - Stage order = execution order.
+ * - Optional parallel fan-out WITHIN a stage; fan-in across stage boundaries.
+ * - Final stage MUST contain exactly one call (invariant 0-6a).
+ */
+/** Scalar variable types supported in v1. */
+export type VariableType = "string" | "number" | "boolean" | "string[]";
+/** Variable declaration in a workflow definition. */
+export interface Variable {
+    readonly type: VariableType;
+    readonly required: boolean;
+    readonly default?: string | number | boolean | readonly string[] | undefined;
+    readonly description?: string | undefined;
+}
+/**
+ * A single call to the ClinkX child process.
+ *
+ * Each call maps to one `tools/call` for the `clink` tool on the child.
+ */
+export interface Call {
+    /** Unique within its parent stage. Must match [A-Za-z0-9_-]+. */
+    readonly id: string;
+    /** Which CLI adapter to use (resolved by child's adapter registry). */
+    readonly cli_name: string;
+    /** Role selector — maps to adapter roles config. */
+    readonly role: string;
+    /**
+     * Exactly ONE of prompt or prompt_template must be set (XOR).
+     * prompt: inline prompt text.
+     * prompt_template: logical path relative to templates root (e.g. "council/member.txt").
+     */
+    readonly prompt?: string | undefined;
+    readonly prompt_template?: 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 (A.json, B.json, ...) to prevent identity leakage. */
+    readonly anonymize_context?: boolean | undefined;
+    /** Request timeout override (seconds). Extends above adapter floor, never shortens. */
+    readonly timeout_seconds?: number | undefined;
+    /** Static file paths to reference. */
+    readonly absolute_file_paths?: readonly string[] | undefined;
+    /** Variable name for dynamic file paths (resolved at run time). */
+    readonly absolute_file_paths_from?: string | undefined;
+    /** Static image paths. */
+    readonly images?: readonly string[] | undefined;
+    /** Variable name for dynamic image paths (resolved at run time). */
+    readonly images_from?: string | undefined;
+    /**
+     * References to prior stage/call outputs.
+     * Single ref or array, normalized to array internally.
+     * May reference a stage ID (all calls) or "stage.call" (specific call).
+     * MUST reference only EARLIER stages — forward references are rejected at load time.
+     */
+    readonly context_from?: readonly string[] | undefined;
+    /**
+     * Required for context-producing calls (any call referenced by context_from).
+     * Points to a registered zod schema in the ValidatorRegistry.
+     */
+    readonly validator_schema_id?: string | undefined;
+    /**
+     * Per-call override for CLINKX_WORKFLOWS_CHILD_MAX_RESPONSE_CHARS.
+     * Prevents limitOutput() from mangling structured output on context-producing stages.
+     * Task 0-10-2.
+     */
+    readonly max_response_chars?: number | undefined;
+    /**
+     * Response contract for structured output.
+     * When set to "json", the call is expected to produce valid JSON output.
+     */
+    readonly response_contract?: "json" | undefined;
+}
+/**
+ * Retry configuration for a stage.
+ *
+ * mode:
+ * - "transport_only" (default): retry on child crash, wall timeout, idle timeout, transport death.
+ * - "all": retry on any isError: true (legacy behavior).
+ *
+ * In both modes, child -32602 (InvalidParams) is ALWAYS permanent (no retry).
+ */
+export interface RetryConfig {
+    readonly mode: "transport_only" | "all";
+    readonly max_retries: number;
+    readonly backoff_seconds: number;
+    readonly max_backoff_seconds: number;
+}
+/**
+ * A stage is an ordered group of calls.
+ *
+ * v1: stages execute in DEFINITION ORDER. No depends_on, no topological sort.
+ */
+export interface Stage {
+    /** Unique across the workflow. Must match [A-Za-z0-9_-]+. */
+    readonly id: string;
+    /** If true (default), calls within this stage execute concurrently. */
+    readonly parallel: boolean;
+    /** Retry policy for calls in this stage. */
+    readonly retry: RetryConfig;
+    /** Failure policy: abort stops the workflow; continue records and proceeds. */
+    readonly on_failure: "abort" | "continue";
+    /**
+     * Calls in this stage.
+     * INVARIANT (0-6a): If this is the FINAL stage in the workflow,
+     * it MUST contain exactly one call.
+     */
+    readonly calls: readonly Call[];
+}
+/** Workflow-level settings. */
+export interface WorkflowSettings {
+    readonly timeout_seconds: number;
+    readonly max_retries: number;
+}
+/**
+ * Complete workflow definition.
+ *
+ * v1 scope:
+ * - Ordered stages only — stage array order = execution order.
+ * - No arbitrary DAGs.
+ * - Final stage must have exactly one call (0-6a).
+ * - Side-effecting workflows rejected at load time (0-5a).
+ */
+export interface WorkflowDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly variables: Readonly<Record<string, Variable>>;
+    readonly settings: WorkflowSettings;
+    /**
+     * Ordered stages. Execution proceeds strictly in array order.
+     * The last element is the final stage and must contain exactly one call.
+     */
+    readonly stages: readonly Stage[];
+}

package/clinkx-workflows/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Core workflow type definitions for clinkx-workflows.
+ *
+ * v1 execution model: ORDERED LINEAR STAGES ONLY.
+ * - No DAGs, no depends_on, no topological sort.
+ * - Stage order = execution order.
+ * - Optional parallel fan-out WITHIN a stage; fan-in across stage boundaries.
+ * - Final stage MUST contain exactly one call (invariant 0-6a).
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}