@exaudeus/workrail 3.3.0 → 3.5.0

package/dist/mcp/workflow-protocol-contracts.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESUME_SESSION_PROTOCOL = exports.CHECKPOINT_WORKFLOW_PROTOCOL = exports.CONTINUE_WORKFLOW_PROTOCOL = exports.START_WORKFLOW_PROTOCOL = exports.CONTINUE_WORKFLOW_SINGLE_CONTEXT_OBJECT_GUIDANCE = exports.CONTINUE_WORKFLOW_CONTEXT_OBJECT_GUIDANCE = void 0;
+exports.renderCompactDescription = renderCompactDescription;
+exports.normalizeAliasedFields = normalizeAliasedFields;
+exports.findAliasFieldConflicts = findAliasFieldConflicts;
+exports.renderProtocolDescription = renderProtocolDescription;
+exports.CONTINUE_WORKFLOW_CONTEXT_OBJECT_GUIDANCE = "Set these keys in the next `continue_workflow` call's `context` object:";
+exports.CONTINUE_WORKFLOW_SINGLE_CONTEXT_OBJECT_GUIDANCE = "Set this key in the next `continue_workflow` call's `context` object:";
+function renderCompactDescription(spec, canonicalParams) {
+    const sections = [spec.purpose];
+    if (spec.whenToUse) {
+        sections.push(spec.whenToUse);
+    }
+    const paramLines = [
+        ...canonicalParams.required.map((param) => `- ${param} (required)`),
+        ...(canonicalParams.optional ?? []).map((param) => `- ${param} (optional)`),
+    ];
+    if (paramLines.length > 0) {
+        sections.push(['Parameters:', ...paramLines].join('\n'));
+    }
+    if ((spec.rules?.length ?? 0) > 0) {
+        sections.push(['Rules:', ...(spec.rules ?? []).map((rule) => `- ${rule}`)].join('\n'));
+    }
+    if (spec.examplePayload) {
+        sections.push(`Example: ${JSON.stringify(spec.examplePayload)}`);
+    }
+    if (spec.returns) {
+        sections.push(`Returns: ${spec.returns}`);
+    }
+    return sections.join('\n\n');
+}
+function normalizeAliasedFields(value, aliasMap) {
+    const normalized = { ...value };
+    for (const [alias, canonical] of Object.entries(aliasMap)) {
+        if (normalized[canonical] === undefined && normalized[alias] !== undefined) {
+            normalized[canonical] = normalized[alias];
+        }
+    }
+    return normalized;
+}
+function findAliasFieldConflicts(value, aliasMap) {
+    return Object.entries(aliasMap)
+        .filter(([alias, canonical]) => value[alias] !== undefined && value[canonical] !== undefined)
+        .map(([alias, canonical]) => ({ alias, canonical }));
+}
+exports.START_WORKFLOW_PROTOCOL = {
+    canonicalParams: {
+        required: ['workflowId'],
+        optional: ['workspacePath'],
+    },
+    descriptions: {
+        standard: {
+            purpose: 'Start a WorkRail v2 workflow and begin following its step-by-step instructions.',
+            whenToUse: 'Use this when you found the right workflow and are ready to execute it. The response body is the current step; the structured response includes the token(s) for your next call.',
+            rules: [
+                'Follow the returned step exactly; it represents the user\'s plan for the task.',
+                'When the step is done, call continue_workflow with the returned continueToken.',
+                'Only pass context on later continue_workflow calls if facts changed.',
+            ],
+            examplePayload: {
+                workflowId: 'coding-task-workflow-agentic',
+                workspacePath: '/Users/you/git/my-project',
+            },
+            returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
+        },
+        authoritative: {
+            purpose: 'Begin executing the selected WorkRail v2 workflow.',
+            whenToUse: 'Call this once you have chosen the workflow you will follow. The returned step is a direct instruction from the user or workflow author.',
+            rules: [
+                'Execute the returned step exactly as written.',
+                'When the step is complete, call continue_workflow with the returned continueToken.',
+                'Pass workspacePath when available so WorkRail anchors the session to the correct workspace.',
+            ],
+            examplePayload: {
+                workflowId: 'coding-task-workflow-agentic',
+                workspacePath: '/Users/you/git/my-project',
+            },
+            returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
+        },
+    },
+};
+exports.CONTINUE_WORKFLOW_PROTOCOL = {
+    canonicalParams: {
+        required: ['continueToken'],
+        optional: ['intent', 'context', 'output'],
+    },
+    aliasMap: {
+        contextVariables: 'context',
+    },
+    descriptions: {
+        standard: {
+            purpose: 'Advance or rehydrate the current WorkRail v2 step using the single-token protocol.',
+            whenToUse: 'Use this after completing a step, or to recover the current step after lost context.',
+            rules: [
+                'Advance by sending output (and intent: "advance" if you want to be explicit).',
+                'Rehydrate by omitting output (and intent: "rehydrate" if you want to be explicit).',
+                'Put changed facts under context only.',
+                'Round-trip continueToken exactly as returned by WorkRail; use the single-token API only.',
+            ],
+            examplePayload: {
+                continueToken: 'ct_...',
+                output: {
+                    notesMarkdown: 'Completed the step and verified the result.',
+                },
+            },
+            returns: 'The next step, or the same current step when rehydrating.',
+        },
+        authoritative: {
+            purpose: 'Continue the active WorkRail v2 workflow with the canonical single-token API.',
+            whenToUse: 'Call this after you complete the current step, or call it in rehydrate mode to recover the current step without advancing.',
+            rules: [
+                'Use continueToken exactly as returned by WorkRail.',
+                'Use the single-token API only.',
+                'Advance by sending output; rehydrate by omitting output.',
+                'Put updated facts in context only.',
+            ],
+            examplePayload: {
+                continueToken: 'ct_...',
+                intent: 'advance',
+                output: {
+                    notesMarkdown: 'Completed the step and verified the result.',
+                },
+            },
+            returns: 'The next required step, or the same current step when rehydrating.',
+        },
+    },
+};
+exports.CHECKPOINT_WORKFLOW_PROTOCOL = {
+    canonicalParams: {
+        required: ['checkpointToken'],
+    },
+    descriptions: {
+        standard: {
+            purpose: 'Save a checkpoint on the current WorkRail v2 step without advancing.',
+            whenToUse: 'Use this on long-running steps when you want a durable save point before continuing later.',
+            rules: [
+                'Use the checkpointToken from the most recent start_workflow or continue_workflow response.',
+                'Checkpointing is idempotent: retrying with the same checkpointToken is safe.',
+                'After checkpointing, continue by calling continue_workflow with nextCall.params.continueToken.',
+            ],
+            examplePayload: {
+                checkpointToken: 'cp_...',
+            },
+            returns: 'checkpointNodeId, a resumeToken (durable cross-chat bookmark — pass as continueToken with intent: "rehydrate" in a future chat to resume exactly here), and nextCall.params.continueToken (a continueToken to continue in the current chat).',
+        },
+        authoritative: {
+            purpose: 'Create a durable checkpoint on the current WorkRail v2 step without advancing.',
+            whenToUse: 'Call this when you need a save point for a long-running step and intend to continue later.',
+            rules: [
+                'Use the checkpointToken from the most recent WorkRail response.',
+                'Checkpointing is idempotent.',
+                'To continue in this chat: use nextCall.params.continueToken.',
+                'To resume in a future chat: pass the returned resumeToken as continueToken with intent: "rehydrate".',
+            ],
+            examplePayload: {
+                checkpointToken: 'cp_...',
+            },
+            returns: 'checkpointNodeId, a resumeToken (durable cross-chat bookmark — pass as continueToken with intent: "rehydrate" in a future chat to resume exactly here), and nextCall.params.continueToken (a continueToken to continue in the current chat).',
+        },
+    },
+};
+exports.RESUME_SESSION_PROTOCOL = {
+    canonicalParams: {
+        required: [],
+        optional: ['query', 'gitBranch', 'gitHeadSha', 'workspacePath'],
+    },
+    descriptions: {
+        standard: {
+            purpose: 'Find and reconnect to an existing WorkRail v2 workflow session.',
+            whenToUse: 'Use this when you need to resume a previously started workflow but no longer have the latest continueToken in chat context.',
+            rules: [
+                'Always pass query with the user\'s stated topic or intent (e.g. "resume the ACEI-1234 workflow"). Without query, only git-context matching runs and the right session may not surface.',
+                'Pass workspacePath when available so WorkRail can match sessions to the correct workspace and git context.',
+                'Pick the best candidate, then call continue_workflow using its nextCall template — no manual parameter construction needed.',
+                'Do not call read_session to resume; use the nextCall from the chosen candidate.',
+                'If candidates is empty, no eligible session exists — call start_workflow to begin a new session instead.',
+                'If all candidates have whyMatched: ["recency_fallback"], the match had no strong signal (git or notes). Verify the snippet before resuming.',
+            ],
+            examplePayload: {
+                workspacePath: '/Users/you/git/my-project',
+                query: 'resume the coding task workflow for protocol drift',
+            },
+            returns: 'Up to 5 ranked candidates, each with whyMatched explaining the match signal and a nextCall template for continue_workflow. If candidates is empty, call start_workflow.',
+        },
+        authoritative: {
+            purpose: 'Find an existing WorkRail v2 session and reconnect to it deterministically.',
+            whenToUse: 'Call this when resuming a workflow without the latest in-chat token block.',
+            rules: [
+                'Always pass query with the user\'s stated topic or intent. Semantic (notes) matching only runs when query is provided.',
+                'Pass workspacePath set to the current workspace whenever possible.',
+                'Pick the best candidate and call continue_workflow with its nextCall — the resumeToken is already embedded in nextCall.params.continueToken.',
+                'Do not invent token values or call read_session to resume execution.',
+                'If candidates is empty, no eligible session exists — call start_workflow instead.',
+                'whyMatched values: matched_head_sha / matched_branch / matched_notes = strong signal; recency_fallback = no signal, verify snippet before resuming.',
+            ],
+            examplePayload: {
+                workspacePath: '/Users/you/git/my-project',
+                query: 'resume the coding task workflow for protocol drift',
+            },
+            returns: 'Up to 5 ranked candidates, each with whyMatched confidence signals and a pre-built nextCall. Empty candidates means no session found — call start_workflow.',
+        },
+    },
+};
+function renderProtocolDescription(contract, mode) {
+    return renderCompactDescription(contract.descriptions[mode], contract.canonicalParams);
+}

package/dist/mcp-server.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export { startServer } from './mcp/server.js';
+export { startStdioServer } from './mcp/transports/stdio-entry.js';
+export { startHttpServer } from './mcp/transports/http-entry.js';
+export { composeServer } from './mcp/server.js';

package/dist/mcp-server.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startServer = void 0;
+exports.composeServer = exports.startHttpServer = exports.startStdioServer = void 0;
 const transport_mode_js_1 = require("./mcp/transports/transport-mode.js");
 const stdio_entry_js_1 = require("./mcp/transports/stdio-entry.js");
 const http_entry_js_1 = require("./mcp/transports/http-entry.js");
 const assert_never_js_1 = require("./runtime/assert-never.js");
+var stdio_entry_js_2 = require("./mcp/transports/stdio-entry.js");
+Object.defineProperty(exports, "startStdioServer", { enumerable: true, get: function () { return stdio_entry_js_2.startStdioServer; } });
+var http_entry_js_2 = require("./mcp/transports/http-entry.js");
+Object.defineProperty(exports, "startHttpServer", { enumerable: true, get: function () { return http_entry_js_2.startHttpServer; } });
 var server_js_1 = require("./mcp/server.js");
-Object.defineProperty(exports, "startServer", { enumerable: true, get: function () { return server_js_1.startServer; } });
+Object.defineProperty(exports, "composeServer", { enumerable: true, get: function () { return server_js_1.composeServer; } });
 const mode = (0, transport_mode_js_1.resolveTransportMode)(process.env);
 switch (mode.kind) {
     case 'stdio':

package/dist/types/workflow-definition.d.ts

@@ -69,6 +69,12 @@ export interface FunctionCall {
     readonly name: string;
     readonly args: Readonly<Record<string, unknown>>;
 }
+export interface ExtensionPoint {
+    readonly slotId: string;
+    readonly purpose: string;
+    readonly default: string;
+    readonly acceptedKinds?: readonly ('routine' | 'workflow')[];
+}
 export interface WorkflowRecommendedPreferences {
     readonly recommendedAutonomy?: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
     readonly recommendedRiskPolicy?: 'conservative' | 'balanced' | 'aggressive';
@@ -85,6 +91,7 @@ export interface WorkflowDefinition {
     readonly functionDefinitions?: readonly FunctionDefinition[];
     readonly recommendedPreferences?: WorkflowRecommendedPreferences;
     readonly features?: readonly string[];
+    readonly extensionPoints?: readonly ExtensionPoint[];
 }
 export declare function isLoopStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is LoopStepDefinition;
 export declare function isWorkflowStepDefinition(step: WorkflowStepDefinition | LoopStepDefinition): step is WorkflowStepDefinition;

package/dist/types/workflow-definition.js

@@ -33,5 +33,6 @@ function createWorkflowDefinition(definition) {
         clarificationPrompts: definition.clarificationPrompts ? Object.freeze([...definition.clarificationPrompts]) : undefined,
         metaGuidance: definition.metaGuidance ? Object.freeze([...definition.metaGuidance]) : undefined,
         functionDefinitions: definition.functionDefinitions ? Object.freeze([...definition.functionDefinitions]) : undefined,
+        extensionPoints: definition.extensionPoints ? Object.freeze([...definition.extensionPoints]) : undefined,
     });
 }

package/dist/v2/durable-core/domain/binding-drift.d.ts

@@ -0,0 +1,8 @@
+export interface BindingDriftWarning {
+    readonly code: 'BINDING_DRIFT';
+    readonly slotId: string;
+    readonly pinnedValue: string;
+    readonly currentValue: string;
+}
+export declare function formatDriftWarning(w: BindingDriftWarning): string;
+export declare function detectBindingDrift(pinnedOverrides: Readonly<Record<string, string>>, currentBindings: ReadonlyMap<string, string>): readonly BindingDriftWarning[];

package/dist/v2/durable-core/domain/binding-drift.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDriftWarning = formatDriftWarning;
+exports.detectBindingDrift = detectBindingDrift;
+function formatDriftWarning(w) {
+    if (w.currentValue === 'default') {
+        return (`Binding '${w.slotId}' was removed from .workrail/bindings.json since this session started. ` +
+            `Session uses '${w.pinnedValue}' (project override at start); ` +
+            `it now falls back to the workflow default. ` +
+            `Start a new session to pick up the change.`);
+    }
+    return (`Binding '${w.slotId}' changed since this session started. ` +
+        `Session uses '${w.pinnedValue}' (compiled at start); ` +
+        `current .workrail/bindings.json specifies '${w.currentValue}'. ` +
+        `Start a new session to pick up the updated binding.`);
+}
+function detectBindingDrift(pinnedOverrides, currentBindings) {
+    const warnings = [];
+    for (const [slotId, pinnedValue] of Object.entries(pinnedOverrides)) {
+        const currentValue = currentBindings.get(slotId);
+        if (currentValue === undefined) {
+            warnings.push({ code: 'BINDING_DRIFT', slotId, pinnedValue, currentValue: 'default' });
+        }
+        else if (currentValue !== pinnedValue) {
+            warnings.push({ code: 'BINDING_DRIFT', slotId, pinnedValue, currentValue });
+        }
+    }
+    return warnings;
+}

package/dist/v2/durable-core/domain/reason-model.js

@@ -162,7 +162,7 @@ function reasonToBlocker(reason) {
                 code: 'MISSING_REQUIRED_OUTPUT',
                 pointer: { kind: 'output_contract', contractRef },
                 message: `Missing required output (contractRef=${contractRef}).`,
-                suggestedFix: 'Call continue_workflow WITHOUT ackToken to rehydrate and receive a fresh ackToken, then retry with output.notesMarkdown that satisfies the step output requirements.',
+                suggestedFix: 'Call continue_workflow without output to rehydrate the current step, then retry with output.notesMarkdown that satisfies the step output requirements.',
             }))
                 .andThen(ensureBlockerTextBudgets);
         case 'invalid_required_output':
@@ -171,7 +171,7 @@ function reasonToBlocker(reason) {
                 code: 'INVALID_REQUIRED_OUTPUT',
                 pointer: { kind: 'output_contract', contractRef },
                 message: `Invalid output for contractRef=${contractRef}.`,
-                suggestedFix: 'Update output.notesMarkdown to satisfy validation. Then call continue_workflow WITHOUT ackToken (rehydrate) to receive a fresh ackToken, and retry advance with that new ackToken. Replaying the same ackToken is idempotent and will keep returning this blocked result.',
+                suggestedFix: 'Update output.notesMarkdown to satisfy validation. Then call continue_workflow without output to rehydrate the current step and retry advance with the corrected output. Replaying the same invalid advance will keep returning this blocked result.',
             }))
                 .andThen(ensureBlockerTextBudgets);
         case 'missing_notes':

package/dist/v2/durable-core/schemas/compiled-workflow/index.d.ts

@@ -51,6 +51,8 @@ export declare const CompiledWorkflowSnapshotV1Schema: z.ZodDiscriminatedUnion<"
     description: z.ZodString;
     version: z.ZodString;
     definition: z.ZodType<unknown, z.ZodTypeDef, unknown>;
+    resolvedBindings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    pinnedOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
@@ -59,6 +61,8 @@ export declare const CompiledWorkflowSnapshotV1Schema: z.ZodDiscriminatedUnion<"
     schemaVersion: 1;
     sourceKind: "v1_pinned";
     definition?: unknown;
+    resolvedBindings?: Record<string, string> | undefined;
+    pinnedOverrides?: Record<string, string> | undefined;
 }, {
     name: string;
     description: string;
@@ -67,6 +71,8 @@ export declare const CompiledWorkflowSnapshotV1Schema: z.ZodDiscriminatedUnion<"
     schemaVersion: 1;
     sourceKind: "v1_pinned";
     definition?: unknown;
+    resolvedBindings?: Record<string, string> | undefined;
+    pinnedOverrides?: Record<string, string> | undefined;
 }>]>;
 export type CompiledWorkflowSnapshotV1 = z.infer<typeof CompiledWorkflowSnapshotV1Schema>;
 export declare const CompiledWorkflowSnapshotSchema: z.ZodDiscriminatedUnion<"sourceKind", [z.ZodObject<{
@@ -121,6 +127,8 @@ export declare const CompiledWorkflowSnapshotSchema: z.ZodDiscriminatedUnion<"so
     description: z.ZodString;
     version: z.ZodString;
     definition: z.ZodType<unknown, z.ZodTypeDef, unknown>;
+    resolvedBindings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    pinnedOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
@@ -129,6 +137,8 @@ export declare const CompiledWorkflowSnapshotSchema: z.ZodDiscriminatedUnion<"so
     schemaVersion: 1;
     sourceKind: "v1_pinned";
     definition?: unknown;
+    resolvedBindings?: Record<string, string> | undefined;
+    pinnedOverrides?: Record<string, string> | undefined;
 }, {
     name: string;
     description: string;
@@ -137,5 +147,7 @@ export declare const CompiledWorkflowSnapshotSchema: z.ZodDiscriminatedUnion<"so
     schemaVersion: 1;
     sourceKind: "v1_pinned";
     definition?: unknown;
+    resolvedBindings?: Record<string, string> | undefined;
+    pinnedOverrides?: Record<string, string> | undefined;
 }>]>;
 export type CompiledWorkflowSnapshot = CompiledWorkflowSnapshotV1;

package/dist/v2/durable-core/schemas/compiled-workflow/index.js

@@ -24,6 +24,8 @@ const CompiledWorkflowSnapshotV1PinnedSchema = zod_1.z.object({
     description: zod_1.z.string().min(1),
     version: zod_1.z.string().min(1),
     definition: json_zod_js_1.JsonValueSchema,
+    resolvedBindings: zod_1.z.record(zod_1.z.string()).optional(),
+    pinnedOverrides: zod_1.z.record(zod_1.z.string()).optional(),
 });
 exports.CompiledWorkflowSnapshotV1Schema = zod_1.z.discriminatedUnion('sourceKind', [
     CompiledWorkflowSnapshotV1PreviewSchema,