@exaudeus/workrail 3.35.1 → 3.37.0

package/dist/daemon/workflow-runner.js

@@ -43,6 +43,7 @@ exports.runStartupRecovery = runStartupRecovery;
 exports.makeContinueWorkflowTool = makeContinueWorkflowTool;
 exports.makeCompleteStepTool = makeCompleteStepTool;
 exports.makeBashTool = makeBashTool;
+exports.makeSpawnAgentTool = makeSpawnAgentTool;
 exports.makeReportIssueTool = makeReportIssueTool;
 exports.buildSessionRecap = buildSessionRecap;
 exports.buildSystemPrompt = buildSystemPrompt;
@@ -62,6 +63,7 @@ const index_js_1 = require("../mcp/handlers/v2-execution/index.js");
 const v2_token_ops_js_1 = require("../mcp/handlers/v2-token-ops.js");
 const index_js_2 = require("../v2/durable-core/ids/index.js");
 const node_outputs_js_1 = require("../v2/projections/node-outputs.js");
+const assert_never_js_1 = require("../runtime/assert-never.js");
 const execAsync = (0, node_util_1.promisify)(node_child_process_1.exec);
 const BASH_TIMEOUT_MS = 5 * 60 * 1000;
 const MAX_SESSION_RECAP_NOTES = 3;
@@ -375,6 +377,30 @@ function getSchemas() {
             },
             required: ['filePath', 'content'],
         },
+        SpawnAgentParams: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'ID of the workflow to run in the child session (e.g. "wr.discovery").',
+                },
+                goal: {
+                    type: 'string',
+                    description: 'One-sentence description of what the child session should accomplish.',
+                },
+                workspacePath: {
+                    type: 'string',
+                    description: 'Absolute path to the workspace directory for the child session.',
+                },
+                context: {
+                    type: 'object',
+                    additionalProperties: true,
+                    description: 'Optional initial context variables to pass to the child workflow.',
+                },
+            },
+            required: ['workflowId', 'goal', 'workspacePath'],
+            additionalProperties: false,
+        },
     };
     return _schemas;
 }
@@ -657,6 +683,106 @@ function makeWriteTool(schemas, sessionId, emitter, workrailSessionId) {
         },
     };
 }
+function makeSpawnAgentTool(sessionId, ctx, apiKey, thisWorkrailSessionId, currentDepth, maxDepth, runWorkflowFn, schemas, emitter) {
+    return {
+        name: 'spawn_agent',
+        description: 'Spawn a child WorkRail session to handle a delegated sub-task. ' +
+            'Blocks until the child session completes, then returns the child\'s outcome and notes. ' +
+            'Use this when a step requires delegating a well-defined sub-task to a separate workflow. ' +
+            'IMPORTANT: The parent session\'s time limit (maxSessionMinutes) keeps ticking while the child runs. ' +
+            'Configure the parent with enough time to cover both its own work and the child\'s work. ' +
+            'Returns: { childSessionId, outcome: "success"|"error"|"timeout", notes: string }. ' +
+            'Check outcome before using notes -- on error/timeout, notes contains the error message.',
+        inputSchema: schemas['SpawnAgentParams'],
+        label: 'Spawn Agent',
+        execute: async (_toolCallId, params) => {
+            console.log(`[WorkflowRunner] Tool: spawn_agent sessionId=${sessionId} workflowId=${String(params.workflowId)} depth=${currentDepth}/${maxDepth}`);
+            emitter?.emit({ kind: 'tool_called', sessionId, toolName: 'spawn_agent', summary: `${String(params.workflowId)} depth=${currentDepth}`, ...withWorkrailSession(thisWorkrailSessionId) });
+            if (currentDepth >= maxDepth) {
+                const limitResult = {
+                    childSessionId: null,
+                    outcome: 'error',
+                    notes: `Max spawn depth exceeded (currentDepth=${currentDepth}, maxDepth=${maxDepth}). ` +
+                        `Cannot spawn a child session from this depth. ` +
+                        `Increase agentConfig.maxSubagentDepth if deeper delegation is intentional.`,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(limitResult) }],
+                    details: limitResult,
+                };
+            }
+            const startInput = {
+                workflowId: String(params.workflowId),
+                workspacePath: String(params.workspacePath),
+                goal: String(params.goal),
+            };
+            const startResult = await (0, start_js_1.executeStartWorkflow)(startInput, ctx, { is_autonomous: 'true', workspacePath: String(params.workspacePath), parentSessionId: thisWorkrailSessionId });
+            if (startResult.isErr()) {
+                const errResult = {
+                    childSessionId: null,
+                    outcome: 'error',
+                    notes: `Failed to start child workflow: ${startResult.error.kind} -- ${JSON.stringify(startResult.error)}`,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(errResult) }],
+                    details: errResult,
+                };
+            }
+            let childSessionId = null;
+            const childContinueToken = startResult.value.response.continueToken ?? '';
+            if (childContinueToken) {
+                const decoded = await (0, v2_token_ops_js_1.parseContinueTokenOrFail)(childContinueToken, ctx.v2.tokenCodecPorts, ctx.v2.tokenAliasStore);
+                if (decoded.isOk()) {
+                    childSessionId = decoded.value.sessionId;
+                }
+                else {
+                    console.warn(`[WorkflowRunner] spawn_agent: could not decode childSessionId from continueToken -- ` +
+                        `childSessionId will be null in result. Reason: ${decoded.error.message}`);
+                }
+            }
+            const childResult = await runWorkflowFn({
+                workflowId: String(params.workflowId),
+                goal: String(params.goal),
+                workspacePath: String(params.workspacePath),
+                context: params.context,
+                spawnDepth: currentDepth + 1,
+                parentSessionId: thisWorkrailSessionId,
+                _preAllocatedStartResponse: startResult.value.response,
+            }, ctx, apiKey, undefined, emitter);
+            let resultObj;
+            if (childResult._tag === 'success') {
+                resultObj = {
+                    childSessionId,
+                    outcome: 'success',
+                    notes: childResult.lastStepNotes ?? '(no notes from child session)',
+                };
+            }
+            else if (childResult._tag === 'error') {
+                resultObj = {
+                    childSessionId,
+                    outcome: 'error',
+                    notes: childResult.message,
+                };
+            }
+            else if (childResult._tag === 'timeout') {
+                resultObj = {
+                    childSessionId,
+                    outcome: 'timeout',
+                    notes: childResult.message,
+                };
+            }
+            else {
+                (0, assert_never_js_1.assertNever)(childResult);
+            }
+            console.log(`[WorkflowRunner] spawn_agent completed: sessionId=${sessionId} childSessionId=${childSessionId ?? 'null'} outcome=${resultObj.outcome}`);
+            emitter?.emit({ kind: 'tool_called', sessionId, toolName: 'spawn_agent_complete', summary: `outcome=${resultObj.outcome} child=${childSessionId ?? 'null'}`, ...withWorkrailSession(thisWorkrailSessionId) });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(resultObj) }],
+                details: resultObj,
+            };
+        },
+    };
+}
 async function appendIssueAsync(issuesDir, sessionId, record) {
     await fs.mkdir(issuesDir, { recursive: true });
     const filePath = path.join(issuesDir, `${sessionId}.jsonl`);
@@ -768,11 +894,12 @@ Good pattern: "Question: Should I check the middleware? Answer: The workflow ste
 
 ## Your tools
 - \`complete_step\`: Mark the current step complete and advance to the next one. Call this after completing ALL work required by the step. Include your notes (min 50 characters) in the notes field. The daemon manages the session token internally -- you do NOT need a continueToken. This is the preferred advancement tool for daemon sessions.
-- \`continue_workflow\`: [DEPRECATED -- use complete_step instead] Legacy advancement tool. Requires a continueToken that you must round-trip exactly. Only use this if complete_step is unavailable.
+- \`continue_workflow\`: [DEPRECATED -- use complete_step instead. Do NOT pass a continueToken.] Only use this if complete_step is unavailable.
 - \`Bash\`: Run shell commands. Use for building, testing, running scripts.
 - \`Read\`: Read files.
 - \`Write\`: Write files.
 - \`report_issue\`: Record a structured issue, error, or unexpected behavior. Call this AND complete_step (unless fatal). Does not stop the session -- it creates a record for the auto-fix coordinator.
+- \`spawn_agent\`: Delegate a sub-task to a child WorkRail session. BLOCKS until the child completes. Returns \`{ childSessionId, outcome: "success"|"error"|"timeout", notes: string }\`. Always check \`outcome\` before using \`notes\`. IMPORTANT: your session's time limit (maxSessionMinutes) keeps running while the child executes -- ensure your parent session has enough time for both your work AND the child's work. Maximum spawn depth is 3 by default (configurable). Use only when a step explicitly asks for delegation or when a clearly separable sub-task would benefit from its own WorkRail audit trail.
 
 ## Execution contract
 1. Read the step carefully. Do ALL the work the step asks for.
@@ -936,6 +1063,8 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter) {
         return { _tag: 'success', workflowId: trigger.workflowId, stopReason: 'stop' };
     }
     const schemas = getSchemas();
+    const spawnCurrentDepth = trigger.spawnDepth ?? 0;
+    const spawnMaxDepth = trigger.agentConfig?.maxSubagentDepth ?? 3;
     const tools = [
         makeCompleteStepTool(sessionId, ctx, () => currentContinueToken, onAdvance, onComplete, (t) => { currentContinueToken = t; }, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSessionId),
         makeContinueWorkflowTool(sessionId, ctx, onAdvance, onComplete, schemas, index_js_1.executeContinueWorkflow, emitter, workrailSessionId),
@@ -947,6 +1076,7 @@ async function runWorkflow(trigger, ctx, apiKey, daemonRegistry, emitter) {
                 issueSummaries.push(summary);
             }
         }),
+        makeSpawnAgentTool(sessionId, ctx, apiKey, workrailSessionId ?? '', spawnCurrentDepth, spawnMaxDepth, runWorkflow, schemas, emitter),
     ];
     const [soulContent, workspaceContext, sessionNotes] = await Promise.all([
         loadDaemonSoul(trigger.soulFile),

package/dist/manifest.json

@@ -430,8 +430,8 @@
       "bytes": 506
     },
     "config/config-file.js": {
-      "sha256": "8d7a93f6153442348c8ef52178a928a722b2c19581097b31bc7de19076096710",
-      "bytes": 7215
+      "sha256": "22006b77ef2c6094c86b97007371b96fbd8792accec652c49bdcccaa40ad327f",
+      "bytes": 7277
     },
     "config/feature-flags.d.ts": {
       "sha256": "49cdf81a9c4f31eca560af5257c569143d2138ec996468b949f9807b7ad7802e",
@@ -445,12 +445,12 @@
       "sha256": "cf9d09641f1c31fffe6c7835b30bbbad52572befec1acab7fb9a0c188431af36",
       "bytes": 60355
     },
-    "console-ui/assets/index-D7jQyCSD.js": {
-      "sha256": "f0692154276f354dbbdce868634b19caf01a3b5d2a2e033bb1ecd19d61889eb9",
+    "console-ui/assets/index-o-p__sHJ.js": {
+      "sha256": "aa021484cd5141eb2d76c22eaed98462b60d0893980aacc0de3c27e7622771c8",
       "bytes": 754955
     },
     "console-ui/index.html": {
-      "sha256": "83c7ee221c0d7e05b7e1728f795a289cd317dfe922a49c460ac66f1cebd4c097",
+      "sha256": "f893a833024bf953eb40aa9474c648cdddc4171fb73be8de5e5836898c2a383d",
       "bytes": 417
     },
     "console/standalone-console.d.ts": {
@@ -502,12 +502,12 @@
       "bytes": 1009
     },
     "daemon/workflow-runner.d.ts": {
-      "sha256": "598ca3cda5dba827d0eddf80baf4136b401d821c81ec83aacbee05a63b836d9a",
-      "bytes": 4103
+      "sha256": "d62587e9c7da974ff986d2d9cb67f0b30f7f3cb98a469cf98daf1d6fd16fa897",
+      "bytes": 4593
     },
     "daemon/workflow-runner.js": {
-      "sha256": "a54677cdf2d2083fd9672b25b9d2264defa8dde7b357055bc14748d0ce9e7098",
-      "bytes": 56093
+      "sha256": "e3784aa04ead526de3ac9103d40967b32e3095ae3021ac13237034290be4ba4c",
+      "bytes": 63597
     },
     "di/container.d.ts": {
       "sha256": "003bb7fb7478d627524b9b1e76bd0a963a243794a687ff233b96dc0e33a06d9f",
@@ -954,8 +954,8 @@
       "bytes": 2769
     },
     "mcp/handlers/v2-advance-events.js": {
-      "sha256": "6b77a18f4818355b986b96af50df86d629f235226d619e27a35eb50384c0f770",
-      "bytes": 5187
+      "sha256": "c23df725685ee2062f44e05512ee4463c9b29ed4d67a4e72846496d59920733c",
+      "bytes": 5235
     },
     "mcp/handlers/v2-checkpoint.d.ts": {
       "sha256": "8f22b341bb0ffffb3b24a89067e2a6513ef004ca21c1a42ce48979c2c663b18c",
@@ -1038,12 +1038,12 @@
       "bytes": 11397
     },
     "mcp/handlers/v2-execution/start.d.ts": {
-      "sha256": "3d93d6119b89d6cabf8bebbaafd24d8de53d84dd671440d221dda5a238ba4fc4",
-      "bytes": 3519
+      "sha256": "1ebd5c3790f5bedaf032e4f5271a78d43629b82ecc351c3fc0f17f326d915d5d",
+      "bytes": 3558
     },
     "mcp/handlers/v2-execution/start.js": {
-      "sha256": "f57771c4baa31204fc683615802a02c4c9cf65e8727426210fc656d173e9fe51",
-      "bytes": 21208
+      "sha256": "d2ffbf775d5ea6ce68174d428129fad1377033e09fcdeb69c24c9d8fb04885b4",
+      "bytes": 21354
     },
     "mcp/handlers/v2-execution/workflow-object-cache.d.ts": {
       "sha256": "7e58a2a020fd8443821dbe4e6a2702a9882c517f032a340c1b393cdebf4af907",
@@ -1557,6 +1557,14 @@
       "sha256": "b8668c607788d560b38cf203750395e84eaa3164fff5711cac8f87f469714592",
       "bytes": 1222
     },
+    "trigger/notification-service.d.ts": {
+      "sha256": "c78406d3748953548f7879df8ac60cecd5e42f2f3b283f777343168ce2470b8d",
+      "bytes": 1572
+    },
+    "trigger/notification-service.js": {
+      "sha256": "693f617adc30b3a4fcebeca6a78b0da1c58819001660c017a4d0901652d675b8",
+      "bytes": 6373
+    },
     "trigger/polled-event-store.d.ts": {
       "sha256": "2952a25804177b2389d4273bfc41192477d100bc26100683861dedf28520dec1",
       "bytes": 1011
@@ -1578,16 +1586,16 @@
       "bytes": 1529
     },
     "trigger/trigger-listener.js": {
-      "sha256": "f2de9f72a7ce75ee47d26c45b5d2e93f10def16098aa718ec69b145862e4b493",
-      "bytes": 10021
+      "sha256": "23f1eed165ae7ec03b2c46ff6d6fdf46f631319d5d58d3a993f710d2732e41f1",
+      "bytes": 10585
     },
     "trigger/trigger-router.d.ts": {
-      "sha256": "c60fa099ea236255d2a51799f3f8c550af1990d167565a976ecb9ec2eb42c6ae",
-      "bytes": 1855
+      "sha256": "5293a744ac4763380716ec7c0b31f16531b9a666d08a3524c6c7993486a728b6",
+      "bytes": 2010
     },
     "trigger/trigger-router.js": {
-      "sha256": "16241f6376d2b6718ee1df4d1873270fd3c0cac69bdeaf2cca9fdaad2ca2bd33",
-      "bytes": 15336
+      "sha256": "e7b620d2b23a5e74f6fd3b5a39a5299d19d38f745401c545277c399336ef5eaf",
+      "bytes": 15565
     },
     "trigger/trigger-store.d.ts": {
       "sha256": "7afb05127d55bc3757a550dd15d4b797766b3fff29d1bfe76b303764b93322e7",
@@ -2166,8 +2174,8 @@
       "bytes": 3397
     },
     "v2/durable-core/schemas/export-bundle/index.d.ts": {
-      "sha256": "4705633548971164d18baa2564fc7306f3687665896a33743a0eccf753c701d4",
-      "bytes": 533636
+      "sha256": "fa406033adbb001b8044836a96c999273814d14b35e4c6d98b644ab22424d3d9",
+      "bytes": 535324
     },
     "v2/durable-core/schemas/export-bundle/index.js": {
       "sha256": "6e3566b2d05ea6302bbf4d311b8ec3e94725a8523834efe7670a79e7bd7dc40d",
@@ -2222,20 +2230,20 @@
       "bytes": 2138
     },
     "v2/durable-core/schemas/session/events.d.ts": {
-      "sha256": "825319ae3964b8983e823f4ed69804840ea69b494d583620387605fb5f127225",
-      "bytes": 80143
+      "sha256": "dc0098d909c240bccd9508c6ed987b50b6a9c162f1f9f7a1d49d53dfefc1535f",
+      "bytes": 80635
     },
     "v2/durable-core/schemas/session/events.js": {
-      "sha256": "cc9f2ae04c788e878533c0b807385bc48341df40c3e01aee22e5881ff5348364",
-      "bytes": 12904
+      "sha256": "8af751c61d8c30802ce13174020893c8dfd59fcb4d15a34efc1abe05a2116e0d",
+      "bytes": 12950
     },
     "v2/durable-core/schemas/session/gaps.d.ts": {
-      "sha256": "399cc4f39e065d60f1a339908da181016281d57903bb7ce525a41d07b53ecc71",
-      "bytes": 8721
+      "sha256": "c42f2b86dd8275f5e35c8b144d5f49775741612b8625806b1aebeeb594248338",
+      "bytes": 8983
     },
     "v2/durable-core/schemas/session/gaps.js": {
-      "sha256": "b57ac509c9cb6c13a5eb3ef7dd4d7bc97d072465613d31a0d24e5607525c2182",
-      "bytes": 2069
+      "sha256": "566d96b60855e4d62360d8ecf0058b810fd514e2be1249221b2bd2cc3e7490d0",
+      "bytes": 2101
     },
     "v2/durable-core/schemas/session/index.d.ts": {
       "sha256": "f4f500d33d212760f480d91fafd4474f7b12f9239a6c5e9c2d80d0fe96207b65",

package/dist/mcp/handlers/v2-advance-events.js

@@ -50,7 +50,7 @@ function buildRecommendationWarningEvents(args) {
             data: {
                 gapId,
                 severity: 'warning',
-                reason: w.kind,
+                reason: { category: 'unexpected', detail: 'evaluation_error' },
                 summary: w.summary,
                 resolution: { kind: 'unresolved' },
             },

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

@@ -46,6 +46,7 @@ export declare function buildInitialEvents(args: {
     };
     readonly goal: string;
     readonly extraContext?: Readonly<Record<string, string>>;
+    readonly parentSessionId?: string;
 }): readonly DomainEventV1[];
 export declare function mintStartTokens(args: {
     readonly sessionId: SessionId;

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

@@ -109,7 +109,7 @@ function loadAndPinWorkflow(args) {
     });
 }
 function buildInitialEvents(args) {
-    const { sessionId, runId, nodeId, workflowId, workflowHash, workflowSourceKind, workflowSourceRef, snapshotRef, observations, idFactory, goal, extraContext, } = args;
+    const { sessionId, runId, nodeId, workflowId, workflowHash, workflowSourceKind, workflowSourceRef, snapshotRef, observations, idFactory, goal, extraContext, parentSessionId, } = args;
     const evtSessionCreated = idFactory.mintEventId();
     const evtRunStarted = idFactory.mintEventId();
     const evtNodeCreated = idFactory.mintEventId();
@@ -123,7 +123,7 @@ function buildInitialEvents(args) {
             sessionId,
             kind: constants_js_1.EVENT_KIND.SESSION_CREATED,
             dedupeKey: `session_created:${sessionId}`,
-            data: {},
+            data: parentSessionId !== undefined ? { parentSessionId } : {},
         },
         {
             v: 1,
@@ -314,6 +314,7 @@ function executeStartWorkflow(input, ctx, internalContext) {
                     idFactory,
                     goal: input.goal,
                     extraContext: internalContext,
+                    parentSessionId: internalContext?.['parentSessionId'],
                 });
                 const emptyTruth = { manifest: [], events: [] };
                 return gate.withHealthySessionLock(sessionId, (lock) => sessionStore.append(lock, {

package/dist/trigger/notification-service.d.ts

@@ -0,0 +1,42 @@
+import type { WorkflowRunResult } from '../daemon/workflow-runner.js';
+export type ExecFileNotifyFn = (file: string, args: readonly string[], options: {
+    timeout: number;
+}, callback: (error: Error | null) => void) => void;
+export type FetchNotifyFn = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface NotificationConfig {
+    readonly macOs: boolean;
+    readonly webhookUrl?: string;
+    readonly execFileFn?: ExecFileNotifyFn;
+    readonly fetchFn?: FetchNotifyFn;
+    readonly platformFn?: () => NodeJS.Platform;
+}
+export interface NotificationPayload {
+    readonly event: 'session_completed';
+    readonly workflowId: string;
+    readonly outcome: 'success' | 'error' | 'timeout' | 'delivery_failed';
+    readonly detail: string;
+    readonly goal: string;
+    readonly timestamp: string;
+}
+export declare function buildNotificationBody(result: WorkflowRunResult, goal: string): string;
+export declare function buildOutcome(result: WorkflowRunResult): NotificationPayload['outcome'];
+export declare function buildDetail(result: WorkflowRunResult): string;
+export declare class NotificationService {
+    private readonly _macOsEnabled;
+    private readonly _webhookUrl;
+    private readonly _execFileFn;
+    private readonly _fetchFn;
+    constructor(config: NotificationConfig);
+    notify(result: WorkflowRunResult, goal: string): void;
+    private _doNotify;
+    private _notifyMacOs;
+    private _notifyWebhook;
+}

package/dist/trigger/notification-service.js

@@ -0,0 +1,164 @@
+"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.NotificationService = void 0;
+exports.buildNotificationBody = buildNotificationBody;
+exports.buildOutcome = buildOutcome;
+exports.buildDetail = buildDetail;
+const childProcess = __importStar(require("node:child_process"));
+const os = __importStar(require("node:os"));
+function buildNotificationBody(result, goal) {
+    const truncated = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;
+    switch (result._tag) {
+        case 'success':
+            return `Session completed: ${truncated}`;
+        case 'error':
+            return `Session failed: ${truncated}`;
+        case 'timeout':
+            return `Session timed out: ${truncated}`;
+        case 'delivery_failed':
+            return `Session completed but result delivery failed: ${truncated}`;
+    }
+}
+function buildOutcome(result) {
+    return result._tag;
+}
+function buildDetail(result) {
+    switch (result._tag) {
+        case 'success':
+            return `stopReason: ${result.stopReason}`;
+        case 'error':
+            return result.message;
+        case 'timeout':
+            return result.message;
+        case 'delivery_failed':
+            return `stopReason: ${result.stopReason}; deliveryError: ${result.deliveryError}`;
+    }
+}
+class NotificationService {
+    constructor(config) {
+        const getPlatform = config.platformFn ?? os.platform.bind(os);
+        if (config.macOs && getPlatform() !== 'darwin') {
+            console.warn('[NotificationService] WORKTRAIN_NOTIFY_MACOS=true but platform is not darwin ' +
+                `(platform: ${getPlatform()}). macOS notifications are disabled.`);
+            this._macOsEnabled = false;
+        }
+        else {
+            this._macOsEnabled = config.macOs;
+        }
+        if (config.webhookUrl !== undefined && config.webhookUrl !== '') {
+            let valid = false;
+            try {
+                const parsed = new URL(config.webhookUrl);
+                valid = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+            }
+            catch {
+                valid = false;
+            }
+            if (!valid) {
+                console.warn(`[NotificationService] WORKTRAIN_NOTIFY_WEBHOOK is not a valid http(s) URL ` +
+                    `("${config.webhookUrl}"). Webhook notifications are disabled.`);
+                this._webhookUrl = undefined;
+            }
+            else {
+                this._webhookUrl = config.webhookUrl;
+            }
+        }
+        else {
+            this._webhookUrl = undefined;
+        }
+        this._execFileFn = config.execFileFn ?? ((file, args, options, callback) => {
+            childProcess.execFile(file, args, options, callback);
+        });
+        this._fetchFn = config.fetchFn ?? ((url, init) => globalThis.fetch(url, init));
+    }
+    notify(result, goal) {
+        void this._doNotify(result, goal).catch(() => {
+        });
+    }
+    async _doNotify(result, goal) {
+        const body = buildNotificationBody(result, goal);
+        const deliveries = [];
+        if (this._macOsEnabled) {
+            deliveries.push(this._notifyMacOs(body, result.workflowId));
+        }
+        if (this._webhookUrl !== undefined) {
+            deliveries.push(this._notifyWebhook(result, goal));
+        }
+        await Promise.allSettled(deliveries);
+    }
+    _notifyMacOs(body, workflowId) {
+        const script = `display notification ${JSON.stringify(body)} with title "WorkTrain" subtitle ${JSON.stringify(workflowId)}`;
+        return new Promise((resolve) => {
+            this._execFileFn('osascript', ['-e', script], { timeout: 5000 }, (error) => {
+                if (error) {
+                    console.warn(`[NotificationService] macOS notification failed: ${error.message}`);
+                }
+                resolve();
+            });
+        });
+    }
+    async _notifyWebhook(result, goal) {
+        const url = this._webhookUrl;
+        const payload = {
+            event: 'session_completed',
+            workflowId: result.workflowId,
+            outcome: buildOutcome(result),
+            detail: buildDetail(result),
+            goal,
+            timestamp: new Date().toISOString(),
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30000);
+        try {
+            const res = await this._fetchFn(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                console.warn(`[NotificationService] Webhook notification failed: HTTP ${res.status} from ${url}`);
+            }
+        }
+        catch (e) {
+            console.warn(`[NotificationService] Webhook notification error: ${String(e)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.NotificationService = NotificationService;

package/dist/trigger/trigger-listener.js

@@ -44,6 +44,7 @@ const http = __importStar(require("node:http"));
 const trigger_store_js_1 = require("./trigger-store.js");
 const trigger_router_js_1 = require("./trigger-router.js");
 const config_file_js_1 = require("../config/config-file.js");
+const notification_service_js_1 = require("./notification-service.js");
 const workflow_runner_js_1 = require("../daemon/workflow-runner.js");
 const types_js_1 = require("./types.js");
 const polling_scheduler_js_1 = require("./polling-scheduler.js");
@@ -177,8 +178,13 @@ async function startTriggerListener(ctx, options) {
         : undefined;
     const parsed = parseInt(maxConcurrencyRaw ?? '', 10);
     const maxConcurrentSessions = !isNaN(parsed) ? parsed : undefined;
+    const notifyMacOs = (workrailConfig.kind === 'ok' && workrailConfig.value['WORKTRAIN_NOTIFY_MACOS'] === 'true');
+    const notifyWebhook = workrailConfig.kind === 'ok' ? workrailConfig.value['WORKTRAIN_NOTIFY_WEBHOOK'] : undefined;
+    const notificationService = (notifyMacOs || (notifyWebhook !== undefined && notifyWebhook !== ''))
+        ? new notification_service_js_1.NotificationService({ macOs: notifyMacOs, webhookUrl: notifyWebhook })
+        : undefined;
     const runWorkflowFn = options.runWorkflowFn ?? workflow_runner_js_1.runWorkflow;
-    const router = new trigger_router_js_1.TriggerRouter(triggerIndex, ctx, apiKey, runWorkflowFn, undefined, maxConcurrentSessions, options.emitter);
+    const router = new trigger_router_js_1.TriggerRouter(triggerIndex, ctx, apiKey, runWorkflowFn, undefined, maxConcurrentSessions, options.emitter, notificationService);
     const app = createTriggerApp(router);
     const allTriggers = [...triggerIndex.values()];
     const polledEventStore = new polled_event_store_js_1.PolledEventStore(env);

package/dist/trigger/trigger-router.d.ts

@@ -3,6 +3,7 @@ import type { V2ToolContext } from '../mcp/types.js';
 import type { TriggerDefinition, WebhookEvent } from './types.js';
 import type { ExecFn } from './delivery-action.js';
 import type { DaemonEventEmitter } from '../daemon/daemon-events.js';
+import type { NotificationService } from './notification-service.js';
 export type RouteError = {
     readonly kind: 'not_found';
     readonly triggerId: string;
@@ -31,7 +32,8 @@ export declare class TriggerRouter {
     private readonly semaphore;
     private readonly _maxConcurrentSessions;
     private readonly emitter;
-    constructor(index: ReadonlyMap<string, TriggerDefinition>, ctx: V2ToolContext, apiKey: string, runWorkflowFn: RunWorkflowFn, execFn?: ExecFn, maxConcurrentSessions?: number, emitter?: DaemonEventEmitter);
+    private readonly notificationService;
+    constructor(index: ReadonlyMap<string, TriggerDefinition>, ctx: V2ToolContext, apiKey: string, runWorkflowFn: RunWorkflowFn, execFn?: ExecFn, maxConcurrentSessions?: number, emitter?: DaemonEventEmitter, notificationService?: NotificationService);
     get activeSessions(): number;
     get maxConcurrentSessions(): number;
     route(event: WebhookEvent): RouteResult;

package/dist/trigger/trigger-router.js

@@ -182,7 +182,7 @@ class Semaphore {
 }
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 3;
 class TriggerRouter {
-    constructor(index, ctx, apiKey, runWorkflowFn, execFn, maxConcurrentSessions, emitter) {
+    constructor(index, ctx, apiKey, runWorkflowFn, execFn, maxConcurrentSessions, emitter, notificationService) {
         this.index = index;
         this.ctx = ctx;
         this.apiKey = apiKey;
@@ -190,6 +190,7 @@ class TriggerRouter {
         this.queue = new index_js_1.KeyedAsyncQueue();
         this.execFn = execFn ?? execFileAsync;
         this.emitter = emitter;
+        this.notificationService = notificationService;
         const requested = maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
         const cap = Number.isNaN(requested) ? DEFAULT_MAX_CONCURRENT_SESSIONS : requested;
         if (cap < 1) {
@@ -301,6 +302,7 @@ class TriggerRouter {
                 console.log(`[TriggerRouter] Workflow failed: triggerId=${trigger.id} ` +
                     `workflowId=${trigger.workflowId} error=${result.message} stopReason=${result.stopReason}`);
             }
+            this.notificationService?.notify(result, workflowTrigger.goal);
             await maybeRunDelivery(trigger.id, trigger, originalResult, this.execFn);
         });
         return { _tag: 'enqueued', triggerId: trigger.id };
@@ -336,6 +338,7 @@ class TriggerRouter {
                 console.log(`[TriggerRouter] Dispatch failed: workflowId=${workflowTrigger.workflowId} ` +
                     `error=${result.message} stopReason=${result.stopReason}`);
             }
+            this.notificationService?.notify(result, workflowTrigger.goal);
         });
         return workflowTrigger.workflowId;
     }