clinkx 0.3.0 → 1.1.0

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

@@ -5,16 +5,27 @@
  * - 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 { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+import type { RunState } from "./state-schema.js";
+import type { InvocationAuditWrite } from "./dashboard/invocation-contract.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";
+import { type AvailableCliCapability, type ResolvedRoster } from "./roster-contract.js";
+import type { RosterLoader } from "./rosters.js";
 export interface WorkflowToolsOptions {
     /**
      * Factory that creates a ClinkBackend for a given run.
@@ -26,24 +37,127 @@ 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;
+    /**
+     * Optional admission-time capability check supplied by the root registry.
+     * Standalone workflow servers omit it and retain dispatch-time validation.
+     */
+    readonly validateInvocationOverrides?: (cliName: string, knobs: {
+        model?: string;
+        effort?: string;
+    }) => void;
+    /**
+     * Optional root-injected per-adapter model/effort capability list. Present
+     * only when the root server can resolve the override registry; standalone
+     * workflow servers omit it so list_workflows does not emit available_clis.
+     */
+    readonly adapterCapabilities?: () => readonly AvailableCliCapability[];
+    /**
+     * Optional roster-preset loader. Present whenever a server configures one
+     * (root: env/user/builtin; standalone: env/user). list_workflows emits
+     * available_rosters only when this is set.
+     */
+    readonly rosterLoader?: RosterLoader | undefined;
+    /**
+     * Optional root-injected model/effort provenance audit. The engine has no
+     * adapter registry; standalone servers omit this and persist no `invocation`.
+     */
+    readonly deriveInvocationAudit?: (cliName: string, role: string, knobs: {
+        model?: string;
+        effort?: string;
+    }) => InvocationAuditWrite;
 }
+/** Internal standalone-lifecycle seam; not part of the public package API. */
+export declare function getActiveWorkflowHandlerCount(): number;
+/** Internal shared lifecycle seam used by the root server's compiled import. */
+export declare function getActiveWorkflowRunCount(): number;
+/**
+ * Install the standalone server's activity sink. The observer is optional and
+ * process-local; library callers leave it unset, so importing this module or
+ * using the in-process registration path has no timer/lifecycle side effects.
+ */
+export declare function setWorkflowActivityObserver(observer: (() => void) | undefined): void;
+export declare function resolveWorkflowAsyncAdmissionCap(options?: Pick<WorkflowToolsOptions, "asyncAdmissionCap">): number;
 interface ParsedMember {
     cli_name: string;
     stance?: string;
+    model?: string;
+    effort?: 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;
+export interface BuildResolvedRosterInput {
+    readonly workflow: string;
+    readonly definition: NormalizedWorkflowDefinition;
+    readonly parsedMembers?: ReadonlyArray<{
+        readonly cli_name: string;
+        readonly stance?: string | undefined;
+        readonly model?: string | undefined;
+        readonly effort?: string | undefined;
+    }> | undefined;
+    readonly parsedChairman?: string | undefined;
+    readonly parsedChairmanModel?: string | undefined;
+    readonly parsedChairmanEffort?: string | undefined;
+    readonly initialContextPolicy: WorkflowContextPolicy;
+    readonly resolvedVariables: Readonly<Record<string, unknown>>;
+    /** Preset name when a roster was used at admission. */
+    readonly rosterName?: string | undefined;
+}
+/**
+ * Requested-value roster projection for council workflows. Call AFTER
+ * `expandCouncilComposition` / `expandRunWorkflowDefinition`, AFTER
+ * `resolveEffectiveChairmanCall` values are on the definition (or passed as
+ * parsed chairman knobs), and AFTER `effectiveFinalizerEnabled` can be
+ * evaluated from `initialContextPolicy` — and BEFORE `WorkflowStateStore.create()`.
+ * `plan-review-receipts` and any non-council workflow return undefined.
+ */
+export declare function buildResolvedRoster(input: BuildResolvedRosterInput): ResolvedRoster | undefined;
+/**
+ * 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 +166,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 +191,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.