@exaudeus/workrail 3.73.2 → 3.74.1

package/dist/manifest.json

@@ -238,8 +238,8 @@
       "bytes": 31
     },
     "cli-worktrain.js": {
-      "sha256": "ab9815d8a2a571ac8fc4923eb3c1f51fc6e096403d3b75a80cd12d0bfe1858f2",
-      "bytes": 60401
+      "sha256": "fe38aca6a553491f3c9e0bd916cedbcd6a58d5cce230b1f47a52066f0b622851",
+      "bytes": 67617
     },
     "cli.d.ts": {
       "sha256": "43e818adf60173644896298637f47b01d5819b17eda46eaa32d0c7d64724d012",
@@ -473,8 +473,8 @@
       "sha256": "5fe866e54f796975dec5d8ba9983aefd86074db212d3fccd64eed04bc9f0b3da",
       "bytes": 8011
     },
-    "console-ui/assets/index-CfI4I3OX.js": {
-      "sha256": "899505f097e5252239bf07f156eb1affe5c94ecdf8c97f23388fd713565bdaa8",
+    "console-ui/assets/index-BmDxs-a5.js": {
+      "sha256": "8090617babfe49eb6f4b313ee45d13d862eba3ba8c9714ef805cda33918e4f08",
       "bytes": 768234
     },
     "console-ui/assets/index-DHrKiMCf.css": {
@@ -482,7 +482,7 @@
       "bytes": 60673
     },
     "console-ui/index.html": {
-      "sha256": "958b1601100f528545fcd2b4fe9cf4580bfd0a7977f826fce6593af47f90c15d",
+      "sha256": "d7ca1e4d2950572216e245c8a6a5130f8393ed3c961f067d2320202295b18183",
       "bytes": 417
     },
     "console/standalone-console.d.ts": {
@@ -574,8 +574,8 @@
       "bytes": 1198
     },
     "coordinators/pr-review.d.ts": {
-      "sha256": "d46e4923995a0b43aefee25da298b86235fae0ad105e548b3174c0eea9c1f8d0",
-      "bytes": 3947
+      "sha256": "0dba830dd29cd82c58300ca9fdfb4c29d0acd0b257740ce3e65f2360239a106b",
+      "bytes": 4501
     },
     "coordinators/pr-review.js": {
       "sha256": "385baa9e6252dbd84060bb423ce219884d519752f4a6e9f8f04e5f503fa38b67",
@@ -589,6 +589,14 @@
       "sha256": "195953d6c0e28d749407e5e3fb29b963cf14629c03508792a44bf0866f7c9d33",
       "bytes": 1815
     },
+    "coordinators/types.d.ts": {
+      "sha256": "3043520258033bcdf5801ce8af81c8fa01c04573fc158a847addd8ec22f992e7",
+      "bytes": 393
+    },
+    "coordinators/types.js": {
+      "sha256": "d43aa81f5bc89faa359e0f97c814ba25155591ff078fbb9bfd40f8c7c9683230",
+      "bytes": 77
+    },
     "core/error-handler.d.ts": {
       "sha256": "80451f12ac8e185133ec3dc4c57285491a785f27525ed21e729db1da3f61010d",
       "bytes": 1368
@@ -1786,8 +1794,8 @@
       "bytes": 854
     },
     "trigger/coordinator-deps.js": {
-      "sha256": "ade7810cf782d88e58074e75a937de08b350ff2ffae533b563fb37753c7ef49c",
-      "bytes": 15048
+      "sha256": "1b400abbd6158e900d4559c74b9f3069a46b60fd02d046f36e30cc40a58acb51",
+      "bytes": 22626
     },
     "trigger/delivery-action.d.ts": {
       "sha256": "bba98a08e35653304b604cd3ec126374cb731620db27ee2c8d6782d5b5b31207",

package/dist/trigger/coordinator-deps.js

@@ -45,6 +45,102 @@ const infra_js_1 = require("../context-assembly/infra.js");
 function createCoordinatorDeps(deps) {
     const { ctx, execFileAsync, consoleService } = deps;
     let dispatch = null;
+    async function fetchAgentResult(sessionHandle) {
+        const emptyResult = { recapMarkdown: null, artifacts: [] };
+        if (consoleService === null) {
+            return emptyResult;
+        }
+        try {
+            const detailResult = await consoleService.getSessionDetail(sessionHandle);
+            if (detailResult.isErr())
+                return emptyResult;
+            const run = detailResult.value.runs[0];
+            if (!run)
+                return emptyResult;
+            const tipNodeId = run.preferredTipNodeId;
+            if (!tipNodeId)
+                return emptyResult;
+            const allNodeIds = run.nodes
+                .map((n) => n.nodeId)
+                .filter((id) => typeof id === 'string' && id !== '');
+            const nodeIdsToFetch = allNodeIds.length > 0 ? allNodeIds : [tipNodeId];
+            let recap = null;
+            const collectedArtifacts = [];
+            for (const nodeId of nodeIdsToFetch) {
+                try {
+                    const nodeResult = await consoleService.getNodeDetail(sessionHandle, nodeId);
+                    if (nodeResult.isErr())
+                        continue;
+                    if (nodeId === tipNodeId)
+                        recap = nodeResult.value.recapMarkdown;
+                    if (nodeResult.value.artifacts.length > 0)
+                        collectedArtifacts.push(...nodeResult.value.artifacts);
+                }
+                catch {
+                    continue;
+                }
+            }
+            return { recapMarkdown: recap, artifacts: collectedArtifacts };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`[WARN coord:reason=exception handle=${sessionHandle.slice(0, 16)}] fetchAgentResult: ${msg}\n`);
+            return emptyResult;
+        }
+    }
+    async function fetchChildSessionResult(handle, coordinatorSessionId) {
+        if (consoleService === null) {
+            process.stderr.write(`[WARN coord:reason=await_degraded handle=${handle.slice(0, 16)}${coordinatorSessionId ? ' parent=' + coordinatorSessionId.slice(0, 16) : ''}] fetchChildSessionResult: ConsoleService unavailable\n`);
+            return {
+                kind: 'await_degraded',
+                message: 'ConsoleService unavailable -- cannot read child session outcome',
+            };
+        }
+        let runStatus = null;
+        try {
+            const detailResult = await consoleService.getSessionDetail(handle);
+            if (detailResult.isErr()) {
+                process.stderr.write(`[WARN coord:reason=getSessionDetail_failed handle=${handle.slice(0, 16)}] fetchChildSessionResult: ${String(detailResult.error)}\n`);
+                return {
+                    kind: 'failed',
+                    reason: 'error',
+                    message: `Could not read session detail: ${String(detailResult.error)}`,
+                };
+            }
+            const run = detailResult.value.runs[0];
+            runStatus = run?.status ?? null;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`[WARN coord:reason=exception handle=${handle.slice(0, 16)}] fetchChildSessionResult getSessionDetail: ${msg}\n`);
+            return { kind: 'failed', reason: 'error', message: `Exception reading session detail: ${msg}` };
+        }
+        if (runStatus === 'complete' || runStatus === 'complete_with_gaps') {
+            const agentResult = await fetchAgentResult(handle);
+            return {
+                kind: 'success',
+                notes: agentResult.recapMarkdown,
+                artifacts: agentResult.artifacts,
+            };
+        }
+        if (runStatus === 'blocked') {
+            return {
+                kind: 'failed',
+                reason: 'stuck',
+                message: `Child session ${handle.slice(0, 16)} reached blocked state`,
+            };
+        }
+        if (runStatus === null) {
+            return {
+                kind: 'timed_out',
+                message: `Child session ${handle.slice(0, 16)} has no terminal run status (likely timed out)`,
+            };
+        }
+        return {
+            kind: 'timed_out',
+            message: `Child session ${handle.slice(0, 16)} is still in state '${runStatus}' -- awaitSessions may not have been called`,
+        };
+    }
     return {
         setDispatch(fn) {
             if (dispatch !== null) {
@@ -53,11 +149,16 @@ function createCoordinatorDeps(deps) {
             }
             dispatch = fn;
         },
-        spawnSession: async (workflowId, goal, workspace, context, agentConfig) => {
+        spawnSession: async (workflowId, goal, workspace, context, agentConfig, parentSessionId) => {
             if (dispatch === null) {
                 return { kind: 'err', error: 'in-process router not initialized -- coordinator deps not ready' };
             }
-            const startResult = await (0, start_js_1.executeStartWorkflow)({ workflowId, workspacePath: workspace, goal }, ctx, { is_autonomous: 'true', workspacePath: workspace, triggerSource: 'daemon' });
+            const startResult = await (0, start_js_1.executeStartWorkflow)({ workflowId, workspacePath: workspace, goal }, ctx, {
+                is_autonomous: 'true',
+                workspacePath: workspace,
+                triggerSource: 'daemon',
+                ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+            });
             if (startResult.isErr()) {
                 const detail = `${startResult.error.kind}${'message' in startResult.error ? ': ' + startResult.error.message : ''}`;
                 return { kind: 'err', error: `Session creation failed: ${detail}` };
@@ -173,47 +274,113 @@ function createCoordinatorDeps(deps) {
             };
         },
         getAgentResult: async (sessionHandle) => {
-            const emptyResult = { recapMarkdown: null, artifacts: [] };
-            if (consoleService === null) {
-                return emptyResult;
+            return fetchAgentResult(sessionHandle);
+        },
+        getChildSessionResult: async (handle, coordinatorSessionId) => {
+            return fetchChildSessionResult(handle, coordinatorSessionId);
+        },
+        spawnAndAwait: async (workflowId, goal, workspace, opts) => {
+            const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+            const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const coordinatorSessionId = opts?.coordinatorSessionId;
+            const agentConfig = opts?.agentConfig;
+            if (dispatch === null) {
+                return {
+                    kind: 'failed',
+                    reason: 'error',
+                    message: 'spawnAndAwait: in-process router not initialized (setDispatch not called)',
+                };
             }
-            try {
-                const detailResult = await consoleService.getSessionDetail(sessionHandle);
-                if (detailResult.isErr())
-                    return emptyResult;
-                const run = detailResult.value.runs[0];
-                if (!run)
-                    return emptyResult;
-                const tipNodeId = run.preferredTipNodeId;
-                if (!tipNodeId)
-                    return emptyResult;
-                const allNodeIds = run.nodes.map((n) => n.nodeId).filter((id) => typeof id === 'string' && id !== '');
-                const nodeIdsToFetch = allNodeIds.length > 0 ? allNodeIds : [tipNodeId];
-                let recap = null;
-                const collectedArtifacts = [];
-                for (const nodeId of nodeIdsToFetch) {
-                    try {
-                        const nodeResult = await consoleService.getNodeDetail(sessionHandle, nodeId);
-                        if (nodeResult.isErr())
-                            continue;
-                        if (nodeId === tipNodeId) {
-                            recap = nodeResult.value.recapMarkdown;
+            const startResult = await (0, start_js_1.executeStartWorkflow)({ workflowId, workspacePath: workspace, goal }, ctx, {
+                is_autonomous: 'true',
+                workspacePath: workspace,
+                triggerSource: 'daemon',
+                ...(coordinatorSessionId !== undefined ? { parentSessionId: coordinatorSessionId } : {}),
+            });
+            if (startResult.isErr()) {
+                const detail = `${startResult.error.kind}${'message' in startResult.error ? ': ' + startResult.error.message : ''}`;
+                return { kind: 'failed', reason: 'error', message: `Session creation failed: ${detail}` };
+            }
+            const startContinueToken = startResult.value.response.continueToken;
+            let handle;
+            if (!startContinueToken) {
+                handle = workflowId;
+            }
+            else {
+                const tokenResult = await (0, v2_token_ops_js_1.parseContinueTokenOrFail)(startContinueToken, ctx.v2.tokenCodecPorts, ctx.v2.tokenAliasStore);
+                if (tokenResult.isErr()) {
+                    return {
+                        kind: 'failed',
+                        reason: 'error',
+                        message: `Internal error: could not extract session handle from new session: ${tokenResult.error.message}`,
+                    };
+                }
+                handle = tokenResult.value.sessionId;
+                const trigger = {
+                    workflowId,
+                    goal,
+                    workspacePath: workspace,
+                    ...(agentConfig !== undefined ? { agentConfig } : {}),
+                };
+                const r = startResult.value.response;
+                const allocatedSession = {
+                    continueToken: r.continueToken ?? '',
+                    checkpointToken: r.checkpointToken,
+                    firstStepPrompt: r.pending?.prompt ?? '',
+                    isComplete: r.isComplete,
+                    triggerSource: 'daemon',
+                };
+                const source = {
+                    kind: 'pre_allocated',
+                    trigger,
+                    session: allocatedSession,
+                };
+                dispatch(trigger, source);
+            }
+            const awaitResult = await (async () => {
+                const POLL_INTERVAL_MS = 3000;
+                if (consoleService === null) {
+                    return null;
+                }
+                const startMs = Date.now();
+                const pending = new Set([handle]);
+                while (pending.size > 0) {
+                    const elapsed = Date.now() - startMs;
+                    if (elapsed >= timeoutMs)
+                        break;
+                    for (const h of [...pending]) {
+                        try {
+                            const detail = await consoleService.getSessionDetail(h);
+                            if (detail.isErr())
+                                continue;
+                            const run = detail.value.runs[0];
+                            if (!run)
+                                continue;
+                            const status = run.status;
+                            if (status === 'complete' || status === 'complete_with_gaps') {
+                                pending.delete(h);
+                            }
+                            else if (status === 'blocked') {
+                                pending.delete(h);
+                            }
                         }
-                        if (nodeResult.value.artifacts.length > 0) {
-                            collectedArtifacts.push(...nodeResult.value.artifacts);
+                        catch {
+                            pending.delete(h);
                         }
                     }
-                    catch {
-                        continue;
+                    if (pending.size > 0) {
+                        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
                     }
                 }
-                return { recapMarkdown: recap, artifacts: collectedArtifacts };
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                process.stderr.write(`[WARN coord:reason=exception handle=${sessionHandle.slice(0, 16)}] getAgentResult: ${msg}\n`);
-                return emptyResult;
+                return handle;
+            })();
+            if (awaitResult === null) {
+                return {
+                    kind: 'await_degraded',
+                    message: 'ConsoleService unavailable -- cannot await child session outcome',
+                };
             }
+            return fetchChildSessionResult(handle, coordinatorSessionId);
         },
         listOpenPRs: async (workspace) => {
             try {

package/docs/authoring.md

@@ -761,6 +761,28 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 
 
 ## Artifacts and planning surfaces
+### coordinator-result-artifact-schema
+- **Level**: required
+- **Status**: active
+- **Scope**: artifact.coordinator-result
+- **Rule**: When a workflow step signals coordinator phase completion, emit a `wr.coordinator_result` artifact with exactly 4 fields: `outcome` (enum: success|failed|timed_out|await_degraded), `summary` (string), `sessionId` (string), `error` (string|null). No additional fields allowed.
+- **Why**: Coordinators read this artifact to determine whether to proceed, retry, or escalate. Extra fields pollute the schema boundary and break forward compatibility. The 4-field constraint is a hard limit, not a guideline.
+- **Enforced by**: advisory
+
+**Checks**
+- Exactly 4 fields present: outcome, summary, sessionId, error.
+- outcome is one of: success, failed, timed_out, await_degraded.
+- error is string|null -- null when outcome is success, non-null string when outcome is failed.
+- No workflow-specific fields (prUrl, branchName, commitSha, etc.) in wr.coordinator_result. Those belong in workflow-specific artifacts.
+
+**Anti-patterns**
+- Adding prUrl, branchName, or commitSha to wr.coordinator_result
+- Using a free-form notes string instead of the typed outcome enum
+- Omitting sessionId (required for coordinator tracing and console parent-child display)
+
+**Source refs**
+- `src/coordinators/types.ts` (runtime) — ChildSessionResult discriminated union -- the runtime type that wr.coordinator_result maps to.
+
 ### artifact-canonicality
 - **Level**: recommended
 - **Status**: active
@@ -913,6 +935,7 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - `artifact.plan`: Implementation-planning artifacts
 - `artifact.spec`: Behavior/specification artifacts
 - `artifact.verification`: Verification or handoff artifacts
+- `artifact.coordinator-result`: wr.coordinator_result artifact emitted by coordinator-phase workflows to signal phase completion to the coordinator
 - `delegation.context-packet`: Structured context passed to subagents
 - `delegation.result-envelope`: Structured result shape returned by subagents
 - `legacy.patterns`: Older authoring patterns that should now be discouraged or avoided