@deepseek-ai/dsh-workflow-worker-thread 0.0.1-rc.3

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-workflow-worker-thread`.
+* @module @deepseek-ai/dsh-workflow-worker-thread/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-workflow-worker-thread";
+/** Cordis companion plugin name. */
+const name = "workflow-worker-thread-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this process-boundary implementation exposes no same-process event relation;
+* worker protocol and built-worker tests cover it.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/host.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Host side of one workflow run. The first worker result, unexpected death, or
+ * cancellation-grace expiry owns settlement and closes message admission.
+ * Pending starts share one abort signal; published children share idempotent
+ * cleanup, and quiescence waits for both while synthesizing any missing end events.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/host
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type SubagentRuntime from '@deepseek-ai/dsh-subagent';
+import type { WorkflowMeta, WorkflowResult, WorkflowRun, WorkflowRunId } from '@deepseek-ai/dsh-workflow';
+import type { ExecutionObserver } from './runtime.ts';
+import type { WorkerInit } from './types.ts';
+/**
+ * One live worker-engine run — the seam's {@link WorkflowRun}, returned by
+ * `start()` directly. Owns the Worker, the child registry, and the result
+ * settlement; `result` never rejects. `meta` is trusted same-process data
+ * borrowed as immutable by the handle and lifecycle events. The holder-bound
+ * SubagentRuntime handle is captured before the
+ * engine returns this run, so unloading the engine removes only the ability to
+ * start another workflow; this run can still start and clean up its children.
+ */
+export declare class WorkerRun implements WorkflowRun {
+    private readonly ctx;
+    private readonly subagents;
+    readonly id: WorkflowRunId;
+    readonly meta: WorkflowMeta;
+    private readonly parent;
+    private readonly provider;
+    private readonly disposeGraceMs;
+    private readonly observer;
+    /** Settles exactly once with the run's outcome; never rejects. */
+    readonly result: Promise<WorkflowResult>;
+    private settleResolve;
+    private settled;
+    /** A Result/death/grace outcome atomically won before teardown callbacks. */
+    private terminalClaimed;
+    /** The first death signal closes worker-message admission and owns failure-time cleanup. */
+    private workerDeathObserved;
+    private cancelReason;
+    private graceTimer;
+    private readonly worker;
+    /** Set on `exit`: the thread is gone, so posting has nowhere to go. */
+    private workerGone;
+    /** Accepted `child-start` messages — the terminate-path `agentsStarted` (see module doc). */
+    private hostStarted;
+    /** Published children by callId; an entry leaves only after disposal settles. */
+    private readonly children;
+    /** Provider starts that have not yet fulfilled or rejected. */
+    private readonly pendingStarts;
+    /** Started-but-not-ended agents by seq — the pairing ledger the HOST guarantees (see {@link endAgent}). */
+    private readonly liveAgents;
+    private readonly quiescenceWaiters;
+    /** The per-run abort fanout every child start request carries. */
+    private readonly controller;
+    /** External start signal and the exact callback installed on it, retained only until first settle/teardown. */
+    private inputSignal;
+    private inputSignalAbort;
+    private disposed;
+    constructor(ctx: Context, subagents: SubagentRuntime, id: WorkflowRunId, meta: WorkflowMeta, parent: Agent, init: WorkerInit, provider: string, disposeGraceMs: number, observer: ExecutionObserver, signal: AbortSignal | undefined);
+    /**
+     * Cancel the run: the worker is told (its hooks start throwing and the
+     * script dies at its next await), the required signal shared by every child
+     * start is aborted, and the grace timer
+     * arms: a run still unsettled `disposeGraceMs` later force-settles
+     * `cancelled` and its worker is TERMINATED. Idempotent; the first reason
+     * wins.
+     * @param reason - human-readable cause (default `'workflow cancelled'`).
+     */
+    cancel(reason?: string): void;
+    /**
+     * Cancel + bounded settle + termination. Host-drives every registered
+     * child's disposal IMMEDIATELY — a wedged worker can relay no dispose RPC,
+     * and deferring child teardown to the post-terminate reap would spend the
+     * whole grace waiting for a quiescence that cannot start, then return with
+     * the disposals still in flight — so child disposal overlaps the same
+     * grace the worker gets to settle (the worker's own dispose RPCs join the
+     * shared per-child disposal). Waits (at most the grace) for the result and
+     * child quiescence, then terminates the worker unconditionally — the
+     * thread never outlives its run — and reaps whatever children remain
+     * (their disposal is contained, not awaited past the grace, the same
+     * abandonment the seam documents for a slow-disposing child). Idempotent;
+     * safe on every path.
+     * @returns resolves when the run's resources are released or abandoned.
+     */
+    dispose(): Promise<void>;
+    /** Post one message to the worker (payload looked up from the tag's map entry), tolerating a thread that is already gone. */
+    private post;
+    private onMessage;
+    /** Why a ready provider result may no longer be admitted to the worker. */
+    private childAdmissionFailure;
+    private onChildStart;
+    /** Await one provider-owned startup transaction and publish only while admitted. */
+    private startChild;
+    private onChildDispose;
+    /**
+     * Start (or join) one registered child's disposal; the registry entry
+     * leaves when it settles. Memoized per callId: the worker's dispose RPC,
+     * the dispose() host drive, and the reap can all land on the same child —
+     * the child's `dispose()` runs once and every caller awaits that one
+     * settlement. A rejection is contained (the subagent seam's dispose() is
+     * not supposed to reject, but a backend that does anyway must not break
+     * quiescence): logged, and the child still leaves the registry.
+     * @param callId - the child's registry key.
+     * @param record - the registered child (the caller looked it up).
+     * @returns resolves when the disposal settled either way; never rejects.
+     */
+    private disposeChild;
+    /** Drop a child record and release quiescence waiters when all work ends. */
+    private finishChild;
+    /** Retire one provider startup transaction. */
+    private finishPendingStart;
+    /** Release waiters only after both pending starts and published children end. */
+    private notifyChildQuiescence;
+    /** Resolves once every pending start and published child has reached quiescence. */
+    private childQuiescence;
+    /** Abort + dispose every registered child (worker death / final teardown); disposal is contained, not awaited. */
+    private reapChildren;
+    /** Abort the one canonical signal shared by pending and published children. */
+    private abortChildren;
+    private onResult;
+    /** Process an error/messageerror/exit signal; `exit` also performs the final disposal sweep. */
+    private onWorkerDeath;
+    /**
+     * The single agent-end emission gate: forwards `end` iff its start is still
+     * unpaired in the ledger, so every forwarded `workflow/agent-start` gets
+     * EXACTLY one `workflow/agent-end` — the worker's own report where it can
+     * speak, a host-synthesized one where it cannot ({@link endStrandedAgents}).
+     * @param end - the settlement to emit (worker-reported or synthesized).
+     */
+    private endAgent;
+    /**
+     * Synthesize the missing `agent-end` for every started-but-unpaired agent,
+     * outcome `'cancelled'`: the reap cancels every child, and a real
+     * settlement racing the force-settle loses to that already-started external
+     * cancellation. The atomic terminal boundaries in {@link onResult} and
+     * {@link onWorkerDeath} deliberately exclude teardown callbacks as contenders.
+     * Called where the worker can no longer speak (the grace force-settle,
+     * worker death, physical exit). When grace/death is the terminal source it
+     * runs before settleResult, so already-known pairs precede `workflow/end`;
+     * after an earlier Result, exit cleanup may close a survivor afterward.
+     * The ledger preserves exactly-once pairing in both orders.
+     */
+    private endStrandedAgents;
+    private cancelledResult;
+    /** Remove the exact abort callback installed on the caller's start signal. */
+    private detachInputSignal;
+    /** First settle wins; disarms the grace timer and releases the caller signal. */
+    private settleResult;
+}
+//# sourceMappingURL=host.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Worker-thread workflow engine. Each run executes its model-written script in
+ * an escapable vm context on a fresh worker and bridges `agent()` calls to host
+ * subagents. The thread prevents synchronous script work from blocking the host
+ * and permits forced termination, but it is containment rather than a security boundary.
+ * @module @deepseek-ai/dsh-workflow-worker-thread
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import WorkflowEngine from '@deepseek-ai/dsh-workflow';
+import type { WorkflowRun, WorkflowStartRequest } from '@deepseek-ai/dsh-workflow';
+export { validateMeta } from './meta.ts';
+export { materializeFromRealm, MaterializeError } from './realm.ts';
+export type { ChildHandle, ChildPort, ChildResult, ChildStartRequest, WorkerInit, WorkerLimits, } from './types.ts';
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+    /** The `ctx.subagents` provider children run on (default `spawn`). */
+    provider?: string;
+    /** Concurrent `agent()` ceiling; `0` (the default) auto-resolves to `min(16, max(1, cores - 2))`. */
+    maxConcurrentAgents?: number;
+    /** Total `agent()` calls one run may start — the runaway-loop backstop (default 1000). */
+    maxTotalAgents?: number;
+    /** Items accepted by a single `parallel()`/`pipeline()` call (default 4096). */
+    maxItemsPerCall?: number;
+    /** vm timeout for the script's initial synchronous slice, inside the worker (default 5000 ms). */
+    syncTimeoutMs?: number;
+    /**
+     * How long after a cancellation an unsettled script may keep running before
+     * the run force-settles `cancelled` and its worker is TERMINATED (default
+     * 5000 ms); also bounds `dispose()`.
+     */
+    disposeGraceMs?: number;
+}
+/**
+ * The worker-thread engine service. `start()` validates the script up front
+ * (meta + a host-side body parse) and returns a {@link WorkflowRun} whose
+ * `result` never rejects; the `workflow/*` events fire around the run per
+ * the seam contract.
+ */
+declare class WorkerThreadWorkflowEngine extends WorkflowEngine {
+    static inject: string[];
+    static Config: z<Config>;
+    private readonly config;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Validate and execute a workflow script in a fresh worker thread. Throws
+     * {@link WorkflowError} synchronously (`META_INVALID` for a malformed meta
+     * block, `SCRIPT_PARSE` for a body that does not compile) for a request
+     * that cannot begin; once a run is returned, every failure resolves through
+     * `result.stopReason` instead.
+     * @param request - the script body, its meta data and `args`, the parent
+     *   agent, and an optional cancel signal.
+     * @returns the live run (its `result` resolves when the script settles).
+     */
+    start(request: WorkflowStartRequest): WorkflowRun;
+}
+export default WorkerThreadWorkflowEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-workflow-worker-thread`.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "workflow-worker-thread-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/meta.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Meta validation checks caller-provided DATA against the {@link WorkflowMeta}
+ * contract and rejects every violation by name. Meta arrives as schema-checked
+ * JSON data, never evaluated script text; evaluating it on the host could run getters outside the
+ * worker timeout that exists to isolate model-written code.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/meta
+ */
+import type { WorkflowMeta } from '@deepseek-ai/dsh-workflow';
+/**
+ * Validate a caller-provided meta value against the {@link WorkflowMeta}
+ * contract. Throws `META_INVALID` naming every violation (unknown fields,
+ * missing/mistyped `name`/`description`, malformed `phases`); the returned
+ * meta is a NORMALIZED copy built from the validated fields, so the engine
+ * never aliases the caller's object.
+ * @param value - the meta data from the start request (plain JSON by the seam contract).
+ * @returns the validated, normalized meta block.
+ */
+export declare function validateMeta(value: unknown): WorkflowMeta;
+//# sourceMappingURL=meta.d.ts.map

package/lib/types/protocol.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The host⇄worker wire protocol: one string-valued enum of message tags per direction, a
+ * payload map giving each tag its parameters (the single source of truth), and the message
+ * unions derived from them. Payloads are plain JSON by construction for structured clone. Both
+ * directions are closed engine protocols whose receivers use `assertNever`; generic typed senders
+ * make tag/payload mismatches compile-time errors rather than silently skipped messages.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/protocol
+ */
+import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResult } from '@deepseek-ai/dsh-workflow';
+import type { ChildResult, ChildStartRequest } from './types.ts';
+/** Message tags the worker sends the host (the wire values are the tag strings). */
+export declare enum WorkerToHostType {
+    /** The startup handshake: the session is listening and awaits {@link HostToWorkerType.Go}. */
+    Ready = "ready",
+    /** Observer narration: a `phase(title)` call. */
+    Phase = "phase",
+    /** Observer narration: a `log(message)` call. */
+    Log = "log",
+    /** Observer lifecycle: one `agent()` call started a child. */
+    AgentStart = "agent-start",
+    /** Observer lifecycle: one `agent()` call settled. */
+    AgentEnd = "agent-end",
+    /** Child RPC: start a child on the host (answered by ChildStarted or ChildStartError). */
+    ChildStart = "child-start",
+    /** Child RPC: dispose a started child (answered by ChildDisposed). */
+    ChildDispose = "child-dispose",
+    /** The run's single terminal result. */
+    Result = "result"
+}
+/** The payload each worker→host tag carries. */
+export interface WorkerToHostPayloads {
+    /** Ready carries nothing. */
+    [WorkerToHostType.Ready]: Record<never, never>;
+    /** The phase title, verbatim. */
+    [WorkerToHostType.Phase]: {
+        title: string;
+    };
+    /** The logged message, verbatim. */
+    [WorkerToHostType.Log]: {
+        message: string;
+    };
+    /** The call's sequence number, label, phase, and child id. */
+    [WorkerToHostType.AgentStart]: {
+        info: WorkflowAgentInfo;
+    };
+    /** The call identity plus its outcome. */
+    [WorkerToHostType.AgentEnd]: {
+        info: WorkflowAgentEndInfo;
+    };
+    /** The RPC correlation id and the prompt plus validated options. */
+    [WorkerToHostType.ChildStart]: {
+        callId: number;
+        request: ChildStartRequest;
+    };
+    /** The RPC correlation id of the child to dispose. */
+    [WorkerToHostType.ChildDispose]: {
+        callId: number;
+    };
+    /** The run's terminal outcome. */
+    [WorkerToHostType.Result]: {
+        result: WorkflowResult;
+    };
+}
+/** Message tags the host sends the worker (the wire values are the tag strings). */
+export declare enum HostToWorkerType {
+    /** Releases the startup gate: run the script body. */
+    Go = "go",
+    /** Cancel the run: hooks start throwing and the script dies at its next await. */
+    Cancel = "cancel",
+    /** Child RPC reply: the provider fulfilled with a published run (exactly one start reply per ChildStart). */
+    ChildStarted = "child-started",
+    /** Child RPC reply: the provider's asynchronous start failed. */
+    ChildStartError = "child-start-error",
+    /** Child RPC: a started child's result RESOLVED (its JSON projection). */
+    ChildSettled = "child-settled",
+    /** Child RPC: a started child's result REJECTED (an infrastructure fault, rendered). */
+    ChildFailed = "child-failed",
+    /** Child RPC reply: a requested disposal completed. */
+    ChildDisposed = "child-disposed"
+}
+/** The payload each host→worker tag carries. */
+export interface HostToWorkerPayloads {
+    /** Go carries nothing. */
+    [HostToWorkerType.Go]: Record<never, never>;
+    /** The cancel reason, canonical for the whole run. */
+    [HostToWorkerType.Cancel]: {
+        reason: string;
+    };
+    /** The RPC correlation id and the child agent's id (minted by the subagent seam). */
+    [HostToWorkerType.ChildStarted]: {
+        callId: number;
+        childId: string;
+    };
+    /** The RPC correlation id and the rendered start failure. */
+    [HostToWorkerType.ChildStartError]: {
+        callId: number;
+        rendered: string;
+    };
+    /** The RPC correlation id and the child's terminal result projection. */
+    [HostToWorkerType.ChildSettled]: {
+        callId: number;
+        result: ChildResult;
+    };
+    /** The RPC correlation id and the rendered infrastructure fault. */
+    [HostToWorkerType.ChildFailed]: {
+        callId: number;
+        rendered: string;
+    };
+    /** The RPC correlation id of the completed disposal. */
+    [HostToWorkerType.ChildDisposed]: {
+        callId: number;
+    };
+}
+/**
+ * One worker→host message of tag `T`; unparameterized, the closed union over
+ * every tag (a discriminated union — `switch` on `type` narrows).
+ */
+export type WorkerToHostMessage<T extends WorkerToHostType = WorkerToHostType> = {
+    [K in T]: {
+        type: K;
+    } & WorkerToHostPayloads[K];
+}[T];
+/**
+ * One host→worker message of tag `T`; unparameterized, the closed union over
+ * every tag (a discriminated union — `switch` on `type` narrows).
+ */
+export type HostToWorkerMessage<T extends HostToWorkerType = HostToWorkerType> = {
+    [K in T]: {
+        type: K;
+    } & HostToWorkerPayloads[K];
+}[T];
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/realm.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Materializes values leaving the script vm into plain JSON before they cross the worker
+ * boundary, and renders thrown script values without rejecting the run. The walk rejects
+ * values that JSON cannot preserve but trusts model-written workflow scripts: getters and proxy traps may
+ * run, and the vm is not a security boundary. The worker provides host-loop isolation and
+ * forced termination, not hostile-value containment. See
+ * .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md for the isolation rationale.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/realm
+ */
+/** Thrown by {@link materializeFromRealm}; the caller wraps it into the right `WorkflowError` code. */
+export declare class MaterializeError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}
+/**
+ * Render a thrown value to failure text without ever throwing: prefer the
+ * `stack` (host or realm — a realm error's `stack` is a plain string read),
+ * fall back to `message`, then `String()`. Reading those properties MAY run
+ * script code (a getter, `toString`) — accepted under the module's trust
+ * premise; if that code itself throws, a fixed label is returned instead.
+ * @param error - any value thrown in the host or worker realm.
+ * @returns human-readable text for the failure report; prefers the stack.
+ */
+export declare function renderThrown(error: unknown): string;
+/**
+ * Copy `value` (typically from the vm realm) into plain host JSON data. Root `undefined` is
+ * returned unchanged; nested `undefined` and values JSON cannot represent losslessly fail
+ * with the offending path. Property accessors run normally, and a throwing read is wrapped
+ * with its rendered failure.
+ *
+ * @param value - the realm value to materialize.
+ * @param root - the path label for the root value (error messages).
+ * @returns the host-realm copy (plain objects/arrays/scalars only).
+ * @throws {@link MaterializeError} for unsupported values, cycles, sparse arrays, exotic
+ *   prototypes, or property reads that throw.
+ */
+export declare function materializeFromRealm(value: unknown, root?: string): unknown;
+//# sourceMappingURL=realm.d.ts.map

package/lib/types/runtime.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-run worker-side vm hooks, child RPC, concurrency/caps, cancellation, and result serialization; it
+ * never touches Cordis. Script values leaving the realm are materialized as plain JSON before
+ * messaging. Values entering the trusted model-written realm are passed directly; `args` alone is
+ * cloned so script mutation cannot alter initialization data. See `./realm.ts` for the trust model.
+ *
+ * Fatal workflow errors—bad hook arguments, unsupported schemas/options, caps, start failures, and
+ * cancellation—propagate through combinators. Only child failures and ordinary stage errors become
+ * per-item nulls. Every returned promise has a rejection consumer so dropped script promises cannot
+ * kill the worker. A cancelled script that never settles emits nothing; the host force-settles the
+ * run within grace and terminates the thread.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/runtime
+ */
+import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowMeta, WorkflowResult } from '@deepseek-ai/dsh-workflow';
+import type { ChildPort, WorkerLimits } from './types.ts';
+/** The observers the execution reports progress through (the session posts them to the host). */
+export interface ExecutionObserver {
+    phase(title: string): void;
+    log(message: string): void;
+    agentStart(info: WorkflowAgentInfo): void;
+    agentEnd(info: WorkflowAgentEndInfo): void;
+}
+/**
+ * One live script execution inside the worker. Constructed per run by the
+ * session; `drive()` is called exactly once and NEVER rejects — every failure
+ * becomes a {@link WorkflowResult} with a non-`completed` stop reason. The
+ * host owns cancellation and cleanup of any dropped child work.
+ */
+export declare class WorkflowExecution {
+    private readonly limits;
+    private readonly observer;
+    private readonly children;
+    /** 1-based count of `agent()` calls started (the `agentsStarted` result field). */
+    private started;
+    private activeSlots;
+    private readonly slotWaiters;
+    private cancelReason;
+    private cancelError;
+    private currentPhase;
+    private readonly context;
+    private readonly compiled;
+    constructor(meta: WorkflowMeta, body: string, args: unknown, limits: WorkerLimits, observer: ExecutionObserver, children: ChildPort);
+    /**
+     * Whether the run has been cancelled. A METHOD, not an inline property
+     * read: `cancel()` mutates `cancelReason` concurrently (the session's
+     * message handler), and an inline read after an `await` gets narrowed by
+     * control flow into an always-false comparison.
+     */
+    private isCancelled;
+    /**
+     * Shared hook entry guard: after {@link cancel}, EVERY hook throws
+     * `CANCELLED` at its next call — cancellation is the next HOOK boundary,
+     * not just the next `agent()`, so a script that caught one cancelled
+     * rejection cannot keep emitting progress through `phase`/`log` or enter a
+     * combinator.
+     */
+    private throwIfCancelled;
+    /**
+     * Cancel the run: waiting `agent()` slots reject and every future hook call
+     * throws `CANCELLED` — the script dies at its next await. A script that
+     * never settles anyway (parked on a promise no hook owns) is the HOST's
+     * problem: its grace timer force-settles the run and terminates the
+     * worker. Idempotent; the first reason wins.
+     * @param reason - human-readable cause carried on the CANCELLED error. The
+     * host independently aborts the required signal shared by every child.
+     */
+    cancel(reason: string): void;
+    /**
+     * Run the script to settlement. Resolves — never rejects — with the run's
+     * {@link WorkflowResult}: the materialized return value on `completed`, the
+     * failure message on `error`, and `cancelled` when the script died of
+     * cancellation. This method only chooses the result; the session publishes
+     * it and the host owns terminal child cancellation.
+     * @returns the settled outcome — this promise NEVER rejects (the seam's
+     * `result`-never-rejects contract); every failure maps to a variant.
+     */
+    drive(): Promise<WorkflowResult>;
+    /**
+     * Attach a no-op rejection consumer WITHOUT changing what the caller
+     * receives: if the script drops the promise (no await), cancellation cannot
+     * become an unhandled rejection (which would kill the worker thread); if
+     * the script does await it, it still observes the rejection.
+     */
+    private contain;
+    private cancelledError;
+    /** Materialize the script's return value; violations become RESULT_UNSERIALIZABLE. */
+    private materializeResult;
+    /**
+     * Acquire one concurrency slot (FIFO). Cancellation rejects QUEUED waiters
+     * (see {@link cancel}); the callers guard their own entry and post-acquire
+     * windows, so no cancelled-precheck is duplicated here.
+     */
+    private acquireSlot;
+    private releaseSlot;
+    /** The `agent(prompt, opts)` hook. */
+    private agent;
+    /** Materialize + validate the `agent()` options bag from the realm. */
+    private readAgentOptions;
+    /** The `parallel(thunks)` hook: each thunk caught → `null`; fatal errors propagate. */
+    private parallel;
+    /** The `pipeline(items, ...stages)` hook: per-item stage chains, NO cross-stage barrier. */
+    private pipeline;
+    private assertItemCap;
+    /** The `phase(title)` hook: sets the current label for subsequent `agent()` calls and notifies observers. */
+    private phase;
+    /** The `log(message)` hook: narration to observers. */
+    private log;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The worker-side half of the engine: {@link runWorkerSession} wires one MessagePort to one
+ * {@link WorkflowExecution} — hook progress and child starts go out as messages, run control
+ * and child lifecycle come back in — and posts the run's terminal result exactly once. Keeping it
+ * separate from `worker.ts` lets unit tests drive the session over a MessageChannel, because main
+ * process coverage cannot observe code inside a real Worker.
+ *
+ * The session announces ready and waits for `go`, so cancellation racing startup can prevent even
+ * the script's synchronous prefix. A cancel in place of `go` releases the gate into a cancelled
+ * drive without executing the body.
+ * @module @deepseek-ai/dsh-workflow-worker-thread/session
+ */
+import type { MessagePort } from 'node:worker_threads';
+import type { WorkerInit } from './types.ts';
+/**
+ * Narrow the nullable `parentPort` the bootstrap reads from
+ * `node:worker_threads`.
+ * @param port - `parentPort` as imported (null on the main thread).
+ * @returns the port, non-null.
+ */
+export declare function requireParentPort(port: MessagePort | null): MessagePort;
+/**
+ * Run one workflow script to settlement against `port`, posting the terminal result message
+ * exactly once; resolves after that post (stray children may still be winding down through the
+ * port — the host owns their teardown and ultimately terminates the thread). It never rejects:
+ * constructor failure becomes an error result. Host pre-parse makes syntax failure here a likely
+ * Node-version skew, but the session still reports it instead of dying silently.
+ * @param port - the channel to the host (the real `parentPort`, or one side
+ *   of an in-process `MessageChannel` in tests).
+ * @param init - the run payload the host provided as `workerData`.
+ */
+export declare function runWorkerSession(port: MessagePort, init: WorkerInit): Promise<void>;
+//# sourceMappingURL=session.d.ts.map