clinkx 0.2.0 → 0.2.1

package/clinkx-workflows/dist/schema.js

@@ -0,0 +1,123 @@
+/**
+ * Zod schemas for workflow definitions (clinkx-workflows).
+ *
+ * This is separate from the parent ClinkX schema.ts — these schemas define
+ * workflow definition structure, not MCP tool input.
+ *
+ * Tasks: 2-1a, 2-2a, 2-3a, 2-4a, 2-5a
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// 2-5a: ID Grammar
+// ---------------------------------------------------------------------------
+/**
+ * ID grammar: [A-Za-z0-9_-]+
+ * Dots are forbidden because "stage.call" is the reference syntax for context_from.
+ */
+const ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+export const IdSchema = z
+    .string()
+    .min(1)
+    .regex(ID_PATTERN, "IDs must match [A-Za-z0-9_-]+ (dots forbidden)");
+// ---------------------------------------------------------------------------
+// 2-2a: VariableSchema
+// ---------------------------------------------------------------------------
+export const VariableTypeSchema = z.enum([
+    "string",
+    "number",
+    "boolean",
+    "string[]",
+]);
+export const VariableSchema = z.object({
+    type: VariableTypeSchema,
+    required: z.boolean(),
+    default: z
+        .union([z.string(), z.number(), z.boolean(), z.array(z.string())])
+        .optional(),
+    description: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// 2-3a: StageSchema — RetryConfig
+// ---------------------------------------------------------------------------
+export const RetryConfigSchema = z.object({
+    mode: z
+        .enum(["transport_only", "all"])
+        .default("transport_only"),
+    max_retries: z.number().int().min(0).default(0),
+    backoff_seconds: z.number().min(0).default(5),
+    max_backoff_seconds: z.number().min(0).default(60),
+});
+// ---------------------------------------------------------------------------
+// 2-4a: CallSchema
+// ---------------------------------------------------------------------------
+/**
+ * Normalize context_from: accept a single string or array, always produce array.
+ */
+const ContextFromSchema = z
+    .union([z.string(), z.array(z.string())])
+    .transform((val) => (typeof val === "string" ? [val] : val))
+    .optional();
+const BaseCallSchema = z.object({
+    id: IdSchema,
+    cli_name: z.string().min(1),
+    role: z.string().min(1),
+    reducer: z.string().optional(),
+    anonymize_context: z.boolean().optional(),
+    timeout_seconds: z.number().positive().optional(),
+    absolute_file_paths: z.array(z.string()).optional(),
+    absolute_file_paths_from: z.string().optional(),
+    images: z.array(z.string()).optional(),
+    images_from: z.string().optional(),
+    context_from: ContextFromSchema,
+    validator_schema_id: z.string().optional(),
+    max_response_chars: z.number().int().positive().optional(),
+    response_contract: z.enum(["json"]).optional(),
+});
+/**
+ * CallSchema: exactly ONE of `prompt` or `prompt_template` (XOR).
+ * Uses zod refine for XOR enforcement.
+ */
+export const CallSchema = BaseCallSchema
+    .extend({
+    prompt: z.string().optional(),
+    prompt_template: z.string().optional(),
+})
+    .refine((c) => {
+    const hasPrompt = c.prompt != null && c.prompt !== "";
+    const hasTemplate = c.prompt_template != null && c.prompt_template !== "";
+    return (hasPrompt && !hasTemplate) || (!hasPrompt && hasTemplate);
+}, {
+    message: "Exactly one of 'prompt' or 'prompt_template' must be specified (XOR)",
+    path: ["prompt"],
+});
+// ---------------------------------------------------------------------------
+// 2-3a: StageSchema
+// ---------------------------------------------------------------------------
+export const StageSchema = z.object({
+    id: IdSchema,
+    description: z.string().min(1).optional(),
+    parallel: z.boolean().default(true),
+    retry: RetryConfigSchema.default({}),
+    on_failure: z.enum(["abort", "continue"]).default("abort"),
+    calls: z.array(CallSchema).min(1, "Stage must have at least one call"),
+});
+// ---------------------------------------------------------------------------
+// 2-1a: WorkflowDefinitionSchema
+// ---------------------------------------------------------------------------
+export const WorkflowSettingsSchema = z.object({
+    timeout_seconds: z.number().positive().default(1800),
+    max_retries: z.number().int().min(0).default(0),
+});
+export const WorkflowDefinitionSchema = z.object({
+    name: IdSchema,
+    description: z.string().min(1),
+    version: z.string().min(1),
+    stages: z.array(StageSchema).min(1, "Workflow must have at least one stage"),
+    variables: z.record(IdSchema, VariableSchema).default({}),
+    settings: WorkflowSettingsSchema.default({}),
+});
+// ---------------------------------------------------------------------------
+// Re-export ID regex for use in other modules
+// ---------------------------------------------------------------------------
+export { ID_PATTERN };
+//# sourceMappingURL=schema.js.map

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * MCP STDIO server factory for clinkx-workflows (Phase 6).
+ *
+ * Creates a standalone MCP server with workflow tools backed by a
+ * ClinkSession child process. For in-process integration, use
+ * registerWorkflowTools() from workflow-tools.ts directly.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Create the clinkx-workflows MCP server.
+ *
+ * Registers three tools: run_workflow, resume_workflow, list_workflows.
+ * Uses ClinkSession (child process) as the backend.
+ * Does NOT connect transport — caller is responsible.
+ */
+export declare function createWorkflowServer(): Server;

package/clinkx-workflows/dist/server.js

@@ -0,0 +1,33 @@
+/**
+ * MCP STDIO server factory for clinkx-workflows (Phase 6).
+ *
+ * Creates a standalone MCP server with workflow tools backed by a
+ * ClinkSession child process. For in-process integration, use
+ * registerWorkflowTools() from workflow-tools.ts directly.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ClinkSession } from "./transport.js";
+import { registerWorkflowTools } from "./workflow-tools.js";
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the clinkx-workflows MCP server.
+ *
+ * Registers three tools: run_workflow, resume_workflow, list_workflows.
+ * Uses ClinkSession (child process) as the backend.
+ * Does NOT connect transport — caller is responsible.
+ */
+export function createWorkflowServer() {
+    const server = new Server({ name: "clinkx-workflows", version: "0.1.0" }, {
+        capabilities: { tools: {} },
+        instructions: "Orchestrates multi-stage workflows by delegating calls to CLI subagents via ClinkX. " +
+            "Use run_workflow to start a new workflow, resume_workflow to continue a failed run, " +
+            "or list_workflows to see available workflows.",
+    });
+    registerWorkflowTools(server, {
+        createBackend: (runId) => new ClinkSession({ runId }),
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC9C;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,YAAY,EACV,sFAAsF;YACtF,sFAAsF;YACtF,+CAA+C;KAClD,CACF,CAAC;IAEF,qBAAqB,CAAC,MAAM,EAAE;QAC5B,aAAa,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC;KAC9D,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,54 @@
+/**
+ * Shutdown coordinator for clinkx-workflows.
+ *
+ * Handles:
+ * - SIGTERM/SIGINT: cancel in-flight calls, persist state (best-effort),
+ *   terminate child, exit
+ * - MCP cancellation: propagate AbortSignal, cancel calls, persist cancelled,
+ *   no response
+ *
+ * Race-tolerant: late child responses remain possible per MCP spec.
+ */
+import type { ClinkBackend } from "./backend.js";
+type StatePersister = () => Promise<void>;
+/**
+ * Manages graceful shutdown across signal handlers and MCP cancellation.
+ */
+export declare class ShutdownCoordinator {
+    private state;
+    private shuttingDown;
+    private signalHandlersInstalled;
+    private readonly boundHandleSignal;
+    constructor();
+    /**
+     * Register the active session and abort controller for this run.
+     * Call at the start of each workflow run.
+     */
+    register(session: ClinkBackend, controller: AbortController, persistState: StatePersister): void;
+    /**
+     * Unregister the current run (on normal completion).
+     */
+    unregister(): void;
+    /**
+     * Get the AbortSignal for the current run.
+     * Use this to propagate cancellation to in-flight calls.
+     */
+    get signal(): AbortSignal | undefined;
+    /**
+     * Cancel the current run (e.g., from MCP notifications/cancelled).
+     * Aborts in-flight calls, persists state, terminates child.
+     * Does NOT call process.exit — caller decides response behavior.
+     */
+    cancelRun(): Promise<void>;
+    /**
+     * Handle SIGTERM/SIGINT.
+     * Cancel, persist, terminate, exit.
+     */
+    private handleSignalShutdown;
+    private safePersistState;
+    private safeTerminateSession;
+    private installSignalHandlers;
+}
+/** Singleton shutdown coordinator. */
+export declare const shutdownCoordinator: ShutdownCoordinator;
+export {};

package/clinkx-workflows/dist/shutdown.js

@@ -0,0 +1,120 @@
+/**
+ * Shutdown coordinator for clinkx-workflows.
+ *
+ * Handles:
+ * - SIGTERM/SIGINT: cancel in-flight calls, persist state (best-effort),
+ *   terminate child, exit
+ * - MCP cancellation: propagate AbortSignal, cancel calls, persist cancelled,
+ *   no response
+ *
+ * Race-tolerant: late child responses remain possible per MCP spec.
+ */
+import { logger } from "./logger.js";
+/**
+ * Manages graceful shutdown across signal handlers and MCP cancellation.
+ */
+export class ShutdownCoordinator {
+    state = {
+        session: null,
+        controller: null,
+        persistState: null,
+    };
+    shuttingDown = false;
+    signalHandlersInstalled = false;
+    boundHandleSignal;
+    constructor() {
+        this.boundHandleSignal = (signal) => {
+            void this.handleSignalShutdown(signal);
+        };
+    }
+    /**
+     * Register the active session and abort controller for this run.
+     * Call at the start of each workflow run.
+     */
+    register(session, controller, persistState) {
+        this.state = { session, controller, persistState };
+        this.shuttingDown = false;
+        this.installSignalHandlers();
+    }
+    /**
+     * Unregister the current run (on normal completion).
+     */
+    unregister() {
+        this.state = { session: null, controller: null, persistState: null };
+    }
+    /**
+     * Get the AbortSignal for the current run.
+     * Use this to propagate cancellation to in-flight calls.
+     */
+    get signal() {
+        return this.state.controller?.signal;
+    }
+    /**
+     * Cancel the current run (e.g., from MCP notifications/cancelled).
+     * Aborts in-flight calls, persists state, terminates child.
+     * Does NOT call process.exit — caller decides response behavior.
+     */
+    async cancelRun() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        logger.info("cancelling current workflow run");
+        // 1. Abort in-flight calls
+        this.state.controller?.abort(new Error("Workflow cancelled"));
+        // 2. Best-effort state persistence
+        await this.safePersistState();
+        // 3. Terminate child session
+        await this.safeTerminateSession();
+    }
+    /**
+     * Handle SIGTERM/SIGINT.
+     * Cancel, persist, terminate, exit.
+     */
+    async handleSignalShutdown(signal) {
+        if (this.shuttingDown) {
+            logger.warn({ signal }, "duplicate shutdown signal ignored");
+            return;
+        }
+        this.shuttingDown = true;
+        logger.info({ signal }, "received shutdown signal");
+        // 1. Abort in-flight calls
+        this.state.controller?.abort(new Error(`Shutdown: ${signal}`));
+        // 2. Best-effort state persistence
+        await this.safePersistState();
+        // 3. Terminate child session
+        await this.safeTerminateSession();
+        // 4. Exit
+        logger.info({ signal }, "shutdown complete, exiting");
+        process.exit(0);
+    }
+    async safePersistState() {
+        if (this.state.persistState == null)
+            return;
+        try {
+            await this.state.persistState();
+        }
+        catch (err) {
+            logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to persist state during shutdown");
+        }
+    }
+    async safeTerminateSession() {
+        if (this.state.session == null)
+            return;
+        try {
+            await this.state.session.terminate();
+        }
+        catch (err) {
+            logger.error({ err: err instanceof Error ? err.message : String(err) }, "failed to terminate child session during shutdown");
+        }
+    }
+    installSignalHandlers() {
+        if (this.signalHandlersInstalled)
+            return;
+        this.signalHandlersInstalled = true;
+        process.on("SIGTERM", () => this.boundHandleSignal("SIGTERM"));
+        process.on("SIGINT", () => this.boundHandleSignal("SIGINT"));
+    }
+}
+/** Singleton shutdown coordinator. */
+export const shutdownCoordinator = new ShutdownCoordinator();
+//# sourceMappingURL=shutdown.js.map

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

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

package/clinkx-workflows/dist/state-schema.d.ts

@@ -0,0 +1,141 @@
+/**
+ * State schema for clinkx-workflows resume authority model (0-12a).
+ *
+ * The snapshot directory is THE resume authority; fingerprints are fast-rejection guards.
+ *
+ * At run start:
+ * 1. Persist normalized adapter bundle into <run>/child-config/
+ * 2. Hash the bundle as a fingerprint for fast mismatch rejection on resume
+ * 3. Persist exact materialized ClinkInput payloads per call before dispatch
+ *
+ * On resume:
+ * - Reuse materialized inputs verbatim (never re-resolve from live configs)
+ * - Fail hard on fingerprint mismatch (no override flag in v1)
+ * - If snapshot directory is missing/corrupted, run is non-resumable
+ *
+ * Resume is NOT stable across delegate CLI binary upgrades.
+ * Persistent resume requires CLINKX_WORKFLOWS_CHILD_CONFIG_PATH;
+ * ambient-config runs are non-resumable.
+ */
+import type { ChildFailureMetadata } from "./errors.js";
+import type { FidelityMetadata } from "./fidelity.js";
+/** Call-level state progression. */
+export type CallState = "pending" | "running" | "succeeded" | "failed" | "cancelled";
+/** Run-level state progression. */
+export type RunStatus = "pending" | "running" | "succeeded" | "failed" | "cancelled";
+/** Failure classification for diagnostics and retry decisions. */
+export type FailureClass = "transient" | "permanent";
+/** Per-call state entry in the run state. */
+export interface CallStateEntry {
+    readonly callId: string;
+    readonly stageId: string;
+    readonly state: CallState;
+    readonly retryCount: number;
+    readonly startedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+    readonly durationMs?: number | undefined;
+    readonly failureClass?: FailureClass | undefined;
+    readonly errorMessage?: string | undefined;
+    /**
+     * Pointer to output file for large outputs (>10KB).
+     * Path relative to run directory: "<stage_id>.<call_id>.output.txt"
+     */
+    readonly outputPath?: string | undefined;
+    /** Inline output for small results. */
+    readonly outputInline?: string | undefined;
+    /** Persisted exact ClinkInput payload written before dispatch. */
+    readonly materializedInputPath?: string | undefined;
+    /** Relative path to the validated artifact JSON, when present. */
+    readonly artifactPath?: string | undefined;
+    /** Whether this call is referenced by downstream context_from. */
+    readonly contextProducing?: boolean | undefined;
+    /** Persisted fidelity diagnostics for threaded outputs. */
+    readonly fidelity?: FidelityMetadata | undefined;
+    /** Structured metadata from child _debug block on failure. */
+    readonly childDebugMetadata?: ChildFailureMetadata | undefined;
+}
+/** Per-stage state entry. */
+export interface StageStateEntry {
+    readonly stageId: string;
+    readonly state: CallState;
+    readonly startedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+    readonly calls: readonly CallStateEntry[];
+}
+/**
+ * Normalized adapter bundle — the complete post-load config for referenced adapters.
+ *
+ * This is the behaviorally-meaningful snapshot:
+ * - All CliAdapterConfigSchema fields (command, args, unsafe_args, env, parser, etc.)
+ * - Resolved role prompt contents (not just prompt_file paths)
+ * - Resolved absolute command paths
+ * - Explicit child env controls
+ *
+ * Raw file hashes don't capture effective behavior because registry.ts normalization
+ * (prompt_file resolution, schema defaults, first-wins dedup) transforms configs.
+ */
+export interface ChildConfigSnapshot {
+    /** Adapter configs keyed by adapter name. Only referenced adapters are included. */
+    readonly adapters: Readonly<Record<string, unknown>>;
+    /** Resolved role prompt contents keyed by "adapter.role". */
+    readonly resolvedPrompts: Readonly<Record<string, string>>;
+    /** Explicit child env controls applied at spawn time. */
+    readonly childEnv: Readonly<Record<string, string>>;
+}
+/**
+ * Fingerprint payload for fast mismatch rejection on resume.
+ *
+ * The fingerprint is a hash of the ChildConfigSnapshot.
+ * If it doesn't match on resume, the run is rejected.
+ */
+export interface Fingerprint {
+    /** Hash algorithm used. */
+    readonly algorithm: "sha256";
+    /** Hex-encoded hash of the serialized ChildConfigSnapshot. */
+    readonly hash: string;
+    /** Timestamp when the fingerprint was computed. */
+    readonly computedAt: string;
+}
+/**
+ * Complete run state persisted to <run>/state.json.
+ *
+ * state_version: 1 from day one to enable future migrations without guesswork.
+ */
+export interface RunState {
+    /** Schema version for forward-compatible migration. Always 1 in v1. */
+    readonly state_version: 1;
+    /** Caller-supplied run ID. */
+    readonly runId: string;
+    /** Workflow name from definition. */
+    readonly workflowName: string;
+    /** Workflow version from definition. */
+    readonly workflowVersion: string;
+    /** Overall run status. */
+    readonly status: RunStatus;
+    /** Whether this run is resumable (requires explicit child config). */
+    readonly resumable: boolean;
+    /** Child config fingerprint for fast mismatch rejection. */
+    readonly fingerprint?: Fingerprint | undefined;
+    /** Relative path to the immutable workflow snapshot file. */
+    readonly workflowSnapshotPath?: string | undefined;
+    /** Digest of workflow.snapshot.json for corruption checks. */
+    readonly workflowSnapshotHash?: string | undefined;
+    /** Relative path to the immutable inputs snapshot file. */
+    readonly inputsSnapshotPath?: string | undefined;
+    /** Digest of inputs.snapshot.json for corruption checks. */
+    readonly inputsSnapshotHash?: string | undefined;
+    /** Relative path to the child config snapshot file, when resumable. */
+    readonly childConfigSnapshotPath?: string | undefined;
+    /** Per-stage state. */
+    readonly stages: readonly StageStateEntry[];
+    /** Resolved variables snapshot (non-secret only per 0-11a). */
+    readonly variables: Readonly<Record<string, unknown>>;
+    /** Run-level timing. */
+    readonly startedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+    /** Error details if run failed. */
+    readonly error?: string | undefined;
+    readonly failureClass?: FailureClass | undefined;
+    /** Retain run directory on success for debugging when true. */
+    readonly debugKeepArtifacts?: boolean | undefined;
+}

package/clinkx-workflows/dist/state-schema.js

@@ -0,0 +1,21 @@
+/**
+ * State schema for clinkx-workflows resume authority model (0-12a).
+ *
+ * The snapshot directory is THE resume authority; fingerprints are fast-rejection guards.
+ *
+ * At run start:
+ * 1. Persist normalized adapter bundle into <run>/child-config/
+ * 2. Hash the bundle as a fingerprint for fast mismatch rejection on resume
+ * 3. Persist exact materialized ClinkInput payloads per call before dispatch
+ *
+ * On resume:
+ * - Reuse materialized inputs verbatim (never re-resolve from live configs)
+ * - Fail hard on fingerprint mismatch (no override flag in v1)
+ * - If snapshot directory is missing/corrupted, run is non-resumable
+ *
+ * Resume is NOT stable across delegate CLI binary upgrades.
+ * Persistent resume requires CLINKX_WORKFLOWS_CHILD_CONFIG_PATH;
+ * ambient-config runs are non-resumable.
+ */
+export {};
+//# sourceMappingURL=state-schema.js.map

package/clinkx-workflows/dist/state-schema.js.map

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

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

@@ -0,0 +1,37 @@
+import type { EngineHooks, EngineResumeState } from "./engine.js";
+import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+import type { RunState } from "./state-schema.js";
+export interface CreateWorkflowStateOptions {
+    readonly runId: string;
+    readonly definition: NormalizedWorkflowDefinition;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly runDir?: string | undefined;
+    readonly debugKeepArtifacts?: boolean | undefined;
+}
+export interface ResumeWorkflowStateOptions {
+    readonly runId: string;
+    readonly runDir?: string | undefined;
+    readonly debugKeepArtifacts?: boolean | undefined;
+}
+export declare class WorkflowStateStore {
+    readonly runDir: string;
+    readonly definition: NormalizedWorkflowDefinition;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly hooks: EngineHooks;
+    readonly resume: EngineResumeState;
+    private state;
+    private readonly lockPath;
+    private readonly debugKeepArtifacts;
+    private writeChain;
+    private lockHeld;
+    private constructor();
+    static create(options: CreateWorkflowStateOptions): Promise<WorkflowStateStore>;
+    static resume(options: ResumeWorkflowStateOptions): Promise<WorkflowStateStore>;
+    get runState(): RunState;
+    markCancelled(reason?: string): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private applyRetryUpdate;
+    private enqueueWrite;
+    private writeState;
+}