clinkx 1.1.2 → 1.2.0

package/clinkx-workflows/dist/workflow-completion.js

@@ -0,0 +1,250 @@
+import { createHash, randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { readContainedRelativeFile } from "./contained-file.js";
+import { DEFAULT_DASHBOARD_MAX_STATE_BYTES } from "./config.js";
+import { readSessionLogGeneration } from "./dashboard/session-log-identity.js";
+import { WorkflowCancellationError } from "./errors.js";
+import { logger } from "./logger.js";
+export const WORKFLOW_WAIT_BUDGET_MS = 30_000;
+export const SETTLED_LIMIT = 128;
+/** sha256 over the exact bytes read from state.json (never a decoded string). */
+function fingerprintStateBytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Provenance only: result bodies and unfinished promise callbacks are never cached.
+ * An execution exists here only once its owner has bound a created/resumed
+ * store, so a request rejected during admission can never displace one.
+ */
+export class WorkflowCompletionRegistry {
+    latest = new Map();
+    byId = new Map();
+    minted = new WeakSet();
+    settledIds = [];
+    bind(runId, runDir, generation) {
+        const listeners = new Set();
+        const record = {
+            executionId: randomUUID(),
+            runId,
+            runDir: resolve(runDir),
+            generation,
+            publication: undefined,
+            settled: false,
+            stamped: false,
+            observers: 0,
+            listeners,
+            get listenerCount() { return listeners.size; },
+        };
+        this.minted.add(record);
+        this.byId.set(record.executionId, record);
+        this.latest.set(record.runDir, record);
+        return record;
+    }
+    owner(runId, runDir) {
+        let entry;
+        let boundStore;
+        return {
+            get entry() { return entry; },
+            bind: (store) => {
+                if (entry !== undefined) {
+                    if (boundStore !== store)
+                        throw new Error(`workflow run ${runId} is already bound to a different state store`);
+                    return entry;
+                }
+                entry = this.bind(runId, runDir, store.sessionLogGeneration);
+                boundStore = store;
+                return entry;
+            },
+        };
+    }
+    select(runDir, expected) {
+        const latest = this.latest.get(resolve(runDir));
+        if (expected === undefined)
+            return latest;
+        const entry = this.byId.get(expected);
+        if (entry === undefined)
+            return "identity_unavailable";
+        if (entry.runDir !== resolve(runDir) || latest !== entry)
+            return "identity_changed";
+        return entry;
+    }
+    /**
+     * Capture the terminal publication while ownership still prevents local
+     * re-admission. Only a terminal state of the bound directory incarnation counts.
+     */
+    async recordPublication(entry) {
+        const record = this.own(entry);
+        if (record.settled || record.generation === undefined)
+            return;
+        const publication = await inspectPublication(record.runDir);
+        if (publication?.generation === record.generation && publication.terminal) {
+            record.publication = publication;
+        }
+    }
+    markStamped(entry) {
+        this.own(entry).stamped = true;
+    }
+    settle(entry) {
+        const record = this.own(entry);
+        if (record.settled)
+            return;
+        record.settled = true;
+        this.settledIds.push(record.executionId);
+        this.prune();
+        for (const listener of [...record.listeners])
+            listener();
+    }
+    /** Protect provenance through the handler's final filesystem rereads. */
+    retain(entry) {
+        const record = this.own(entry);
+        record.observers += 1;
+        return () => {
+            record.observers -= 1;
+            this.prune();
+        };
+    }
+    /**
+     * Execution fence around a projection. `observedDigest` is the fingerprint of
+     * the state bytes the projection actually parsed (null: unreadable); pass it
+     * only when the entry was already settled before that projection began.
+     * Without it, only provenance and directory incarnation are checked, which
+     * is correct for an active execution that legitimately republishes state.
+     */
+    async check(entry, observedDigest) {
+        const record = this.own(entry);
+        const before = this.selectionFailure(record);
+        if (before !== undefined)
+            return before;
+        if (record.generation === undefined)
+            return "identity_unavailable";
+        const generation = await readSessionLogGeneration(record.runDir);
+        // Recheck after the I/O: a replacement may bind while the read is pending.
+        const after = this.selectionFailure(record);
+        if (after !== undefined)
+            return after;
+        if (generation.kind !== "available")
+            return "identity_unavailable";
+        if (generation.sessionLogGeneration !== record.generation)
+            return "identity_changed";
+        if (record.settled && record.publication === undefined)
+            return "identity_unavailable";
+        if (observedDigest !== undefined) {
+            if (record.publication === undefined || observedDigest === null)
+                return "identity_unavailable";
+            if (observedDigest !== record.publication.fingerprint)
+                return "identity_changed";
+        }
+        return undefined;
+    }
+    wait(entry, signal) {
+        const record = this.own(entry);
+        if (signal.aborted)
+            return Promise.reject(new WorkflowCancellationError());
+        if (record.settled)
+            return Promise.resolve("settled");
+        return new Promise((resolveWait, reject) => {
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                record.listeners.delete(onComplete);
+                signal.removeEventListener("abort", onAbort);
+            };
+            const onComplete = () => {
+                cleanup();
+                resolveWait("settled");
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(new WorkflowCancellationError());
+            };
+            record.listeners.add(onComplete);
+            signal.addEventListener("abort", onAbort, { once: true });
+            timer = setTimeout(() => {
+                cleanup();
+                resolveWait("budget_elapsed");
+            }, WORKFLOW_WAIT_BUDGET_MS);
+            // A pending observation must not keep an otherwise idle process alive.
+            timer.unref?.();
+            // Inspect after registration, so a fast completion cannot strand a waiter.
+            if (record.settled)
+                onComplete();
+            else if (signal.aborted)
+                onAbort();
+        });
+    }
+    selectionFailure(record) {
+        const selected = this.select(record.runDir, record.executionId);
+        if (typeof selected === "string")
+            return selected;
+        return selected === record ? undefined : "identity_unavailable";
+    }
+    own(entry) {
+        if (!this.minted.has(entry))
+            throw new Error("workflow completion was not bound by this registry");
+        return entry;
+    }
+    prune() {
+        while (this.settledIds.length > SETTLED_LIMIT) {
+            const index = this.settledIds.findIndex((id) => this.byId.get(id)?.observers === 0);
+            if (index === -1)
+                return;
+            const id = this.settledIds.splice(index, 1)[0];
+            const retired = this.byId.get(id);
+            this.byId.delete(id);
+            if (retired !== undefined && this.latest.get(retired.runDir) === retired) {
+                this.latest.delete(retired.runDir);
+            }
+        }
+    }
+}
+function isTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+/**
+ * Persisted provenance for a pin this process retains no record for. Only a
+ * terminal state stamped with exactly that id, whose run.lock is released
+ * (`stale_or_absent`), counts as its settlement: a live or unknown lock means
+ * an owner may still be inside its cleanup fence, and a non-terminal match has
+ * no local owner whose fence could be witnessed.
+ */
+export function persistedIdentityFailure(state, lock, runId, expected) {
+    if (typeof state.executionId !== "string" || state.runId !== runId)
+        return "identity_unavailable";
+    if (state.executionId !== expected)
+        return "identity_changed";
+    if (!isTerminalStatus(state.status) || lock !== "stale_or_absent")
+        return "identity_unavailable";
+    return typeof state.completedAt === "string" && state.executionCompletedAt === state.completedAt
+        ? undefined
+        : "identity_unavailable";
+}
+export async function inspectPublication(runDir) {
+    try {
+        const before = await readSessionLogGeneration(runDir);
+        if (before.kind !== "available")
+            return undefined;
+        const file = await readContainedRelativeFile(runDir, "state.json", {
+            wantBytes: true,
+            requireRegular: true,
+            requireExactRequestedPath: true,
+            maxBytes: DEFAULT_DASHBOARD_MAX_STATE_BYTES,
+        });
+        const state = JSON.parse(file.bytes.toString("utf-8"));
+        const after = await readSessionLogGeneration(runDir);
+        if (after.kind !== "available" || after.sessionLogGeneration !== before.sessionLogGeneration) {
+            return undefined;
+        }
+        return {
+            generation: before.sessionLogGeneration,
+            fingerprint: fingerprintStateBytes(file.bytes),
+            terminal: isTerminalStatus(state.status),
+        };
+    }
+    catch (error) {
+        // Class only: messages can carry paths or state values.
+        logger.debug({ errClass: error instanceof Error ? error.constructor.name : typeof error, runDir }, "workflow publication identity unavailable");
+        return undefined;
+    }
+}
+//# sourceMappingURL=workflow-completion.js.map

package/clinkx-workflows/dist/workflow-completion.js.map

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

package/clinkx-workflows/dist/workflow-tools.d.ts

@@ -5,11 +5,12 @@
  * - Standalone STDIO server (ClinkSession child process backend)
  * - In-process integration (LocalClinkBackend via root ClinkX)
  *
- * The `registerWorkflowTools()` function registers five tools on a Server:
+ * The `registerWorkflowTools()` function registers six tools on a Server:
  * - run_workflow: start a new workflow execution
  * - resume_workflow: resume a failed/cancelled run
  * - list_workflows: list available workflow definitions
  * - workflow_run_status: read workflow run progress/result
+ * - workflow_run_wait: observe local execution settlement
  * - cancel_workflow: cancel a live or orphaned workflow run
  *
  * The caller provides a `createBackend` factory that determines how clink
@@ -194,8 +195,8 @@ export declare function handleWorkflowToolCall(server: Server, options: Workflow
  * Register workflow tools on an MCP Server instance.
  *
  * This is the reusable core extracted from createWorkflowServer().
- * It registers five tools: run_workflow, resume_workflow, list_workflows,
- * workflow_run_status, cancel_workflow.
+ * It registers six tools: run_workflow, resume_workflow, list_workflows,
+ * workflow_run_status, workflow_run_wait, cancel_workflow.
  *
  * The `options.createBackend` factory determines how clink calls are
  * dispatched — callers provide either a child-process or in-process backend.