@exaudeus/workrail 3.5.0 → 3.6.1

package/README.md

@@ -156,9 +156,12 @@ The agent will find the workflow, start at step 1, and proceed systematically.
 
 - **Lockfile is enforced**: `package-lock.json` is canonical and CI will fail if `npm ci` would modify it. Commit lockfile changes intentionally.
 - **Release authority**: releases are produced by **semantic-release** in GitHub Actions (don’t bump versions/tags locally).
+- **Major releases are approval-gated**: breaking changes become **minor by default** and only become **major** when `WORKRAIL_ALLOW_MAJOR_RELEASE=true`.
 - **Preview a release (dry-run)**:
   - **Locally**: `npx semantic-release --dry-run --no-ci`
-  - **In Actions**: run the **Release (dry-run)** workflow (`.github/workflows/release-dry-run.yml`).
+  - **Locally (major allowed)**: `WORKRAIL_ALLOW_MAJOR_RELEASE=true npx semantic-release --dry-run --no-ci`
+- **In Actions**: run the **Release (dry-run)** workflow (`.github/workflows/release-dry-run.yml`).
+- **Full release policy**: see [`docs/reference/releases.md`](docs/reference/releases.md)
 
 ---
 

package/dist/application/services/validation-engine.js

@@ -562,6 +562,33 @@ let ValidationEngine = ValidationEngine_1 = class ValidationEngine {
                 }
             }
         }
+        if (workflow.definition.references !== undefined) {
+            const seenRefIds = new Set();
+            for (const ref of workflow.definition.references) {
+                if (!ref.id || typeof ref.id !== 'string') {
+                    issues.push(`Workflow reference has missing or empty id`);
+                }
+                else {
+                    if (seenRefIds.has(ref.id)) {
+                        issues.push(`Workflow reference has duplicate id '${ref.id}'`);
+                        suggestions.push('Each workflow reference id must be unique');
+                    }
+                    seenRefIds.add(ref.id);
+                }
+                if (!ref.title || typeof ref.title !== 'string') {
+                    issues.push(`Workflow reference '${ref.id ?? '(unknown)'}' has missing or empty title`);
+                }
+                if (!ref.source || typeof ref.source !== 'string') {
+                    issues.push(`Workflow reference '${ref.id ?? '(unknown)'}' has missing or empty source`);
+                }
+                if (!ref.purpose || typeof ref.purpose !== 'string') {
+                    issues.push(`Workflow reference '${ref.id ?? '(unknown)'}' has missing or empty purpose`);
+                }
+                if (typeof ref.authoritative !== 'boolean') {
+                    issues.push(`Workflow reference '${ref.id ?? '(unknown)'}' has missing or non-boolean authoritative field`);
+                }
+            }
+        }
         const stepIds = new Set();
         for (const step of workflow.definition.steps) {
             if (stepIds.has(step.id)) {
@@ -602,6 +629,29 @@ let ValidationEngine = ValidationEngine_1 = class ValidationEngine {
                     issues.push(`Step '${step.id}' declares multiple prompt sources (prompt, promptBlocks, templateCall) — use exactly one`);
                 }
                 this.collectQuotedJsonValidationMessageWarnings(step, `Step '${step.id}'`, warnings);
+                const typedStepForFragments = step;
+                if (typedStepForFragments.promptFragments !== undefined) {
+                    const seenFragmentIds = new Set();
+                    for (const fragment of typedStepForFragments.promptFragments) {
+                        if (!fragment.id || typeof fragment.id !== 'string') {
+                            issues.push(`Step '${step.id}': promptFragment has missing or empty id`);
+                        }
+                        else {
+                            if (seenFragmentIds.has(fragment.id)) {
+                                issues.push(`Step '${step.id}': promptFragments has duplicate id '${fragment.id}'`);
+                                suggestions.push('Each promptFragment id must be unique within a step');
+                            }
+                            seenFragmentIds.add(fragment.id);
+                        }
+                        if (!fragment.text || typeof fragment.text !== 'string') {
+                            issues.push(`Step '${step.id}': promptFragment '${fragment.id ?? '(unknown)'}' has missing or empty text`);
+                        }
+                        else if (/\{\{wr\./i.test(fragment.text)) {
+                            issues.push(`Step '${step.id}': promptFragment '${fragment.id}' text contains '{{wr.*}}' token — fragments are raw text and do not support token resolution`);
+                            suggestions.push('Move {{wr.*}} tokens to the step prompt or promptBlocks where they are resolved at compile time');
+                        }
+                    }
+                }
                 const callValidation = this.validateStepFunctionCalls(step, workflow.definition.functionDefinitions || []);
                 if (!callValidation.valid) {
                     issues.push(...callValidation.issues.map(i => `Step '${step.id}': ${i}`));

package/dist/config/feature-flags.js

@@ -69,6 +69,14 @@ exports.FEATURE_FLAG_DEFINITIONS = [
         since: '0.9.0',
         stable: true,
     },
+    {
+        key: 'cleanResponseFormat',
+        envVar: 'WORKRAIL_CLEAN_RESPONSE_FORMAT',
+        defaultValue: false,
+        description: 'Use clean response format that removes system scaffolding from step prompts to improve agent authority perception',
+        since: '0.11.0',
+        stable: false,
+    },
 ];
 function parseBoolean(value, defaultValue) {
     if (value === undefined) {

package/dist/engine/engine-factory.js

@@ -52,6 +52,8 @@ function mapStartError(e) {
             return { kind: 'storage_error', message: e.cause.message, code: e.cause.code };
         case 'session_append_failed':
             return { kind: 'session_error', message: e.cause.message, code: e.cause.code };
+        case 'reference_resolution_failed':
+            return { kind: 'internal_error', message: 'WorkRail could not resolve workflow references.' };
     }
 }
 function mapContinueError(e) {
@@ -242,7 +244,7 @@ async function createWorkRailEngine(config = {}) {
             if (result.isErr()) {
                 return (0, types_js_1.engineErr)(mapStartError(result.error));
             }
-            return (0, types_js_1.engineOk)(mapStartOutput(result.value));
+            return (0, types_js_1.engineOk)(mapStartOutput(result.value.response));
         },
         async continueWorkflow(stateToken, ackToken, output, context) {
             const intent = ackToken ? 'advance' : 'rehydrate';
@@ -261,7 +263,7 @@ async function createWorkRailEngine(config = {}) {
             if (result.isErr()) {
                 return (0, types_js_1.engineErr)(mapContinueError(result.error));
             }
-            return (0, types_js_1.engineOk)(mapContinueOutput(result.value));
+            return (0, types_js_1.engineOk)(mapContinueOutput(result.value.response));
         },
         async checkpointWorkflow(checkpointToken) {
             const result = await (0, v2_checkpoint_js_1.executeCheckpoint)({ checkpointToken: (0, types_js_1.unwrapToken)(checkpointToken) }, v2Ctx);

package/dist/manifest.json

@@ -126,8 +126,8 @@
       "bytes": 2122
     },
     "application/services/validation-engine.js": {
-      "sha256": "efbe402b22980383558863abf61bec728604ad81d07d9d48d0a6f52e69fafa3b",
-      "bytes": 37800
+      "sha256": "05edc2d65f29fcdbb0a87738ee575dae06423dbb044d7af6bac56d7dba7dbede",
+      "bytes": 40905
     },
     "application/services/workflow-compiler.d.ts": {
       "sha256": "f51443e1c3e8e079a972dd032e8de3bcde7b82d891e9a3621a6357cc4fc0e30d",
@@ -358,8 +358,8 @@
       "bytes": 1512
     },
     "config/feature-flags.js": {
-      "sha256": "ce45dded930747e989783df453bfea0458f87bf790c8be4a1b0bd9ceac9ac2a5",
-      "bytes": 7374
+      "sha256": "70f945ac04d894134f762f6a6dac856d04583ecb71dad98cc3806641a366cafd",
+      "bytes": 7688
     },
     "core/error-handler.d.ts": {
       "sha256": "80451f12ac8e185133ec3dc4c57285491a785f27525ed21e729db1da3f61010d",
@@ -438,8 +438,8 @@
       "bytes": 213
     },
     "engine/engine-factory.js": {
-      "sha256": "a189ecc0d6c06da36f472c62647f59de05b244e00073d67e7f0965b3537b6ff8",
-      "bytes": 13489
+      "sha256": "07d88be2ab8488615871ae363b9db4fc23caebba8231c8c2aaa2f97da2b18fdd",
+      "bytes": 13658
     },
     "engine/index.d.ts": {
       "sha256": "91e12882c565e96a9809fdf43a0dc0a77fdffdfd562aaf43d2e86e6590ed0b16",
@@ -670,8 +670,8 @@
       "bytes": 883
     },
     "mcp/handler-factory.js": {
-      "sha256": "fc4c13d109dcfbe4ea3b5a9d4118edf7f736c8e8c1a50d6087289c76c3286dfb",
-      "bytes": 4369
+      "sha256": "1216fe5e913c832242b3c9c2d9954441300b08660db59fe9deac8a4b7dc583db",
+      "bytes": 5310
     },
     "mcp/handlers/session.d.ts": {
       "sha256": "38926e69a0e4935d1dbcdc53848be9fff0e4d8f96827883da3216f217918fa82",
@@ -778,12 +778,12 @@
       "bytes": 10680
     },
     "mcp/handlers/v2-execution-helpers.d.ts": {
-      "sha256": "06c8820bb6667d30374733c10e537680ff63acfffa3fc29d7b454f08c6d6918c",
-      "bytes": 5383
+      "sha256": "bf374e9b9cd8bf05947d72f3ee100871fe825773e50ff48452f51ed51ff1ec3c",
+      "bytes": 5439
     },
     "mcp/handlers/v2-execution-helpers.js": {
-      "sha256": "569d7cfe3e3476aea113aa922c9299311e33a2f22952accbc589b98eabd94cf9",
-      "bytes": 19071
+      "sha256": "149aa6e6e643b6f42683d1d1b97ab5dbeade356edb7f6139fef1b64c8937867b",
+      "bytes": 19388
     },
     "mcp/handlers/v2-execution.d.ts": {
       "sha256": "f76cd1bb6a6e25c5a37a1f5b01b1046f4afd41162b620f3be3861509e1fcd1d3",
@@ -810,20 +810,20 @@
       "bytes": 8269
     },
     "mcp/handlers/v2-execution/continue-rehydrate.d.ts": {
-      "sha256": "38c3381de5ae15769d356d21196948a8e1e371e2d062aaacd5c89c10b52a142a",
-      "bytes": 1559
+      "sha256": "f689b374ba48ffda4533e519608acb03c792f8c509c5b5da03c6a5a23729bee9",
+      "bytes": 1763
     },
     "mcp/handlers/v2-execution/continue-rehydrate.js": {
-      "sha256": "e6525294ee20b4a4ec53cadf8fe6c567a64a082987143bb4695bcdc6615e160a",
-      "bytes": 9574
+      "sha256": "4d92f0eed365ca1e8f4076d75bee9511ff45a580a393576bbcce4a46951b3d47",
+      "bytes": 10365
     },
     "mcp/handlers/v2-execution/index.d.ts": {
-      "sha256": "e60e1e0c65e51d101fb06248e882494e6df52762e1d68f5de7081c1cf1ec8bc5",
-      "bytes": 1226
+      "sha256": "2fcb7d3c059a4c79ca66ef0f0b28a0d45dc0e327b45c9ec183a1d1aea78d08d4",
+      "bytes": 1437
     },
     "mcp/handlers/v2-execution/index.js": {
-      "sha256": "b5f67907b27594cb18482e494caaffa89c62bbc7304e5ce6582cb90329286ac6",
-      "bytes": 6731
+      "sha256": "adb91a7f6ca0a8cbe07c32908019b012dc72365da900dda13cbbec2e76ee22e6",
+      "bytes": 7239
     },
     "mcp/handlers/v2-execution/replay.d.ts": {
       "sha256": "bbf97633d7e47af3574a9690a1976bb474ca49cecc08af1d5c07e90f9868036d",
@@ -834,12 +834,28 @@
       "bytes": 8654
     },
     "mcp/handlers/v2-execution/start.d.ts": {
-      "sha256": "6847beabf35eb4c8780a649c99f4f60047c34e7ce7d8295c528d72f0f7d35f2d",
-      "bytes": 3036
+      "sha256": "14e91fa5531c3bbc05fd96157633d7de7cb4ccb8b85dfaad9c077afbe440a145",
+      "bytes": 3422
     },
     "mcp/handlers/v2-execution/start.js": {
-      "sha256": "4f52d3b4dea3e1bdfcdb1057cb925de6293d938a4f1bddc396dc982bebab5ff6",
-      "bytes": 15841
+      "sha256": "593edf798bb1d2d0011ec81e4f170e4f4003b978cd9900fd785b583d15cd1085",
+      "bytes": 18014
+    },
+    "mcp/handlers/v2-reference-resolver.d.ts": {
+      "sha256": "0b1d2640306b6a0c1067ca66bb20e6ec35d291b33dc328a78d5bfa8006394234",
+      "bytes": 756
+    },
+    "mcp/handlers/v2-reference-resolver.js": {
+      "sha256": "5aeabc5d2a078446458d51918f86019895562a1cf7eef99cba19863c6b63d36c",
+      "bytes": 4619
+    },
+    "mcp/handlers/v2-resolve-refs-envelope.d.ts": {
+      "sha256": "daa88ef4cc5ed12cec550b0b6975ede225a6278ca9c2328c755048210ff518bb",
+      "bytes": 471
+    },
+    "mcp/handlers/v2-resolve-refs-envelope.js": {
+      "sha256": "abcd80dd947bef61bfc068027a0ef1af3a3e13bd67aa3bc410efe66670dbdb50",
+      "bytes": 917
     },
     "mcp/handlers/v2-resume.d.ts": {
       "sha256": "d88f6c35bcaf946666c837b72fda3702a2ebab5e478eb90f7b4b672a0e5fa24f",
@@ -870,8 +886,8 @@
       "bytes": 396
     },
     "mcp/handlers/v2-workflow.js": {
-      "sha256": "e869550933484b473ee51e4f66b29324c17213b87f3fc8bbb3e098ffc00d6f88",
-      "bytes": 7034
+      "sha256": "d305d516bd450d409b8658857f7713cfa74299f9ccf85e103057f684fcd7008a",
+      "bytes": 7185
     },
     "mcp/handlers/v2-workspace-resolution.d.ts": {
       "sha256": "dd4de57b4918ebe749cf8c1df70c02bf1effc50932634bae60db53c9a157e872",
@@ -898,12 +914,28 @@
       "bytes": 7991
     },
     "mcp/output-schemas.d.ts": {
-      "sha256": "bb39f2c47db899f5e55da46f268423c20ded9c6ebce7f35aef14c4359f056e2b",
-      "bytes": 50378
+      "sha256": "450ac819bddaf668eb662b8327591df72b68d553fb16a7bd7797fadc68b8b8c8",
+      "bytes": 51526
     },
     "mcp/output-schemas.js": {
-      "sha256": "7a2fa7e0ec17a713314c19fa17edfe56cf8c3882a2046d12ad6d38a68eb5d2e7",
-      "bytes": 12703
+      "sha256": "73c8cd97868afd6f6e6f3deac1a3aabc38384f82c532be91bd5ea6ad2f744a49",
+      "bytes": 13044
+    },
+    "mcp/render-envelope.d.ts": {
+      "sha256": "22e83e1aba52968a7136cf289125a217b5f462a5a66a1eebe4669006e3326fdb",
+      "bytes": 1224
+    },
+    "mcp/render-envelope.js": {
+      "sha256": "137fa6d6a31c86ab27ac8f924493be3e587e96ee0ff35428382c114caa596eca",
+      "bytes": 2403
+    },
+    "mcp/response-supplements.d.ts": {
+      "sha256": "f6b811998ebfe61d77d207caf8d4443f3c4274fea6435121ed7631fffa92642c",
+      "bytes": 626
+    },
+    "mcp/response-supplements.js": {
+      "sha256": "674f63b6fed305148e429d3221a4693902f383c31b83c177e401935ebdcdc2ec",
+      "bytes": 2473
     },
     "mcp/server.d.ts": {
       "sha256": "3260bb40e88c3eca469940f3d7e20f6442c267ea7a189984d5c569924c9e1ef0",
@@ -913,6 +945,14 @@
       "sha256": "1e5faf28495dff31b83b9f86ba07e05e14fb88c757f4e9e3460235f92c0602ab",
       "bytes": 11642
     },
+    "mcp/step-content-envelope.d.ts": {
+      "sha256": "19bd63c4d4de1d5d93393d346625d28ffd1bebdc320d4ba4e694cb740ec97d3b",
+      "bytes": 1171
+    },
+    "mcp/step-content-envelope.js": {
+      "sha256": "7e203c40878c2c1c8ece561a0c0f8d1471edb3c1da42a0a2841854116f3a353d",
+      "bytes": 483
+    },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
       "bytes": 755
@@ -974,8 +1014,8 @@
       "bytes": 59
     },
     "mcp/transports/stdio-entry.js": {
-      "sha256": "f7331ff9cf82d2963c5d509680027e95361058916c04fc16e3092f207afbfaab",
-      "bytes": 3222
+      "sha256": "4829c1b777598cd188a834941cc7644fde3b9b1bc8f166d1c28a2727c81fd731",
+      "bytes": 3702
     },
     "mcp/transports/transport-mode.d.ts": {
       "sha256": "1c59128ab0174bd2a113fff17521e6339ca367f2b8980c2f2c164ec393c10518",
@@ -1018,12 +1058,12 @@
       "bytes": 2674
     },
     "mcp/v2-response-formatter.d.ts": {
-      "sha256": "51d09b828d7dcfa1c82607d4f27030c8913b2c7502ee2fb65c0cfc7618916701",
-      "bytes": 81
+      "sha256": "b0dfb56016eabbc61fdb9d1f668d35c3fba7e8060b70be5aa74356ae0334ff0e",
+      "bytes": 438
     },
     "mcp/v2-response-formatter.js": {
-      "sha256": "8696b360c0b6a586d3118e7009c76ec2c06812940950d75f2a06c2528a673bde",
-      "bytes": 7854
+      "sha256": "76615380b865b264d8c124231bae44d285ae738a17dc3b7b2ff5906c08eee646",
+      "bytes": 14437
     },
     "mcp/v2/tool-registry.d.ts": {
       "sha256": "d4d4927728c3cab1c014661d499dd0119538371bc6c5e821a4cd31df7abebedf",
@@ -1110,8 +1150,8 @@
       "bytes": 1863
     },
     "mcp/workflow-protocol-contracts.js": {
-      "sha256": "8bc9e73b604471bf60de9499c708d7393a82f97917390acc3c14456d9534a77d",
-      "bytes": 11646
+      "sha256": "715cf1dfa780a62b5b5dc08a3da9cbba3d444dc75c1d68db0b5c2ede804c5bd3",
+      "bytes": 12840
     },
     "mcp/workflow-tool-edition-selector.d.ts": {
       "sha256": "75194908a89aaf7dc48fb661aea099827e7032ec76daf8f2de91bd59d46764ef",
@@ -1266,12 +1306,12 @@
       "bytes": 395
     },
     "types/workflow-definition.d.ts": {
-      "sha256": "1a76d084ea7af32c95c2858e8b42fd48002194657a30fe32c446094b42b074a9",
-      "bytes": 4284
+      "sha256": "0ef5f195dfb9783cf0fa73ee9a7523efd56816f6174a530cc24c3cb6468e5ce0",
+      "bytes": 4823
     },
     "types/workflow-definition.js": {
-      "sha256": "de2b3366741898bd187ea6ad5064e131beec33213a8c1d2c8182496880250d79",
-      "bytes": 1863
+      "sha256": "1099b87129abeb986e19d5ec03006eaa83cbed9ab902e2b4401363a9e04b42dc",
+      "bytes": 1995
     },
     "types/workflow-source.d.ts": {
       "sha256": "ee439c36ac3002780837ff393120d08a1c21ef2641421cdf72f0e1449d0211eb",
@@ -1298,12 +1338,12 @@
       "bytes": 6700
     },
     "utils/condition-evaluator.d.ts": {
-      "sha256": "e758a7deefc801e0499ea1696da0ac92bdcc8babf08438b189471193cba61672",
-      "bytes": 566
+      "sha256": "ba0a7fbb2c9a2f5b52bfe8578507f13d304266c02ac8b4d7a21a52741dec975f",
+      "bytes": 586
     },
     "utils/condition-evaluator.js": {
-      "sha256": "e8425e1db73699b67b6f8df890764113e1d5ed08a39f303c3ca25f6701a79525",
-      "bytes": 5302
+      "sha256": "5ea160466959f432576ee55f63d6ef81be977251264855bb9b2f1463209369ba",
+      "bytes": 5570
     },
     "utils/context-size.d.ts": {
       "sha256": "52cbcff69a237491228b075cb5e052567cbe4e9e405475d92a1d0a49f662a75b",
@@ -1449,6 +1489,14 @@
       "sha256": "3015757f6e3d909ee6cefd5734ce62b81f1716779c640f71e0e86a925bbc7345",
       "bytes": 1734
     },
+    "v2/durable-core/domain/context-template-resolver.d.ts": {
+      "sha256": "fe5df7658a41186ff7abb390815c2d961fb07fec76774e544f153f43614d7f4c",
+      "bytes": 161
+    },
+    "v2/durable-core/domain/context-template-resolver.js": {
+      "sha256": "3e46f8c05304a53bcde9799837b21b855c983c5cc33a75d5ef074e019f26059f",
+      "bytes": 990
+    },
     "v2/durable-core/domain/decision-trace-builder.d.ts": {
       "sha256": "bcc7892a25099be88ca92770d98f2e7e232eef007ff8f48001aefe9c08ee876c",
       "bytes": 1742
@@ -1514,12 +1562,12 @@
       "bytes": 942
     },
     "v2/durable-core/domain/prompt-renderer.d.ts": {
-      "sha256": "6bbafe042ad3e6be2043f8d79ffbf4b3e800dbc862427b41e02e7986357a9df5",
-      "bytes": 968
+      "sha256": "0acacb335ea0101f9df823c0513690796edea08f77dc6aef18c6d1988c3cfa48",
+      "bytes": 1175
     },
     "v2/durable-core/domain/prompt-renderer.js": {
-      "sha256": "43a0bce6e074755b5385723f956ce670736d216e8ab47fcbc02bfa3d162dbc3f",
-      "bytes": 14004
+      "sha256": "2ac48cd9cdcecd19bec6bec710e6f45437f68a62df6fac60ce3eff1cdb821b32",
+      "bytes": 18266
     },
     "v2/durable-core/domain/reason-model.d.ts": {
       "sha256": "650fcb2d9969a4e6123cccbd4913f4d57aeab21a19bb907aa1e11f95e5a95089",
@@ -1714,12 +1762,12 @@
       "bytes": 2115
     },
     "v2/durable-core/schemas/compiled-workflow/index.d.ts": {
-      "sha256": "513623689776543a66cf002353b5e8f2fe5b12b3f7df7a45eb8891de09989a66",
-      "bytes": 4415
+      "sha256": "e7adc0105bce4f60f4fc3ecfa158dd623ce09e78fe75ec90d5718197a3f7a301",
+      "bytes": 11821
     },
     "v2/durable-core/schemas/compiled-workflow/index.js": {
-      "sha256": "9530bc6dd70cbfa4c1bfdcf1e9061ff28d83135ec36733ebcccf0c6d5d8559ee",
-      "bytes": 1483
+      "sha256": "67e9ccfbcf6e07d804fe925c6a8b67e5624d655f9564eec44658cb07f38a6486",
+      "bytes": 2750
     },
     "v2/durable-core/schemas/execution-snapshot/blocked-snapshot.d.ts": {
       "sha256": "278fa4bf5b42f7560382bd821ec706151bba0ab8fc7a17118dfcd02824757625",

package/dist/mcp/handler-factory.js

@@ -8,18 +8,35 @@ const index_js_1 = require("./validation/index.js");
 const bounded_json_js_1 = require("./validation/bounded-json.js");
 const v2_execution_helpers_js_1 = require("./handlers/v2-execution-helpers.js");
 const v2_response_formatter_js_1 = require("./v2-response-formatter.js");
+const render_envelope_js_1 = require("./render-envelope.js");
 const jsonResponsesOverride = process.env.WORKRAIL_JSON_RESPONSES === 'true';
 function toMcpResult(result) {
     switch (result.type) {
         case 'success': {
             if (!jsonResponsesOverride) {
-                const nl = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data);
-                if (nl !== null) {
-                    return { content: [{ type: 'text', text: nl }] };
+                const formatted = (0, v2_response_formatter_js_1.formatV2ExecutionResponse)(result.data);
+                if (formatted !== null) {
+                    const content = [{ type: 'text', text: formatted.primary }];
+                    if (formatted.references != null) {
+                        content.push({ type: 'text', text: formatted.references.text });
+                    }
+                    for (const supplement of formatted.supplements ?? []) {
+                        content.push({ type: 'text', text: supplement.text });
+                    }
+                    return { content };
                 }
             }
+            const envelope = (0, render_envelope_js_1.getV2ExecutionRenderEnvelope)(result.data);
+            const responseBody = envelope != null ? envelope.response : result.data;
+            const refs = envelope?.contentEnvelope?.references;
+            const jsonPayload = (refs != null && refs.length > 0)
+                ? { ...responseBody, references: refs }
+                : responseBody;
             return {
-                content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(jsonPayload, null, 2),
+                    }],
             };
         }
         case 'error':

package/dist/mcp/handlers/v2-execution/continue-rehydrate.d.ts

@@ -6,6 +6,11 @@ import type { TokenCodecPorts } from '../../../v2/durable-core/tokens/token-code
 import { ResultAsync as RA } from 'neverthrow';
 import { type ContinueWorkflowError } from '../v2-execution-helpers.js';
 import * as z from 'zod';
+import { type StepContentEnvelope } from '../../step-content-envelope.js';
+export interface RehydrateResult {
+    readonly response: z.infer<typeof V2ContinueWorkflowOutputSchema>;
+    readonly contentEnvelope?: StepContentEnvelope;
+}
 export declare function handleRehydrateIntent(args: {
     readonly input: V2ContinueWorkflowInput;
     readonly sessionId: SessionId;
@@ -22,4 +27,4 @@ export declare function handleRehydrateIntent(args: {
     readonly aliasStore: import('../../../v2/ports/token-alias-store.port.js').TokenAliasStorePortV2;
     readonly entropy: import('../../../v2/ports/random-entropy.port.js').RandomEntropyPortV2;
     readonly resolvedRootUris?: readonly string[];
-}): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;
+}): RA<RehydrateResult, ContinueWorkflowError>;

package/dist/mcp/handlers/v2-execution/continue-rehydrate.js

@@ -18,6 +18,7 @@ const v2_token_ops_js_1 = require("../v2-token-ops.js");
 const v2_state_conversion_js_1 = require("../v2-state-conversion.js");
 const constants_js_1 = require("../../../v2/durable-core/constants.js");
 const index_js_2 = require("./index.js");
+const step_content_envelope_js_1 = require("../../step-content-envelope.js");
 function handleRehydrateIntent(args) {
     const { input, sessionId, runId, nodeId, workflowHashRef, truth, tokenCodecPorts, pinnedStore, snapshotStore, idFactory, aliasStore, entropy, resolvedRootUris } = args;
     const runStarted = truth.events.find((e) => e.kind === constants_js_1.EVENT_KIND.RUN_STARTED && e.scope.runId === String(runId));
@@ -92,7 +93,7 @@ function handleRehydrateIntent(args) {
             if (!pending) {
                 const preferences = (0, v2_execution_helpers_js_1.derivePreferencesOrDefault)({ truth, runId, nodeId });
                 const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: true, isComplete, pending: null });
-                return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                const parsed = output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
                     kind: 'ok',
                     isComplete,
                     pending: null,
@@ -100,7 +101,8 @@ function handleRehydrateIntent(args) {
                     nextIntent,
                     nextCall: null,
                     ...(driftWarnings.length > 0 ? { warnings: driftWarnings } : {}),
-                }));
+                });
+                return (0, neverthrow_1.okAsync)({ response: parsed });
             }
             const attemptId = (0, v2_token_ops_js_1.newAttemptId)(idFactory);
             const entryBase = {
@@ -132,7 +134,11 @@ function handleRehydrateIntent(args) {
                 const meta = metaRes.value;
                 const preferences = (0, v2_execution_helpers_js_1.derivePreferencesOrDefault)({ truth, runId, nodeId });
                 const nextIntent = (0, v2_state_conversion_js_1.deriveNextIntent)({ rehydrateOnly: true, isComplete, pending: meta });
-                return (0, neverthrow_1.okAsync)(output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
+                const contentEnvelope = (0, step_content_envelope_js_1.buildStepContentEnvelope)({
+                    meta,
+                    references: pinned.resolvedReferences ?? buildPinnedReferencesFallback(pinned.definition.references ?? []),
+                });
+                const parsed = output_schemas_js_1.V2ContinueWorkflowOutputSchema.parse({
                     kind: 'ok',
                     continueToken: continueTokenValue,
                     checkpointToken: checkpointTokenValue,
@@ -142,11 +148,23 @@ function handleRehydrateIntent(args) {
                     nextIntent,
                     nextCall: (0, index_js_2.buildNextCall)({ continueToken: continueTokenValue, isComplete, pending: meta }),
                     ...(driftWarnings.length > 0 ? { warnings: driftWarnings } : {}),
-                }));
+                });
+                return (0, neverthrow_1.okAsync)({ response: parsed, contentEnvelope });
             });
         });
     });
 }
+function buildPinnedReferencesFallback(refs) {
+    return refs.map((ref) => ({
+        id: ref.id,
+        title: ref.title,
+        source: ref.source,
+        purpose: ref.purpose,
+        authoritative: ref.authoritative,
+        resolveFrom: (ref.resolveFrom ?? 'workspace'),
+        status: 'pinned',
+    }));
+}
 function detectBindingDriftForSnapshot(pinned, workflowId, baseDir) {
     const pinnedOverrides = pinned.pinnedOverrides ?? pinned.resolvedBindings;
     if (!pinnedOverrides || Object.keys(pinnedOverrides).length === 0)

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

@@ -4,6 +4,11 @@ import { V2ContinueWorkflowOutputSchema } from '../../output-schemas.js';
 import { ResultAsync as RA } from 'neverthrow';
 import { type ContinueWorkflowError } from '../v2-execution-helpers.js';
 import * as z from 'zod';
+import type { StepContentEnvelope } from '../../step-content-envelope.js';
+interface ContinueWorkflowResult {
+    readonly response: z.infer<typeof V2ContinueWorkflowOutputSchema>;
+    readonly contentEnvelope?: StepContentEnvelope;
+}
 type NextCallTemplate = {
     readonly tool: 'continue_workflow';
     readonly params: {
@@ -20,5 +25,5 @@ export declare function buildNextCall(args: {
 }): NextCallTemplate | null;
 export declare function handleV2StartWorkflow(input: V2StartWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
 export declare function handleV2ContinueWorkflow(input: V2ContinueWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
-export declare function executeContinueWorkflow(input: V2ContinueWorkflowInput, ctx: V2ToolContext): RA<z.infer<typeof V2ContinueWorkflowOutputSchema>, ContinueWorkflowError>;
+export declare function executeContinueWorkflow(input: V2ContinueWorkflowInput, ctx: V2ToolContext): RA<ContinueWorkflowResult, ContinueWorkflowError>;
 export {};

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

@@ -15,6 +15,7 @@ const v2_context_budget_js_1 = require("../v2-context-budget.js");
 const start_js_1 = require("./start.js");
 const continue_rehydrate_js_1 = require("./continue-rehydrate.js");
 const continue_advance_js_1 = require("./continue-advance.js");
+const render_envelope_js_1 = require("../../render-envelope.js");
 function buildNextCall(args) {
     if (args.isComplete && !args.pending)
         return null;
@@ -30,13 +31,21 @@ async function handleV2StartWorkflow(input, ctx) {
     const guard = (0, types_js_1.requireV2Context)(ctx);
     if (!guard.ok)
         return guard.error;
-    return (0, start_js_1.executeStartWorkflow)(input, guard.ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapStartWorkflowErrorToToolError)(e));
+    return (0, start_js_1.executeStartWorkflow)(input, guard.ctx).match((result) => (0, types_js_1.success)((0, render_envelope_js_1.attachV2ExecutionRenderMetadata)({
+        response: result.response,
+        lifecycle: 'start',
+        contentEnvelope: result.contentEnvelope,
+    })), (e) => (0, v2_execution_helpers_js_1.mapStartWorkflowErrorToToolError)(e));
 }
 async function handleV2ContinueWorkflow(input, ctx) {
     const guard = (0, types_js_1.requireV2Context)(ctx);
     if (!guard.ok)
         return guard.error;
-    return executeContinueWorkflow(input, guard.ctx).match((payload) => (0, types_js_1.success)(payload), (e) => (0, v2_execution_helpers_js_1.mapContinueWorkflowErrorToToolError)(e));
+    return executeContinueWorkflow(input, guard.ctx).match((result) => (0, types_js_1.success)((0, render_envelope_js_1.attachV2ExecutionRenderMetadata)({
+        response: result.response,
+        lifecycle: input.intent === 'rehydrate' ? 'rehydrate' : 'advance',
+        contentEnvelope: result.contentEnvelope,
+    })), (e) => (0, v2_execution_helpers_js_1.mapContinueWorkflowErrorToToolError)(e));
 }
 function classifyToken(raw) {
     if (raw.startsWith('st_') || raw.startsWith('st1'))
@@ -127,7 +136,8 @@ function executeContinueWorkflow(input, ctx) {
                     sha256,
                     aliasStore: tokenAliasStore,
                     entropy,
-                }));
+                }))
+                    .map((response) => ({ response }));
             });
         }
     }

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

@@ -10,12 +10,19 @@ import { type ValidationPipelineDepsPhase1a } from '../../../application/service
 import { type ObservationEventData } from '../../../v2/durable-core/domain/observation-builder.js';
 import { type StartWorkflowError } from '../v2-execution-helpers.js';
 import * as z from 'zod';
+import { type StepContentEnvelope, type ResolvedReference } from '../../step-content-envelope.js';
+export interface StartWorkflowResult {
+    readonly response: z.infer<typeof V2StartWorkflowOutputSchema>;
+    readonly contentEnvelope: StepContentEnvelope;
+}
 export declare function loadAndPinWorkflow(args: {
     readonly workflowId: string;
     readonly workflowReader: Pick<import('../../../types/storage.js').IWorkflowReader, 'getWorkflowById'>;
     readonly crypto: Sha256PortV2;
     readonly pinnedStore: import('../../../v2/ports/pinned-workflow-store.port.js').PinnedWorkflowStorePortV2;
     readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
+    readonly workspacePath?: string;
+    readonly resolvedRootUris?: readonly string[];
 }): RA<{
     readonly workflow: import('../../../types/workflow.js').Workflow;
     readonly workflowHash: WorkflowHash;
@@ -23,6 +30,7 @@ export declare function loadAndPinWorkflow(args: {
     readonly firstStep: {
         readonly id: string;
     };
+    readonly resolvedReferences: readonly ResolvedReference[];
 }, StartWorkflowError>;
 export declare function buildInitialEvents(args: {
     readonly sessionId: SessionId;
@@ -51,4 +59,4 @@ export declare function mintStartTokens(args: {
     readonly continueToken: string;
     readonly checkpointToken: string;
 }, StartWorkflowError>;
-export declare function executeStartWorkflow(input: import('../../v2/tools.js').V2StartWorkflowInput, ctx: V2ToolContext): RA<z.infer<typeof V2StartWorkflowOutputSchema>, StartWorkflowError>;
+export declare function executeStartWorkflow(input: import('../../v2/tools.js').V2StartWorkflowInput, ctx: V2ToolContext): RA<StartWorkflowResult, StartWorkflowError>;