@exaudeus/workrail 3.7.0 → 3.7.2

package/README.md

@@ -245,8 +245,12 @@ support [conditions, loops, validation criteria](docs/authoring.md), and more.
 
 - [All Workflows](docs/workflows.md) – Full list with detailed descriptions
 - [Writing Workflows](docs/authoring.md) – Custom workflow creation guide
+- [Workflow Authoring Principles (v2)](docs/authoring-v2.md) – Cross-workflow design rules and authoring principles
 - [Configuration](docs/configuration.md) – Git repos, environment variables, local paths
 - [Advanced Features](docs/advanced.md) – Loops, conditionals, validation
+- **Integrations**
+  - [Claude Code Setup](docs/integrations/claude-code.md) – Complete guide for Desktop & CLI
+  - [Firebender Setup](docs/integrations/firebender.md) – Firebender integration
 
 ---
 

package/dist/manifest.json

@@ -670,8 +670,8 @@
       "bytes": 883
     },
     "mcp/handler-factory.js": {
-      "sha256": "1216fe5e913c832242b3c9c2d9954441300b08660db59fe9deac8a4b7dc583db",
-      "bytes": 5310
+      "sha256": "6eb67d1501582d1cfcf777d7d930a6cf3cb32ccbd450c7083133745ef27d2661",
+      "bytes": 5381
     },
     "mcp/handlers/session.d.ts": {
       "sha256": "38926e69a0e4935d1dbcdc53848be9fff0e4d8f96827883da3216f217918fa82",
@@ -862,8 +862,8 @@
       "bytes": 471
     },
     "mcp/handlers/v2-resume.js": {
-      "sha256": "726f92eb12aa0b28fafc4ceef354500dac7c4f18b85c4fe02a7997f869fe533f",
-      "bytes": 3612
+      "sha256": "780e4611d4fb7d7f7fac8cddf576ada1e9ba752f167a678ebd03d94ee518e298",
+      "bytes": 3828
     },
     "mcp/handlers/v2-state-conversion.d.ts": {
       "sha256": "94bd06904ef58dd210ff17ffb75c2492beea8937eb06d99749e5d860c0e0d96b",
@@ -914,12 +914,12 @@
       "bytes": 7991
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "450ac819bddaf668eb662b8327591df72b68d553fb16a7bd7797fadc68b8b8c8",
-      "bytes": 51526
+      "sha256": "b33bd6e889811ee4de7bd3b4b4fd6d52042cb7a6bdd23c8bd38baa42775e39c3",
+      "bytes": 52320
     },
     "mcp/output-schemas.js": {
-      "sha256": "73c8cd97868afd6f6e6f3deac1a3aabc38384f82c532be91bd5ea6ad2f744a49",
-      "bytes": 13044
+      "sha256": "ba7dda4faec5a8bc1e497b41966b5033ab2930c9cae7b46e85ea1d25b39f79fa",
+      "bytes": 13715
     },
     "mcp/render-envelope.d.ts": {
       "sha256": "22e83e1aba52968a7136cf289125a217b5f462a5a66a1eebe4669006e3326fdb",
@@ -942,8 +942,8 @@
       "bytes": 960
     },
     "mcp/server.js": {
-      "sha256": "1e5faf28495dff31b83b9f86ba07e05e14fb88c757f4e9e3460235f92c0602ab",
-      "bytes": 11642
+      "sha256": "9689ba068eaac9f36f328fa5429b5abe84bb8bd0062f0a59b60dc361dea09cd2",
+      "bytes": 11677
     },
     "mcp/step-content-envelope.d.ts": {
       "sha256": "19bd63c4d4de1d5d93393d346625d28ffd1bebdc320d4ba4e694cb740ec97d3b",
@@ -1058,12 +1058,12 @@
       "bytes": 2674
     },
     "mcp/v2-response-formatter.d.ts": {
-      "sha256": "b0dfb56016eabbc61fdb9d1f668d35c3fba7e8060b70be5aa74356ae0334ff0e",
-      "bytes": 438
+      "sha256": "3dd2bb5beef01afc8dca6b3df8bfd52283dc4393c5d85d2906a56bf4ae9806c9",
+      "bytes": 527
     },
     "mcp/v2-response-formatter.js": {
-      "sha256": "76615380b865b264d8c124231bae44d285ae738a17dc3b7b2ff5906c08eee646",
-      "bytes": 14437
+      "sha256": "f8a8cb5c1fe1b081eca9228a09732dde7247aaf396ff14556cc721c66eee5ab8",
+      "bytes": 21118
     },
     "mcp/v2/tool-registry.d.ts": {
       "sha256": "d4d4927728c3cab1c014661d499dd0119538371bc6c5e821a4cd31df7abebedf",
@@ -1074,12 +1074,12 @@
       "bytes": 3276
     },
     "mcp/v2/tools.d.ts": {
-      "sha256": "8802e914f1eae0cfcd5b9b7838d00a3a87c8416c1ade1fce1ee57e7744bf64b9",
-      "bytes": 7010
+      "sha256": "89fff4db9e2b8f734d7453801fbc404a1518fccafce2a942af6656a6cdc2dc1e",
+      "bytes": 7228
     },
     "mcp/v2/tools.js": {
-      "sha256": "a275de4ce4ccf31d429ce2c32f86169485676aad6f41cfe9babc3f00df2495a1",
-      "bytes": 8838
+      "sha256": "c8bfc63a04911d44f13e62c0d9357dacf62ec437dd21f5b6f09c289a973687cb",
+      "bytes": 9406
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",
@@ -1150,8 +1150,8 @@
       "bytes": 1863
     },
     "mcp/workflow-protocol-contracts.js": {
-      "sha256": "715cf1dfa780a62b5b5dc08a3da9cbba3d444dc75c1d68db0b5c2ede804c5bd3",
-      "bytes": 12840
+      "sha256": "8da5f9dfb6f87ec12de5f6e925ae25b022a91432c430738bff1ba14fafeb03fb",
+      "bytes": 13357
     },
     "mcp/workflow-tool-edition-selector.d.ts": {
       "sha256": "75194908a89aaf7dc48fb661aea099827e7032ec76daf8f2de91bd59d46764ef",
@@ -1802,7 +1802,7 @@
       "bytes": 3397
     },
     "v2/durable-core/schemas/export-bundle/index.d.ts": {
-      "sha256": "a0c0c9c904b11e79f403bec154e118583709d1440916b7e30b1f3101b87acbf2",
+      "sha256": "6521642cefd019f75dba36890b71c20c5508e04baef584a09557a4b98f894321",
       "bytes": 479848
     },
     "v2/durable-core/schemas/export-bundle/index.js": {
@@ -1882,7 +1882,7 @@
       "bytes": 715
     },
     "v2/durable-core/schemas/session/manifest.d.ts": {
-      "sha256": "3eff60c200f81c87bb0e0946ba23000bc30fdd98678d316e5a401c189612408b",
+      "sha256": "82840f71d8cde0d10834fe411c9ea494e043af93637c4ffb9c14fdf27bbb1b8c",
       "bytes": 1594
     },
     "v2/durable-core/schemas/session/manifest.js": {
@@ -1938,7 +1938,7 @@
       "bytes": 4205
     },
     "v2/durable-core/tokens/payloads.d.ts": {
-      "sha256": "f0428631b6addaa4c842a1abb4d9e4b1f26cb647b6f42a99060114ccb64eab28",
+      "sha256": "4b84627aeee7c8f6d4c142e9ffb3511674d74d012601731d81193dfd6b95ba1c",
       "bytes": 6921
     },
     "v2/durable-core/tokens/payloads.js": {
@@ -2114,12 +2114,12 @@
       "bytes": 28456
     },
     "v2/infra/local/session-summary-provider/index.d.ts": {
-      "sha256": "59db8bf5e38f983eedd21ff902a24324f7bedbb5f3eade1e4b0d5742b28447c2",
-      "bytes": 1004
+      "sha256": "291d1303ef9f1ee0889830c5b42964a2d9b8c7d27b36a9b55d710ca5950c32ca",
+      "bytes": 1136
     },
     "v2/infra/local/session-summary-provider/index.js": {
-      "sha256": "1d8a543361c582f6e089f63f24318ff7caf97a78659ecdc5b89152b78d18c6aa",
-      "bytes": 5942
+      "sha256": "93ca7df8ae1ae5e29c29470a6fb947e05b2def481c2b3d8decf4a5dbe8fd8e1c",
+      "bytes": 7611
     },
     "v2/infra/local/sha256/index.d.ts": {
       "sha256": "8a727b7e54a38275ca6f9f1b8730f97cfc0a212df035df1bdc58e716e6824230",
@@ -2386,12 +2386,12 @@
       "bytes": 732
     },
     "v2/projections/resume-ranking.d.ts": {
-      "sha256": "ff128aa669f995b350a1e4ee8da6f0321f999d492e23975816d3f70caefa4dbb",
-      "bytes": 2595
+      "sha256": "5f15f10b632b8e771c74e1f3823616f761be4142493d1142176583e6495528b2",
+      "bytes": 3531
     },
     "v2/projections/resume-ranking.js": {
-      "sha256": "381dbac1868bc88bdfa3e3c13da94b1392ba3858f2bc86cc3c4331e919aac899",
-      "bytes": 4300
+      "sha256": "b9d48c8e08ae8b794771b44fc592158422e832ff64633817fa11093f64282715",
+      "bytes": 6782
     },
     "v2/projections/run-context.d.ts": {
       "sha256": "a4d57470a435ac9860f60b3244d1b828853995027cd510d8da42762d21b2a687",
@@ -2458,12 +2458,12 @@
       "bytes": 77
     },
     "v2/usecases/enumerate-sessions.d.ts": {
-      "sha256": "46da8960bdeb154f79dee443425260f3ce18c50a0db01e7ab60700432d864857",
-      "bytes": 699
+      "sha256": "230eda9e0f377741cb9018edba4b8c26cecde9439e2db68b249b0cab3e9e50aa",
+      "bytes": 809
     },
     "v2/usecases/enumerate-sessions.js": {
-      "sha256": "4ae73f47c1e8ebea0d9a48dc786e5e4d0442a38827c427378712e9d198410ae2",
-      "bytes": 1050
+      "sha256": "7fd54b65e914487ea0cfbc60e7059aa1134b3f9850ae2af0fdba340f9aa0b282",
+      "bytes": 1091
     },
     "v2/usecases/execution-session-gate.d.ts": {
       "sha256": "339c4a8e02a77416e725e063a57d39a20788244498ae2c7a31dc48d111af6280",

package/dist/mcp/handler-factory.js

@@ -14,7 +14,7 @@ function toMcpResult(result) {
     switch (result.type) {
         case 'success': {
             if (!jsonResponsesOverride) {
-                const formatted = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data);
+                const formatted = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data) ?? (0, v2_response_formatter_js_1.formatV2ResumeResponse)(result.data);
                 if (formatted !== null) {
                     const content = [{ type: 'text', text: formatted.primary }];
                     if (formatted.references != null) {

package/dist/mcp/handlers/v2-resume.js

@@ -25,6 +25,8 @@ async function handleV2ResumeSession(input, ctx) {
         gitHeadSha: input.gitHeadSha ?? anchorValue(anchors, 'git_head_sha'),
         gitBranch: input.gitBranch ?? anchorValue(anchors, 'git_branch'),
         freeTextQuery: input.query,
+        runId: input.runId,
+        sessionId: input.sessionId,
     };
     const resumeResult = await (0, resume_session_js_1.resumeSession)(query, v2.sessionSummaryProvider);
     if (resumeResult.isErr()) {
@@ -75,6 +77,9 @@ function mintCandidateTokens(candidates, ports) {
             resumeToken: resumeTokenRes.value,
             snippet: candidate.snippet,
             whyMatched: [...candidate.whyMatched],
+            pendingStepId: candidate.pendingStepId,
+            isComplete: candidate.isComplete,
+            lastModifiedMs: candidate.lastModifiedMs,
             nextCall: {
                 tool: 'continue_workflow',
                 params: { continueToken: resumeTokenRes.value, intent: 'rehydrate' },

package/dist/mcp/output-schemas.d.ts

@@ -1162,7 +1162,10 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         workflowId: z.ZodString;
         resumeToken: z.ZodString;
         snippet: z.ZodString;
-        whyMatched: z.ZodArray<z.ZodEnum<["matched_head_sha", "matched_branch", "matched_notes", "matched_workflow_id", "recency_fallback"]>, "many">;
+        pendingStepId: z.ZodNullable<z.ZodString>;
+        isComplete: z.ZodBoolean;
+        lastModifiedMs: z.ZodNullable<z.ZodNumber>;
+        whyMatched: z.ZodArray<z.ZodEnum<["matched_exact_id", "matched_head_sha", "matched_branch", "matched_notes", "matched_notes_partial", "matched_workflow_id", "recency_fallback"]>, "many">;
         nextCall: z.ZodObject<{
             tool: z.ZodLiteral<"continue_workflow">;
             params: z.ZodObject<{
@@ -1190,8 +1193,9 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         workflowId: string;
-        sessionId: string;
         runId: string;
+        sessionId: string;
+        isComplete: boolean;
         nextCall: {
             params: {
                 continueToken: string;
@@ -1201,11 +1205,14 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         };
         resumeToken: string;
         snippet: string;
-        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+        pendingStepId: string | null;
+        lastModifiedMs: number | null;
+        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
     }, {
         workflowId: string;
-        sessionId: string;
         runId: string;
+        sessionId: string;
+        isComplete: boolean;
         nextCall: {
             params: {
                 continueToken: string;
@@ -1215,14 +1222,17 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         };
         resumeToken: string;
         snippet: string;
-        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+        pendingStepId: string | null;
+        lastModifiedMs: number | null;
+        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
     }>, "many">;
     totalEligible: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     candidates: {
         workflowId: string;
-        sessionId: string;
         runId: string;
+        sessionId: string;
+        isComplete: boolean;
         nextCall: {
             params: {
                 continueToken: string;
@@ -1232,14 +1242,17 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         };
         resumeToken: string;
         snippet: string;
-        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+        pendingStepId: string | null;
+        lastModifiedMs: number | null;
+        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
     }[];
     totalEligible: number;
 }, {
     candidates: {
         workflowId: string;
-        sessionId: string;
         runId: string;
+        sessionId: string;
+        isComplete: boolean;
         nextCall: {
             params: {
                 continueToken: string;
@@ -1249,7 +1262,9 @@ export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
         };
         resumeToken: string;
         snippet: string;
-        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+        pendingStepId: string | null;
+        lastModifiedMs: number | null;
+        whyMatched: ("matched_exact_id" | "matched_head_sha" | "matched_branch" | "matched_notes" | "matched_notes_partial" | "matched_workflow_id" | "recency_fallback")[];
     }[];
     totalEligible: number;
 }>;

package/dist/mcp/output-schemas.js

@@ -244,14 +244,21 @@ exports.V2ResumeSessionOutputSchema = zod_1.z.object({
         workflowId: zod_1.z.string().min(1),
         resumeToken: zod_1.z.string().regex(token_patterns_js_1.STATE_TOKEN_PATTERN, 'Invalid resumeToken format'),
         snippet: zod_1.z.string().max(1024),
+        pendingStepId: zod_1.z.string().nullable().describe('The current pending step ID (e.g. "phase-3-implement") if the workflow is in progress. ' +
+            'Null if the workflow is complete or the step could not be determined.'),
+        isComplete: zod_1.z.boolean().describe('Whether the workflow run has completed. Completed sessions are deprioritized in ranking.'),
+        lastModifiedMs: zod_1.z.number().nullable().describe('Filesystem modification time (epoch ms) of the session. Null if unavailable.'),
         whyMatched: zod_1.z.array(zod_1.z.enum([
+            'matched_exact_id',
             'matched_head_sha',
             'matched_branch',
             'matched_notes',
+            'matched_notes_partial',
             'matched_workflow_id',
             'recency_fallback',
         ])).describe('Match signals explaining why this candidate was ranked. ' +
-            'matched_head_sha/branch/notes/workflow_id = strong signal. ' +
+            'matched_exact_id/head_sha/branch/notes = strong signal. ' +
+            'matched_notes_partial = moderate signal (some query words matched). ' +
             'recency_fallback = no strong signal; inspect the snippet before resuming.'),
         nextCall: exports.V2ResumeNextCallSchema,
     })).max(5),

package/dist/mcp/server.js

@@ -129,6 +129,7 @@ async function createToolContext() {
                     directoryListing,
                     dataDir,
                     sessionStore,
+                    snapshotStore,
                 }),
             };
             console.error('[FeatureFlags] v2 tools enabled');

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

@@ -147,17 +147,23 @@ export declare const V2ContinueWorkflowInput: z.ZodEffects<z.ZodEffects<z.ZodObj
 export type V2ContinueWorkflowInput = z.infer<typeof V2ContinueWorkflowInput>;
 export declare const V2ResumeSessionInput: z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
     gitBranch: z.ZodOptional<z.ZodString>;
     gitHeadSha: z.ZodOptional<z.ZodString>;
     workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strict", z.ZodTypeAny, {
     workspacePath?: string | undefined;
     query?: string | undefined;
+    runId?: string | undefined;
+    sessionId?: string | undefined;
     gitBranch?: string | undefined;
     gitHeadSha?: string | undefined;
 }, {
     workspacePath?: string | undefined;
     query?: string | undefined;
+    runId?: string | undefined;
+    sessionId?: string | undefined;
     gitBranch?: string | undefined;
     gitHeadSha?: string | undefined;
 }>;

package/dist/mcp/v2/tools.js

@@ -85,7 +85,12 @@ exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape
 });
 exports.V2ResumeSessionInput = zod_1.z.object({
     query: zod_1.z.string().min(1).max(256).optional().describe('Free text search to find a relevant session. Matches against recap notes and workflow IDs. ' +
+        'Tip: use the user\'s exact words (e.g. "mr ownership", "ACEI-1234"). ' +
         'Without query, only git-context matching runs — the semantic (notes) tier is skipped.'),
+    runId: zod_1.z.string().regex(/^run_[a-z0-9]+$/).optional().describe('Exact run ID to find (e.g. "run_tbi2ag7njfjgc2aitt4qg5eaiq"). ' +
+        'When provided, the matching session is returned as the sole top-priority candidate.'),
+    sessionId: zod_1.z.string().regex(/^sess_[a-zA-Z0-9_]+$/).optional().describe('Exact session ID to find (e.g. "sess_s5o2ieem4mwypoqnn6ztzyyag4"). ' +
+        'When provided, the matching session is returned as the sole top-priority candidate.'),
     gitBranch: zod_1.z.string().max(256).optional().describe('Git branch name to match against session observations. Overrides auto-detected branch.'),
     gitHeadSha: zod_1.z.string().regex(/^[0-9a-f]{40}$/).optional().describe('Git HEAD SHA to match against session observations. Overrides auto-detected HEAD.'),
     workspacePath: zod_1.z.string()

package/dist/mcp/v2-response-formatter.d.ts

@@ -9,3 +9,4 @@ export interface FormattedResponse {
     readonly supplements?: readonly FormattedSupplement[];
 }
 export declare function formatV2ExecutionResponse(data: unknown): FormattedResponse | null;
+export declare function formatV2ResumeResponse(data: unknown): FormattedResponse | null;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatV2ExecutionResponse = formatV2ExecutionResponse;
+exports.formatV2ResumeResponse = formatV2ResumeResponse;
 const render_envelope_js_1 = require("./render-envelope.js");
 const response_supplements_js_1 = require("./response-supplements.js");
 function isV2ExecutionResponse(data) {
@@ -388,3 +389,150 @@ function formatV2Clean(data) {
         primary: formatCleanSuccess(data),
     };
 }
+function isResumeSessionResponse(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const d = data;
+    return (Array.isArray(d.candidates) &&
+        typeof d.totalEligible === 'number' &&
+        !('pending' in d) &&
+        !('nextIntent' in d));
+}
+const WHY_MATCHED_LABELS = {
+    matched_exact_id: 'Exact ID match',
+    matched_head_sha: 'Same git commit (HEAD SHA)',
+    matched_branch: 'Same git branch',
+    matched_notes: 'Query matched session notes',
+    matched_notes_partial: 'Query partially matched session notes',
+    matched_workflow_id: 'Query matched workflow type',
+    recency_fallback: 'No strong match signal (recent session)',
+};
+function formatRelativeTime(epochMs) {
+    const diffMs = Date.now() - epochMs;
+    if (diffMs < 0)
+        return 'just now';
+    const minutes = Math.floor(diffMs / 60000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    const weeks = Math.floor(days / 7);
+    if (weeks < 5)
+        return `${weeks} week${weeks === 1 ? '' : 's'} ago`;
+    const months = Math.floor(days / 30);
+    return `${months} month${months === 1 ? '' : 's'} ago`;
+}
+function formatResumeCandidate(c, index) {
+    const lines = [];
+    const matchLabel = c.whyMatched.map(w => WHY_MATCHED_LABELS[w] ?? w).join(', ');
+    const isWeak = c.whyMatched.every(w => w === 'recency_fallback');
+    const statusTag = c.isComplete ? ' (completed)' : '';
+    lines.push(`### Candidate ${index + 1}: \`${c.workflowId}\`${statusTag}${isWeak ? ' (weak match)' : ''}`);
+    lines.push(`- **Session**: \`${c.sessionId}\``);
+    lines.push(`- **Run**: \`${c.runId}\``);
+    lines.push(`- **Match reason**: ${matchLabel}`);
+    if (c.pendingStepId) {
+        lines.push(`- **Current step**: \`${c.pendingStepId}\``);
+    }
+    else if (c.isComplete) {
+        lines.push('- **Status**: Workflow completed');
+    }
+    if (c.lastModifiedMs != null) {
+        lines.push(`- **Last active**: ${formatRelativeTime(c.lastModifiedMs)}`);
+    }
+    if (c.snippet) {
+        const preview = c.snippet.length > 200 ? c.snippet.slice(0, 200) + '...' : c.snippet;
+        lines.push(`- **Preview**: ${preview.replace(/\n/g, ' ')}`);
+    }
+    else {
+        lines.push('- **Preview**: (no recap notes available)');
+    }
+    if (c.isComplete) {
+        lines.push('');
+        lines.push('> This workflow has already completed. Resuming it will show the final state.');
+    }
+    lines.push('');
+    lines.push('To resume, call `continue_workflow` with:');
+    lines.push('```json');
+    lines.push(JSON.stringify(c.nextCall.params, null, 2));
+    lines.push('```');
+    return lines.join('\n');
+}
+const SEARCH_PARAMS_HELP = [
+    '**To narrow results, call `resume_session` again with any of these parameters:**',
+    '- `query`: Free text keywords from the session (e.g. "mr ownership", "ACEI-1234", "login feature")',
+    '- `runId`: Exact run ID if the user has one (e.g. "run_abc123def456")',
+    '- `sessionId`: Exact session ID if the user has one (e.g. "sess_abc123")',
+    '- `workspacePath`: Absolute path to the workspace (helps match by git branch/commit)',
+].join('\n');
+function formatV2ResumeResponse(data) {
+    if (!isResumeSessionResponse(data))
+        return null;
+    const { candidates, totalEligible } = data;
+    const lines = [];
+    if (candidates.length === 0) {
+        lines.push('## No Resumable Sessions Found');
+        lines.push('');
+        lines.push(`Searched ${totalEligible} session(s) but none matched your query or workspace context.`);
+        lines.push('');
+        lines.push('**What to do**: Ask the user for more details about which session they want to resume. They might know:');
+        lines.push('- A description of what they were working on (pass as `query`)');
+        lines.push('- A run ID or session ID (pass as `runId` or `sessionId`)');
+        lines.push('- Or start a fresh workflow with `start_workflow`.');
+        lines.push('');
+        lines.push(SEARCH_PARAMS_HELP);
+        return { primary: lines.join('\n') };
+    }
+    const hasStrongMatch = candidates.some(c => !c.whyMatched.every(w => w === 'recency_fallback'));
+    const allRecencyFallback = !hasStrongMatch;
+    if (allRecencyFallback) {
+        lines.push('## Recent Workflow Sessions');
+        lines.push('');
+        lines.push(`No specific search criteria matched, so here are the **${candidates.length} most recent** sessions (out of ${totalEligible} total).`);
+        lines.push('');
+        lines.push('**Action required**: Present these to the user and ask which one they want to resume. If none of these are right, ask the user to describe what they were working on so you can search more specifically.');
+        lines.push('');
+        for (let i = 0; i < candidates.length; i++) {
+            lines.push(formatResumeCandidate(candidates[i], i));
+            lines.push('');
+        }
+        if (totalEligible > candidates.length) {
+            lines.push('---');
+            lines.push(`${totalEligible - candidates.length} more session(s) not shown.`);
+            lines.push('');
+        }
+        lines.push(SEARCH_PARAMS_HELP);
+    }
+    else {
+        lines.push('## Resumable Workflow Sessions');
+        lines.push('');
+        lines.push(`Found **${totalEligible}** session(s) total. Showing the top ${candidates.length} ranked by match strength.`);
+        lines.push('');
+        const best = candidates[0];
+        const bestIsExact = best.whyMatched.includes('matched_exact_id');
+        if (bestIsExact) {
+            lines.push(`**Recommendation**: Candidate 1 is an exact ID match. Resume it directly.`);
+        }
+        else {
+            lines.push(`**Recommendation**: Candidate 1 has the strongest match signal. Present the top candidates to the user and let them confirm which one to resume.`);
+        }
+        lines.push('');
+        for (let i = 0; i < candidates.length; i++) {
+            lines.push(formatResumeCandidate(candidates[i], i));
+            lines.push('');
+        }
+        if (totalEligible > candidates.length) {
+            lines.push('---');
+            lines.push(`${totalEligible - candidates.length} more session(s) not shown.`);
+            lines.push('');
+            lines.push(SEARCH_PARAMS_HELP);
+        }
+    }
+    return { primary: lines.join('\n') };
+}

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

@@ -165,42 +165,42 @@ exports.CHECKPOINT_WORKFLOW_PROTOCOL = {
 exports.RESUME_SESSION_PROTOCOL = {
     canonicalParams: {
         required: [],
-        optional: ['query', 'gitBranch', 'gitHeadSha', 'workspacePath'],
+        optional: ['query', 'runId', 'sessionId', '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.',
+            purpose: 'Find and reconnect to an existing WorkRail workflow session. WorkRail is a workflow engine that persists session state across chat conversations. When a user says "resume my workflow", this is the tool to call.',
+            whenToUse: 'Use this when the user wants to resume, continue, or reconnect to a previously started workflow. The user may provide a session ID, run ID, a description of what they were working on, or nothing at all. This tool searches stored sessions and returns the best matches.',
             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.',
+                'If the user provides a run ID (run_...) or session ID (sess_...), pass it as runId or sessionId for an exact match. This is the most reliable way to find a specific session.',
+                'If the user describes what they were working on (e.g. "the mr ownership task"), pass their words as query. This searches session recap notes and workflow IDs for matching keywords.',
+                'Always pass workspacePath (from your system parameters) so WorkRail can also match by git context (branch, commit).',
+                'The response includes ranked candidates with match explanations and ready-to-use continuation templates. Present the top candidates to the user if there is ambiguity.',
+                'To resume a candidate: call continue_workflow with the candidate\'s nextCall.params (continueToken and intent: "rehydrate"). The response will give you the full session context.',
+                'If no candidates match, ask the user for more details or suggest starting a fresh workflow with start_workflow.',
             ],
             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.',
+            returns: 'Up to 5 ranked candidates with match signals, session previews, and ready-to-use continuation templates. The response explains which candidate to pick and exactly how to resume it.',
         },
         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.',
+            purpose: 'Find an existing WorkRail workflow session and reconnect to it. WorkRail persists workflow state across chat conversations. When a user says "resume my workflow", call this tool.',
+            whenToUse: 'Call this when resuming a workflow. The user may provide a run ID, session ID, a description, or nothing.',
             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.',
+                'If the user provides a run ID (run_...) or session ID (sess_...), pass it as runId or sessionId for exact lookup.',
+                'If the user describes their task, pass their words as query to search session notes.',
+                'Always pass workspacePath from your system parameters for git-context matching.',
+                'Present candidates to the user when there is ambiguity. The response explains match strength.',
+                'To resume: call continue_workflow with the chosen candidate\'s nextCall.params (continueToken + intent: "rehydrate").',
+                'If no candidates match, ask for more details or start a fresh workflow.',
             ],
             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.',
+            returns: 'Up to 5 ranked candidates with match signals, previews, and ready-to-use continuation templates.',
         },
     },
 };