@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/web/preapproved-hosts.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The 92 literals exactly as they appear in `c7t`'s source order (duplicate `learn.microsoft.com`
+ * included) -- kept verbatim so a future re-extraction diffs cleanly against this array.
+ */
+export declare const PREAPPROVED_HOST_ENTRIES: readonly string[];
+/**
+ * `wX(hostname, pathname)`, verbatim: an EXACT hostname match (no subdomains) against the
+ * hostname-only half, OR a hostname with a registered path prefix whose pathname is that prefix or a
+ * `/`-bounded child of it -- rejected outright when the raw pathname contains an encoded slash,
+ * backslash or dot (`%2f`, `%5c`, `%2e`, doubly-encoded or not), which is exactly the traversal class
+ * that would otherwise let `/docs%2f..%2fadmin` read as a legitimate child of `/docs`.
+ */
+export declare function isPreapprovedHost(hostname: string, pathname: string): boolean;
+/** `isPreapprovedHost`, taking the URL directly. A URL that fails to parse is never preapproved. */
+export declare function isPreapprovedUrl(url: URL): boolean;
+/**
+ * The registered entry that matched `url`, if any -- distinguishes a bare hostname match from a
+ * path-scoped one, and names the scope's prefix, so the redirect walk can ask "does the hop's own
+ * path still fall under the SAME scope" rather than only "is this host preapproved at all."
+ */
+export interface PreapprovedMatch {
+    host: string;
+    /** `undefined` for a hostname-only entry; the exact `/`-prefixed scope for a path-scoped one. */
+    pathPrefix?: string;
+}
+/**
+ * Security review round 2, minor: this was EXACT-hostname-only, while `staysWithinScope` (below)
+ * already applied the three-way `[host, stripped, "www."+stripped]` match -- half of one fix. The
+ * gap is not cosmetic: a redirect chain `claude.com/docs/a` -> `www.claude.com/docs/a` (eligible,
+ * `staysWithinScope` says so) -> `www.claude.com/other` recomputes THIS function fresh at the top of
+ * the SECOND hop, on hostname `www.claude.com` -- which `PATH_PREFIXES` only ever keys by
+ * `claude.com`, so the old exact match returned `undefined` for it. An `undefined` scope makes
+ * `isEligibleAutoFollow`'s own `scope !== undefined && ...` check SHORT-CIRCUIT to "no restriction
+ * at all," so the THIRD hop (genuinely outside `/docs`) was auto-followed, not refused -- and because
+ * `claude.com/docs/a` (the ORIGINAL input URL) is still preapproved, that off-scope content got
+ * permissive guidelines and was eligible for the verbatim markdown passthrough. Matching hosts the
+ * same three-way way `staysWithinScope` does closes it: hop 2 now still resolves a scope (matched via
+ * the `claude.com` entry), and `staysWithinScope` correctly refuses hop 3's `/other` path.
+ */
+export declare function preapprovedScopeOf(url: URL): PreapprovedMatch | undefined;
+/**
+ * Whether `url` still falls under the SAME preapproved scope `from` matched -- used by the redirect
+ * walk's "not leaving a preapproved path scope" gate.
+ *
+ * HOST comparison is the same three-way test claude's own code runs (security review corrections
+ * §4.8, measured): `[host, stripped, "www."+stripped]`, i.e. the scope's own host, that host with a
+ * leading `www.` stripped, and that stripped form with `www.` re-added -- so a scope matched on
+ * `claude.com/docs` still covers a redirect to `www.claude.com/docs/x`, and one matched on
+ * `www.example.com/docs` still covers a redirect to `example.com/docs/x`. An EXACT match only (this
+ * lane's earlier version) refused a same-site www-variant redirect claude itself follows.
+ */
+export declare function staysWithinScope(from: PreapprovedMatch, url: URL): boolean;

package/dist/web/private-address.d.ts

@@ -0,0 +1,55 @@
+export type AddressVerdict = "public" | "private";
+/** One classified fact about a hop's target -- WHERE it came from is what a caller's message names. */
+export interface PrivateAddressFinding {
+    class: AddressVerdict;
+    /** The shared classifier's own class name, or a reserved-name label -- safe to show the model. */
+    reason?: string;
+}
+/** Strips a `[...]` IPv6 literal's brackets; a non-bracketed host is returned unchanged. */
+export declare function stripIpv6Brackets(hostname: string): string;
+/**
+ * Classifies a literal IP address -- family auto-detected via `net.isIP` (0 = not a literal IP at
+ * all, in which case this returns `undefined` rather than guessing). Delegates the actual range
+ * logic to the shared classifier, which already handles IPv4-mapped IPv6 in both its dotted-quad
+ * (`::ffff:127.0.0.1`) and hex-group (`::ffff:7f00:1`) forms.
+ */
+export declare function classifyIpLiteral(address: string): PrivateAddressFinding | undefined;
+/** Reserved names RFC 6761 (`localhost`) and mDNS (`.local`) carve out -- private by NAME, whatever they resolve to. A single trailing dot (the DNS root, `localhost.`/`a.localhost.`/`foo.local.`) is stripped first so it cannot defeat the check. */
+export declare function classifyReservedName(hostname: string): PrivateAddressFinding | undefined;
+/**
+ * The LEXICAL verdict for `hostname` as written in the URL: an IP literal classified by range, or a
+ * reserved name. `undefined` means "not lexically decidable" -- an ordinary DNS name, which is only
+ * classifiable by its RESOLVED address (see `classifyHostname` below).
+ */
+export declare function classifyHostnameLexically(hostname: string): PrivateAddressFinding | undefined;
+/** The verdict for one resolved connection address (whatever DNS returned for an ordinary name). */
+export declare function classifyResolvedAddress(address: string): PrivateAddressFinding;
+/**
+ * The full verdict for `hostname`: lexical first (an IP literal or reserved name never needs a
+ * lookup), else every address `resolve` returns for it -- ANY private address among them makes the
+ * whole hostname private, because a caller reaches whichever address the OS connects to, not
+ * necessarily the first one.
+ *
+ * NOT the function that guards the actual connection any more (security review finding M6):
+ * `_web-fetch-net.ts`'s own `resolveTarget` now does its own single resolution and PINS the fetch
+ * to the exact address it classified (`Host` + `tls.serverName` carrying the logical name), closing
+ * the rebinding TOCTOU this function's own resolve-then-classify shape cannot by itself (a second,
+ * independent `fetch()`-internal resolution could still answer differently). This function remains
+ * the upfront, pre-cache gate in `web-fetch.ts` -- a decision, not a connection -- where that gap
+ * does not apply the same way (nothing here opens a socket).
+ *
+ * FAILS CLOSED on a resolution failure (security review finding M6): an EARLIER version of this
+ * function answered `PUBLIC` when `resolve` threw or answered nothing, on the reasoning that "the
+ * fetch step reports the real failure" -- but a caller that only asks THIS function before deciding
+ * whether to proceed (as `web-fetch.ts`'s own upfront gate does, ahead of a cache-hit) would treat an
+ * unresolvable name as safe to serve. There is no address to pin a decision to, so the honest answer
+ * is `private` (refuse), never `public` (silently proceed).
+ */
+/**
+ * Item 2: the ONE spelling of "resolution failed" -- shared so a caller that needs to tell "actually
+ * private" apart from "unknown, because DNS didn't answer" (`web-fetch.ts`'s own cache-hit refusal,
+ * which used to say "it is a private/loopback address" for BOTH) compares against this constant,
+ * never a re-typed literal that could drift from the one below.
+ */
+export declare const UNRESOLVABLE_HOST_REASON = "could not resolve any address for this host";
+export declare function classifyHostname(hostname: string, resolve: (hostname: string) => Promise<readonly string[]>): Promise<PrivateAddressFinding>;

package/dist/web/session-runtime.d.ts

@@ -0,0 +1,86 @@
+import type { CredentialRef, ResolvedWebToolsConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { MessageOrigin } from "@yanlinglabs/winter-provider-runtime";
+import type { Provider, ProviderUsage } from "../engine.js";
+import type { AuxiliaryModelResolution } from "../provider/session-provider.js";
+import type { ToolSecretResolver } from "../provider/tool-secret.js";
+/** The model a run is generating with RIGHT NOW -- live across `set_model` and a fallback. */
+export interface SessionModelHandle {
+    provider: Provider;
+    /**
+     * The session's live model string -- BOTH what an inner request carries as `model` (exactly what
+     * the main loop sends, so the adapter translates it identically) AND the key its usage is
+     * accounted under (so an inner generation lands on the SAME `modelUsage` row as the main loop's).
+     * `undefined` only for a scripted double started with no model string.
+     */
+    model: string | undefined;
+    /** Stamped onto the inner transcript's assistant messages so a real adapter replays them in-domain. */
+    origin?: MessageOrigin;
+}
+export interface WebSessionRuntime {
+    /** `RuntimeConfig.web` with every default applied (`resolveWebToolsConfig`). */
+    readonly web: ResolvedWebToolsConfig;
+    /**
+     * THE SESSION'S OWN MODEL, live. The default for every inner pass: always resolvable (the session
+     * is already generating on it) and needing no second credential. Read at CALL time, never cached
+     * by a consumer -- a `set_model` between two tool calls must move the inner pass with it.
+     */
+    sessionModel(): SessionModelHandle;
+    /**
+     * A STATED inner model (`web.fetch.digestModel`), by tag, under the cross-provider credential
+     * rule. ABSENT when the session has no catalog identity to resolve against (a scripted double, a
+     * session whose own model was refused): a stated tag is then unresolvable, and the consumer says
+     * so rather than falling back.
+     */
+    resolveAuxiliaryModel?: (tag: string, opts?: {
+        authRef?: CredentialRef;
+    }) => AuxiliaryModelResolution;
+    /**
+     * Folds ONE inner generation's usage into this run's accounting, exactly as far as a main-loop
+     * generation's goes and no further: it is SPEND (cumulative tokens, the cost ledger, and therefore
+     * `maxBudgetUsd`), and it is NOT context -- the inner prompt is never part of the session's next
+     * request, so it must not move the context reading compaction triggers on.
+     */
+    accountUsage(modelKey: string | undefined, usage: ProviderUsage): void;
+    /**
+     * Has this run crossed `maxBudgetUsd`? The main loop asks this only before ITS OWN requests, so an
+     * inner pass asks it before each of its generations -- otherwise a bounded inner loop is the one
+     * place a session could keep spending past its ceiling. OPTIONAL and additive: absent (a hand-built
+     * runtime, a run with no budget) reads as "no".
+     */
+    budgetExceeded?(): boolean;
+    /** Resolves a tool's secret from a ref. ABSENT for an engine run with no provider wiring (a bare `runEngine` over a double). */
+    resolveToolSecret?: ToolSecretResolver;
+}
+/**
+ * Registers `runtime` under `key` (`config.agentId ?? config.sessionId` -- a child shares its
+ * parent's session id, so the agent id is what tells them apart). Returns an IDENTITY-CHECKED
+ * disposer: a late teardown of a previous generation never removes the live one's registration.
+ */
+export declare function registerWebSessionRuntime(key: string, runtime: WebSessionRuntime): () => void;
+export declare function getWebSessionRuntime(key: string): WebSessionRuntime | undefined;
+/**
+ * The runtime for the engine run EXECUTING this tool call: the child's own when the call is a
+ * child's, else the session's. Falls back to the owning session's for a child whose own
+ * registration is missing, so a wiring gap degrades to "the parent's model" rather than to a tool
+ * that cannot run.
+ */
+export declare function webSessionRuntimeFor(ctx: {
+    sessionId: string;
+    agentId?: string;
+}): WebSessionRuntime | undefined;
+/** The three SESSION-level facts a child run inherits from the root's registration (see the header). */
+export declare function inheritedWebSessionFacts(sessionId: string): Pick<WebSessionRuntime, "web" | "resolveAuxiliaryModel" | "resolveToolSecret"> | undefined;
+/** Test hygiene only: the registry is a process-wide singleton and `bun test` shares one module graph. */
+export declare function resetWebSessionRuntimesForTest(): void;
+/** `winter.search-backend`'s session fact: the host has not switched the backend off. */
+export declare function searchBackendUsable(runtime: Pick<WebSessionRuntime, "web">): boolean;
+/**
+ * `winter.fetch-extractor`'s session fact: a digest model resolves.
+ *
+ * With no `digestModel` stated the digest runs on the session's own model, which resolves by
+ * construction. A STATED one must actually resolve -- it is never quietly replaced -- so an
+ * unresolvable tag withdraws the tool rather than advertising one that can only refuse. (Whether a
+ * CREDENTIAL exists for a cross-provider digest model is not knowable synchronously; that arrives as
+ * a typed refusal in the tool's result at the first generation.)
+ */
+export declare function digestModelResolves(runtime: Pick<WebSessionRuntime, "web" | "resolveAuxiliaryModel">): boolean;

package/dist/workflows/bridge.d.ts

@@ -0,0 +1,87 @@
+import type { AgentOpts } from "./types.js";
+import type { BudgetSnapshot } from "./budget.js";
+/** Worker -> parent. */
+export type BridgeRequest = {
+    op: "agent";
+    callId: number;
+    prompt: string;
+    opts?: AgentOpts;
+} | {
+    op: "workflow";
+    callId: number;
+    ref: WorkflowRef;
+    args?: unknown;
+} | {
+    op: "log";
+    message: string;
+} | {
+    op: "resumed";
+    cachedPrefix: number;
+} | {
+    op: "phase";
+    title: string;
+} | {
+    op: "done";
+    result: unknown;
+} | {
+    op: "error";
+    message: string;
+};
+/** WS-11 §1.6's `workflow(nameOrRef, args?)`: "a saved name or `{scriptPath}`". */
+export type WorkflowRef = {
+    name: string;
+} | {
+    scriptPath: string;
+};
+/**
+ * Parent -> worker: the reply to an `agent`/`workflow` request.
+ *
+ * `ok: true, value: null` is a MEANINGFUL, non-error outcome for `agent` -- WS-11 §1.6: "Resolves
+ * `null` when the user skips the agent or it dies on a terminal error -- callers filter with
+ * `.filter(Boolean)`." `ok: false` is reserved for the conditions that must THROW inside the script
+ * (the total-agent cap, the budget ceiling, an unresolvable nested workflow), because those are
+ * conditions a `.filter(Boolean)` must not be able to swallow.
+ */
+export type BridgeResponse = {
+    callId: number;
+    ok: true;
+    value: unknown;
+    budget?: BudgetSnapshot;
+} | {
+    callId: number;
+    ok: false;
+    error: string;
+    budget?: BudgetSnapshot;
+};
+/** The single init line the parent writes on spawn, before anything else. */
+export interface WorkerInit {
+    runId: string;
+    source: string;
+    args: unknown;
+    /** `min(16, CPUs - 2)`, resolved parent-side (semaphore.ts). */
+    concurrency: number;
+    /** WS-11 §1.6: 1000 total agents per run. Mirrored so the worker can fail fast; enforced parent-side regardless. */
+    totalAgentCap: number;
+    /** WS-11 §1.6: 4096 items max per `parallel`/`pipeline` call -- an EXPLICIT error, entirely in-worker (the parent never sees the array). */
+    maxItemsPerCall: number;
+    budget: BudgetSnapshot;
+    /** WS-11 §1.5: the prior run's ordered agent() results. Absent/empty for a fresh run. */
+    resumeJournal?: Array<{
+        promptKey: string;
+        value: unknown;
+    }>;
+}
+/**
+ * The framing both ends share. Deliberately a FUNCTION over a string buffer rather than a class:
+ * the worker and the runtime both need it, the worker's copy is bundled into the compiled binary,
+ * and a shared pure function has no lifecycle to get wrong on either side.
+ *
+ * Returns the complete lines found and the unconsumed remainder, which the caller carries forward --
+ * a `data` chunk may split a line in half or coalesce ten of them.
+ */
+export declare function splitNdjson(buffer: string): {
+    lines: string[];
+    rest: string;
+};
+/** One NDJSON frame, terminator included. One place, so the two ends cannot disagree about the newline. */
+export declare function encodeNdjson(value: unknown): string;

package/dist/workflows/budget.d.ts

@@ -0,0 +1,24 @@
+/** What crosses the bridge so the worker's own `budget` object can answer without a round trip. */
+export interface BudgetSnapshot {
+    total: number | null;
+    spent: number;
+}
+export interface WorkflowBudget {
+    /** `null` = no ceiling. THE DEFAULT (WS-11 §1.6 as amended by the task brief). */
+    readonly total: number | null;
+    spent(): number;
+    remaining(): number;
+    /** True once `spent() >= total`. Always false when `total` is null. */
+    exceeded(): boolean;
+    snapshot(): BudgetSnapshot;
+}
+export interface BudgetDeps {
+    /**
+     * The session's CUMULATIVE token spend (RULING P5-J). Absent = 0, never `contextTokens()` -- see
+     * this module's header for why substituting that quantity is worse than reporting nothing.
+     */
+    spentTokens?: () => number;
+    /** Omitted (or null) = no ceiling. */
+    total?: number | null;
+}
+export declare function createBudget(deps: BudgetDeps): WorkflowBudget;

package/dist/workflows/host-registry.d.ts

@@ -0,0 +1,142 @@
+import type { BrandProfile, SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import type { RuntimeAgentDefinition } from "@yanlinglabs/winter-agent-sdk";
+import type { ContextAccountant } from "../engine.js";
+import type { StructuredOutputSeam } from "../structured/seam.js";
+export interface WorkflowSessionRuntime {
+    /**
+     * THE REGISTRATION KEY (fix wave, whole-branch I5). The engine's own `config.sessionId`.
+     *
+     * OPTIONAL ONLY FOR COMPILE COMPATIBILITY, and the omission is not the intended shape: an
+     * unkeyed registration lands in the single legacy slot below, which is exactly the
+     * one-live-session-per-process assumption I5 is about. `engine.ts` (the sole production
+     * registrant) is another lane's file in this wave and still omits it -- see this module's own
+     * "PRODUCTION WIRING" note.
+     *
+     * A CHILD engine reaches the registration site with its PARENT's `config.sessionId`, which is why
+     * registration is FIRST-WINS: see `registerWorkflowSession`.
+     */
+    sessionId?: string;
+    /** The winter root this session persists under -- `resolveWinterHome()`'s value, whose `projects/` child holds the session area. */
+    winterHome: string;
+    /**
+     * SV-5 fix round 3: the DISCOVERY root a nested `workflow(name)` call's project/user tier
+     * resolution reads (`resolveWorkflowByName`'s `winterHome` -- the user tier's
+     * `<winterHome>/workflows`) -- DELIBERATELY DISTINCT from `winterHome` above, which is the
+     * DURABLE persist root (`storeHome ?? winterHome`) capture (3)'s script path is built from.
+     * Conflating the two would read the user tier from the wrong root whenever a router-linked run
+     * has a `storeHome` that differs from its per-run `winterHome` -- exactly the SV-1/SV-2 bug class
+     * this field exists to not repeat. Absent means the nested resolver's user tier stays inert,
+     * matching every pre-fix-round-3 caller.
+     */
+    discoveryWinterHome?: string;
+    /** P7a (D19): the session's brand -- the project dot-dir a `workflow(name)` resolves under, and the worker seatbelt's fences. */
+    brand?: BrandProfile;
+    /** SV-5 fix round 3 (I-4): threaded to `resolveWorkflowByName` so a nested call's project/user tier resolution is source-gated exactly like the top-level Workflow tool. */
+    settingSources?: readonly SettingSource[];
+    /**
+     * WS-21 §6.3 item 1 (batch-2 fix round): the session's ENABLED plugins that ship a `workflows/`
+     * directory -- threaded to `defaultNestedResolver` (workflows/runtime.ts) so a nested
+     * `workflow("plugin:name")` call resolves a plugin workflow exactly like the top-level Workflow
+     * tool does (tools/impl/workflow.ts). Absent means a qualified name never resolves here either,
+     * matching every pre-fix caller.
+     *
+     * Fix round 4 (minors, M-3's last bullet): also carries `workflowsPaths` -- see
+     * `engine.ts`'s `EngineOptions.pluginWorkflows` for why every hop widened rather than gaining a
+     * new field.
+     */
+    pluginWorkflows?: readonly {
+        name: string;
+        workflowsPath?: string;
+        workflowsPaths?: readonly string[];
+    }[];
+    /** `compatibilityKeys(cwd).transcriptProjectKey`, after `resolveProjectDirName` -- the SAME key the transcript store uses, never a second derivation. */
+    projectKey: string;
+    /** The session's own temp directory (paths/temp.ts) -- where per-run journals live (store.ts's `workflowRunsDir`). */
+    sessionTempDir: string;
+    /** Borrowed from Lane K through the seam (R5-12's named W->K coupling) -- never a second validator. */
+    structured: StructuredOutputSeam;
+    /** The session's live context accounting. Passed straight to `WorkflowRunHost.accountant`. */
+    accountant: ContextAccountant;
+    /**
+     * The session's CUMULATIVE token spend, for `budget.spent()` -- RULING P5-J (spine, fix wave).
+     *
+     * Deliberately NOT `accountant.contextTokens()`, which is the last provider call's context SIZE:
+     * an overwrite rather than an accumulation, non-monotonic, and blind to a workflow's own agents
+     * (each child builds its own accountant). Absent = `spent()` reports 0 and a ceiling never trips,
+     * which is honest; substituting the wrong quantity would look plausible and bound nothing.
+     *
+     * P5-J is expected to add the counter to `ContextAccountant` and route child usage into the
+     * parent's; when it lands, T8 wires that accessor here.
+     */
+    spentTokens?: () => number;
+    /**
+     * The workflow budget ceiling, if the host set one. `null`/absent is the DEFAULT and means no
+     * ceiling (WS-11 §1.6 as amended by the task brief). No `WorkflowInput` field carries this -- it is
+     * a host/session-level setting, which is why it arrives here rather than through the tool call.
+     */
+    budgetTotal?: number | null;
+    /**
+     * Resolves `agent({ agentType })` against the SAME registry the Agent tool uses (WS-11 §1.6:
+     * "a custom subagent type resolved from the same registry as the Agent tool"). Injected rather
+     * than called directly so this module keeps no dependency on `subagents/definitions.ts`, and so a
+     * host that has already loaded its definitions does not make the runtime re-read the filesystem
+     * once per `agent()` call.
+     *
+     * Absent = no custom types resolve; `agent({agentType})` then spawns a child whose definition
+     * records the unresolved name (runtime.ts's `resolveChildDefinition`), never a silent generic one.
+     */
+    resolveAgentType?(agentType: string, ctx: {
+        cwd: string;
+        trustedWorkspace: boolean;
+    }): RuntimeAgentDefinition | undefined;
+}
+/**
+ * Register this session's runtime and return an IDENTITY-CHECKED disposer (the shape
+ * `registerSessionMcpLifecycle` already uses): the disposer withdraws the registration only while it
+ * is still the one this call made, so a stopped-and-immediately-restarted run's late teardown cannot
+ * remove the live generation's runtime.
+ *
+ * FIRST-WINS PER SESSION ID, deliberately. A CHILD engine reaches the production registration site
+ * (`engine.ts`) with `config.sessionId` -- which for a child IS the parent's id -- because the child
+ * is given the parent's structured-output seam, the condition that site gates on. Last-wins would
+ * therefore let a child replace its parent's registration mid-run (different `sessionTempDir`,
+ * different `projectKey`) and withdraw it at the child's teardown: the daemon defect, reachable
+ * inside one session. First-wins makes the child's register/dispose pair a no-op, which is also the
+ * "children resolve against the parent's registration" reading the seam already documents.
+ *
+ * PRODUCTION WIRING IS **NEEDS_CONTEXT** (this wave's lane split): `engine.ts` is another lane's
+ * file, so its two call sites still pass no `sessionId` and still call `clearWorkflowSession()` with
+ * no argument -- which is why the legacy slot below exists and why production behaviour is BYTE
+ * IDENTICAL to the pre-fix build until those two lines change to
+ * `registerWorkflowSession({ sessionId: config.sessionId, ... })` and `disposeWorkflowSession?.()`.
+ */
+export declare function registerWorkflowSession(runtime: WorkflowSessionRuntime): () => void;
+/**
+ * The runtime registered for `sessionId`, or the legacy unkeyed one when no keyed registration
+ * exists for it (the pre-I5 production path, unchanged). `undefined` when nothing is registered at
+ * all -- the Workflow tool answers a typed tool error rather than crashing.
+ */
+export declare function getWorkflowSession(sessionId?: string): WorkflowSessionRuntime | undefined;
+/**
+ * Withdraw one session's registration. PRODUCTION teardown calls this (engine.ts, at the end of
+ * every run) for the reason the registration shape makes concrete: a run that left its registration
+ * standing would let a LATER session's Workflow call persist its script under the finished session's
+ * `projects/<key>/<uuid>/` directory.
+ *
+ * With no argument it clears the LEGACY slot only -- never the whole map. Clearing every session
+ * would reinstate I5 in the other direction: one run's teardown disabling every other live session's
+ * workflows.
+ *
+ * AT ENGINE TEARDOWN, USE THE DISPOSER `registerWorkflowSession` RETURNS -- never
+ * `clearWorkflowSession(config.sessionId)`. First-wins protects REGISTRATION from a child engine
+ * (which arrives with its parent's `config.sessionId`); only the identity-checked disposer protects
+ * WITHDRAWAL from the same child, whose teardown would otherwise delete its still-running parent's
+ * entry by key. This by-key form is for a host that is genuinely ending that session.
+ */
+export declare function clearWorkflowSession(sessionId?: string): void;
+/**
+ * Test-only: clears EVERY registration, keyed and legacy. Same rationale as every sibling singleton
+ * in this codebase: bun's test runner shares ONE module instance across every file in a run, so one
+ * file's registration would otherwise leak into another's assertions.
+ */
+export declare function resetWorkflowSessionForTest(): void;

package/dist/workflows/journal.d.ts

@@ -0,0 +1,29 @@
+import type { AgentOpts } from "./types.js";
+export interface JournalEntry {
+    promptKey: string;
+    value: unknown;
+}
+/**
+ * The positional cache key: `(prompt, opts)` serialized. WS-11 §1.5's "a per-run journal keyed by
+ * call order + prompt/opts key" -- the ORDER is the array index, this is the identity check at that
+ * index. `undefined` opts normalize to `null` so `agent("go")` and `agent("go", undefined)` are the
+ * same call, which they are.
+ */
+export declare function promptKey(prompt: string, opts?: AgentOpts): string;
+export declare class RunJournal {
+    private readonly path;
+    constructor(dir: string, runId: string);
+    append(promptKeyValue: string, value: unknown): void;
+    /** Escape hatch for the corrupt-line test -- a real caller always uses `append`. */
+    appendRaw(line: string): void;
+    /**
+     * The journal's readable prefix. A missing file is an empty array (a fresh run has no journal),
+     * and a CORRUPT line is skipped rather than fatal: a run killed mid-append leaves a partial last
+     * line, and refusing to resume at all because of it would be strictly worse than resuming the
+     * complete entries that precede it. The positional replay in script-api.ts diverges at the first
+     * key mismatch anyway, so a skipped line can only ever shorten the cached prefix, never
+     * misalign it -- a dropped middle entry shifts the entries after it, and the very next key
+     * comparison fails and latches `diverged`, sending everything from there on live.
+     */
+    load(): JournalEntry[];
+}

package/dist/workflows/meta.d.ts

@@ -0,0 +1,45 @@
+/** A declared phase (WS-11 §1.2). `title` is matched against `phase()` calls EXACTLY. */
+export interface WorkflowMetaPhase {
+    title: string;
+    detail?: string;
+    model?: string;
+}
+export interface WorkflowMeta {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    phases?: WorkflowMetaPhase[];
+    /** Any further literal keys the author wrote. Preserved, never interpreted -- this parser validates the SHAPE it is specified to validate and does not silently drop what it does not know. */
+    [key: string]: unknown;
+}
+export type ParsedWorkflowMeta = {
+    ok: true;
+    meta: WorkflowMeta;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses and validates a script's `meta` block.
+ *
+ * Never throws and never evaluates: every failure -- absent block, non-literal value, missing
+ * required key, malformed `phases` -- comes back as `{ ok: false, error }`. The Workflow tool turns
+ * that into a `WorkflowOutput` carrying `error` (derived-shapes-p5 item (g): a script that fails the
+ * syntax check still RETURNS a WorkflowOutput, it does not throw).
+ */
+export declare function parseWorkflowMeta(source: string): ParsedWorkflowMeta;
+/** The resolution of one `phase(title)` call against the declared phases. */
+export interface PhaseGroup extends WorkflowMetaPhase {
+    /** true when `title` matched a declared `meta.phases` entry EXACTLY. */
+    declared: boolean;
+}
+/**
+ * WS-11 §1.2's own rule, at the one point it actually applies -- when a `phase()` call arrives over
+ * the bridge, not at parse time: "phase titles match `phase()` calls exactly; an unmatched `phase()`
+ * call gets its own progress group."
+ *
+ * A near-miss is deliberately NOT fuzzy-matched to a declared phase: a script that mistypes a phase
+ * title gets a visible extra group, which is a diagnosable outcome, rather than silently landing in
+ * the wrong one.
+ */
+export declare function matchPhaseGroup(declared: readonly WorkflowMetaPhase[] | undefined, title: string): PhaseGroup;

package/dist/workflows/registry.d.ts

@@ -0,0 +1,24 @@
+import type { WorkflowCounts, WorkflowRunView } from "./types.js";
+export declare class WorkflowRegistry {
+    private readonly runs;
+    register(entry: {
+        runId: string;
+        sessionId: string;
+        taskId: string;
+        name: string;
+        abort: AbortController;
+        startedAt?: number;
+    }): void;
+    setPhase(runId: string, phase: string): void;
+    setCounts(runId: string, counts: WorkflowCounts): void;
+    /** `running -> completed | failed`. No-op if unknown or already terminal. */
+    complete(runId: string, outcome: {
+        ok: boolean;
+        result: string;
+    }): void;
+    fail(runId: string, error: string): void;
+    /** `running -> stopped`, firing the run's abort. Returns false if unknown or already terminal. */
+    stop(runId: string): boolean;
+    get(runId: string): WorkflowRunView | undefined;
+    list(sessionId: string): WorkflowRunView[];
+}