@exaudeus/workrail 3.14.0 → 3.16.0

package/dist/mcp/server.js

@@ -47,6 +47,8 @@ const workspace_roots_manager_js_1 = require("./workspace-roots-manager.js");
 const index_js_2 = require("../v2/infra/local/directory-listing/index.js");
 const index_js_3 = require("../v2/infra/local/session-summary-provider/index.js");
 const tool_factory_js_1 = require("./tool-factory.js");
+const dev_mode_js_1 = require("./dev-mode.js");
+const tool_call_timing_js_1 = require("./tool-call-timing.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");
@@ -159,8 +161,9 @@ function toMcpTool(tool) {
     };
 }
 async function composeServer() {
-    await (0, container_js_1.bootstrap)({ runtimeMode: { kind: 'production' } });
+    await (0, container_js_1.bootstrap)();
     const ctx = await createToolContext();
+    const timingRingBuffer = new tool_call_timing_js_1.ToolCallTimingRingBuffer(tool_call_timing_js_1.DEFAULT_RING_BUFFER_CAPACITY);
     if (ctx.v2 && ctx.httpServer && ctx.v2.dataDir && ctx.v2.directoryListing) {
         const { ConsoleService } = await Promise.resolve().then(() => __importStar(require('../v2/usecases/console-service.js')));
         const { mountConsoleRoutes } = await Promise.resolve().then(() => __importStar(require('../v2/usecases/console-routes.js')));
@@ -171,7 +174,7 @@ async function composeServer() {
             snapshotStore: ctx.v2.snapshotStore,
             pinnedWorkflowStore: ctx.v2.pinnedStore,
         });
-        ctx.httpServer.mountRoutes((app) => mountConsoleRoutes(app, consoleService));
+        ctx.httpServer.mountRoutes((app) => mountConsoleRoutes(app, consoleService, ctx.workflowService, timingRingBuffer));
         console.error('[Console] v2 Console API routes mounted at /api/v2/');
     }
     ctx.httpServer?.finalize();
@@ -190,13 +193,14 @@ async function composeServer() {
     }
     const rootsManager = new workspace_roots_manager_js_1.WorkspaceRootsManager();
     const { Server } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/index.js')));
-    const { CallToolRequestSchema, ListToolsRequestSchema, } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/types.js')));
+    const { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/types.js')));
     const server = new Server({
         name: 'workrail-server',
         version: '0.1.0',
     }, {
         capabilities: {
             tools: {},
+            resources: {},
         },
     });
     const tools = workflowEdition.tools.map(toMcpTool);
@@ -213,19 +217,80 @@ async function composeServer() {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools,
     }));
+    const timingSink = dev_mode_js_1.DEV_MODE
+        ? (0, tool_call_timing_js_1.composeSinks)((0, tool_call_timing_js_1.createRingBufferSink)(timingRingBuffer), (0, tool_call_timing_js_1.createDevPerfSink)())
+        : (0, tool_call_timing_js_1.createRingBufferSink)(timingRingBuffer);
+    if (dev_mode_js_1.DEV_MODE) {
+        console.error('[PerfTrace] WORKRAIL_DEV=1 -- tool call timing active');
+    }
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        const handlerStartMs = Date.now();
+        const handlerStartHr = performance.now();
         const handler = handlers[name];
         if (!handler) {
-            return {
+            const unknownResult = {
                 content: [{ type: 'text', text: `Unknown tool: ${name}` }],
                 isError: true,
             };
+            const durationMs = Math.round((performance.now() - handlerStartHr) * 100) / 100;
+            try {
+                timingSink({ toolName: name ?? '(unknown)', startedAtMs: handlerStartMs, durationMs, outcome: 'unknown_tool' });
+            }
+            catch {
+            }
+            return unknownResult;
         }
         const requestCtx = ctx.v2
             ? { ...ctx, v2: { ...ctx.v2, resolvedRootUris: rootsManager.getCurrentRootUris() } }
             : ctx;
-        return handler(args ?? {}, requestCtx);
+        return (0, tool_call_timing_js_1.withToolCallTiming)(name, () => handler(args ?? {}, requestCtx), timingSink);
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: 'workrail://tags',
+                name: 'WorkRail Tag Catalog',
+                description: 'Closed-set tag definitions for workflow discovery. ' +
+                    'Read this before calling list_workflows — it tells you which tags exist ' +
+                    'and when to use each one, so you can call list_workflows with tags=[...] ' +
+                    'instead of loading all 36+ workflows into context.',
+                mimeType: 'application/json',
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params?.uri ?? '';
+        if (uri !== 'workrail://tags') {
+            return {
+                contents: [],
+                isError: true,
+                _meta: { error: `Unknown resource: ${uri}` },
+            };
+        }
+        try {
+            const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+            const path = await Promise.resolve().then(() => __importStar(require('path')));
+            const tagsPath = path.resolve(__dirname, '../../spec/workflow-tags.json');
+            const raw = fs.readFileSync(tagsPath, 'utf-8');
+            return {
+                contents: [
+                    {
+                        uri: 'workrail://tags',
+                        mimeType: 'application/json',
+                        text: raw,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                contents: [],
+                isError: true,
+                _meta: { error: `Failed to read tag catalog: ${message}` },
+            };
+        }
     });
     return { server, ctx, rootsManager, rootsReader: rootsManager, tools, handlers };
 }

package/dist/mcp/tool-call-timing.d.ts

@@ -0,0 +1,24 @@
+export type ToolCallOutcome = 'success' | 'error' | 'unknown_tool';
+export interface ToolCallTiming {
+    readonly toolName: string;
+    readonly startedAtMs: number;
+    readonly durationMs: number;
+    readonly outcome: ToolCallOutcome;
+}
+export type ToolCallTimingSink = (timing: ToolCallTiming) => void;
+export declare const noopToolCallTimingSink: ToolCallTimingSink;
+export declare class ToolCallTimingRingBuffer {
+    private readonly capacity;
+    private readonly buffer;
+    private head;
+    private count;
+    constructor(capacity: number);
+    push(timing: ToolCallTiming): void;
+    recent(limit?: number): readonly ToolCallTiming[];
+    get size(): number;
+}
+export declare const DEFAULT_RING_BUFFER_CAPACITY = 100;
+export declare function createRingBufferSink(buffer: ToolCallTimingRingBuffer): ToolCallTimingSink;
+export declare function createDevPerfSink(): ToolCallTimingSink;
+export declare function composeSinks(...sinks: ToolCallTimingSink[]): ToolCallTimingSink;
+export declare function withToolCallTiming<T>(toolName: string, handler: () => Promise<T>, sink: ToolCallTimingSink): Promise<T>;

package/dist/mcp/tool-call-timing.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RING_BUFFER_CAPACITY = exports.ToolCallTimingRingBuffer = exports.noopToolCallTimingSink = void 0;
+exports.createRingBufferSink = createRingBufferSink;
+exports.createDevPerfSink = createDevPerfSink;
+exports.composeSinks = composeSinks;
+exports.withToolCallTiming = withToolCallTiming;
+const noopToolCallTimingSink = () => { };
+exports.noopToolCallTimingSink = noopToolCallTimingSink;
+class ToolCallTimingRingBuffer {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.head = 0;
+        this.count = 0;
+        if (capacity < 1)
+            throw new Error('Ring buffer capacity must be >= 1');
+        this.buffer = new Array(capacity).fill(undefined);
+    }
+    push(timing) {
+        this.buffer[this.head] = timing;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.count < this.capacity)
+            this.count++;
+    }
+    recent(limit) {
+        const n = limit !== undefined ? Math.min(limit, this.count) : this.count;
+        const results = [];
+        for (let i = 1; i <= n; i++) {
+            const idx = (this.head - i + this.capacity) % this.capacity;
+            const entry = this.buffer[idx];
+            if (entry !== undefined)
+                results.push(entry);
+        }
+        return results;
+    }
+    get size() {
+        return this.count;
+    }
+}
+exports.ToolCallTimingRingBuffer = ToolCallTimingRingBuffer;
+exports.DEFAULT_RING_BUFFER_CAPACITY = 100;
+function createRingBufferSink(buffer) {
+    return (timing) => {
+        buffer.push(timing);
+    };
+}
+function createDevPerfSink() {
+    return (timing) => {
+        const outcomeLabel = timing.outcome === 'success' ? 'OK' : timing.outcome.toUpperCase();
+        const line = `[PerfTrace] ${timing.toolName} ${timing.durationMs.toFixed(1)}ms [${outcomeLabel}]`;
+        console.error(line);
+    };
+}
+function composeSinks(...sinks) {
+    return (timing) => {
+        for (const sink of sinks) {
+            try {
+                sink(timing);
+            }
+            catch { }
+        }
+    };
+}
+async function withToolCallTiming(toolName, handler, sink) {
+    const startedAtMs = Date.now();
+    const startHr = performance.now();
+    let outcome = 'error';
+    try {
+        const result = await handler();
+        outcome = result?.isError === true ? 'error' : 'success';
+        return result;
+    }
+    catch (err) {
+        outcome = 'error';
+        throw err;
+    }
+    finally {
+        const durationMs = Math.round((performance.now() - startHr) * 100) / 100;
+        try {
+            sink({ toolName, startedAtMs, durationMs, outcome });
+        }
+        catch {
+        }
+    }
+}

package/dist/mcp/tool-descriptions.js

@@ -48,12 +48,17 @@ 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 WorkRail v2 (feature-flagged). Returns workflow metadata plus pinned snapshot hashes for deterministic execution.
+        list_workflows: `Lists available workflows. When a workflow exists for the user's request, following it means following the user's structured instructions.
 
-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.
+Discovery pattern (token-efficient — do this):
+- Preferred: read the workrail://tags MCP resource — tag definitions with no tool call.
+- Or: call with no tags → returns tagSummary (~500 tokens) with when-to-use phrases per tag.
+- Then: call with tags=["<tagId>"] → returns the filtered workflow list for that tag.
+- Shortcut: if a workflow ID in tagSummary examples[] already matches, call start_workflow directly — skip the second list call.
+- Multiple tags: if more than one tag fits, pick the most specific one.
 
-Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory. Shared MCP servers cannot infer this safely.`,
-        inspect_workflow: `Inspect a workflow structure before starting it (WorkRail v2, feature-flagged).
+Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.`,
+        inspect_workflow: `Inspect a workflow structure before starting it.
 
 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.
 
@@ -139,14 +144,17 @@ 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 WorkRail v2 (feature-flagged).
+        list_workflows: `Lists available workflows. When a workflow exists for the user's request, you MUST use it instead of improvising your own approach.
 
-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.
-
-Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.
+Discovery pattern (token-efficient — do this):
+- Preferred: read the workrail://tags MCP resource — tag definitions with no tool call.
+- Or: call with no tags → returns tagSummary (~500 tokens) with when-to-use phrases per tag.
+- Then: call with tags=["<tagId>"] → returns the filtered workflow list for that tag.
+- Shortcut: if a workflow ID in tagSummary examples[] already matches, call start_workflow directly — skip the second list call.
+- Multiple tags: if more than one tag fits, pick the most specific one.
 
 Pass workspacePath on every call so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.`,
-        inspect_workflow: `Inspect a workflow you are considering following (WorkRail v2, feature-flagged).
+        inspect_workflow: `Inspect a workflow you are considering following.
 
 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.
 

package/dist/mcp/transports/http-entry.js

@@ -42,9 +42,11 @@ const http_listener_js_1 = require("./http-listener.js");
 const shutdown_hooks_js_1 = require("./shutdown-hooks.js");
 const crypto = __importStar(require("crypto"));
 const express_1 = __importDefault(require("express"));
+const HTTP_PORT_SCAN_END = 3199;
 async function startHttpServer(port) {
     const { server, ctx } = await (0, server_js_1.composeServer)();
-    const listener = (0, http_listener_js_1.createHttpListener)(port);
+    const scanEnd = Math.max(port, HTTP_PORT_SCAN_END);
+    const listener = await (0, http_listener_js_1.bindWithPortFallback)(port, scanEnd);
     const { StreamableHTTPServerTransport } = await Promise.resolve().then(() => __importStar(require('@modelcontextprotocol/sdk/server/streamableHttp.js')));
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => crypto.randomUUID(),
@@ -54,7 +56,6 @@ async function startHttpServer(port) {
     listener.app.post('/mcp', (req, res) => transport.handleRequest(req, res, req.body));
     listener.app.get('/mcp', (req, res) => transport.handleRequest(req, res));
     listener.app.delete('/mcp', (req, res) => transport.handleRequest(req, res));
-    await listener.start();
     await server.connect(transport);
     const boundPort = listener.getBoundPort();
     console.error('[Transport] WorkRail MCP Server running on HTTP');

package/dist/mcp/transports/http-listener.d.ts

@@ -7,3 +7,4 @@ export interface HttpListener {
     stop(): Promise<void>;
 }
 export declare function createHttpListener(requestedPort: number): HttpListener;
+export declare function bindWithPortFallback(startPort: number, endPort: number): Promise<HttpListener>;

package/dist/mcp/transports/http-listener.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHttpListener = createHttpListener;
+exports.bindWithPortFallback = bindWithPortFallback;
 const express_1 = __importDefault(require("express"));
 const http_1 = require("http");
 function createHttpListener(requestedPort) {
@@ -62,3 +63,27 @@ function createHttpListener(requestedPort) {
         },
     };
 }
+async function bindWithPortFallback(startPort, endPort) {
+    let lastError;
+    for (let port = startPort; port <= endPort; port++) {
+        const listener = createHttpListener(port);
+        try {
+            await listener.start();
+            if (port !== startPort) {
+                console.error(`[HttpListener] Port ${startPort} unavailable; bound to fallback port ${port}`);
+            }
+            return listener;
+        }
+        catch (err) {
+            const nodeErr = err;
+            if (nodeErr.code === 'EADDRINUSE' ||
+                (err instanceof Error && err.message.includes('already in use'))) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error(`[HttpListener] No available port in range ${startPort}-${endPort}. ` +
+        `Last error: ${lastError?.message}`);
+}

package/dist/mcp/transports/shutdown-hooks.d.ts

@@ -2,4 +2,7 @@ export interface ShutdownHookOptions {
     readonly onBeforeTerminate: () => Promise<void>;
 }
 export declare function wireShutdownHooks(opts: ShutdownHookOptions): void;
-export declare function wireStdinShutdown(): void;
+export interface StdinShutdownOptions {
+    readonly stdin?: NodeJS.ReadableStream;
+}
+export declare function wireStdinShutdown(opts?: StdinShutdownOptions): void;

package/dist/mcp/transports/shutdown-hooks.js

@@ -29,9 +29,10 @@ function wireShutdownHooks(opts) {
         })();
     });
 }
-function wireStdinShutdown() {
+function wireStdinShutdown(opts) {
     const shutdownEvents = container_js_1.container.resolve(tokens_js_1.DI.Runtime.ShutdownEvents);
-    process.stdin.on('end', () => {
+    const stdin = opts?.stdin ?? process.stdin;
+    stdin.once('end', () => {
         console.error('[MCP] stdin closed, initiating shutdown');
         shutdownEvents.emit({ kind: 'shutdown_requested', signal: 'SIGHUP' });
     });

package/dist/mcp/transports/stdio-entry.js

@@ -35,8 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startStdioServer = startStdioServer;
 const server_js_1 = require("../server.js");
-const container_js_1 = require("../../di/container.js");
-const tokens_js_1 = require("../../di/tokens.js");
+const shutdown_hooks_js_1 = require("./shutdown-hooks.js");
 const INITIAL_ROOTS_TIMEOUT_MS = 1000;
 async function fetchInitialRootsWithTimeout(server) {
     return Promise.race([
@@ -75,31 +74,10 @@ async function startStdioServer() {
         .catch(() => {
         console.error('[Roots] Client does not support roots/list; workspace context will use server CWD fallback');
     });
-    const shutdownEvents = container_js_1.container.resolve(tokens_js_1.DI.Runtime.ShutdownEvents);
-    const processSignals = container_js_1.container.resolve(tokens_js_1.DI.Runtime.ProcessSignals);
-    const terminator = container_js_1.container.resolve(tokens_js_1.DI.Runtime.ProcessTerminator);
-    processSignals.on('SIGINT', () => shutdownEvents.emit({ kind: 'shutdown_requested', signal: 'SIGINT' }));
-    processSignals.on('SIGTERM', () => shutdownEvents.emit({ kind: 'shutdown_requested', signal: 'SIGTERM' }));
-    processSignals.on('SIGHUP', () => shutdownEvents.emit({ kind: 'shutdown_requested', signal: 'SIGHUP' }));
-    process.stdin.on('end', () => {
-        console.error('[MCP] stdin closed, initiating shutdown');
-        shutdownEvents.emit({ kind: 'shutdown_requested', signal: 'SIGHUP' });
-    });
-    let shutdownStarted = false;
-    shutdownEvents.onShutdown((event) => {
-        if (shutdownStarted)
-            return;
-        shutdownStarted = true;
-        void (async () => {
-            try {
-                console.error(`[Shutdown] Requested by ${event.signal}. Stopping services...`);
-                await ctx.httpServer?.stop();
-                terminator.terminate({ kind: 'success' });
-            }
-            catch (err) {
-                console.error('[Shutdown] Error while stopping services:', err);
-                terminator.terminate({ kind: 'failure' });
-            }
-        })();
+    (0, shutdown_hooks_js_1.wireStdinShutdown)();
+    (0, shutdown_hooks_js_1.wireShutdownHooks)({
+        onBeforeTerminate: async () => {
+            await ctx.httpServer?.stop();
+        },
     });
 }

package/dist/mcp/v2/tools.d.ts

@@ -3,12 +3,15 @@ import type { ToolAnnotations } from '../tool-factory.js';
 export declare const V2ListWorkflowsInput: z.ZodObject<{
     workspacePath: z.ZodEffects<z.ZodString, string, string>;
     includeSources: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     workspacePath: string;
     includeSources?: boolean | undefined;
+    tags?: string[] | undefined;
 }, {
     workspacePath: string;
     includeSources?: boolean | undefined;
+    tags?: string[] | undefined;
 }>;
 export type V2ListWorkflowsInput = z.infer<typeof V2ListWorkflowsInput>;
 export declare const V2InspectWorkflowInput: z.ZodObject<{
@@ -28,12 +31,15 @@ export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;
 export declare const V2StartWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
     workspacePath: z.ZodEffects<z.ZodString, string, string>;
+    goal: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
     workspacePath: string;
+    goal: string;
 }, {
     workflowId: string;
     workspacePath: string;
+    goal: string;
 }>;
 export type V2StartWorkflowInput = z.infer<typeof V2StartWorkflowInput>;
 export declare const V2ContinueWorkflowInputShape: z.ZodObject<{

package/dist/mcp/v2/tools.js

@@ -17,6 +17,7 @@ const optionalWorkspacePathField = workspacePathField.optional();
 exports.V2ListWorkflowsInput = zod_1.z.object({
     workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve project-scoped workflow variants against the correct workspace for discovery-sensitive workflow listing. Shared MCP servers cannot infer this safely.'),
     includeSources: zod_1.z.boolean().optional().describe('When true, includes a source catalog in the response showing where workflows come from (built-in, project-scoped, rooted-sharing, external), with effective and shadowed workflow counts per source. Omit or set false for the default workflow-list-only response.'),
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Filter by one or more domain tags (e.g. ["coding"], ["review_audit", "investigation"]). When present, returns the full workflow list for workflows matching any of the specified tags. When absent, returns a compact tagSummary instead of the full list — use this first to discover which tags exist, then call again with a specific tag. Valid tags: coding, review_audit, investigation, design, documentation, tickets, learning, routines, authoring.'),
 });
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^([a-z0-9_-]+|[a-z][a-z0-9_-]+\.[a-z][a-z0-9_-]+)$/, 'Workflow ID must be a valid legacy ID (e.g. my-workflow) or namespaced ID (e.g. wr.discovery)').describe('The workflow ID to inspect'),
@@ -26,6 +27,7 @@ exports.V2InspectWorkflowInput = zod_1.z.object({
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^([a-z0-9_-]+|[a-z][a-z0-9_-]+\.[a-z][a-z0-9_-]+)$/, 'Workflow ID must be a valid legacy ID (e.g. my-workflow) or namespaced ID (e.g. wr.discovery)').describe('The workflow ID to start'),
     workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve the correct project-scoped workflow variant and to anchor the session to the correct repo for future resume_session discovery. Shared MCP servers cannot infer this safely.'),
+    goal: zod_1.z.string().min(1).describe('A short sentence describing what you are trying to accomplish (e.g. "implement OAuth refresh token rotation", "review PR #47 before merge", "investigate why the build fails on CI").'),
 });
 exports.V2ContinueWorkflowInputShape = zod_1.z.object({
     workspacePath: optionalWorkspacePathField,

package/dist/mcp/v2-response-formatter.js

@@ -4,6 +4,7 @@ exports.formatV2ExecutionResponse = formatV2ExecutionResponse;
 exports.formatV2ResumeResponse = formatV2ResumeResponse;
 const render_envelope_js_1 = require("./render-envelope.js");
 const response_supplements_js_1 = require("./response-supplements.js");
+const env_flags_js_1 = require("../env-flags.js");
 function isV2ExecutionResponse(data) {
     if (typeof data !== 'object' || data === null)
         return false;
@@ -216,9 +217,6 @@ function formatSuccess(data) {
     }
     return lines.join('\n');
 }
-function isCleanResponseFormat() {
-    return process.env.WORKRAIL_CLEAN_RESPONSE_FORMAT === 'true';
-}
 const CLEAN_ADVANCE_FOOTERS = [
     'WorkRail: when done, call continue_workflow with your notes. Token:',
     'WorkRail: advance with continue_workflow when ready. Include your notes. Token:',
@@ -354,7 +352,7 @@ function formatV2ExecutionResponse(data) {
     const renderInput = deriveRenderInput(data);
     if (!renderInput)
         return null;
-    const cleanFormat = isCleanResponseFormat();
+    const cleanFormat = env_flags_js_1.CLEAN_RESPONSE_FORMAT;
     const { response, lifecycle, contentEnvelope } = renderInput;
     const references = renderReferencesSection(contentEnvelope, lifecycle);
     if (cleanFormat) {

package/dist/mcp/validation/schema-introspection.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+export declare function getCachedShape(schema: z.ZodObject<z.ZodRawShape>): z.ZodRawShape;
 export declare function extractExpectedKeys(schema: z.ZodType): readonly string[];
 export declare function extractRequiredKeys(schema: z.ZodType): readonly string[];
 export declare function findUnknownKeys(args: unknown, schema: z.ZodType): readonly string[];

package/dist/mcp/validation/schema-introspection.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedShape = getCachedShape;
 exports.extractExpectedKeys = extractExpectedKeys;
 exports.extractRequiredKeys = extractRequiredKeys;
 exports.findUnknownKeys = findUnknownKeys;
@@ -8,9 +9,18 @@ exports.generateExampleValue = generateExampleValue;
 exports.generateTemplate = generateTemplate;
 exports.extractEnumValues = extractEnumValues;
 const zod_1 = require("zod");
+const shapeCache = new WeakMap();
+function getCachedShape(schema) {
+    const cached = shapeCache.get(schema);
+    if (cached !== undefined)
+        return cached;
+    const shape = schema._def.shape();
+    shapeCache.set(schema, shape);
+    return shape;
+}
 function extractExpectedKeys(schema) {
     if (schema instanceof zod_1.z.ZodObject) {
-        return Object.keys(schema._def.shape());
+        return Object.keys(getCachedShape(schema));
     }
     return [];
 }
@@ -18,7 +28,7 @@ function extractRequiredKeys(schema) {
     if (!(schema instanceof zod_1.z.ZodObject)) {
         return [];
     }
-    const shape = schema._def.shape();
+    const shape = getCachedShape(schema);
     const required = [];
     for (const [key, value] of Object.entries(shape)) {
         const field = value;
@@ -55,7 +65,7 @@ function generateExampleValue(schema, depth = 0, maxDepth = 3, includeOptional =
         return generateExampleValue(schema._def.innerType, depth, maxDepth, includeOptional);
     }
     if (schema instanceof zod_1.z.ZodObject) {
-        const shape = schema._def.shape();
+        const shape = getCachedShape(schema);
         const result = {};
         for (const [key, value] of Object.entries(shape)) {
             const field = value;
@@ -124,7 +134,7 @@ function extractEnumValues(schema, path) {
     let current = schema;
     for (const part of parts) {
         if (current instanceof zod_1.z.ZodObject) {
-            const shape = current._def.shape();
+            const shape = getCachedShape(current);
             const field = shape[part];
             if (!field)
                 return [];
@@ -133,7 +143,7 @@ function extractEnumValues(schema, path) {
         else if (current instanceof zod_1.z.ZodOptional) {
             current = current._def.innerType;
             if (current instanceof zod_1.z.ZodObject) {
-                const shape = current._def.shape();
+                const shape = getCachedShape(current);
                 const field = shape[part];
                 if (!field)
                     return [];

package/dist/mcp/validation/suggestion-generator.js

@@ -38,7 +38,7 @@ function generateMissingRequiredSuggestions(missingKeys, schema, config) {
     if (!(schema instanceof zod_1.z.ZodObject)) {
         return [];
     }
-    const shape = schema._def.shape();
+    const shape = (0, schema_introspection_js_1.getCachedShape)(schema);
     const suggestions = [];
     for (const key of missingKeys) {
         const field = shape[key];
@@ -118,7 +118,7 @@ function patchTemplateForFailedOptionals(correctTemplate, args, zodErrors, schem
     if (args === null || typeof args !== 'object' || Array.isArray(args))
         return correctTemplate;
     const argsObj = args;
-    const shape = schema._def.shape();
+    const shape = (0, schema_introspection_js_1.getCachedShape)(schema);
     const patched = { ...correctTemplate };
     let changed = false;
     for (const error of zodErrors) {

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

@@ -46,7 +46,7 @@ function findAliasFieldConflicts(value, aliasMap) {
 }
 exports.START_WORKFLOW_PROTOCOL = {
     canonicalParams: {
-        required: ['workflowId', 'workspacePath'],
+        required: ['workflowId', 'workspacePath', 'goal'],
         optional: [],
     },
     descriptions: {
@@ -57,11 +57,13 @@ exports.START_WORKFLOW_PROTOCOL = {
                 'Follow the returned step exactly; treat it as the user\'s current instruction.',
                 'When the step is done, call continue_workflow with the returned continueToken.',
                 'Always pass workspacePath. Shared MCP servers cannot safely infer which repo/workspace you mean.',
+                'Always pass goal. A short sentence describing what you are trying to accomplish (e.g. "implement OAuth refresh token rotation").',
                 'Only pass context on later continue_workflow calls if facts changed.',
             ],
             examplePayload: {
                 workflowId: 'coding-task-workflow-agentic',
                 workspacePath: '/Users/you/git/my-project',
+                goal: 'implement OAuth refresh token rotation',
             },
             returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
         },
@@ -72,10 +74,12 @@ exports.START_WORKFLOW_PROTOCOL = {
                 'Execute the returned step exactly as written.',
                 'When the step is complete, call continue_workflow with the returned continueToken.',
                 'Pass workspacePath on every call. Shared MCP servers cannot safely infer the correct workspace.',
+                'Pass goal on every call. A short sentence describing what you are trying to accomplish.',
             ],
             examplePayload: {
                 workflowId: 'coding-task-workflow-agentic',
                 workspacePath: '/Users/you/git/my-project',
+                goal: 'implement OAuth refresh token rotation',
             },
             returns: 'Step instructions plus continueToken and checkpointToken in the structured response.',
         },

package/dist/runtime/adapters/node-process-signals.d.ts

@@ -1,4 +1,5 @@
 import type { ProcessSignal, ProcessSignals } from '../ports/process-signals.js';
 export declare class NodeProcessSignals implements ProcessSignals {
     on(signal: ProcessSignal, handler: () => void | Promise<void>): void;
+    once(signal: ProcessSignal, handler: () => void | Promise<void>): void;
 }

package/dist/runtime/adapters/node-process-signals.js

@@ -7,5 +7,10 @@ class NodeProcessSignals {
             void handler();
         });
     }
+    once(signal, handler) {
+        process.once(signal, () => {
+            void handler();
+        });
+    }
 }
 exports.NodeProcessSignals = NodeProcessSignals;

package/dist/runtime/adapters/noop-process-signals.d.ts

@@ -1,4 +1,5 @@
 import type { ProcessSignal, ProcessSignals } from '../ports/process-signals.js';
 export declare class NoopProcessSignals implements ProcessSignals {
     on(_signal: ProcessSignal, _handler: () => void | Promise<void>): void;
+    once(_signal: ProcessSignal, _handler: () => void | Promise<void>): void;
 }