clinkx 0.2.3 → 1.0.0

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

@@ -5,16 +5,23 @@
  * - Standalone STDIO server (ClinkSession child process backend)
  * - In-process integration (LocalClinkBackend via root ClinkX)
  *
- * The `registerWorkflowTools()` function registers three tools on a Server:
+ * The `registerWorkflowTools()` function registers five 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
+ * - cancel_workflow: cancel a live or orphaned workflow run
  *
  * The caller provides a `createBackend` factory that determines how clink
  * calls are dispatched — either via child process or in-process.
  */
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { ClinkBackend } from "./backend.js";
+import type { RunState } from "./state-schema.js";
+import type { ContextBuilderRunner, WorkflowContext } from "./context-preflight.js";
+import type { WorkflowContextBuilderLifecycleRouter } from "./context-builder-lifecycle-router.js";
+import type { Variable } from "./schema.js";
+import { type WorkflowContextRequestedMode, type WorkflowContextPolicy } from "./context-mode-resolver.js";
 export interface WorkflowToolsOptions {
     /**
      * Factory that creates a ClinkBackend for a given run.
@@ -26,24 +33,61 @@ export interface WorkflowToolsOptions {
     readonly templatesRoot?: string | undefined;
     /** Override workflows search path. */
     readonly workflowsPath?: string | undefined;
+    /** Optional context-builder preflight runner for future in-process injection. */
+    readonly contextBuilderRunner?: ContextBuilderRunner | undefined;
+    /**
+     * Per-run store router paired with the injected root runner's lifecycleFactory.
+     * The composition owner must pass the same router instance to both sides.
+     */
+    readonly contextBuilderLifecycleRouter?: WorkflowContextBuilderLifecycleRouter | undefined;
+    /** Soft default for workflow context-builder preflight mode. */
+    readonly contextDefault?: WorkflowContextRequestedMode | undefined;
+    /** Curator adapter name used by the injected default full delegate. */
+    readonly defaultCurator?: string | undefined;
+    /** Optional state/store callback used by injected preflight runners. */
+    readonly commitPreflightContext?: ((input: {
+        readonly variables: Readonly<Record<string, unknown>>;
+        readonly workflow_context: WorkflowContext;
+    }) => Promise<void>) | undefined;
+    /**
+     * Root-computed admitted async cap. Standalone workflow servers omit this and
+     * fall back to CLINKX_WORKFLOWS_MAX_CONCURRENT_ASYNC.
+     */
+    readonly asyncAdmissionCap?: number | undefined;
     /**
      * Known CLI adapter names for pre-flight validation of members[].cli_name.
      * When provided, parseMembersOverride() rejects unknown cli_name values
      * at parse time instead of deferring to runtime adapter resolution.
      */
     readonly availableCliNames?: readonly string[] | undefined;
+    /**
+     * Subset of availableCliNames that expose roles.json, used only for
+     * plan-review-receipts admission and discovery. Does not affect
+     * available_cli_names / members / chairman enums. When omitted, plan-review
+     * falls back to availableCliNames (standalone callers that do not filter).
+     */
+    readonly planReviewAvailableCliNames?: readonly string[] | undefined;
 }
+export declare function resolveWorkflowAsyncAdmissionCap(options?: Pick<WorkflowToolsOptions, "asyncAdmissionCap">): number;
 interface ParsedMember {
     cli_name: string;
     stance?: string;
 }
 export declare function parseMembersOverride(raw: unknown, knownCliNames?: ReadonlySet<string>): ParsedMember[] | undefined;
 export declare function parseChairmanOverride(raw: unknown, knownCliNames?: ReadonlySet<string>): string | undefined;
+/** @internal Shared with the compiled producer-fixture admission check. */
+export declare function validateVariables(supplied: Record<string, unknown> | undefined, schema: Record<string, Variable>): Record<string, unknown>;
 /**
  * Humanize a stage ID: replace underscores with spaces, capitalize first letter only.
  * e.g. "cross_review" → "Cross review", "ranking_analysis" → "Ranking analysis"
  */
 export declare function humanizeStageId(id: string): string;
+/**
+ * Legacy state-v1 runs did not persist their admission-time default. Rebuild
+ * only caller-explicit choices; otherwise require deterministic preflight so a
+ * changed server default cannot silently introduce or switch a delegate.
+ */
+export declare function reconstructLegacyInitialContextPolicy(state: RunState, defaultCurator: string | undefined): WorkflowContextPolicy;
 /** MCP tool definition shape (matches SDK's Tool type). */
 export interface WorkflowToolDefinition {
     readonly name: string;
@@ -52,7 +96,7 @@ export interface WorkflowToolDefinition {
     readonly annotations?: Record<string, unknown> | undefined;
 }
 /**
- * Return the three workflow tool definitions for tools/list.
+ * Return the workflow tool definitions for tools/list.
  *
  * Dynamically discovers available workflows to include in the
  * run_workflow description. Safe to call repeatedly — no side effects.
@@ -77,7 +121,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 three tools: run_workflow, resume_workflow, list_workflows.
+ * It registers five tools: run_workflow, resume_workflow, list_workflows,
+ * workflow_run_status, cancel_workflow.
  *
  * The `options.createBackend` factory determines how clink calls are
  * dispatched — callers provide either a child-process or in-process backend.