@exaudeus/workrail 1.0.0 → 1.2.0

package/dist/mcp/output-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
+exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2ContinueWorkflowOutputSchema = exports.V2BlockerReportSchema = exports.V2NextCallSchema = exports.V2NextIntentSchema = exports.V2PreferencesSchema = exports.V2PendingStepSchema = exports.V2WorkflowInspectOutputSchema = exports.V2WorkflowListOutputSchema = exports.V2WorkflowListItemSchema = exports.WorkflowGetSchemaOutputSchema = exports.WorkflowValidateJsonOutputSchema = exports.WorkflowNextOutputSchema = exports.WorkflowGetOutputSchema = exports.WorkflowListOutputSchema = exports.WorkflowSummarySchema = exports.JsonValueSchema = void 0;
 const zod_1 = require("zod");
 const state_js_1 = require("../domain/execution/state.js");
 const JsonPrimitiveSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]);
@@ -67,11 +67,43 @@ exports.V2PendingStepSchema = zod_1.z.object({
     title: zod_1.z.string().min(1),
     prompt: zod_1.z.string().min(1),
 });
+exports.V2PreferencesSchema = zod_1.z.object({
+    autonomy: zod_1.z.enum(['guided', 'full_auto_stop_on_user_deps', 'full_auto_never_stop']),
+    riskPolicy: zod_1.z.enum(['conservative', 'balanced', 'aggressive']),
+});
+exports.V2NextIntentSchema = zod_1.z.enum([
+    'perform_pending_then_continue',
+    'await_user_confirmation',
+    'rehydrate_only',
+    'complete',
+]);
+exports.V2NextCallSchema = zod_1.z.object({
+    tool: zod_1.z.literal('continue_workflow'),
+    params: zod_1.z.object({
+        intent: zod_1.z.literal('advance'),
+        stateToken: zod_1.z.string().min(1),
+        ackToken: zod_1.z.string().min(1),
+    }),
+}).nullable();
+function utf8ByteLength(s) {
+    return new TextEncoder().encode(s).length;
+}
+const MAX_BLOCKER_MESSAGE_BYTES = 512;
+const MAX_BLOCKER_SUGGESTED_FIX_BYTES = 1024;
+const MAX_BLOCKERS = 10;
+const DELIMITER_SAFE_ID_PATTERN = /^[a-z0-9_-]+$/;
 const V2BlockerPointerSchema = zod_1.z.discriminatedUnion('kind', [
-    zod_1.z.object({ kind: zod_1.z.literal('context_key'), key: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        kind: zod_1.z.literal('context_key'),
+        key: zod_1.z.string().min(1).regex(DELIMITER_SAFE_ID_PATTERN, 'context_key must be delimiter-safe: [a-z0-9_-]+'),
+    }),
+    zod_1.z.object({ kind: zod_1.z.literal('context_budget') }),
     zod_1.z.object({ kind: zod_1.z.literal('output_contract'), contractRef: zod_1.z.string().min(1) }),
     zod_1.z.object({ kind: zod_1.z.literal('capability'), capability: zod_1.z.enum(['delegation', 'web_browsing']) }),
-    zod_1.z.object({ kind: zod_1.z.literal('workflow_step'), stepId: zod_1.z.string().min(1) }),
+    zod_1.z.object({
+        kind: zod_1.z.literal('workflow_step'),
+        stepId: zod_1.z.string().min(1).regex(DELIMITER_SAFE_ID_PATTERN, 'stepId must be delimiter-safe: [a-z0-9_-]+'),
+    }),
 ]);
 const V2BlockerSchema = zod_1.z.object({
     code: zod_1.z.enum([
@@ -84,11 +116,57 @@ const V2BlockerSchema = zod_1.z.object({
         'STORAGE_CORRUPTION_DETECTED',
     ]),
     pointer: V2BlockerPointerSchema,
-    message: zod_1.z.string().min(1).max(512),
-    suggestedFix: zod_1.z.string().min(1).max(1024).optional(),
+    message: zod_1.z
+        .string()
+        .min(1)
+        .refine((s) => utf8ByteLength(s) <= MAX_BLOCKER_MESSAGE_BYTES, {
+        message: `Blocker message exceeds ${MAX_BLOCKER_MESSAGE_BYTES} bytes (UTF-8)`,
+    }),
+    suggestedFix: zod_1.z
+        .string()
+        .min(1)
+        .refine((s) => utf8ByteLength(s) <= MAX_BLOCKER_SUGGESTED_FIX_BYTES, {
+        message: `Blocker suggestedFix exceeds ${MAX_BLOCKER_SUGGESTED_FIX_BYTES} bytes (UTF-8)`,
+    })
+        .optional(),
 });
-exports.V2BlockerReportSchema = zod_1.z.object({
-    blockers: zod_1.z.array(V2BlockerSchema).min(1).max(10),
+exports.V2BlockerReportSchema = zod_1.z
+    .object({
+    blockers: zod_1.z.array(V2BlockerSchema).min(1).max(MAX_BLOCKERS).readonly(),
+})
+    .superRefine((v, ctx) => {
+    const keyFor = (b) => {
+        const p = b.pointer;
+        let ptrStable;
+        switch (p.kind) {
+            case 'context_key':
+                ptrStable = p.key;
+                break;
+            case 'output_contract':
+                ptrStable = p.contractRef;
+                break;
+            case 'capability':
+                ptrStable = p.capability;
+                break;
+            case 'workflow_step':
+                ptrStable = p.stepId;
+                break;
+            case 'context_budget':
+                ptrStable = '';
+                break;
+            default: {
+                const _exhaustive = p;
+                ptrStable = _exhaustive;
+            }
+        }
+        return `${b.code}|${p.kind}|${String(ptrStable)}`;
+    };
+    for (let i = 1; i < v.blockers.length; i++) {
+        if (keyFor(v.blockers[i - 1]) > keyFor(v.blockers[i])) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'blockers must be deterministically sorted', path: ['blockers'] });
+            break;
+        }
+    }
 });
 const V2ContinueWorkflowOkSchema = zod_1.z.object({
     kind: zod_1.z.literal('ok'),
@@ -96,6 +174,9 @@ const V2ContinueWorkflowOkSchema = zod_1.z.object({
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
+    preferences: exports.V2PreferencesSchema,
+    nextIntent: exports.V2NextIntentSchema,
+    nextCall: exports.V2NextCallSchema,
 });
 const V2ContinueWorkflowBlockedSchema = zod_1.z.object({
     kind: zod_1.z.literal('blocked'),
@@ -103,7 +184,18 @@ const V2ContinueWorkflowBlockedSchema = zod_1.z.object({
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
+    preferences: exports.V2PreferencesSchema,
+    nextIntent: exports.V2NextIntentSchema,
+    nextCall: exports.V2NextCallSchema,
     blockers: exports.V2BlockerReportSchema,
+    retryable: zod_1.z.boolean().optional(),
+    retryAckToken: zod_1.z.string().optional(),
+    validation: zod_1.z
+        .object({
+        issues: zod_1.z.array(zod_1.z.string()),
+        suggestions: zod_1.z.array(zod_1.z.string()),
+    })
+        .optional(),
 });
 exports.V2ContinueWorkflowOutputSchema = zod_1.z.discriminatedUnion('kind', [
     V2ContinueWorkflowOkSchema,
@@ -114,6 +206,9 @@ exports.V2StartWorkflowOutputSchema = zod_1.z.object({
     ackToken: zod_1.z.string().regex(/^ack1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid ackToken format').optional(),
     isComplete: zod_1.z.boolean(),
     pending: exports.V2PendingStepSchema.nullable(),
+    preferences: exports.V2PreferencesSchema,
+    nextIntent: exports.V2NextIntentSchema,
+    nextCall: exports.V2NextCallSchema,
 }).refine((data) => (data.pending ? data.ackToken != null : true), { message: 'ackToken is required when a pending step exists' });
 exports.CreateSessionOutputSchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),

package/dist/mcp/server.js

@@ -38,37 +38,14 @@ exports.startServer = startServer;
 const zod_to_json_schema_js_1 = require("./zod-to-json-schema.js");
 const container_js_1 = require("../di/container.js");
 const tokens_js_1 = require("../di/tokens.js");
-const types_js_1 = require("./types.js");
+const assert_never_js_1 = require("../runtime/assert-never.js");
 const token_codec_ports_js_1 = require("../v2/durable-core/tokens/token-codec-ports.js");
+const index_js_1 = require("../v2/infra/local/workspace-anchor/index.js");
 const tool_factory_js_1 = require("./tool-factory.js");
-const workflow_next_prevalidate_js_1 = require("./validation/workflow-next-prevalidate.js");
-const bounded_json_js_1 = require("./validation/bounded-json.js");
-const index_js_1 = require("./validation/index.js");
+const handler_factory_js_1 = require("./handler-factory.js");
+const workflow_tool_edition_selector_js_1 = require("./workflow-tool-edition-selector.js");
 const tools_js_1 = require("./tools.js");
-const tool_registry_js_1 = require("./v2/tool-registry.js");
-const workflow_js_1 = require("./handlers/workflow.js");
 const session_js_1 = require("./handlers/session.js");
-function toMcpResult(result) {
-    switch (result.type) {
-        case 'success':
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
-            };
-        case 'error':
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            code: result.code,
-                            message: result.message,
-                            retry: result.retry,
-                            ...(result.details !== undefined ? { details: result.details } : {}),
-                        }, null, 2),
-                    }],
-                isError: true,
-            };
-    }
-}
 async function createToolContext() {
     const workflowService = container_js_1.container.resolve(tokens_js_1.DI.Services.Workflow);
     const featureFlags = container_js_1.container.resolve(tokens_js_1.DI.Infra.FeatureFlags);
@@ -119,6 +96,7 @@ async function createToolContext() {
                 crypto,
                 idFactory,
                 tokenCodecPorts,
+                workspaceAnchor: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),
             };
             console.error('[FeatureFlags] v2 tools enabled');
         }
@@ -142,81 +120,22 @@ function toMcpTool(tool) {
         annotations: tool.annotations,
     };
 }
-function createHandler(schema, handler) {
-    return async (args, ctx) => {
-        const parseResult = schema.safeParse(args);
-        if (!parseResult.success) {
-            const suggestionResult = (0, index_js_1.generateSuggestions)(args, schema, index_js_1.DEFAULT_SUGGESTION_CONFIG);
-            const suggestionDetails = (0, index_js_1.formatSuggestionDetails)(suggestionResult);
-            return toMcpResult((0, types_js_1.errNotRetryable)('VALIDATION_ERROR', 'Invalid input', {
-                validationErrors: parseResult.error.errors.map(e => ({
-                    path: e.path.join('.'),
-                    message: e.message,
-                })),
-                ...suggestionDetails,
-            }));
-        }
-        return toMcpResult(await handler(parseResult.data, ctx));
-    };
-}
-function createValidatingHandler(schema, preValidate, handler) {
-    return async (args, ctx) => {
-        const pre = preValidate(args);
-        if ('error' in pre && !pre.ok) {
-            const error = pre.error;
-            const details = error.details && typeof error.details === 'object' ? error.details : {};
-            const correctTemplate = details.correctTemplate;
-            if (correctTemplate !== undefined) {
-                const boundedTemplate = (0, bounded_json_js_1.toBoundedJsonValue)(correctTemplate, 512);
-                const boundedError = {
-                    ...error,
-                    details: {
-                        ...details,
-                        correctTemplate: boundedTemplate,
-                    },
-                };
-                return toMcpResult(boundedError);
-            }
-            return toMcpResult(error);
-        }
-        return createHandler(schema, handler)(args, ctx);
-    };
-}
 async function startServer() {
     await (0, container_js_1.bootstrap)({ runtimeMode: { kind: 'production' } });
     const ctx = await createToolContext();
     const descriptionProvider = container_js_1.container.resolve(tokens_js_1.DI.Mcp.DescriptionProvider);
     const buildTool = (0, tool_factory_js_1.createToolFactory)(descriptionProvider);
-    const discoverWorkflowsTool = buildTool({
-        name: 'discover_workflows',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.discover_workflows,
-        inputSchema: tools_js_1.WorkflowListInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.discover_workflows,
-    });
-    const previewWorkflowTool = buildTool({
-        name: 'preview_workflow',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.preview_workflow,
-        inputSchema: tools_js_1.WorkflowGetInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.preview_workflow,
-    });
-    const advanceWorkflowTool = buildTool({
-        name: 'advance_workflow',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.advance_workflow,
-        inputSchema: tools_js_1.WorkflowNextInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.advance_workflow,
-    });
-    const validateWorkflowTool = buildTool({
-        name: 'validate_workflow',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.validate_workflow,
-        inputSchema: tools_js_1.WorkflowValidateJsonInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.validate_workflow,
-    });
-    const getWorkflowSchemaTool = buildTool({
-        name: 'get_workflow_schema',
-        title: tools_js_1.WORKFLOW_TOOL_TITLES.get_workflow_schema,
-        inputSchema: tools_js_1.WorkflowGetSchemaInput,
-        annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.get_workflow_schema,
-    });
+    const workflowEdition = (0, workflow_tool_edition_selector_js_1.selectWorkflowToolEdition)(ctx.featureFlags, buildTool);
+    switch (workflowEdition.kind) {
+        case 'v1':
+            console.error('[ToolEdition] v1 workflow tools active');
+            break;
+        case 'v2':
+            console.error('[ToolEdition] v2 workflow tools active (v1 excluded)');
+            break;
+        default:
+            (0, assert_never_js_1.assertNever)(workflowEdition);
+    }
     const { Server } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/index.js')));
     const { StdioServerTransport } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/stdio.js')));
     const { CallToolRequestSchema, ListToolsRequestSchema, } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/types.js')));
@@ -228,39 +147,16 @@ async function startServer() {
             tools: {},
         },
     });
-    const tools = [
-        toMcpTool(discoverWorkflowsTool),
-        toMcpTool(previewWorkflowTool),
-        toMcpTool(advanceWorkflowTool),
-        toMcpTool(validateWorkflowTool),
-        toMcpTool(getWorkflowSchemaTool),
-    ];
+    const tools = workflowEdition.tools.map(toMcpTool);
     if (ctx.featureFlags.isEnabled('sessionTools')) {
         tools.push(toMcpTool(tools_js_1.createSessionTool), toMcpTool(tools_js_1.updateSessionTool), toMcpTool(tools_js_1.readSessionTool), toMcpTool(tools_js_1.openDashboardTool));
     }
-    const v2Registry = ctx.featureFlags.isEnabled('v2Tools') ? (0, tool_registry_js_1.buildV2ToolRegistry)(buildTool) : null;
-    if (v2Registry) {
-        console.error('[FeatureFlags] v2 tools enabled (enable with WORKRAIL_ENABLE_V2_TOOLS=true)');
-        tools.push(...v2Registry.tools.map(toMcpTool));
-    }
-    else {
-        console.error('[FeatureFlags] v2 tools disabled (enable with WORKRAIL_ENABLE_V2_TOOLS=true)');
-    }
-    const handlers = {
-        discover_workflows: createHandler(tools_js_1.WorkflowListInput, workflow_js_1.handleWorkflowList),
-        preview_workflow: createHandler(tools_js_1.WorkflowGetInput, workflow_js_1.handleWorkflowGet),
-        advance_workflow: createValidatingHandler(tools_js_1.WorkflowNextInput, workflow_next_prevalidate_js_1.preValidateWorkflowNextArgs, workflow_js_1.handleWorkflowNext),
-        validate_workflow: createHandler(tools_js_1.WorkflowValidateJsonInput, workflow_js_1.handleWorkflowValidateJson),
-        get_workflow_schema: createHandler(tools_js_1.WorkflowGetSchemaInput, workflow_js_1.handleWorkflowGetSchema),
-        create_session: createHandler(tools_js_1.createSessionTool.inputSchema, session_js_1.handleCreateSession),
-        update_session: createHandler(tools_js_1.updateSessionTool.inputSchema, session_js_1.handleUpdateSession),
-        read_session: createHandler(tools_js_1.readSessionTool.inputSchema, session_js_1.handleReadSession),
-        open_dashboard: createHandler(tools_js_1.openDashboardTool.inputSchema, session_js_1.handleOpenDashboard),
-    };
-    if (v2Registry) {
-        for (const [name, entry] of Object.entries(v2Registry.handlers)) {
-            handlers[name] = createHandler(entry.schema, entry.handler);
-        }
+    const handlers = { ...workflowEdition.handlers };
+    if (ctx.featureFlags.isEnabled('sessionTools')) {
+        handlers.create_session = (0, handler_factory_js_1.createHandler)(tools_js_1.createSessionTool.inputSchema, session_js_1.handleCreateSession);
+        handlers.update_session = (0, handler_factory_js_1.createHandler)(tools_js_1.updateSessionTool.inputSchema, session_js_1.handleUpdateSession);
+        handlers.read_session = (0, handler_factory_js_1.createHandler)(tools_js_1.readSessionTool.inputSchema, session_js_1.handleReadSession);
+        handlers.open_dashboard = (0, handler_factory_js_1.createHandler)(tools_js_1.openDashboardTool.inputSchema, session_js_1.handleOpenDashboard);
     }
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools,

package/dist/mcp/tool-descriptions.js

@@ -47,17 +47,73 @@ This tool provides:
 - Field descriptions and validation rules
 - Examples of valid patterns and formats
 - Schema version and metadata information`,
-        list_workflows: `Lists available workflows using the WorkRail v2 read-only surface (feature-flagged). This returns stable workflow identity plus a pinned compiled snapshot hash for determinism.`,
-        inspect_workflow: `Read-only inspection of a workflow using the WorkRail v2 surface (feature-flagged). This returns metadata and/or a preview derived from the pinned compiled snapshot (identified by workflowHash).`,
-        start_workflow: `Start a WorkRail v2 workflow run (feature-flagged). Returns an initial pending step plus opaque execution tokens.
+        list_workflows: `Lists available workflows using WorkRail v2 (feature-flagged). Returns workflow metadata plus pinned snapshot hashes for deterministic execution.
 
-Notes:
-- Tokens are opaque: round-trip them unchanged.
-- This tool may create durable session/run state. Keep inputs small and deterministic.`,
-        continue_workflow: `Continue a WorkRail v2 workflow run (feature-flagged).
+Use this to discover workflows before attempting multi-step tasks. When a workflow exists for the user's request, following it means following the user's structured instructions.`,
+        inspect_workflow: `Inspect a workflow structure before starting it (WorkRail v2, feature-flagged).
 
-- If you provide \`ackToken\`: acknowledge completion of the pending step for the given snapshot (idempotent).
-- If you omit \`ackToken\`: rehydrate the pending step for the given snapshot (MUST be side-effect-free).`,
+Use this to understand what steps the workflow will guide you through. The workflow is a step-by-step plan the user (or workflow author) created for this type of task.
+
+Returns:
+- metadata mode: Just name and description
+- preview mode: Full step-by-step breakdown (default)
+
+Remember: inspecting is read-only. Call start_workflow when ready to begin.`,
+        start_workflow: `Begin following a workflow's step-by-step instructions (WorkRail v2, feature-flagged).
+
+The workflow represents the user's plan for this task. Each step will tell you exactly what to do. Your job is to execute each step's instructions and report back.
+
+What you'll receive:
+- pending.prompt: The first step's instructions — read this and do what it says
+- nextCall: A pre-built template for your next continue_workflow call (copy its params when done)
+- nextIntent: How to approach this step (usually "perform_pending_then_continue")
+- preferences: Execution mode settings (autonomy level, risk policy)
+
+What to do:
+1. Read pending.prompt and execute the step exactly as described
+2. When done, call continue_workflow using the params from nextCall (it has intent, stateToken, ackToken pre-filled)
+3. Optionally add output.notesMarkdown summarizing your work
+4. Don't predict what comes next - the workflow will tell you
+
+Context auto-loads: If you provide context at start, WorkRail remembers it. On future continue_workflow calls, only pass context if you have NEW information to add.`,
+        continue_workflow: `Get the next step in the workflow (WorkRail v2, feature-flagged).
+
+QUICK START — How to call back after completing a step:
+Copy the params from the "nextCall" field of the previous response. It has intent, stateToken, and ackToken pre-filled. Just add your output if desired.
+
+Two modes — set intent explicitly:
+
+ADVANCE (intent: "advance"):
+- "I completed the current step; give me the next one"
+- Requires: intent + stateToken + ackToken (all provided in nextCall.params)
+- Optional: output (your work summary), context (if facts changed)
+- Result: WorkRail advances to next step and returns it
+
+REHYDRATE (intent: "rehydrate"):
+- "Remind me what the current step is" (after rewind or lost context)
+- Requires: intent + stateToken
+- Do NOT include ackToken or output
+- Result: Same pending step returned; no advancement; side-effect-free
+
+Reading the response:
+- pending.prompt: The step's instructions — what to do
+- nextCall: Pre-built template for your next call — how to proceed when done (null if workflow complete)
+- nextIntent: How to approach this step — execute it, confirm first, or continue working on it
+
+nextIntent values:
+- "perform_pending_then_continue": Execute this step, then use nextCall to advance
+- "await_user_confirmation": Auto-confirm and proceed (you don't need to wait for user in agent mode)
+- "rehydrate_only": You just recovered state; continue working on the current step, then use nextCall
+- "complete": Workflow finished; nextCall is null
+
+Parameters:
+- intent (required): "advance" or "rehydrate"
+- stateToken (required): From nextCall.params or previous response
+- ackToken (required for advance): From nextCall.params or previous response
+- context (optional): NEW facts only. Omit if unchanged - WorkRail auto-loads previous context
+- output.notesMarkdown (optional, advance only): Fresh summary of THIS step only - never accumulated
+
+The workflow is the user's structured instructions. Follow each step exactly as described.`,
     },
     authoritative: {
         discover_workflows: `Check for workflows that apply to the user's request. Workflows are the user's pre-defined instructions that you MUST follow when they exist.
@@ -114,19 +170,87 @@ Returns validation result with specific errors and suggestions if invalid.`,
         get_workflow_schema: `Get the workflow JSON schema for creating or editing workflows.
 
 Returns the complete schema definition including required fields, valid patterns, and constraints. Use this as reference when authoring workflow JSON.`,
-        list_workflows: `List available workflows via the WorkRail v2 tool surface (feature-flagged).
+        list_workflows: `List available workflows via WorkRail v2 (feature-flagged).
+
+Workflows are the user's pre-defined instructions for complex tasks. When a workflow exists for the user's request, you MUST use it instead of improvising your own approach.
 
-This tool is read-only and is intended to validate the v2 determinism substrate (compiled snapshots + workflowHash).`,
-        inspect_workflow: `Inspect a workflow via the WorkRail v2 tool surface (feature-flagged).
+Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.`,
+        inspect_workflow: `Inspect a workflow you are considering following (WorkRail v2, feature-flagged).
 
-This tool is read-only. It MUST reflect the pinned compiled snapshot identified by workflowHash (not mutable on-disk source).`,
-        start_workflow: `Start a workflow run via the WorkRail v2 token-based execution surface (feature-flagged).
+Use this to understand the workflow's structure before starting. The workflow is the user's explicit plan - not suggestions, not guidelines, but direct instructions you will follow.
 
-You MUST treat returned tokens as opaque and round-trip them unchanged.`,
-        continue_workflow: `Continue a workflow run via the WorkRail v2 token-based execution surface (feature-flagged).
+Parameters:
+- workflowId: The workflow to inspect
+- mode: 'metadata' (name/description only) or 'preview' (full step breakdown)
+
+This is read-only. Call start_workflow when ready to commit to following the workflow.`,
+        start_workflow: `Begin executing the user's workflow instructions (WorkRail v2, feature-flagged).
+
+The workflow is the USER'S VOICE expressing their plan for this task. Each step is a DIRECT INSTRUCTION from the user (or workflow author representing user intent). You MUST execute each step exactly as specified.
+
+What you receive:
+- pending.prompt: The user's first instruction — execute this EXACTLY as described
+- nextCall: Pre-built template for your next continue_workflow call — copy its params when done
+- nextIntent: How to approach this step (execute, confirm, etc.)
+- preferences: User's execution mode preferences (autonomy, risk tolerance)
+
+REQUIRED BEHAVIOR:
+1. Execute the pending step EXACTLY as the prompt describes
+2. When done, call continue_workflow using the params from nextCall (intent, stateToken, ackToken are pre-filled)
+3. Optionally add output.notesMarkdown summarizing your work
+4. Round-trip tokens UNCHANGED (don't decode, inspect, or modify them)
+5. Follow the workflow to completion - don't improvise alternative approaches
+
+Context handling:
+- Pass context at start to establish baseline facts
+- WorkRail auto-loads context on subsequent calls
+- Only pass context again if facts have CHANGED (e.g., user provided new information)`,
+        continue_workflow: `Get your next INSTRUCTION from the workflow (WorkRail v2, feature-flagged).
+
+The workflow represents the USER'S PLAN. The pending step returned is a DIRECT INSTRUCTION you MUST follow.
+
+HOW TO CALL — Copy nextCall.params from the previous response. It has intent, stateToken, and ackToken pre-filled. Add output if desired.
+
+Two modes — set intent explicitly:
+
+ADVANCE (intent: "advance"):
+- Purpose: "I completed the current step; give me the next instruction"
+- Requires: intent + stateToken + ackToken (all in nextCall.params from previous response)
+- Optional: output (your work summary), context (if facts changed)
+- Result: WorkRail advances to next step
+- Idempotent: Safe to retry with same tokens if unsure
+
+REHYDRATE (intent: "rehydrate"):
+- Purpose: "Remind me what the current step is" (after rewind/lost context)
+- Requires: intent + stateToken only
+- Do NOT include ackToken or output
+- Result: Same pending step returned; no advancement
+- Side-effect-free: No durable writes; pure state recovery
 
 REQUIRED BEHAVIOR:
-- If \`ackToken\` is omitted: rehydrate-only MUST be side-effect-free (no durable writes).
-- If \`ackToken\` is provided: advancement MUST be idempotent and replay-safe for the given tokens.`,
+1. Execute the step EXACTLY as specified in pending.prompt
+2. When done, call continue_workflow using nextCall.params — do NOT construct params manually
+3. Do NOT predict what comes next - call continue_workflow and the workflow will tell you
+4. Do NOT skip steps, combine steps, or improvise your own approach
+
+Reading the response:
+- pending.prompt: The step's instructions — WHAT to do
+- nextCall: Pre-built call template — HOW to proceed when done (null if complete)
+- nextIntent: Step disposition — HOW to approach this step
+
+nextIntent is PRESCRIPTIVE (not advisory):
+- "perform_pending_then_continue": Execute this step, then use nextCall to advance
+- "await_user_confirmation": Auto-confirm and proceed (workflow represents user's intent)
+- "rehydrate_only": State recovery occurred; continue working on current step, then use nextCall
+- "complete": Workflow finished; nextCall is null
+
+Parameters:
+- intent (required): "advance" or "rehydrate"
+- stateToken (required): From nextCall.params or previous response
+- ackToken (required for advance): From nextCall.params or previous response
+- context (optional): NEW facts only (auto-merges with previous). Omit if unchanged
+- output.notesMarkdown (optional, advance only): Summary of THIS step only (fresh, never accumulated)
+  
+The workflow is the user's structured will. Follow it exactly — it may validate, loop, or branch in ways you don't predict.`,
     },
 };

package/dist/mcp/types/workflow-tool-edition.d.ts

@@ -0,0 +1,28 @@
+import type { z } from 'zod';
+import type { ToolDefinition } from '../tool-factory.js';
+import type { ToolContext } from '../types.js';
+export type V1WorkflowToolName = 'discover_workflows' | 'preview_workflow' | 'advance_workflow' | 'validate_workflow' | 'get_workflow_schema';
+export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow';
+export type McpCallToolResult = {
+    readonly content: ReadonlyArray<{
+        readonly type: 'text';
+        readonly text: string;
+    }>;
+    readonly isError?: boolean;
+};
+export type WrappedToolHandler = (args: unknown, ctx: ToolContext) => Promise<McpCallToolResult>;
+export type V1WorkflowHandlers = Readonly<Record<V1WorkflowToolName, WrappedToolHandler>>;
+export type V2WorkflowHandlers = Readonly<Record<V2WorkflowToolName, WrappedToolHandler>>;
+export interface V1WorkflowToolEdition {
+    readonly kind: 'v1';
+    readonly tools: readonly ToolDefinition<z.ZodType>[];
+    readonly handlers: V1WorkflowHandlers;
+}
+export interface V2WorkflowToolEdition {
+    readonly kind: 'v2';
+    readonly tools: readonly ToolDefinition<z.ZodType>[];
+    readonly handlers: V2WorkflowHandlers;
+}
+export type WorkflowToolEdition = V1WorkflowToolEdition | V2WorkflowToolEdition;
+export declare function isV1Edition(edition: WorkflowToolEdition): edition is V1WorkflowToolEdition;
+export declare function isV2Edition(edition: WorkflowToolEdition): edition is V2WorkflowToolEdition;

package/dist/mcp/types/workflow-tool-edition.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isV1Edition = isV1Edition;
+exports.isV2Edition = isV2Edition;
+function isV1Edition(edition) {
+    return edition.kind === 'v1';
+}
+function isV2Edition(edition) {
+    return edition.kind === 'v2';
+}

package/dist/mcp/types.d.ts

@@ -12,6 +12,7 @@ import type { CryptoPortV2 } from '../v2/durable-core/canonical/hashing.js';
 import type { IdFactoryV2 } from '../v2/infra/local/id-factory/index.js';
 import type { JsonValue } from './output-schemas.js';
 import type { TokenCodecPorts } from '../v2/durable-core/tokens/token-codec-ports.js';
+import type { WorkspaceAnchorPortV2 } from '../v2/ports/workspace-anchor.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -51,6 +52,7 @@ export interface V2Dependencies {
     readonly crypto: CryptoPortV2;
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
+    readonly workspaceAnchor?: WorkspaceAnchorPortV2;
 }
 export interface ToolContext {
     readonly workflowService: WorkflowService;

package/dist/mcp/v1/tool-registry.d.ts

@@ -0,0 +1,8 @@
+import type { z } from 'zod';
+import type { ToolBuilder, ToolDefinition } from '../tool-factory.js';
+import type { V1WorkflowHandlers } from '../types/workflow-tool-edition.js';
+export interface V1ToolRegistration {
+    readonly tools: readonly ToolDefinition<z.ZodType>[];
+    readonly handlers: V1WorkflowHandlers;
+}
+export declare function buildV1ToolRegistry(buildTool: ToolBuilder): V1ToolRegistration;

package/dist/mcp/v1/tool-registry.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildV1ToolRegistry = buildV1ToolRegistry;
+const handler_factory_js_1 = require("../handler-factory.js");
+const workflow_next_prevalidate_js_1 = require("../validation/workflow-next-prevalidate.js");
+const tools_js_1 = require("../tools.js");
+const workflow_js_1 = require("../handlers/workflow.js");
+function buildV1ToolRegistry(buildTool) {
+    const tools = [
+        buildTool({
+            name: 'discover_workflows',
+            title: tools_js_1.WORKFLOW_TOOL_TITLES.discover_workflows,
+            inputSchema: tools_js_1.WorkflowListInput,
+            annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.discover_workflows,
+        }),
+        buildTool({
+            name: 'preview_workflow',
+            title: tools_js_1.WORKFLOW_TOOL_TITLES.preview_workflow,
+            inputSchema: tools_js_1.WorkflowGetInput,
+            annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.preview_workflow,
+        }),
+        buildTool({
+            name: 'advance_workflow',
+            title: tools_js_1.WORKFLOW_TOOL_TITLES.advance_workflow,
+            inputSchema: tools_js_1.WorkflowNextInput,
+            annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.advance_workflow,
+        }),
+        buildTool({
+            name: 'validate_workflow',
+            title: tools_js_1.WORKFLOW_TOOL_TITLES.validate_workflow,
+            inputSchema: tools_js_1.WorkflowValidateJsonInput,
+            annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.validate_workflow,
+        }),
+        buildTool({
+            name: 'get_workflow_schema',
+            title: tools_js_1.WORKFLOW_TOOL_TITLES.get_workflow_schema,
+            inputSchema: tools_js_1.WorkflowGetSchemaInput,
+            annotations: tools_js_1.WORKFLOW_TOOL_ANNOTATIONS.get_workflow_schema,
+        }),
+    ];
+    const handlers = {
+        discover_workflows: (0, handler_factory_js_1.createHandler)(tools_js_1.WorkflowListInput, workflow_js_1.handleWorkflowList),
+        preview_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.WorkflowGetInput, workflow_js_1.handleWorkflowGet),
+        advance_workflow: (0, handler_factory_js_1.createValidatingHandler)(tools_js_1.WorkflowNextInput, workflow_next_prevalidate_js_1.preValidateWorkflowNextArgs, workflow_js_1.handleWorkflowNext),
+        validate_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.WorkflowValidateJsonInput, workflow_js_1.handleWorkflowValidateJson),
+        get_workflow_schema: (0, handler_factory_js_1.createHandler)(tools_js_1.WorkflowGetSchemaInput, workflow_js_1.handleWorkflowGetSchema),
+    };
+    return { tools, handlers };
+}