@exaudeus/workrail 1.4.0 → 1.5.1

package/dist/mcp/handlers/v2-resume.d.ts

@@ -0,0 +1,8 @@
+import type { z } from 'zod';
+import type { V2ResumeSessionInput } from '../v2/tools.js';
+import type { ToolContext, ToolResult } from '../types.js';
+import { V2ResumeSessionOutputSchema } from '../output-schemas.js';
+type ResumeInput = z.infer<typeof V2ResumeSessionInput>;
+type ResumeOutput = z.infer<typeof V2ResumeSessionOutputSchema>;
+export declare function handleV2ResumeSession(input: ResumeInput, ctx: ToolContext): Promise<ToolResult<ResumeOutput>>;
+export {};

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleV2ResumeSession = handleV2ResumeSession;
+const types_js_1 = require("../types.js");
+const output_schemas_js_1 = require("../output-schemas.js");
+const v2_token_ops_js_1 = require("./v2-token-ops.js");
+const index_js_1 = require("../../v2/durable-core/ids/index.js");
+const resume_session_js_1 = require("../../v2/usecases/resume-session.js");
+function anchorValue(anchors, key) {
+    const anchor = anchors.find((a) => a.key === key);
+    return anchor?.value;
+}
+async function handleV2ResumeSession(input, ctx) {
+    const v2 = ctx.v2;
+    if (!v2) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'v2 dependencies not available');
+    }
+    if (!v2.sessionSummaryProvider) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'resume_session requires sessionSummaryProvider port');
+    }
+    let anchors = [];
+    if (v2.workspaceAnchor) {
+        const anchorRes = await v2.workspaceAnchor.resolveAnchors();
+        if (anchorRes.isOk()) {
+            anchors = anchorRes.value;
+        }
+    }
+    const query = {
+        gitHeadSha: input.gitHeadSha ?? anchorValue(anchors, 'git_head_sha'),
+        gitBranch: input.gitBranch ?? anchorValue(anchors, 'git_branch'),
+        freeTextQuery: input.query,
+    };
+    const resumeResult = await (0, resume_session_js_1.resumeSession)(query, v2.sessionSummaryProvider);
+    if (resumeResult.isErr()) {
+        return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `Resume failed: ${resumeResult.error.message}`);
+    }
+    const candidates = resumeResult.value;
+    const outputCandidates = [];
+    for (const candidate of candidates) {
+        const stateTokenRes = (0, v2_token_ops_js_1.signTokenOrErr)({
+            payload: {
+                tokenVersion: 1,
+                tokenKind: 'state',
+                sessionId: candidate.sessionId,
+                runId: (0, index_js_1.asRunId)(candidate.runId),
+                nodeId: (0, index_js_1.asNodeId)(candidate.preferredTipNodeId),
+                workflowHashRef: (0, index_js_1.asWorkflowHashRef)(''),
+            },
+            ports: v2.tokenCodecPorts,
+        });
+        if (stateTokenRes.isErr()) {
+            continue;
+        }
+        outputCandidates.push({
+            sessionId: candidate.sessionId,
+            runId: candidate.runId,
+            stateToken: stateTokenRes.value,
+            snippet: candidate.snippet,
+            whyMatched: [...candidate.whyMatched],
+        });
+    }
+    const output = output_schemas_js_1.V2ResumeSessionOutputSchema.parse({
+        candidates: outputCandidates,
+        totalEligible: candidates.length,
+    });
+    return {
+        type: 'success',
+        data: output,
+    };
+}

package/dist/mcp/handlers/v2-state-conversion.d.ts

@@ -2,7 +2,6 @@ import type { EngineStateV1 } from '../../v2/durable-core/schemas/execution-snap
 import type { ExecutionState } from '../../domain/execution/state.js';
 import type { RunId, NodeId } from '../../v2/durable-core/ids/index.js';
 import type { LoadedSessionTruthV2 } from '../../v2/ports/session-event-log-store.port.js';
-import { createWorkflow } from '../../types/workflow.js';
 export declare function toV1ExecutionState(engineState: EngineStateV1): ExecutionState;
 export declare function convertRunningExecutionStateToEngineState(state: Extract<ExecutionState, {
     kind: 'running';
@@ -18,10 +17,6 @@ export interface StepMetadata {
     readonly prompt: string;
     readonly requireConfirmation: boolean;
 }
-export declare function extractStepMetadata(workflow: ReturnType<typeof createWorkflow>, stepId: string | null, options?: {
-    defaultTitle?: string;
-    defaultPrompt?: string;
-}): StepMetadata;
 export type PreferencesV2 = {
     readonly autonomy: 'guided' | 'full_auto_stop_on_user_deps' | 'full_auto_never_stop';
     readonly riskPolicy: 'conservative' | 'balanced' | 'aggressive';

package/dist/mcp/handlers/v2-state-conversion.js

@@ -5,12 +5,11 @@ exports.toV1ExecutionState = toV1ExecutionState;
 exports.convertRunningExecutionStateToEngineState = convertRunningExecutionStateToEngineState;
 exports.fromV1ExecutionState = fromV1ExecutionState;
 exports.mapWorkflowSourceKind = mapWorkflowSourceKind;
-exports.extractStepMetadata = extractStepMetadata;
 exports.derivePreferencesForNode = derivePreferencesForNode;
 exports.deriveNextIntent = deriveNextIntent;
 const step_instance_key_js_1 = require("../../v2/durable-core/schemas/execution-snapshot/step-instance-key.js");
 const preferences_js_1 = require("../../v2/projections/preferences.js");
-const workflow_js_1 = require("../../types/workflow.js");
+const constants_js_1 = require("../../v2/durable-core/constants.js");
 function toV1ExecutionState(engineState) {
     if (engineState.kind === 'init')
         return { kind: 'init' };
@@ -85,29 +84,11 @@ function mapWorkflowSourceKind(kind) {
     const mapped = workflowSourceKindMap[kind];
     return mapped ?? 'project';
 }
-function extractStepMetadata(workflow, stepId, options) {
-    const resolvedStepId = stepId ?? '';
-    const step = stepId ? (0, workflow_js_1.getStepById)(workflow, stepId) : null;
-    const hasStringProp = (obj, prop) => typeof obj === 'object' &&
-        obj !== null &&
-        prop in obj &&
-        typeof obj[prop] === 'string';
-    const title = hasStringProp(step, 'title')
-        ? String(step.title)
-        : options?.defaultTitle ?? resolvedStepId;
-    const prompt = hasStringProp(step, 'prompt')
-        ? String(step.prompt)
-        : options?.defaultPrompt ?? (stepId ? `Pending step: ${stepId}` : '');
-    const requireConfirmation = typeof step === 'object' && step !== null && 'requireConfirmation' in step
-        ? Boolean(step.requireConfirmation)
-        : false;
-    return { stepId: resolvedStepId, title, prompt, requireConfirmation };
-}
 exports.defaultPreferences = { autonomy: 'guided', riskPolicy: 'conservative' };
 function derivePreferencesForNode(args) {
     const parentByNodeId = {};
     for (const e of args.truth.events) {
-        if (e.kind !== 'node_created')
+        if (e.kind !== constants_js_1.EVENT_KIND.NODE_CREATED)
             continue;
         if (e.scope?.runId !== String(args.runId))
             continue;

package/dist/mcp/handlers/v2-token-ops.d.ts

@@ -36,7 +36,7 @@ export declare function parseCheckpointTokenOrFail(raw: string, ports: TokenCode
 export declare function newAttemptId(idFactory: {
     readonly mintAttemptId: () => AttemptId;
 }): AttemptId;
-export declare function attemptIdForNextNode(parentAttemptId: AttemptId, sha256: Sha256PortV2): AttemptId;
+export declare function attemptIdForNextNode(parentAttemptId: AttemptId, sha256: Sha256PortV2): Result<AttemptId, import('../../v2/durable-core/ids/attempt-id-derivation.js').AttemptIdDerivationError>;
 export declare function signTokenOrErr(args: {
     payload: TokenPayloadV1;
     ports: TokenCodecPorts;

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleV2ListWorkflows = handleV2ListWorkflows;
 exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
+const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
 const output_schemas_js_1 = require("../output-schemas.js");
@@ -20,93 +21,104 @@ async function handleV2ListWorkflows(_input, ctx) {
     if (v2Err)
         return v2Err;
     const { crypto, pinnedStore } = ctx.v2;
-    try {
-        const summaries = await (0, with_timeout_js_1.withTimeout)(ctx.workflowService.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows');
-        const compiled = await Promise.all(summaries.map(async (s) => {
-            const wf = await ctx.workflowService.getWorkflowById(s.id);
-            if (!wf) {
-                return {
-                    workflowId: s.id,
-                    name: s.name,
-                    description: s.description,
-                    version: s.version,
-                    workflowHash: null,
-                    kind: 'workflow',
-                };
-            }
-            const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(wf);
-            const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
-            if (hashRes.isErr()) {
-                return {
-                    workflowId: s.id,
-                    name: s.name,
-                    description: s.description,
-                    version: s.version,
-                    workflowHash: null,
-                    kind: 'workflow',
-                };
-            }
-            const hash = hashRes.value;
-            const existing = await pinnedStore.get(hash).match((v) => v, () => null);
-            if (!existing) {
-                await pinnedStore.put(hash, snapshot).match(() => undefined, () => undefined);
-            }
-            return {
+    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
+        .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(ctx.workflowService.getWorkflowById(s.id), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).andThen((wf) => {
+        if (!wf) {
+            return (0, neverthrow_1.okAsync)({
+                workflowId: s.id,
+                name: s.name,
+                description: s.description,
+                version: s.version,
+                workflowHash: null,
+                kind: 'workflow',
+            });
+        }
+        const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(wf);
+        const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
+        if (hashRes.isErr()) {
+            return (0, neverthrow_1.okAsync)({
                 workflowId: s.id,
                 name: s.name,
                 description: s.description,
                 version: s.version,
-                workflowHash: hash,
+                workflowHash: null,
                 kind: 'workflow',
-            };
+            });
+        }
+        const hash = hashRes.value;
+        return pinnedStore
+            .get(hash)
+            .andThen((existing) => {
+            if (!existing) {
+                return pinnedStore.put(hash, snapshot).map(() => undefined);
+            }
+            return (0, neverthrow_1.okAsync)(undefined);
+        })
+            .map(() => ({
+            workflowId: s.id,
+            name: s.name,
+            description: s.description,
+            version: s.version,
+            workflowHash: hash,
+            kind: 'workflow',
+        }))
+            .orElse(() => (0, neverthrow_1.okAsync)({
+            workflowId: s.id,
+            name: s.name,
+            description: s.description,
+            version: s.version,
+            workflowHash: hash,
+            kind: 'workflow',
         }));
+    }))))
+        .map((compiled) => {
         const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
             workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
         });
         return (0, types_js_1.success)(payload);
-    }
-    catch (err) {
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
-    }
+    })
+        .match((result) => Promise.resolve(result), (err) => Promise.resolve(err));
 }
 async function handleV2InspectWorkflow(input, ctx) {
     const v2Err = requireV2(ctx);
     if (v2Err)
         return v2Err;
     const { crypto, pinnedStore } = ctx.v2;
-    try {
-        const workflow = await (0, with_timeout_js_1.withTimeout)(ctx.workflowService.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow');
+    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
+        .andThen((workflow) => {
         if (!workflow) {
-            return (0, types_js_1.errNotRetryable)('NOT_FOUND', `Workflow not found: ${input.workflowId}`);
+            return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('NOT_FOUND', `Workflow not found: ${input.workflowId}`));
         }
         const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(workflow);
         const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
         if (hashRes.isErr()) {
-            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', hashRes.error.message);
+            return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('INTERNAL_ERROR', hashRes.error.message));
         }
         const workflowHash = hashRes.value;
-        const existing = await pinnedStore.get(workflowHash).match((v) => v, () => null);
-        if (!existing) {
-            const wrote = await pinnedStore.put(workflowHash, snapshot).match(() => ({ ok: true }), (e) => ({ ok: false, error: e }));
-            if (!wrote.ok) {
-                return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', wrote.error.message);
+        return pinnedStore
+            .get(workflowHash)
+            .andThen((existing) => {
+            if (!existing) {
+                return pinnedStore.put(workflowHash, snapshot).map(() => snapshot);
             }
-        }
-        const compiled = (await pinnedStore.get(workflowHash).match((v) => v, () => null)) ?? snapshot;
-        const body = input.mode === 'metadata'
-            ? { schemaVersion: compiled.schemaVersion, sourceKind: compiled.sourceKind, workflowId: compiled.workflowId }
-            : compiled;
-        const payload = output_schemas_js_1.V2WorkflowInspectOutputSchema.parse({
-            workflowId: input.workflowId,
-            workflowHash,
-            mode: input.mode,
-            compiled: body,
+            return (0, neverthrow_1.okAsync)(existing);
+        })
+            .orElse(() => (0, neverthrow_1.okAsync)(snapshot))
+            .map((compiled) => {
+            if (!compiled) {
+                throw new Error('Compiled workflow unexpectedly null');
+            }
+            const body = input.mode === 'metadata'
+                ? { schemaVersion: compiled.schemaVersion, sourceKind: compiled.sourceKind, workflowId: compiled.workflowId }
+                : compiled;
+            const payload = output_schemas_js_1.V2WorkflowInspectOutputSchema.parse({
+                workflowId: input.workflowId,
+                workflowHash,
+                mode: input.mode,
+                compiled: body,
+            });
+            return (0, types_js_1.success)(payload);
         });
-        return (0, types_js_1.success)(payload);
-    }
-    catch (err) {
-        const mapped = (0, error_mapper_js_1.mapUnknownErrorToToolError)(err);
-        return mapped;
-    }
+    })
+        .match((result) => Promise.resolve(result), (err) => Promise.resolve(err));
 }

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

@@ -1067,6 +1067,46 @@ export declare const V2ContinueWorkflowOutputSchema: z.ZodEffects<z.ZodDiscrimin
     retryable?: boolean | undefined;
     retryAckToken?: string | undefined;
 }>;
+export declare const V2ResumeSessionOutputSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        runId: z.ZodString;
+        stateToken: z.ZodString;
+        snippet: z.ZodString;
+        whyMatched: z.ZodArray<z.ZodEnum<["matched_head_sha", "matched_branch", "matched_notes", "matched_workflow_id", "recency_fallback"]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }, {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }>, "many">;
+    totalEligible: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    candidates: {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }[];
+    totalEligible: number;
+}, {
+    candidates: {
+        sessionId: string;
+        runId: string;
+        stateToken: string;
+        snippet: string;
+        whyMatched: ("matched_head_sha" | "matched_branch" | "matched_notes" | "matched_workflow_id" | "recency_fallback")[];
+    }[];
+    totalEligible: number;
+}>;
 export declare const V2CheckpointWorkflowOutputSchema: z.ZodObject<{
     checkpointNodeId: z.ZodString;
     stateToken: z.ZodString;

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.V2CheckpointWorkflowOutputSchema = 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;
+exports.OpenDashboardOutputSchema = exports.ReadSessionSchemaOutputSchema = exports.ReadSessionOutputSchema = exports.UpdateSessionOutputSchema = exports.CreateSessionOutputSchema = exports.V2StartWorkflowOutputSchema = exports.V2CheckpointWorkflowOutputSchema = exports.V2ResumeSessionOutputSchema = 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()]);
@@ -204,6 +204,22 @@ exports.V2ContinueWorkflowOutputSchema = zod_1.z.discriminatedUnion('kind', [
     V2ContinueWorkflowOkSchema,
     V2ContinueWorkflowBlockedSchema,
 ]).refine((data) => (data.pending ? data.ackToken != null : true), { message: 'ackToken is required when a pending step exists' });
+exports.V2ResumeSessionOutputSchema = zod_1.z.object({
+    candidates: zod_1.z.array(zod_1.z.object({
+        sessionId: zod_1.z.string().min(1),
+        runId: zod_1.z.string().min(1),
+        stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),
+        snippet: zod_1.z.string().max(1024),
+        whyMatched: zod_1.z.array(zod_1.z.enum([
+            'matched_head_sha',
+            'matched_branch',
+            'matched_notes',
+            'matched_workflow_id',
+            'recency_fallback',
+        ])),
+    })).max(5),
+    totalEligible: zod_1.z.number().int().min(0),
+});
 exports.V2CheckpointWorkflowOutputSchema = zod_1.z.object({
     checkpointNodeId: zod_1.z.string().min(1),
     stateToken: zod_1.z.string().regex(/^st1[023456789acdefghjklmnpqrstuvwxyz]+$/, 'Invalid stateToken format'),

package/dist/mcp/server.js

@@ -41,6 +41,8 @@ const tokens_js_1 = require("../di/tokens.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 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 handler_factory_js_1 = require("./handler-factory.js");
 const workflow_tool_edition_selector_js_1 = require("./workflow-tool-edition-selector.js");
@@ -87,6 +89,9 @@ async function createToolContext() {
                 base32,
                 bech32m,
             });
+            const dataDir = container_js_1.container.resolve(tokens_js_1.DI.V2.DataDir);
+            const fsPort = container_js_1.container.resolve(tokens_js_1.DI.V2.FileSystem);
+            const directoryListing = new index_js_2.LocalDirectoryListingV2(fsPort);
             v2 = {
                 gate,
                 sessionStore,
@@ -97,6 +102,13 @@ async function createToolContext() {
                 idFactory,
                 tokenCodecPorts,
                 workspaceAnchor: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),
+                dataDir,
+                directoryListing,
+                sessionSummaryProvider: new index_js_3.LocalSessionSummaryProviderV2({
+                    directoryListing,
+                    dataDir,
+                    sessionStore,
+                }),
             };
             console.error('[FeatureFlags] v2 tools enabled');
         }

package/dist/mcp/tool-descriptions.js

@@ -123,6 +123,18 @@ Requires: checkpointToken (from the most recent start_workflow or continue_workf
 Idempotent: calling with the same checkpointToken multiple times is safe and returns the same result.
 
 Returns: checkpointNodeId + a fresh stateToken.`,
+        resume_session: `Find and reconnect to an existing workflow session (WorkRail v2, feature-flagged).
+
+Use this when you need to resume a previously started workflow but don't have the stateToken (e.g., new chat, lost context).
+
+WorkRail ranks sessions using a 5-tier matching algorithm:
+1. Exact git HEAD SHA match
+2. Git branch match (exact or prefix)
+3. Free text match against session notes
+4. Free text match against workflow ID
+5. Recency fallback
+
+Returns: Up to 5 ranked candidates, each with a stateToken you can use with continue_workflow.`,
     },
     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.
@@ -268,5 +280,15 @@ Creates a durable checkpoint without advancing. Use for long-running steps to sa
 Requires: checkpointToken from the most recent response. Idempotent.
 
 Returns: checkpointNodeId + fresh stateToken.`,
+        resume_session: `Find and reconnect to an existing workflow session (WorkRail v2, feature-flagged).
+
+Call this when resuming a workflow without a stateToken. WorkRail ranks sessions deterministically:
+1. Exact git HEAD SHA match (tier 1)
+2. Git branch match (tier 2)
+3. Notes content match (tier 3)
+4. Workflow ID match (tier 4)
+5. Recency (tier 5)
+
+Returns: Up to 5 candidates with stateTokens. Use the best match's stateToken with continue_workflow.`,
     },
 };

package/dist/mcp/tools.js

@@ -87,6 +87,11 @@ exports.WORKFLOW_TOOL_ANNOTATIONS = {
         destructiveHint: false,
         idempotentHint: true,
     },
+    resume_session: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
 };
 exports.WORKFLOW_TOOL_TITLES = {
     discover_workflows: 'Discover Available Workflows',
@@ -99,6 +104,7 @@ exports.WORKFLOW_TOOL_TITLES = {
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
     checkpoint_workflow: 'Checkpoint Workflow (v2)',
+    resume_session: 'Resume Session (v2)',
 };
 exports.CreateSessionInput = zod_1.z.object({
     workflowId: zod_1.z

package/dist/mcp/types/tool-description-types.d.ts

@@ -1,6 +1,6 @@
 export declare const DESCRIPTION_MODES: readonly ["standard", "authoritative"];
 export type DescriptionMode = typeof DESCRIPTION_MODES[number];
-export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow", "checkpoint_workflow"];
+export declare const WORKFLOW_TOOL_NAMES: readonly ["discover_workflows", "preview_workflow", "advance_workflow", "validate_workflow", "get_workflow_schema", "list_workflows", "inspect_workflow", "start_workflow", "continue_workflow", "checkpoint_workflow", "resume_session"];
 export type WorkflowToolName = typeof WORKFLOW_TOOL_NAMES[number];
 export type ToolDescriptionMap = Readonly<Record<WorkflowToolName, string>>;
 export type DescriptionsByMode = Readonly<Record<DescriptionMode, ToolDescriptionMap>>;

package/dist/mcp/types/tool-description-types.js

@@ -18,6 +18,7 @@ exports.WORKFLOW_TOOL_NAMES = [
     'start_workflow',
     'continue_workflow',
     'checkpoint_workflow',
+    'resume_session',
 ];
 function isDescriptionMode(value) {
     return exports.DESCRIPTION_MODES.includes(value);

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

@@ -2,7 +2,7 @@ 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' | 'checkpoint_workflow';
+export type V2WorkflowToolName = 'list_workflows' | 'inspect_workflow' | 'start_workflow' | 'continue_workflow' | 'checkpoint_workflow' | 'resume_session';
 export type McpCallToolResult = {
     readonly content: ReadonlyArray<{
         readonly type: 'text';

package/dist/mcp/types.d.ts

@@ -13,6 +13,9 @@ 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';
+import type { DataDirPortV2 } from '../v2/ports/data-dir.port.js';
+import type { DirectoryListingPortV2 } from '../v2/ports/directory-listing.port.js';
+import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-provider.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -53,6 +56,9 @@ export interface V2Dependencies {
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
     readonly workspaceAnchor?: WorkspaceAnchorPortV2;
+    readonly dataDir?: DataDirPortV2;
+    readonly directoryListing?: DirectoryListingPortV2;
+    readonly sessionSummaryProvider?: SessionSummaryProviderPortV2;
 }
 export interface ToolContext {
     readonly workflowService: WorkflowService;

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

@@ -6,6 +6,7 @@ const tools_js_1 = require("./tools.js");
 const v2_execution_js_1 = require("../handlers/v2-execution.js");
 const v2_workflow_js_1 = require("../handlers/v2-workflow.js");
 const v2_checkpoint_js_1 = require("../handlers/v2-checkpoint.js");
+const v2_resume_js_1 = require("../handlers/v2-resume.js");
 function buildV2ToolRegistry(buildTool) {
     const tools = [
         buildTool({
@@ -38,6 +39,12 @@ function buildV2ToolRegistry(buildTool) {
             inputSchema: tools_js_1.V2CheckpointWorkflowInput,
             annotations: tools_js_1.V2_TOOL_ANNOTATIONS.checkpoint_workflow,
         }),
+        buildTool({
+            name: 'resume_session',
+            title: tools_js_1.V2_TOOL_TITLES.resume_session,
+            inputSchema: tools_js_1.V2ResumeSessionInput,
+            annotations: tools_js_1.V2_TOOL_ANNOTATIONS.resume_session,
+        }),
     ];
     const handlers = {
         list_workflows: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ListWorkflowsInput, v2_workflow_js_1.handleV2ListWorkflows),
@@ -45,6 +52,7 @@ function buildV2ToolRegistry(buildTool) {
         start_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2StartWorkflowInput, v2_execution_js_1.handleV2StartWorkflow),
         continue_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ContinueWorkflowInput, v2_execution_js_1.handleV2ContinueWorkflow),
         checkpoint_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2CheckpointWorkflowInput, v2_checkpoint_js_1.handleV2CheckpointWorkflow),
+        resume_session: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ResumeSessionInput, v2_resume_js_1.handleV2ResumeSession),
     };
     return { tools, handlers };
 }

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

@@ -77,6 +77,20 @@ export declare const V2ContinueWorkflowInput: z.ZodEffects<z.ZodObject<{
     ackToken?: string | undefined;
 }>;
 export type V2ContinueWorkflowInput = z.infer<typeof V2ContinueWorkflowInput>;
+export declare const V2ResumeSessionInput: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    gitBranch: z.ZodOptional<z.ZodString>;
+    gitHeadSha: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    query?: string | undefined;
+    gitBranch?: string | undefined;
+    gitHeadSha?: string | undefined;
+}, {
+    query?: string | undefined;
+    gitBranch?: string | undefined;
+    gitHeadSha?: string | undefined;
+}>;
+export type V2ResumeSessionInput = z.infer<typeof V2ResumeSessionInput>;
 export declare const V2CheckpointWorkflowInput: z.ZodObject<{
     checkpointToken: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -91,5 +105,6 @@ export declare const V2_TOOL_TITLES: {
     readonly start_workflow: "Start Workflow (v2)";
     readonly continue_workflow: "Continue Workflow (v2)";
     readonly checkpoint_workflow: "Checkpoint Workflow (v2)";
+    readonly resume_session: "Resume Session (v2)";
 };
 export declare const V2_TOOL_ANNOTATIONS: Readonly<Record<keyof typeof V2_TOOL_TITLES, ToolAnnotations>>;

package/dist/mcp/v2/tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
+exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
 const zod_1 = require("zod");
 exports.V2ListWorkflowsInput = zod_1.z.object({});
 exports.V2InspectWorkflowInput = zod_1.z.object({
@@ -54,6 +54,11 @@ exports.V2ContinueWorkflowInput = zod_1.z.object({
         });
     }
 });
+exports.V2ResumeSessionInput = zod_1.z.object({
+    query: zod_1.z.string().max(256).optional().describe('Free text search to find a relevant session. Matches against recap notes and workflow IDs.'),
+    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.'),
+}).strict();
 exports.V2CheckpointWorkflowInput = zod_1.z.object({
     checkpointToken: zod_1.z.string().min(1).describe('The checkpoint token from the most recent start_workflow or continue_workflow response. ' +
         'Creates a checkpoint on the current step without advancing. Idempotent — calling with the same token is safe.'),
@@ -64,6 +69,7 @@ exports.V2_TOOL_TITLES = {
     start_workflow: 'Start Workflow (v2)',
     continue_workflow: 'Continue Workflow (v2)',
     checkpoint_workflow: 'Checkpoint Workflow (v2)',
+    resume_session: 'Resume Session (v2)',
 };
 exports.V2_TOOL_ANNOTATIONS = {
     list_workflows: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -71,4 +77,5 @@ exports.V2_TOOL_ANNOTATIONS = {
     start_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     continue_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     checkpoint_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    resume_session: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
 };