@exaudeus/workrail 3.5.0 → 3.6.0

package/dist/mcp/handlers/v2-execution/start.js

@@ -24,8 +24,11 @@ const constants_js_1 = require("../../../v2/durable-core/constants.js");
 const index_js_2 = require("./index.js");
 const start_construction_js_1 = require("../../../v2/durable-core/domain/start-construction.js");
 const request_workflow_reader_js_1 = require("../shared/request-workflow-reader.js");
+const step_content_envelope_js_1 = require("../../step-content-envelope.js");
+const v2_workspace_resolution_js_2 = require("../v2-workspace-resolution.js");
+const v2_reference_resolver_js_1 = require("../v2-reference-resolver.js");
 function loadAndPinWorkflow(args) {
-    const { workflowId, workflowReader, crypto, pinnedStore, validationPipelineDeps } = args;
+    const { workflowId, workflowReader, crypto, pinnedStore, validationPipelineDeps, workspacePath, resolvedRootUris } = args;
     return neverthrow_1.ResultAsync.fromPromise(workflowReader.getWorkflowById(workflowId), (e) => ({
         kind: 'precondition_failed',
         message: e instanceof Error ? e.message : String(e),
@@ -59,38 +62,48 @@ function loadAndPinWorkflow(args) {
             });
         }
         const compiled = pipelineOutcome.snapshot;
-        const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(compiled, crypto);
-        if (workflowHashRes.isErr()) {
-            return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
-        }
-        const workflowHash = workflowHashRes.value;
-        return pinnedStore.get(workflowHash)
-            .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
-            .andThen((existingPinned) => {
-            if (!existingPinned) {
-                return pinnedStore.put(workflowHash, compiled)
-                    .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }));
+        const bindingBaseDir = (0, v2_workspace_resolution_js_2.resolveBindingBaseDir)(workspacePath, resolvedRootUris ?? []);
+        return enrichPinnedSnapshotWithResolvedReferences(compiled, workflow.definition.references ?? [], bindingBaseDir)
+            .andThen(({ snapshot: enrichedCompiled, resolvedReferences }) => {
+            const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(enrichedCompiled, crypto);
+            if (workflowHashRes.isErr()) {
+                return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
             }
-            return (0, neverthrow_1.okAsync)(undefined);
-        })
-            .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })))
-            .andThen((pinned) => {
-            if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
-                return (0, neverthrow_1.errAsync)({
-                    kind: 'invariant_violation',
-                    message: 'Failed to pin executable workflow snapshot (missing or invalid pinned workflow).',
+            const workflowHash = workflowHashRes.value;
+            return pinnedStore.get(workflowHash)
+                .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+                .andThen((existingPinned) => {
+                if (!existingPinned) {
+                    return pinnedStore.put(workflowHash, enrichedCompiled)
+                        .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }));
+                }
+                return (0, neverthrow_1.okAsync)(undefined);
+            })
+                .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })))
+                .andThen((pinned) => {
+                if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
+                    return (0, neverthrow_1.errAsync)({
+                        kind: 'invariant_violation',
+                        message: 'Failed to pin executable workflow snapshot (missing or invalid pinned workflow).',
+                    });
+                }
+                const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+                const resolution = (0, start_construction_js_1.resolveFirstStep)(workflow, pinned);
+                if (resolution.isErr()) {
+                    const error = resolution.error.reason === 'no_steps'
+                        ? { kind: 'workflow_has_no_steps', workflowId: (0, index_js_1.asWorkflowId)(resolution.error.detail) }
+                        : { kind: 'invariant_violation', message: resolution.error.detail };
+                    return (0, neverthrow_1.errAsync)(error);
+                }
+                const firstStep = resolution.value;
+                return (0, neverthrow_1.okAsync)({
+                    workflow,
+                    firstStep,
+                    workflowHash,
+                    pinnedWorkflow,
+                    resolvedReferences: pinned.resolvedReferences ?? resolvedReferences,
                 });
-            }
-            const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
-            const resolution = (0, start_construction_js_1.resolveFirstStep)(workflow, pinned);
-            if (resolution.isErr()) {
-                const error = resolution.error.reason === 'no_steps'
-                    ? { kind: 'workflow_has_no_steps', workflowId: (0, index_js_1.asWorkflowId)(resolution.error.detail) }
-                    : { kind: 'invariant_violation', message: resolution.error.detail };
-                return (0, neverthrow_1.errAsync)(error);
-            }
-            const firstStep = resolution.value;
-            return (0, neverthrow_1.okAsync)({ workflow, firstStep, workflowHash, pinnedWorkflow });
+            });
         });
     });
 }
@@ -215,8 +228,10 @@ function executeStartWorkflow(input, ctx) {
         crypto,
         pinnedStore,
         validationPipelineDeps,
+        workspacePath: input.workspacePath,
+        resolvedRootUris: ctx.v2.resolvedRootUris,
     })
-        .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
+        .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences }) => {
         const anchorsRA = (0, v2_workspace_resolution_js_1.resolveWorkspaceAnchors)(ctx.v2, input.workspacePath)
             .map((anchors) => (0, observation_builder_js_1.anchorsToObservations)(anchors));
         return anchorsRA.andThen((observations) => {
@@ -265,11 +280,11 @@ function executeStartWorkflow(input, ctx) {
                     snapshotPins: [{ snapshotRef, eventIndex: 2, createdByEventId: events[2].eventId }],
                 }))
                     .mapErr((cause) => ({ kind: 'session_append_failed', cause }))
-                    .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, sessionId, runId, nodeId }));
+                    .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences, sessionId, runId, nodeId }));
             });
         });
     })
-        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId }) => {
+        .andThen(({ pinnedWorkflow, firstStep, workflowHash, sessionId, runId, nodeId, resolvedReferences }) => {
         const wfRefRes = (0, workflow_hash_ref_js_1.deriveWorkflowHashRef)(workflowHash);
         if (wfRefRes.isErr()) {
             return (0, neverthrow_1.errAsync)({
@@ -308,7 +323,11 @@ function executeStartWorkflow(input, ctx) {
             const pending = (0, output_schemas_js_1.toPendingStep)(meta);
             const preferences = v2_execution_helpers_js_1.defaultPreferences;
             const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: false, isComplete: false, pending: meta });
-            return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
+            const contentEnvelope = (0, step_content_envelope_js_1.buildStepContentEnvelope)({
+                meta,
+                references: resolvedReferences,
+            });
+            const parsed = output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
                 continueToken: tokens.continueToken,
                 checkpointToken: tokens.checkpointToken,
                 isComplete: false,
@@ -316,7 +335,26 @@ function executeStartWorkflow(input, ctx) {
                 preferences,
                 nextIntent,
                 nextCall: (0, index_js_2.buildNextCall)({ continueToken: tokens.continueToken, isComplete: false, pending }),
-            }));
+            });
+            return (0, neverthrow_1.okAsync)({ response: parsed, contentEnvelope });
         });
     });
 }
+function enrichPinnedSnapshotWithResolvedReferences(snapshot, references, workspacePath) {
+    if (references.length === 0) {
+        return (0, neverthrow_1.okAsync)({ snapshot, resolvedReferences: [] });
+    }
+    return neverthrow_1.ResultAsync.fromPromise((0, v2_reference_resolver_js_1.resolveWorkflowReferences)(references, workspacePath), () => ({ kind: 'reference_resolution_failed' })).map((result) => {
+        for (const warning of result.warnings) {
+            console.warn(`[workrail:reference-resolution] ${warning.message}`);
+        }
+        const pinnedResolvedReferences = [...result.resolved];
+        return {
+            snapshot: {
+                ...snapshot,
+                resolvedReferences: pinnedResolvedReferences,
+            },
+            resolvedReferences: result.resolved,
+        };
+    });
+}

package/dist/mcp/handlers/v2-execution-helpers.d.ts

@@ -49,6 +49,8 @@ export type StartWorkflowError = {
 } | {
     readonly kind: 'prompt_render_failed';
     readonly message: string;
+} | {
+    readonly kind: 'reference_resolution_failed';
 };
 export type ContinueWorkflowError = {
     readonly kind: 'precondition_failed';

package/dist/mcp/handlers/v2-execution-helpers.js

@@ -52,6 +52,8 @@ function mapStartWorkflowErrorToToolError(e) {
             return mapTokenSigningErrorToToolError(e.cause);
         case 'prompt_render_failed':
             return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', `WorkRail could not render the pending step prompt: ${e.message}`, { suggestion: internalSuggestion('Retry start_workflow.', 'A step referenced by the workflow was not found in the executable definition.') });
+        case 'reference_resolution_failed':
+            return (0, types_js_1.errNotRetryable)('INTERNAL_ERROR', 'WorkRail could not resolve workflow references. This is not caused by your input.', { suggestion: internalSuggestion('Retry start_workflow.', 'Reference resolution encountered an unexpected error.') });
         default:
             const _exhaustive = e;
             return _exhaustive;

package/dist/mcp/handlers/v2-reference-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { WorkflowReference } from '../../types/workflow-definition.js';
+import type { ResolvedReference } from '../step-content-envelope.js';
+export interface ReferenceResolutionWarning {
+    readonly referenceId: string;
+    readonly source: string;
+    readonly message: string;
+}
+export interface ReferenceResolutionResult {
+    readonly resolved: readonly ResolvedReference[];
+    readonly warnings: readonly ReferenceResolutionWarning[];
+}
+export type FileExistsPort = (filePath: string) => Promise<boolean>;
+export declare const defaultFileExists: FileExistsPort;
+export declare function resolveWorkflowReferences(references: readonly WorkflowReference[], workspacePath: string, fileExists?: FileExistsPort): Promise<ReferenceResolutionResult>;

package/dist/mcp/handlers/v2-reference-resolver.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultFileExists = void 0;
+exports.resolveWorkflowReferences = resolveWorkflowReferences;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs/promises"));
+const defaultFileExists = async (filePath) => {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+};
+exports.defaultFileExists = defaultFileExists;
+function getPackageRoot() {
+    const thisDir = __dirname;
+    return path.resolve(thisDir, '..', '..', '..');
+}
+async function resolveWorkflowReferences(references, workspacePath, fileExists = exports.defaultFileExists) {
+    const normalizedWorkspaceBase = path.resolve(workspacePath) + path.sep;
+    const packageRoot = getPackageRoot();
+    const normalizedPackageBase = path.resolve(packageRoot) + path.sep;
+    const entries = await Promise.all(references.map(async (ref) => {
+        const isPackageRef = ref.resolveFrom === 'package';
+        const resolveBase = isPackageRef ? packageRoot : workspacePath;
+        const normalizedBase = isPackageRef ? normalizedPackageBase : normalizedWorkspaceBase;
+        const resolvedPath = path.resolve(resolveBase, ref.source);
+        if (!resolvedPath.startsWith(normalizedBase) && resolvedPath !== path.resolve(resolveBase)) {
+            return { ref, resolvedPath, exists: false, escaped: true, ioError: null };
+        }
+        try {
+            const exists = await fileExists(resolvedPath);
+            return { ref, resolvedPath, exists, escaped: false, ioError: null };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { ref, resolvedPath, exists: false, escaped: false, ioError: message };
+        }
+    }));
+    const resolved = [];
+    const warnings = [];
+    for (const { ref, resolvedPath, exists, escaped, ioError } of entries) {
+        if (escaped) {
+            warnings.push({
+                referenceId: ref.id,
+                source: ref.source,
+                message: `Reference '${ref.id}' source path escapes ${ref.resolveFrom === 'package' ? 'package' : 'workspace'} boundary: ${ref.source}`,
+            });
+        }
+        else if (ioError != null) {
+            warnings.push({
+                referenceId: ref.id,
+                source: ref.source,
+                message: `Reference '${ref.id}' source path could not be checked: ${ioError}`,
+            });
+        }
+        else if (!exists) {
+            warnings.push({
+                referenceId: ref.id,
+                source: ref.source,
+                message: `Reference '${ref.id}' source path does not exist: ${resolvedPath}`,
+            });
+        }
+        const base = {
+            id: ref.id,
+            title: ref.title,
+            source: ref.source,
+            purpose: ref.purpose,
+            authoritative: ref.authoritative,
+            resolveFrom: (ref.resolveFrom ?? 'workspace'),
+        };
+        resolved.push((!escaped && exists)
+            ? { ...base, status: 'resolved', resolvedPath }
+            : { ...base, status: 'unresolved' });
+    }
+    return { resolved, warnings };
+}

package/dist/mcp/handlers/v2-resolve-refs-envelope.d.ts

@@ -0,0 +1,5 @@
+import { ResultAsync as RA } from 'neverthrow';
+import type { WorkflowReference } from '../../types/workflow-definition.js';
+import type { StepMetadata } from '../../v2/durable-core/domain/prompt-renderer.js';
+import { type StepContentEnvelope } from '../step-content-envelope.js';
+export declare function resolveRefsAndBuildEnvelope<E>(meta: StepMetadata, workflowRefs: readonly WorkflowReference[], workspacePath: string, toError: () => E): RA<StepContentEnvelope, E>;

package/dist/mcp/handlers/v2-resolve-refs-envelope.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRefsAndBuildEnvelope = resolveRefsAndBuildEnvelope;
+const neverthrow_1 = require("neverthrow");
+const v2_reference_resolver_js_1 = require("./v2-reference-resolver.js");
+const step_content_envelope_js_1 = require("../step-content-envelope.js");
+function resolveRefsAndBuildEnvelope(meta, workflowRefs, workspacePath, toError) {
+    return neverthrow_1.ResultAsync.fromPromise((0, v2_reference_resolver_js_1.resolveWorkflowReferences)(workflowRefs, workspacePath), toError).andThen((refResult) => {
+        for (const warning of refResult.warnings) {
+            console.warn(`[workrail:reference-resolution] ${warning.message}`);
+        }
+        return (0, neverthrow_1.okAsync)((0, step_content_envelope_js_1.buildStepContentEnvelope)({
+            meta,
+            references: refResult.resolved,
+        }));
+    });
+}

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

@@ -127,11 +127,13 @@ async function handleV2InspectWorkflow(input, ctx) {
             const body = input.mode === 'metadata'
                 ? { schemaVersion: compiled.schemaVersion, sourceKind: compiled.sourceKind, workflowId: compiled.workflowId }
                 : compiled;
+            const references = workflow.definition.references;
             const payload = output_schemas_js_1.V2WorkflowInspectOutputSchema.parse({
                 workflowId: input.workflowId,
                 workflowHash,
                 mode: input.mode,
                 compiled: body,
+                ...(references != null && references.length > 0 ? { references } : {}),
             });
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         });

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

@@ -221,16 +221,54 @@ export declare const V2WorkflowInspectOutputSchema: z.ZodObject<{
     workflowHash: z.ZodString;
     mode: z.ZodEnum<["metadata", "preview"]>;
     compiled: z.ZodType<JsonValue, z.ZodTypeDef, JsonValue>;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        source: z.ZodString;
+        purpose: z.ZodString;
+        authoritative: z.ZodBoolean;
+        resolveFrom: z.ZodOptional<z.ZodEnum<["workspace", "package"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        title: string;
+        source: string;
+        purpose: string;
+        authoritative: boolean;
+        resolveFrom?: "workspace" | "package" | undefined;
+    }, {
+        id: string;
+        title: string;
+        source: string;
+        purpose: string;
+        authoritative: boolean;
+        resolveFrom?: "workspace" | "package" | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
     workflowHash: string;
     mode: "metadata" | "preview";
     compiled: JsonValue;
+    references?: {
+        id: string;
+        title: string;
+        source: string;
+        purpose: string;
+        authoritative: boolean;
+        resolveFrom?: "workspace" | "package" | undefined;
+    }[] | undefined;
 }, {
     workflowId: string;
     workflowHash: string;
     mode: "metadata" | "preview";
     compiled: JsonValue;
+    references?: {
+        id: string;
+        title: string;
+        source: string;
+        purpose: string;
+        authoritative: boolean;
+        resolveFrom?: "workspace" | "package" | undefined;
+    }[] | undefined;
 }>;
 export declare const V2PendingStepSchema: z.ZodObject<{
     stepId: z.ZodString;

package/dist/mcp/output-schemas.js

@@ -63,6 +63,14 @@ exports.V2WorkflowInspectOutputSchema = zod_1.z.object({
     workflowHash: zod_1.z.string().min(1),
     mode: zod_1.z.enum(['metadata', 'preview']),
     compiled: exports.JsonValueSchema,
+    references: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string().min(1),
+        title: zod_1.z.string().min(1),
+        source: zod_1.z.string().min(1),
+        purpose: zod_1.z.string().min(1),
+        authoritative: zod_1.z.boolean(),
+        resolveFrom: zod_1.z.enum(['workspace', 'package']).optional(),
+    })).optional(),
 });
 exports.V2PendingStepSchema = zod_1.z.object({
     stepId: zod_1.z.string().min(1),

package/dist/mcp/render-envelope.d.ts

@@ -0,0 +1,21 @@
+import type { StepContentEnvelope } from './step-content-envelope.js';
+export declare const V2_EXECUTION_LIFECYCLES: readonly ["start", "advance", "rehydrate"];
+export type V2ExecutionResponseLifecycle = (typeof V2_EXECUTION_LIFECYCLES)[number];
+export interface V2ExecutionRenderEnvelope<TResponse> {
+    readonly kind: 'v2_execution_render_envelope';
+    readonly response: TResponse;
+    readonly lifecycle: V2ExecutionResponseLifecycle;
+    readonly contentEnvelope?: StepContentEnvelope;
+}
+export declare function createV2ExecutionRenderEnvelope<TResponse>(args: {
+    readonly response: TResponse;
+    readonly lifecycle: V2ExecutionResponseLifecycle;
+    readonly contentEnvelope?: StepContentEnvelope;
+}): V2ExecutionRenderEnvelope<TResponse>;
+export declare function attachV2ExecutionRenderMetadata<TResponse extends object>(args: {
+    readonly response: TResponse;
+    readonly lifecycle: V2ExecutionResponseLifecycle;
+    readonly contentEnvelope?: StepContentEnvelope;
+}): TResponse;
+export declare function getV2ExecutionRenderEnvelope(value: unknown): V2ExecutionRenderEnvelope<unknown> | null;
+export declare function isV2ExecutionRenderEnvelope(value: unknown): value is V2ExecutionRenderEnvelope<unknown>;

package/dist/mcp/render-envelope.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V2_EXECUTION_LIFECYCLES = void 0;
+exports.createV2ExecutionRenderEnvelope = createV2ExecutionRenderEnvelope;
+exports.attachV2ExecutionRenderMetadata = attachV2ExecutionRenderMetadata;
+exports.getV2ExecutionRenderEnvelope = getV2ExecutionRenderEnvelope;
+exports.isV2ExecutionRenderEnvelope = isV2ExecutionRenderEnvelope;
+exports.V2_EXECUTION_LIFECYCLES = ['start', 'advance', 'rehydrate'];
+const V2_EXECUTION_RENDER_META = Symbol.for('workrail.v2ExecutionRenderMeta');
+function createV2ExecutionRenderEnvelope(args) {
+    return Object.freeze({
+        kind: 'v2_execution_render_envelope',
+        response: args.response,
+        lifecycle: args.lifecycle,
+        ...(args.contentEnvelope != null ? { contentEnvelope: args.contentEnvelope } : {}),
+    });
+}
+const VALID_LIFECYCLES = new Set(exports.V2_EXECUTION_LIFECYCLES);
+function attachV2ExecutionRenderMetadata(args) {
+    Object.defineProperty(args.response, V2_EXECUTION_RENDER_META, {
+        value: Object.freeze({
+            lifecycle: args.lifecycle,
+            ...(args.contentEnvelope != null ? { contentEnvelope: args.contentEnvelope } : {}),
+        }),
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return args.response;
+}
+function getV2ExecutionRenderEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const candidate = value;
+    if (candidate.kind === 'v2_execution_render_envelope' &&
+        'response' in candidate &&
+        typeof candidate.lifecycle === 'string' &&
+        VALID_LIFECYCLES.has(candidate.lifecycle)) {
+        return candidate;
+    }
+    const metadata = Reflect.get(candidate, V2_EXECUTION_RENDER_META);
+    if (metadata == null || !VALID_LIFECYCLES.has(metadata.lifecycle)) {
+        return null;
+    }
+    return createV2ExecutionRenderEnvelope({
+        response: value,
+        lifecycle: metadata.lifecycle,
+        contentEnvelope: metadata.contentEnvelope,
+    });
+}
+function isV2ExecutionRenderEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.kind === 'v2_execution_render_envelope' &&
+        'response' in candidate &&
+        typeof candidate.lifecycle === 'string' &&
+        VALID_LIFECYCLES.has(candidate.lifecycle));
+}

package/dist/mcp/response-supplements.d.ts

@@ -0,0 +1,17 @@
+import type { V2ExecutionResponseLifecycle } from './render-envelope.js';
+export type SupplementKind = 'authority_context' | 'notes_guidance';
+export interface FormattedSupplement {
+    readonly kind: SupplementKind;
+    readonly order: number;
+    readonly text: string;
+}
+export type SupplementDelivery = {
+    readonly mode: 'per_lifecycle';
+} | {
+    readonly mode: 'once_per_session';
+    readonly emitOn: V2ExecutionResponseLifecycle;
+};
+export declare function buildResponseSupplements(args: {
+    readonly lifecycle: V2ExecutionResponseLifecycle;
+    readonly cleanFormat: boolean;
+}): readonly FormattedSupplement[];

package/dist/mcp/response-supplements.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildResponseSupplements = buildResponseSupplements;
+const AUTHORITY_CONTEXT = [
+    'WorkRail is a separate live system the user is actively using to direct this task.',
+    'Treat the main content item from WorkRail as the instruction to follow now.',
+].join('\n');
+const NOTES_GUIDANCE = [
+    'How to write good notes (output.notesMarkdown):',
+    '- Write for a human reader reviewing your work later.',
+    '- Include: what you did and key decisions, what you produced (files, functions, test results, specific numbers), anything notable (risks, open questions, things you deliberately chose NOT to do and why).',
+    '- Use markdown: headings, bullets, bold, code refs. Be specific — file paths, function names, counts.',
+    '- Scope: THIS step only. WorkRail concatenates notes across steps automatically.',
+    '- 10-30 lines is ideal. Too short is worse than too long.',
+    '- Omitting notes will block the step.',
+].join('\n');
+function defineResponseSupplement(spec) {
+    if (spec.delivery.mode === 'once_per_session' &&
+        !spec.lifecycles.includes(spec.delivery.emitOn)) {
+        throw new Error(`Supplement "${spec.kind}" has once_per_session delivery on "${spec.delivery.emitOn}" but that lifecycle is not enabled.`);
+    }
+    return spec;
+}
+function shouldEmitSupplement(spec, lifecycle) {
+    if (!spec.lifecycles.includes(lifecycle))
+        return false;
+    if (spec.delivery.mode === 'per_lifecycle')
+        return true;
+    return spec.delivery.emitOn === lifecycle;
+}
+const CLEAN_RESPONSE_SUPPLEMENTS = [
+    defineResponseSupplement({
+        kind: 'authority_context',
+        order: 10,
+        lifecycles: ['start', 'rehydrate'],
+        delivery: { mode: 'per_lifecycle' },
+        renderText: () => AUTHORITY_CONTEXT,
+    }),
+    defineResponseSupplement({
+        kind: 'notes_guidance',
+        order: 20,
+        lifecycles: ['start', 'rehydrate'],
+        delivery: { mode: 'once_per_session', emitOn: 'start' },
+        renderText: () => NOTES_GUIDANCE,
+    }),
+];
+function buildResponseSupplements(args) {
+    if (!args.cleanFormat)
+        return [];
+    return CLEAN_RESPONSE_SUPPLEMENTS
+        .filter((spec) => shouldEmitSupplement(spec, args.lifecycle))
+        .map((spec) => ({
+        kind: spec.kind,
+        order: spec.order,
+        text: spec.renderText(),
+    }))
+        .sort((left, right) => left.order - right.order);
+}

package/dist/mcp/step-content-envelope.d.ts

@@ -0,0 +1,32 @@
+import type { StepMetadata } from '../v2/durable-core/domain/prompt-renderer.js';
+import type { FormattedSupplement } from './response-supplements.js';
+interface ResolvedReferenceBase {
+    readonly id: string;
+    readonly title: string;
+    readonly source: string;
+    readonly purpose: string;
+    readonly authoritative: boolean;
+    readonly resolveFrom: 'workspace' | 'package';
+}
+export type ResolvedReference = (ResolvedReferenceBase & {
+    readonly status: 'resolved';
+    readonly resolvedPath: string;
+}) | (ResolvedReferenceBase & {
+    readonly status: 'unresolved';
+}) | (ResolvedReferenceBase & {
+    readonly status: 'pinned';
+});
+export interface StepContentEnvelope {
+    readonly stepId: string;
+    readonly title: string;
+    readonly authoredPrompt: string;
+    readonly agentRole?: string;
+    readonly references: readonly ResolvedReference[];
+    readonly supplements: readonly FormattedSupplement[];
+}
+export declare function buildStepContentEnvelope(args: {
+    readonly meta: StepMetadata;
+    readonly references?: readonly ResolvedReference[];
+    readonly supplements?: readonly FormattedSupplement[];
+}): StepContentEnvelope;
+export {};

package/dist/mcp/step-content-envelope.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStepContentEnvelope = buildStepContentEnvelope;
+function buildStepContentEnvelope(args) {
+    return Object.freeze({
+        stepId: args.meta.stepId,
+        title: args.meta.title,
+        authoredPrompt: args.meta.prompt,
+        agentRole: args.meta.agentRole,
+        references: Object.freeze(args.references ?? []),
+        supplements: Object.freeze(args.supplements ?? []),
+    });
+}

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

@@ -1 +1,11 @@
-export declare function formatV2ExecutionResponse(data: unknown): string | null;
+import { type FormattedSupplement } from './response-supplements.js';
+export interface FormattedReferences {
+    readonly kind: 'references';
+    readonly text: string;
+}
+export interface FormattedResponse {
+    readonly primary: string;
+    readonly references?: FormattedReferences;
+    readonly supplements?: readonly FormattedSupplement[];
+}
+export declare function formatV2ExecutionResponse(data: unknown): FormattedResponse | null;