clinkx 0.3.0 → 1.1.0

package/clinkx-workflows/dist/seed-terms.js

@@ -0,0 +1,176 @@
+/**
+ * Deterministic seed-term synthesis (Plan Phase 5, tasks 5-1/5-2/5-3).
+ *
+ * Pure function: no clock, no RNG, no LLM, no I/O. Identical input always
+ * yields a byte-identical array (verified by tests/seed-terms.test.ts).
+ *
+ * Used to seed context_builder discovery when a workflow runs preflight in
+ * `full`/`deterministic` mode but the caller supplied neither focus paths nor
+ * search terms (wiring lives in Phase 3 — not here).
+ *
+ * Algorithm (pinned in plan task 5-3, authoritative):
+ *   1. Preserve quoted phrases, then camelCase/snake_case/dotted identifiers as
+ *      WHOLE terms before any prose splitting (5-2).
+ *   2. Lowercase and split the remaining prose; drop the fixed 21-word stop set
+ *      and tokens shorter than 3 chars (5-3).
+ *   3. Dedupe case-insensitively; rank by `score = frequency + lengthBonus`
+ *      with a first-seen tie-break; cap at 12 terms (5-3).
+ */
+/** Fixed stop-word set — exactly the 21 words pinned in plan task 5-3. */
+const STOP_WORDS = new Set([
+    "the", "a", "an", "of", "to", "and", "or", "is", "are", "for", "with",
+    "on", "in", "this", "that", "please", "add", "fix", "make", "use", "run",
+]);
+const MIN_TERM_LENGTH = 3;
+const MAX_TERMS = 12;
+export const MAX_SEED_SOURCE_CHARACTERS = 4000;
+export const MAX_CONTEXT_SEARCH_TERMS = 20;
+export const MAX_CONTEXT_SEARCH_TERM_CODE_POINTS = 256;
+export const MAX_CONTEXT_SEARCH_TERMS_UTF8_BYTES = 4_096;
+/** Resolve the workflow context task using the runner's nonblank cb_task rule. */
+export function resolveSeedSource(cbTask, userRequest) {
+    return cbTask != null && cbTask.trim() !== "" ? cbTask : userRequest ?? "";
+}
+/** Match the root task schema's trim-before-max character bound. */
+export function seedSourceExceedsLimit(seedSource) {
+    return seedSource.trim().length > MAX_SEED_SOURCE_CHARACTERS;
+}
+/** Match the root NonBlankStringSchema + post-parse task bound. */
+export function contextSeedSourceValidationError(seedSource) {
+    const normalized = seedSource.trim();
+    if (normalized.length === 0) {
+        return "Context seed source must be nonblank after trimming";
+    }
+    if (normalized.length > MAX_SEED_SOURCE_CHARACTERS) {
+        return `Context seed source must be at most ${String(MAX_SEED_SOURCE_CHARACTERS)} characters`;
+    }
+    return undefined;
+}
+export function contextSearchTermsValidationError(searchTerms) {
+    if (searchTerms.length > MAX_CONTEXT_SEARCH_TERMS) {
+        return `context_builder search_terms must contain at most ${String(MAX_CONTEXT_SEARCH_TERMS)} terms`;
+    }
+    let aggregateBytes = 0;
+    for (const [index, rawTerm] of searchTerms.entries()) {
+        const term = rawTerm.trim();
+        if (term.length === 0) {
+            return `context_builder search_terms[${String(index)}] must be nonblank after trimming`;
+        }
+        if (countCodePoints(term) > MAX_CONTEXT_SEARCH_TERM_CODE_POINTS) {
+            return `context_builder search_terms[${String(index)}] must be <= ${String(MAX_CONTEXT_SEARCH_TERM_CODE_POINTS)} characters`;
+        }
+        aggregateBytes += Buffer.byteLength(term, "utf8");
+    }
+    if (aggregateBytes > MAX_CONTEXT_SEARCH_TERMS_UTF8_BYTES) {
+        return `context_builder search_terms must total <= ${String(MAX_CONTEXT_SEARCH_TERMS_UTF8_BYTES)} UTF-8 bytes after trimming`;
+    }
+    return undefined;
+}
+function countCodePoints(value) {
+    let count = 0;
+    for (const _character of value) {
+        count += 1;
+    }
+    return count;
+}
+function termFitsPublicChannel(term) {
+    return countCodePoints(term.trim()) <= MAX_CONTEXT_SEARCH_TERM_CODE_POINTS;
+}
+/**
+ * Pinned, pure length bonus in [0, 1]: monotonic non-decreasing in length,
+ * saturating at 12 chars. Fixed rational of the term length — no clock/RNG —
+ * which keeps scoring (and therefore ordering) byte-deterministic.
+ */
+function lengthBonus(term) {
+    return Math.min(term.length, 12) / 12;
+}
+/**
+ * A token qualifies as a preservable identifier when it contains an internal
+ * underscore (snake_case), an internal dot (dotted identifier), or a
+ * lower→upper transition (camelCase / PascalCase). "Internal" means an
+ * alphanumeric on both sides, so a trailing sentence dot does not qualify.
+ */
+function isPreservableIdentifier(token) {
+    if (/[A-Za-z0-9]_[A-Za-z0-9]/.test(token))
+        return true;
+    if (/[A-Za-z0-9]\.[A-Za-z0-9]/.test(token))
+        return true;
+    if (/[a-z][A-Z]/.test(token))
+        return true;
+    return false;
+}
+export function synthesizeSeedTerms(text) {
+    if (typeof text !== "string" || text.trim() === "") {
+        return [];
+    }
+    // First-seen-ordered accumulation. `order` holds dedup keys in the order they
+    // first appear; `firstForm` records the surface form to emit; `freq` counts
+    // case-insensitive occurrences for scoring.
+    const order = [];
+    const firstForm = new Map();
+    const freq = new Map();
+    const consider = (term) => {
+        const key = term.toLowerCase();
+        const current = freq.get(key);
+        if (current === undefined) {
+            freq.set(key, 1);
+            firstForm.set(key, term);
+            order.push(key);
+        }
+        else {
+            freq.set(key, current + 1);
+        }
+    };
+    // 5-2: preserve quoted phrases as whole terms, then blank them out so the
+    // identifier/prose passes never re-split their contents.
+    let working = text.replace(/"([^"]+)"|'([^']+)'/g, (_match, dq, sq) => {
+        const phrase = (dq ?? sq ?? "").trim();
+        if (phrase === "")
+            return " ";
+        consider(phrase);
+        return termFitsPublicChannel(phrase) ? " " : ` ${phrase} `;
+    });
+    // 5-2: preserve camelCase/snake_case/dotted identifiers as whole terms,
+    // blanking only the ones we preserve so plain words flow to the prose pass.
+    working = working.replace(/[A-Za-z0-9_.]+/g, (token) => {
+        if (isPreservableIdentifier(token)) {
+            consider(token);
+            return termFitsPublicChannel(token) ? " " : token;
+        }
+        return token;
+    });
+    // 5-3: lowercase the remaining prose, split into alphanumeric tokens, drop
+    // stop words and sub-3-char tokens.
+    const proseTokens = working.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+    for (const token of proseTokens) {
+        if (token.length < MIN_TERM_LENGTH)
+            continue;
+        if (STOP_WORDS.has(token))
+            continue;
+        consider(token);
+    }
+    // 5-3: rank by score = frequency + lengthBonus, first-seen tie-break, cap 12.
+    const ranked = order.map((key, idx) => {
+        const term = firstForm.get(key);
+        return { term, idx, score: freq.get(key) + lengthBonus(term) };
+    });
+    ranked.sort((a, b) => (b.score !== a.score ? b.score - a.score : a.idx - b.idx));
+    const selected = [];
+    let aggregateBytes = 0;
+    for (const { term } of ranked) {
+        if (selected.length >= MAX_TERMS) {
+            break;
+        }
+        if (!termFitsPublicChannel(term)) {
+            continue;
+        }
+        const termBytes = Buffer.byteLength(term.trim(), "utf8");
+        if (aggregateBytes + termBytes > MAX_CONTEXT_SEARCH_TERMS_UTF8_BYTES) {
+            continue;
+        }
+        selected.push(term);
+        aggregateBytes += termBytes;
+    }
+    return selected;
+}
+//# sourceMappingURL=seed-terms.js.map

package/clinkx-workflows/dist/seed-terms.js.map

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

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

@@ -9,7 +9,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 /**
  * Create the clinkx-workflows MCP server.
  *
- * Registers three tools: run_workflow, resume_workflow, list_workflows.
+ * Registers five tools: run_workflow, resume_workflow, list_workflows,
+ * workflow_run_status, cancel_workflow.
  * Uses ClinkSession (child process) as the backend.
  * Does NOT connect transport — caller is responsible.
  *
@@ -18,6 +19,8 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
  * standalone server schema enum injection and parse-time validation
  * without requiring the caller to wire discovery manually.
  */
+export type WorkflowServer = Server;
 export declare function createWorkflowServer(options?: {
     availableCliNames?: readonly string[];
-}): Server;
+    asyncAdmissionCap?: number;
+}): WorkflowServer;

package/clinkx-workflows/dist/server.js

@@ -8,52 +8,45 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, extname } from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { getChildConfigPath } from "./config.js";
+import { getChildConfigPath, getRunsDir, hasExplicitWorkspaceRoot, resolveWorkspaceRoot, } from "./config.js";
 import { logger } from "./logger.js";
-import { ClinkSession } from "./transport.js";
+import { reconcileStaleRunDirectories } from "./state.js";
+import { ClinkSession, resolveClinkChildRuntime } from "./transport.js";
 import { registerWorkflowTools } from "./workflow-tools.js";
-// ---------------------------------------------------------------------------
-// Adapter name discovery
-// ---------------------------------------------------------------------------
-/**
- * Best-effort adapter name discovery from child config path.
- *
- * Reads CLINKX_WORKFLOWS_CHILD_CONFIG_PATH — supports both directory
- * (scan for .json files) and single-file paths, mirroring the path-
- * resolution behavior of AdapterRegistry.loadFromPath.
- *
- * This performs lightweight structural validation (requires `name` +
- * `command` fields) rather than full CliAdapterConfigSchema parsing,
- * which lives in the root package and cannot be imported without
- * creating a circular dependency. Runtime validation in the child
- * process remains the authoritative gate. Returns undefined when no
- * config path is set or no valid adapters are found.
- */
-function discoverChildAdapterNames() {
+import { createRosterLoader, resolveRosterLoaderOptionsFromEnv } from "./rosters.js";
+function discoverChildAdapters() {
     const configPath = getChildConfigPath();
     if (configPath == null)
         return undefined;
     try {
         const stat = statSync(configPath);
-        const names = [];
+        const cliNames = [];
+        const planReviewCliNames = [];
+        const record = (entry) => {
+            if (entry == null)
+                return;
+            if (!cliNames.includes(entry.name))
+                cliNames.push(entry.name);
+            if (entry.hasJsonRole && !planReviewCliNames.includes(entry.name)) {
+                planReviewCliNames.push(entry.name);
+            }
+        };
         if (stat.isFile()) {
             // Single-file config path
-            const name = extractAdapterName(configPath);
-            if (name != null)
-                names.push(name);
+            record(extractAdapter(configPath));
         }
         else if (stat.isDirectory()) {
             // Directory config path — scan for .json files
-            const files = readdirSync(configPath).filter((f) => extname(f) === ".json");
+            const files = readdirSync(configPath)
+                .filter((f) => extname(f) === ".json")
+                .sort();
             for (const file of files) {
-                const name = extractAdapterName(join(configPath, file));
-                if (name != null)
-                    names.push(name);
+                record(extractAdapter(join(configPath, file)));
             }
         }
-        if (names.length > 0) {
-            logger.debug({ names, configPath }, "discovered child adapter names for standalone server");
-            return names;
+        if (cliNames.length > 0) {
+            logger.debug({ names: cliNames, planReviewNames: planReviewCliNames, configPath }, "discovered child adapter names for standalone server");
+            return { cliNames, planReviewCliNames };
         }
     }
     catch (err) {
@@ -62,19 +55,35 @@ function discoverChildAdapterNames() {
     return undefined;
 }
 /**
- * Extract the adapter name from a config JSON file.
+ * Extract adapter name (+ plan-review role eligibility) from a config JSON file.
  *
  * Requires both `name` (string) and `command` (string) fields to be
  * present — the two mandatory fields in any valid adapter config.
  * Skips files that don't meet this minimum bar.
+ *
+ * `backend: "app_server"` adapters are EXCLUDED. They are driven exclusively by
+ * the async `clink_agent_run` / `clink_agent_manage` tools; the synchronous
+ * pipeline every workflow seat runs through rejects them with `-32602`. Naming
+ * one in a workflow enum would advertise a seat that can only fail at dispatch.
+ * The root server filters these already; this is the standalone path, which the
+ * removal of the `eligible:false` bit left unguarded.
+ *
+ * Plan-review eligibility is presence of a `roles` object with a `"json"` key
+ * (raw JSON field read only — no AdapterRegistry import, no dependency cycle).
  */
-function extractAdapterName(filePath) {
+function extractAdapter(filePath) {
     try {
         const raw = readFileSync(filePath, "utf-8");
         const parsed = JSON.parse(raw);
         if (typeof parsed["name"] === "string" && parsed["name"] !== "" &&
-            typeof parsed["command"] === "string" && parsed["command"] !== "") {
-            return parsed["name"];
+            typeof parsed["command"] === "string" && parsed["command"] !== "" &&
+            parsed["backend"] !== "app_server") {
+            const roles = parsed["roles"];
+            const hasJsonRole = roles != null &&
+                typeof roles === "object" &&
+                !Array.isArray(roles) &&
+                Object.prototype.hasOwnProperty.call(roles, "json");
+            return { name: parsed["name"], hasJsonRole };
         }
     }
     catch {
@@ -82,21 +91,6 @@ function extractAdapterName(filePath) {
     }
     return undefined;
 }
-// ---------------------------------------------------------------------------
-// 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.
- *
- * When `availableCliNames` is not explicitly provided, attempts to
- * discover adapter names from the child config path. This gives the
- * standalone server schema enum injection and parse-time validation
- * without requiring the caller to wire discovery manually.
- */
 export function createWorkflowServer(options) {
     const server = new Server({ name: "clinkx-workflows", version: "0.1.0" }, {
         capabilities: { tools: {} },
@@ -104,15 +98,53 @@ export function createWorkflowServer(options) {
             "Use run_workflow to start a new workflow, resume_workflow to continue a failed run, " +
             "or list_workflows to see available workflows.",
     });
+    // `resolveWorkspaceRoot()` silently falls back to process.cwd(), and an MCP
+    // server's cwd is chosen by the client — so the same request can pass or fail
+    // purely on where the client happened to spawn us. Surface the implicit root
+    // instead of leaving it invisible (config.ts cannot log: logger imports it).
+    if (!hasExplicitWorkspaceRoot()) {
+        logger.warn({
+            env_var: "CLINKX_WORKFLOWS_WORKSPACE_ROOT",
+            workspace_root: resolveWorkspaceRoot(),
+            cwd: process.cwd(),
+        }, "CLINKX_WORKFLOWS_WORKSPACE_ROOT is not set; defaulting the workflows workspace root to process.cwd(). " +
+            "This root governs plan_file containment and the workflow child process cwd, so workflow behavior " +
+            "depends on the cwd the MCP client spawned this server with. Set CLINKX_WORKFLOWS_WORKSPACE_ROOT explicitly.");
+    }
+    // One-time startup reconcile of runs frozen as running/pending with no live
+    // worker (fire-and-forget: bounded, idempotent, never blocks startup).
+    try {
+        void reconcileStaleRunDirectories(getRunsDir()).catch((err) => {
+            logger.warn({ err: err instanceof Error ? err.message : String(err) }, "startup stale workflow run reconcile failed");
+        });
+    }
+    catch (err) {
+        logger.warn({ err: err instanceof Error ? err.message : String(err) }, "startup stale workflow run reconcile could not be scheduled");
+    }
+    const childRuntime = resolveClinkChildRuntime();
     // Normalize empty arrays to undefined — an empty list would suppress schema
     // hints while still enabling validation (rejecting all adapter names).
     const explicit = options?.availableCliNames;
+    const discovered = explicit != null && explicit.length > 0
+        ? undefined
+        : discoverChildAdapters();
     const cliNames = (explicit != null && explicit.length > 0)
         ? explicit
-        : discoverChildAdapterNames();
+        : discovered?.cliNames;
+    // When the caller supplies availableCliNames explicitly, they own filtering
+    // (or accept the availableCliNames fallback in workflow-tools). Auto-discovery
+    // always supplies the roles.json-filtered plan-review set.
+    const planReviewCliNames = discovered?.planReviewCliNames;
     registerWorkflowTools(server, {
-        createBackend: (runId) => new ClinkSession({ runId }),
+        createBackend: (runId) => new ClinkSession({ runId, runtime: childRuntime }),
         ...(cliNames != null ? { availableCliNames: cliNames } : {}),
+        ...(planReviewCliNames != null
+            ? { planReviewAvailableCliNames: planReviewCliNames }
+            : {}),
+        ...(options?.asyncAdmissionCap != null
+            ? { asyncAdmissionCap: options.asyncAdmissionCap }
+            : {}),
+        rosterLoader: createRosterLoader(resolveRosterLoaderOptionsFromEnv()),
     });
     return server;
 }

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

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

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

@@ -11,39 +11,50 @@
  */
 import type { ClinkBackend } from "./backend.js";
 type StatePersister = () => Promise<void>;
+/** Opaque handle returned by register(); identifies a single run's entry. */
+export type ShutdownHandle = number;
 /**
  * Manages graceful shutdown across signal handlers and MCP cancellation.
+ *
+ * Keyed registry: each run registers its own entry so concurrent runs (cap > 1)
+ * never clobber each other. Shutdown/cancel iterate over ALL registered entries.
  */
 export declare class ShutdownCoordinator {
-    private state;
+    private readonly entries;
+    private nextHandle;
     private shuttingDown;
+    private shutdownDrain;
+    private shutdownSignal;
     /**
-     * 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).
+     * Synchronously latch shutdown admission and abort every entry currently
+     * owned by the coordinator. The asynchronous persistence/termination drain
+     * is deliberately separate so no awaited cleanup for one entry can let
+     * another registered run continue dispatching work.
      */
-    unregister(): void;
+    beginShutdown(signal: string): void;
+    /** Internal admission guard used by workflow-tools before acquiring a slot. */
+    isShuttingDown(): boolean;
     /**
-     * Get the AbortSignal for the current run.
-     * Use this to propagate cancellation to in-flight calls.
+     * Register a run's session and abort controller. Returns an opaque handle
+     * to be passed to unregister(). Each call adds a new entry; existing entries
+     * are never clobbered. Setup may supply a lazy terminate-only session and a
+     * completion fence covering its entire cleanup. Such runs own persistence
+     * themselves and pass a no-op persistState callback.
      */
-    get signal(): AbortSignal | undefined;
+    register(session: Pick<ClinkBackend, "terminate">, controller: AbortController, persistState: StatePersister, completion?: Promise<void>): ShutdownHandle;
     /**
-     * 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.
+     * Unregister a single run (on normal completion). Deletes only this handle's
+     * entry; other registered runs remain.
      */
-    cancelRun(): Promise<void>;
+    unregister(handle: ShutdownHandle): void;
     /**
      * Handle process shutdown.
-     * Cancel, persist, and terminate. The entrypoint owns process.exit.
+     * Cancel, persist, and terminate all registered runs. The entrypoint owns
+     * process.exit.
      */
     shutdown(signal: string): Promise<void>;
-    private safePersistState;
-    private safeTerminateSession;
+    /** Abort, persist, and terminate every registered entry (best-effort). */
+    private handleAll;
 }
 /** Singleton shutdown coordinator. */
 export declare const shutdownCoordinator: ShutdownCoordinator;