@x1a0f3n9/dsh-tool-workflow 0.1.5-rc.2

package/lib/invariant.js

@@ -0,0 +1,129 @@
+//#region lib/types/invariant.js
+/** Package-owned durable workflow-record invariants. @module @x1a0f3n9/dsh-tool-workflow/invariant */
+const PACKAGE_NAME = "@x1a0f3n9/dsh-tool-workflow";
+/** Cordis companion plugin name. */
+const name = "tool-workflow-invariant";
+/** Services required to validate existing and newly appended Session logs. */
+const inject = ["invariants"];
+/** Whether this package owns the candidate Session event. */
+function isWorkflowRecordEvent(event) {
+	return event.type.startsWith("tool-workflow/");
+}
+/** Require a durable opaque identity to be a non-empty string. */
+function stringId(value, label, fail) {
+	if (typeof value !== "string" || value.length === 0) fail(`${label} must be a non-empty string`);
+	return value;
+}
+/** Require one workflow member's 1-based sequence identity. */
+function memberSeq(value, fail) {
+	if (!Number.isSafeInteger(value) || value < 1) fail("tool-workflow member seq must be a positive safe integer");
+	return value;
+}
+/** Read one plain payload field without trusting restored plugin data. */
+function recordOf(event, fail) {
+	const data = event.data;
+	if (data === null || typeof data !== "object" || Array.isArray(data)) fail(`${event.type} data must be a JSON object`);
+	return data;
+}
+/** Copy only the run one candidate can mutate; other committed states stay shared. */
+function cloneTraceForEvent(source, event, fail) {
+	const trace = new Map(source);
+	if (event.type === "tool-workflow/run-start") return trace;
+	const runId = stringId(recordOf(event, fail).runId, `${event.type} runId`, fail);
+	const run = source.get(runId);
+	if (run !== void 0) trace.set(runId, {
+		ended: run.ended,
+		members: new Map(run.members)
+	});
+	return trace;
+}
+/** Require the named run to exist and remain open. */
+function openRun(trace, runId, eventType, fail) {
+	const run = trace.get(runId);
+	if (run === void 0) fail(`${eventType} has no matching tool-workflow/run-start for run ${runId}`);
+	if (run.ended) fail(`${eventType} appears after tool-workflow/run-end for run ${runId}`);
+	return run;
+}
+/** Advance the workflow-record fold with one relevant Session event. */
+function applyEvent(trace, event, fail) {
+	const data = recordOf(event, fail);
+	const runId = stringId(data.runId, `${event.type} runId`, fail);
+	switch (event.type) {
+		case "tool-workflow/run-start":
+			if (typeof data.name !== "string" || data.name.length === 0) fail("tool-workflow/run-start name must be a non-empty string");
+			if (trace.has(runId)) fail(`tool-workflow/run-start repeats run ${runId}`);
+			trace.set(runId, {
+				ended: false,
+				members: /* @__PURE__ */ new Map()
+			});
+			return;
+		case "tool-workflow/agent-start": {
+			const run = openRun(trace, runId, event.type, fail);
+			const seq = memberSeq(data.seq, fail);
+			if (typeof data.label !== "string") fail("tool-workflow/agent-start label must be a string");
+			if (data.phase !== void 0 && typeof data.phase !== "string") fail("tool-workflow/agent-start phase must be a string when present");
+			stringId(data.childId, "tool-workflow/agent-start childId", fail);
+			if (run.members.has(seq)) fail(`tool-workflow/agent-start repeats member seq ${seq} in run ${runId}`);
+			run.members.set(seq, false);
+			return;
+		}
+		case "tool-workflow/agent-end": {
+			const run = openRun(trace, runId, event.type, fail);
+			const seq = memberSeq(data.seq, fail);
+			if (data.outcome !== "completed" && data.outcome !== "failed" && data.outcome !== "cancelled") fail(`tool-workflow/agent-end outcome ${String(data.outcome)} is invalid`);
+			const ended = run.members.get(seq);
+			if (ended === void 0) fail(`tool-workflow/agent-end has no matching member seq ${seq} in run ${runId}`);
+			if (ended) fail(`tool-workflow/agent-end repeats member seq ${seq} in run ${runId}`);
+			run.members.set(seq, true);
+			return;
+		}
+		case "tool-workflow/run-end": {
+			const run = openRun(trace, runId, event.type, fail);
+			if (data.stopReason !== "completed" && data.stopReason !== "cancelled" && data.stopReason !== "error") fail(`tool-workflow/run-end stopReason ${String(data.stopReason)} is invalid`);
+			const openMembers = [...run.members].filter(([, ended]) => !ended).map(([seq]) => seq);
+			if (openMembers.length > 0) fail(`tool-workflow/run-end leaves member seq ${openMembers.join(", ")} open in run ${runId}`);
+			run.ended = true;
+			run.members.clear();
+			return;
+		}
+		default: fail(`unknown tool-workflow event type ${event.type}`);
+	}
+}
+/** Install an independent incremental fold over every attached Session. */
+const install = Object.assign((ctx, fail) => {
+	const traces = /* @__PURE__ */ new WeakMap();
+	const staged = /* @__PURE__ */ new WeakMap();
+	const seed = (session) => {
+		const trace = /* @__PURE__ */ new Map();
+		for (const event of session.snapshotEvents().filter(isWorkflowRecordEvent)) applyEvent(trace, event, fail);
+		traces.set(session, trace);
+		return trace;
+	};
+	ctx.sessions.list().forEach(seed);
+	ctx.on("session/created", (session) => {
+		seed(session);
+	}, { global: true });
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		if (!isWorkflowRecordEvent(event)) return;
+		const trace = cloneTraceForEvent(traces.get(session), event, fail);
+		applyEvent(trace, event, fail);
+		staged.set(event, {
+			session,
+			trace
+		});
+	}, { global: true });
+	ctx.on("session/event", (session, event) => {
+		if (!isWorkflowRecordEvent(event)) return;
+		const candidate = staged.get(event);
+		/* v8 ignore next 2 -- internal/dispatch stages the exact session/event callback arguments. */
+		if (candidate === void 0 || candidate.session !== session) return fail("session/event reached publication without matching workflow-record validation");
+		staged.delete(event);
+		traces.set(session, candidate.trace);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/** Register this package's invariant companion. */
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The model-facing `workflow` tool: run a JavaScript orchestration script that fans out
+ * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
+ * parsing, execution, caps, and cancellation live behind `ctx.workflowEngine`
+ * (`@x1a0f3n9/dsh-workflow`), so a hardened engine swaps in without touching what the model
+ * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
+ * errors, and background collection remains deferred. Presentation is an args-only generic card
+ * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
+ * section rather than deployment persona prose.
+ * @module @x1a0f3n9/dsh-tool-workflow
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-workflow";
+export declare const inject: string[];
+/** Config: the model-facing tool name plus result rendering caps. */
+export interface Config {
+    /** The model-facing tool name to register (default `workflow`). */
+    toolName?: string;
+    /** Rendered-result ceiling, in characters: a longer JSON value is truncated with a notice (default 50000). */
+    maxResultChars?: number;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,278 @@
+/**
+ * The model-facing `workflow` tool: run a JavaScript orchestration script that fans out
+ * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
+ * parsing, execution, caps, and cancellation live behind `ctx.workflowEngine`
+ * (`@x1a0f3n9/dsh-workflow`), so a hardened engine swaps in without touching what the model
+ * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
+ * errors, and background collection remains deferred. Presentation is an args-only generic card
+ * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
+ * section rather than deployment persona prose.
+ * @module @x1a0f3n9/dsh-tool-workflow
+ */
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@x1a0f3n9/dsh-tools';
+export const name = 'tool-workflow';
+export const inject = ['tools', 'workflowEngine', 'systemPrompt'];
+export const Config = z.object({
+    toolName: z.string().default('workflow'),
+    maxResultChars: z.natural().min(1).default(50_000),
+});
+/** Render a contained recording failure without trusting the thrown value. */
+function renderRecordingError(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        return '[unrenderable thrown value]';
+    }
+}
+/**
+ * Project active top-level workflow runs into their parent Sessions without
+ * letting recording failure affect tool execution.
+ */
+function createWorkflowRecorder(ctx) {
+    const active = new Map();
+    const append = (session, type, data) => {
+        // These four package-owned events are all log-only. Narrowing the generic
+        // append face here discharges Session.append's conditional options tuple.
+        const appendRecord = session.append.bind(session);
+        try {
+            appendRecord(type, data);
+            return true;
+        }
+        catch (error) {
+            ctx.logger.warn(`tool-workflow: disabled durable record after ${type} append failed: ${renderRecordingError(error)}`);
+            return false;
+        }
+    };
+    ctx.on('workflow/agent-start', (info, agent) => {
+        const session = active.get(info.id);
+        if (session === undefined)
+            return;
+        const data = {
+            runId: info.id,
+            seq: agent.seq,
+            label: agent.label,
+            ...agent.phase === undefined ? {} : { phase: agent.phase },
+            childId: agent.childId,
+        };
+        if (!append(session, 'tool-workflow/agent-start', data))
+            active.delete(info.id);
+    });
+    ctx.on('workflow/agent-end', (info, agent) => {
+        const session = active.get(info.id);
+        if (session === undefined)
+            return;
+        const data = {
+            runId: info.id,
+            seq: agent.seq,
+            outcome: agent.outcome,
+        };
+        if (!append(session, 'tool-workflow/agent-end', data))
+            active.delete(info.id);
+    });
+    return {
+        start(session, run) {
+            if (append(session, 'tool-workflow/run-start', { runId: run.id, name: run.meta.name })) {
+                active.set(run.id, session);
+            }
+        },
+        finish(runId, stopReason) {
+            const session = active.get(runId);
+            if (session !== undefined)
+                append(session, 'tool-workflow/run-end', { runId, stopReason });
+            active.delete(runId);
+        },
+        abandon: (runId) => { active.delete(runId); },
+    };
+}
+/**
+ * The script-authoring contract, embedded in the tool description. This IS the
+ * model-facing spec: the meta block, the hooks and their exact semantics, and
+ * the supported schema subset.
+ */
+const DESCRIPTION = `Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.
+
+The workflow's identity rides the \`meta\` parameter as JSON: required \`name\` (short kebab-case) and \`description\` strings, optional \`whenToUse\` string and \`phases\` array (\`{title, detail?, provider?, model?}\`). The \`script\` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO \`export const meta\` statement — meta is a parameter, not code), running with top-level await; end with \`return <value>\` — the value must be JSON-serializable and is this tool's result.
+
+Script-body hooks:
+- \`agent(prompt, opts?): Promise<any>\` — run one subagent to completion. Without \`opts.schema\` it resolves to the child's final text; with \`opts.schema\` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves \`null\` when the child fails (filter with \`.filter(Boolean)\`). Other opts: \`label\` (display), \`phase\` (progress group), and independent \`provider\`/\`model\` LLM target overrides (either may be provided alone). Anything else (\`effort\`/\`isolation\`/\`agentType\`) is rejected loudly.
+- \`pipeline(items, ...stages): Promise<any[]>\` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives \`(prev, item, index)\`. An ordinary stage throw drops that ITEM to \`null\` and skips its remaining stages.
+- \`parallel(thunks): Promise<any[]>\` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to \`null\`.
+- \`phase(title)\` — start a progress phase; \`log(message)\` — narrate progress; \`args\` — the tool call's \`args\` input, verbatim.
+
+Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item \`null\`.
+
+Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.`;
+/** The pending-state card: a generic card titled by the workflow's meta name. */
+function presentWorkflowCall(args) {
+    return {
+        card: 'generic',
+        title: `workflow: ${args.meta.name}`,
+        rawInput: args.script,
+    };
+}
+/** The completed-state card: keep the pending title; render the result content as-is. */
+function presentWorkflowResult(args, result) {
+    void args;
+    void result;
+    return { card: 'generic' };
+}
+/** A non-`completed` stop reason means the script did not finish cleanly. */
+function stopReasonError(result) {
+    switch (result.stopReason) {
+        case 'completed':
+            return undefined;
+        case 'cancelled':
+            return `workflow run was cancelled${result.error !== undefined ? ` (${result.error})` : ''}`;
+        case 'error':
+            return `workflow run failed: ${result.error ?? 'unknown error'}`;
+        /* v8 ignore start -- defensive: WorkflowStopReason is a closed union, exhaustive by construction; a future variant fails here loudly */
+        default:
+            return `workflow run ended abnormally (${String(result.stopReason)})`;
+        /* v8 ignore stop */
+    }
+}
+/** Render the run's outcome text: the meta name, agent count, and the JSON value (capped). */
+function renderResult(name, agentsStarted, value, maxChars) {
+    // The engine returns JSON data (null for a valueless script), so stringify never yields undefined.
+    const rendered = JSON.stringify(value, null, 2);
+    const clipped = rendered.length > maxChars
+        ? `${rendered.slice(0, maxChars)}\n… [truncated: ${rendered.length - maxChars} more characters]`
+        : rendered;
+    return `workflow "${name}" completed (${agentsStarted} agent${agentsStarted === 1 ? '' : 's'}).\nReturn value:\n${clipped}`;
+}
+export function apply(ctx, config) {
+    // schemastery (the exported Config schema) has already filled the defaulted
+    // fields; the assertion records that resolution, not a hidden fallback.
+    const { toolName, maxResultChars } = config;
+    const recorder = createWorkflowRecorder(ctx);
+    // Usage policy ships with the tool (the master convention: tool guidance
+    // lives in tool plugins as prompt sections, not in the deployment persona).
+    ctx.systemPrompt.section({
+        name: `tool:${toolName}`,
+        order: ctx.systemPrompt.getSectionOrder('TOOL_WORKFLOW'),
+        text: `Use the ${toolName} tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.`,
+    });
+    ctx.tools.register(defineTool({
+        name: toolName,
+        description: DESCRIPTION,
+        parameters: {
+            script: {
+                type: 'string',
+                required: true,
+                description: 'The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`).',
+            },
+            meta: {
+                type: 'object',
+                additionalProperties: true,
+                required: true,
+                description: 'The workflow identity block (plain JSON — never code).',
+                properties: {
+                    name: { type: 'string', required: true, description: 'Short kebab-case workflow name.' },
+                    description: { type: 'string', required: true, description: 'One-line description of what the workflow does.' },
+                    whenToUse: { type: 'string', description: 'Optional guidance on when this workflow applies.' },
+                    phases: {
+                        type: 'array',
+                        description: 'Optional phase declarations matched by phase() calls.',
+                        items: {
+                            type: 'object',
+                            additionalProperties: true,
+                            properties: {
+                                title: { type: 'string', required: true, description: 'The phase title phase() calls match by exact string.' },
+                                detail: { type: 'string', description: 'Optional one-line description of the phase.' },
+                                provider: { type: 'string', description: 'Optional provider override this phase is expected to use.' },
+                                model: { type: 'string', description: 'Optional model override this phase is expected to use.' },
+                            },
+                        },
+                    },
+                },
+            },
+            args: {
+                type: 'object',
+                additionalProperties: true,
+                description: 'Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {"files": [...]}).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    runId: { type: 'string', required: true },
+                    agentsStarted: { type: 'integer', required: true },
+                    result: { type: 'json', required: true },
+                },
+            },
+            render: (args, value) => [{
+                    type: 'text',
+                    text: renderResult(args.meta.name, value.agentsStarted, value.result, maxResultChars),
+                }],
+        },
+        async execute(args, exec) {
+            const parent = exec.agent;
+            if (!parent) {
+                // The loop sets `exec.agent` for every model-driven call; its absence
+                // means a non-agent caller invoked the tool directly, which has no
+                // parent to attribute the children to. Fail loud rather than guess.
+                throw new Error('workflow tool requires a calling agent (exec.agent was undefined)');
+            }
+            // Meta/body validation failures (META_INVALID/SCRIPT_PARSE) throw
+            // synchronously here and become isError results via the registry — the
+            // model sees the violation list and can correct the call.
+            const run = ctx.workflowEngine.start({
+                script: args.script,
+                meta: args.meta,
+                ...args.args !== undefined ? { args: args.args } : {},
+                parent,
+                signal: exec.signal,
+            });
+            const recordsRun = exec.parent === undefined;
+            // The shipped worker-thread engine publishes member events from later
+            // worker messages, after start() returns and this run record is active.
+            if (recordsRun)
+                recorder.start(parent.session, run);
+            // Bridge the tool's abort signal to the run: if the parent step is aborted while the
+            // script is in flight, cancel the whole run. The signal also enters the engine directly, but
+            // this local bridge preserves the tool contract even if an implementation ignores it.
+            const onAbort = () => { run.cancel('parent step aborted'); };
+            exec.signal.addEventListener('abort', onAbort, { once: true });
+            let result;
+            try {
+                result = await run.result;
+                const error = stopReasonError(result);
+                if (error !== undefined) {
+                    // Map a non-clean finish to an isError result (the registry turns a
+                    // throw into an isError). Report the reason, not partial output.
+                    throw new Error(error);
+                }
+                return {
+                    runId: run.id,
+                    agentsStarted: result.agentsStarted,
+                    result: result.value,
+                };
+            }
+            finally {
+                exec.signal.removeEventListener('abort', onAbort);
+                try {
+                    // Keep member listeners alive through disposal: an engine may
+                    // synthesize cancelled member endings while reaching quiescence.
+                    await run.dispose();
+                    if (recordsRun) {
+                        /* v8 ignore next -- WorkflowRun.result never rejects by contract, so result is assigned before finally. */
+                        if (result === undefined)
+                            throw new Error('workflow run settled without a result');
+                        recorder.finish(run.id, result.stopReason);
+                    }
+                }
+                finally {
+                    if (recordsRun)
+                        recorder.abandon(run.id);
+                }
+            }
+        },
+        presentCall: args => presentWorkflowCall(args),
+        presentResult: (args, result) => presentWorkflowResult(args, result),
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,9 @@
+/** Package-owned durable workflow-record invariants. @module @x1a0f3n9/dsh-tool-workflow/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-workflow-invariant";
+/** Services required to validate existing and newly appended Session logs. */
+export declare const inject: string[];
+/** Register this package's invariant companion. */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,152 @@
+/** Package-owned durable workflow-record invariants. @module @x1a0f3n9/dsh-tool-workflow/invariant */
+const PACKAGE_NAME = '@x1a0f3n9/dsh-tool-workflow';
+/** Cordis companion plugin name. */
+export const name = 'tool-workflow-invariant';
+/** Services required to validate existing and newly appended Session logs. */
+export const inject = ['invariants'];
+/** Whether this package owns the candidate Session event. */
+function isWorkflowRecordEvent(event) {
+    return event.type.startsWith('tool-workflow/');
+}
+/** Require a durable opaque identity to be a non-empty string. */
+function stringId(value, label, fail) {
+    if (typeof value !== 'string' || value.length === 0)
+        fail(`${label} must be a non-empty string`);
+    return value;
+}
+/** Require one workflow member's 1-based sequence identity. */
+function memberSeq(value, fail) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        fail('tool-workflow member seq must be a positive safe integer');
+    }
+    return value;
+}
+/** Read one plain payload field without trusting restored plugin data. */
+function recordOf(event, fail) {
+    const data = event.data;
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        fail(`${event.type} data must be a JSON object`);
+    }
+    return data;
+}
+/** Copy only the run one candidate can mutate; other committed states stay shared. */
+function cloneTraceForEvent(source, event, fail) {
+    const trace = new Map(source);
+    if (event.type === 'tool-workflow/run-start')
+        return trace;
+    const data = recordOf(event, fail);
+    const runId = stringId(data.runId, `${event.type} runId`, fail);
+    const run = source.get(runId);
+    if (run !== undefined) {
+        trace.set(runId, { ended: run.ended, members: new Map(run.members) });
+    }
+    return trace;
+}
+/** Require the named run to exist and remain open. */
+function openRun(trace, runId, eventType, fail) {
+    const run = trace.get(runId);
+    if (run === undefined)
+        fail(`${eventType} has no matching tool-workflow/run-start for run ${runId}`);
+    if (run.ended)
+        fail(`${eventType} appears after tool-workflow/run-end for run ${runId}`);
+    return run;
+}
+/** Advance the workflow-record fold with one relevant Session event. */
+function applyEvent(trace, event, fail) {
+    const data = recordOf(event, fail);
+    const runId = stringId(data.runId, `${event.type} runId`, fail);
+    switch (event.type) {
+        case 'tool-workflow/run-start': {
+            if (typeof data.name !== 'string' || data.name.length === 0) {
+                fail('tool-workflow/run-start name must be a non-empty string');
+            }
+            if (trace.has(runId))
+                fail(`tool-workflow/run-start repeats run ${runId}`);
+            trace.set(runId, { ended: false, members: new Map() });
+            return;
+        }
+        case 'tool-workflow/agent-start': {
+            const run = openRun(trace, runId, event.type, fail);
+            const seq = memberSeq(data.seq, fail);
+            if (typeof data.label !== 'string')
+                fail('tool-workflow/agent-start label must be a string');
+            if (data.phase !== undefined && typeof data.phase !== 'string') {
+                fail('tool-workflow/agent-start phase must be a string when present');
+            }
+            stringId(data.childId, 'tool-workflow/agent-start childId', fail);
+            if (run.members.has(seq))
+                fail(`tool-workflow/agent-start repeats member seq ${seq} in run ${runId}`);
+            run.members.set(seq, false);
+            return;
+        }
+        case 'tool-workflow/agent-end': {
+            const run = openRun(trace, runId, event.type, fail);
+            const seq = memberSeq(data.seq, fail);
+            if (data.outcome !== 'completed' && data.outcome !== 'failed' && data.outcome !== 'cancelled') {
+                fail(`tool-workflow/agent-end outcome ${String(data.outcome)} is invalid`);
+            }
+            const ended = run.members.get(seq);
+            if (ended === undefined)
+                fail(`tool-workflow/agent-end has no matching member seq ${seq} in run ${runId}`);
+            if (ended)
+                fail(`tool-workflow/agent-end repeats member seq ${seq} in run ${runId}`);
+            run.members.set(seq, true);
+            return;
+        }
+        case 'tool-workflow/run-end': {
+            const run = openRun(trace, runId, event.type, fail);
+            if (data.stopReason !== 'completed' && data.stopReason !== 'cancelled' && data.stopReason !== 'error') {
+                fail(`tool-workflow/run-end stopReason ${String(data.stopReason)} is invalid`);
+            }
+            const openMembers = [...run.members].filter(([, ended]) => !ended).map(([seq]) => seq);
+            if (openMembers.length > 0) {
+                fail(`tool-workflow/run-end leaves member seq ${openMembers.join(', ')} open in run ${runId}`);
+            }
+            run.ended = true;
+            run.members.clear();
+            return;
+        }
+        default:
+            fail(`unknown tool-workflow event type ${event.type}`);
+    }
+}
+/** Install an independent incremental fold over every attached Session. */
+const install = Object.assign((ctx, fail) => {
+    const traces = new WeakMap();
+    const staged = new WeakMap();
+    const seed = (session) => {
+        const trace = new Map();
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+        for (const event of session.snapshotEvents().filter(isWorkflowRecordEvent))
+            applyEvent(trace, event, fail);
+        traces.set(session, trace);
+        return trace;
+    };
+    ctx.sessions.list().forEach(seed);
+    ctx.on('session/created', (session) => { seed(session); }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        if (!isWorkflowRecordEvent(event))
+            return;
+        // session/event dispatch follows list() or session/created seeding.
+        const trace = cloneTraceForEvent(traces.get(session), event, fail);
+        applyEvent(trace, event, fail);
+        staged.set(event, { session, trace });
+    }, { global: true });
+    ctx.on('session/event', (session, event) => {
+        if (!isWorkflowRecordEvent(event))
+            return;
+        const candidate = staged.get(event);
+        /* v8 ignore next 2 -- internal/dispatch stages the exact session/event callback arguments. */
+        if (candidate === undefined || candidate.session !== session) {
+            return fail('session/event reached publication without matching workflow-record validation');
+        }
+        staged.delete(event);
+        traces.set(session, candidate.trace);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/** Register this package's invariant companion. */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Browser-safe durable workflow-record events written by the model-facing
+ * workflow tool into its calling parent Session.
+ *
+ * @module @x1a0f3n9/dsh-tool-workflow/types
+ */
+import type { SessionId } from '@x1a0f3n9/dsh-session/types';
+import type { WorkflowAgentOutcome, WorkflowRunId, WorkflowStopReason } from '@x1a0f3n9/dsh-workflow/types';
+/** Opens one durable top-level workflow run record. */
+export interface ToolWorkflowRunStartData {
+    readonly runId: WorkflowRunId;
+    readonly name: string;
+}
+/** Records one workflow member after its child Session is published. */
+export interface ToolWorkflowAgentStartData {
+    readonly runId: WorkflowRunId;
+    readonly seq: number;
+    readonly label: string;
+    readonly phase?: string;
+    readonly childId: SessionId;
+}
+/** Settles one previously started workflow member. */
+export interface ToolWorkflowAgentEndData {
+    readonly runId: WorkflowRunId;
+    readonly seq: number;
+    readonly outcome: WorkflowAgentOutcome;
+}
+/** Settles one workflow run after its live resources reach quiescence. */
+export interface ToolWorkflowRunEndData {
+    readonly runId: WorkflowRunId;
+    readonly stopReason: WorkflowStopReason;
+}
+declare module '@x1a0f3n9/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Opens one top-level workflow record.
+         * @param data - stable run identity and display name.
+         */
+        'tool-workflow/run-start': ToolWorkflowRunStartData;
+        /**
+         * Records one published workflow member.
+         * @param data - run identity, member sequence, display identity, and child Session.
+         */
+        'tool-workflow/agent-start': ToolWorkflowAgentStartData;
+        /**
+         * Records one member settlement.
+         * @param data - run identity, paired member sequence, and outcome.
+         */
+        'tool-workflow/agent-end': ToolWorkflowAgentEndData;
+        /**
+         * Closes one workflow record after cleanup.
+         * @param data - stable run identity and terminal reason.
+         */
+        'tool-workflow/run-end': ToolWorkflowRunEndData;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe durable workflow-record events written by the model-facing
+ * workflow tool into its calling parent Session.
+ *
+ * @module @x1a0f3n9/dsh-tool-workflow/types
+ */
+export {};
+//# sourceMappingURL=types.js.map