@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/workflows/runtime.d.ts

@@ -0,0 +1,254 @@
+import { type JournalEntry } from "./journal.js";
+import { type WorkerCommand } from "./sandbox.js";
+import type { SandboxBrand } from "../sandbox/profile.js";
+import type { BrandProfile, SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import { type WorkflowRef } from "./bridge.js";
+import type { WorkflowSessionRuntime } from "./host-registry.js";
+import { type WorkflowMeta } from "./meta.js";
+import type { WorkflowRunView, WorkflowStatus } from "./types.js";
+import type { WorkflowRunHost } from "./seam.js";
+/** WS-11 §1.6's own three numbers, in one place so nothing re-derives them. */
+export declare const TOTAL_AGENTS_PER_RUN = 1000;
+export declare const MAX_ITEMS_PER_CALL = 4096;
+/** A typed launch/resume refusal -- `code` so a tool executor can render each case differently without matching on message text. */
+export declare class WorkflowRuntimeError extends Error {
+    readonly code: "unknown-run" | "cross-session" | "not-stopped" | "sandbox-unavailable" | "no-source";
+    constructor(code: "unknown-run" | "cross-session" | "not-stopped" | "sandbox-unavailable" | "no-source", message: string);
+}
+export interface WorkerProcess {
+    stdin: NodeJS.WritableStream;
+    stdout: NodeJS.ReadableStream;
+    pid?: number;
+    onExit(cb: (code: number | null) => void): void;
+    onError(cb: (err: Error) => void): void;
+    kill(): void;
+}
+export type WorkerSpawner = (command: WorkerCommand, opts: {
+    home?: string;
+    winterHome?: string;
+    brand?: SandboxBrand;
+    cwd?: string;
+}) => WorkerProcess;
+/**
+ * The production spawner: `sandbox-exec -p <profile> <worker>`, its own process-group leader.
+ *
+ * `sandbox: false` spawns the worker DIRECTLY, with no seatbelt. It exists for exactly one caller --
+ * `scripts/verify-workflow.ts` on a host that has no `/usr/bin/sandbox-exec` (the linux CI runner),
+ * where that gate's subject is the COMPILED ARGV DISPATCH and refusing to run at all would leave that
+ * leg unverified. It is NOT a production posture and nothing in the runtime reaches it: `launch`
+ * refuses outright when the sandbox is required and unavailable, and the seatbelt's own claims are
+ * proved separately in `workflows/worker.darwin.test.ts`.
+ */
+export declare function realWorkerSpawner(opts?: {
+    sandbox?: boolean;
+}): WorkerSpawner;
+export interface WorkflowRuntimeDeps {
+    session: WorkflowSessionRuntime;
+    caps?: {
+        concurrency?: number;
+        totalAgents?: number;
+        maxItemsPerCall?: number;
+    };
+    /** Test seam. Defaults to `realWorkerSpawner()`. */
+    spawnWorker?: WorkerSpawner;
+    /** Test seam over the worker COMMAND (pre-sandbox). Defaults to the compiled-vs-dev split. */
+    workerCommand?: () => WorkerCommand;
+    /** Overridable resolver for a nested `workflow(nameOrRef)`. Defaults to store.ts's project resolution. */
+    resolveNestedWorkflow?: (ref: WorkflowRef, ctx: {
+        cwd: string;
+        trustedWorkspace: boolean;
+        brand?: BrandProfile;
+        pluginWorkflows?: readonly {
+            name: string;
+            workflowsPath?: string;
+            workflowsPaths?: readonly string[];
+        }[];
+        winterHome?: string;
+        settingSources?: readonly SettingSource[];
+    }) => Promise<{
+        ok: true;
+        source: string;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Skips the `sandbox-exec` availability refusal. Only a non-default spawner has any business setting this. */
+    requireSandbox?: boolean;
+}
+export interface WorkflowLaunchInput {
+    sessionId: string;
+    cwd: string;
+    trustedWorkspace: boolean;
+    source: string;
+    meta: Pick<WorkflowMeta, "name" | "description"> & Partial<WorkflowMeta>;
+    args?: unknown;
+    /**
+     * The MODEL's own `tool_use` id for the Workflow call (F11). REQUIRED, and deliberately so: WS-10
+     * §4 correlates a child's forwarded frames on `SpawnChildRequest.parentToolUseId`, and the previous
+     * `?? run.task.taskId` fallback quietly substituted a task id -- a different id space entirely, and
+     * exactly the class of fabricated-value-on-a-pinned-field that this lane already removed once from
+     * `task_started.workflow_name`. The tool executor refuses the call outright when `ctx.toolUseId` is
+     * absent rather than inventing one here.
+     */
+    parentToolUseId: string;
+    /** Only `resume` supplies these; a fresh launch never does. */
+    runId?: string;
+    resumeJournal?: JournalEntry[];
+}
+export interface WorkflowLaunchResult {
+    taskId: string;
+    runId: string;
+    /**
+     * `meta.name` VERBATIM -- item (g) doc-asserts (`4061`) that `WorkflowOutput.workflowName` is
+     * `meta.name` and equals `task_started.workflow_name`. It is threaded rather than recovered from
+     * the persisted filename, because that filename is SANITIZED (`store.ts`'s `sanitizeFileStem`):
+     * a `meta.name` of `My Workflow!` persists as `My-Workflow-<runId>.js`, so a filename-derived name
+     * would silently disagree with the pin for every name outside the slug alphabet.
+     */
+    name: string;
+    scriptPath: string;
+    transcriptDir: string;
+    status: WorkflowStatus;
+    summary: string;
+}
+export declare class WorkflowRuntime {
+    private readonly deps;
+    private readonly registry;
+    private readonly live;
+    private readonly settlers;
+    /** Kept beside `live` because `finish` runs AFTER teardown deleted the LiveRun and still has to settle the task. */
+    private readonly tasks;
+    /** A-14: same reason as `tasks` -- the terminal record is written after the LiveRun is gone. */
+    private readonly transcripts;
+    /** Each run's source + launch context, so `resume` can replay it verbatim. Never pruned -- one string per run this session launched. */
+    private readonly launches;
+    private readonly runsDir;
+    private readonly concurrency;
+    private readonly totalAgents;
+    private readonly maxItemsPerCall;
+    private readonly spawnWorker;
+    constructor(deps: WorkflowRuntimeDeps);
+    launch(input: WorkflowLaunchInput, host: WorkflowRunHost): WorkflowLaunchResult;
+    /**
+     * WS-11 §1.5: a same-session resume of a STOPPED run, replaying its journal.
+     *
+     * Both preconditions are the pin's own (`sdk-tools.d.ts:2786`: "same-session only, with the prior
+     * run stopped first via TaskStop") and both are typed refusals rather than silent no-ops -- this
+     * launches a subprocess, so a typo'd runId failing loudly is worth more than a quiet nothing.
+     * `sessionId` is taken from the CALLER, never from the input, so a run cannot be resumed into a
+     * session that did not own it.
+     *
+     * RULING I6 (fix wave) -- `opts.replacement` / `opts.args`: a resume that supplies a NEW source
+     * (the model edited the persisted script between the stop and the resume, which is exactly what
+     * WS-11 §1.3's loop tells it to do) runs the NEW source against the OLD journal. The positional
+     * replay then diverges at the first changed call and everything from there runs live, which is
+     * §1.5's own contract. This used to rebuild the launch from `this.launches` unconditionally, so a
+     * `{scriptPath: <edited>, resumeFromRunId}` call silently re-ran the PRIOR source and a changed
+     * `args` was dropped -- the edit loop's own door was the one input the door ignored. With neither
+     * supplied, the original launch input is replayed verbatim (the ruling's other half).
+     */
+    resume(runId: string, sessionId: string, host: WorkflowRunHost, opts?: {
+        parentToolUseId?: string;
+        /**
+         * The edited script AND its re-parsed meta, together: `meta.name` is what the new run's task,
+         * persisted filename and `WorkflowOutput.workflowName` are built from, so carrying the source
+         * without re-parsing the meta would label the edited run with the old script's name.
+         */
+        replacement?: {
+            source: string;
+            meta: WorkflowLaunchInput["meta"];
+        };
+        /** Supplied = the new args; OMITTED = the original launch's args, unchanged. */
+        args?: unknown;
+    }): WorkflowLaunchResult;
+    stop(runId: string): boolean;
+    get(runId: string): WorkflowRunView | undefined;
+    list(sessionId: string): WorkflowRunView[];
+    /** Resolves when the run reaches a terminal state. An already-terminal or unknown run resolves immediately. */
+    await(runId: string): Promise<WorkflowRunView>;
+    /**
+     * Whether a run reached `stopped` (as opposed to `failed`). The frozen `WorkflowTaskHandle` has no
+     * `stop()`, so this is how a host renders the third terminal state truthfully -- see
+     * `tools/impl/workflow.ts`'s `fail` implementation.
+     */
+    wasStopped(runId: string): boolean;
+    /** Test-only: simulates an external kill, for the crash-fallback path. */
+    killWorkerForTest(runId: string): void;
+    private onWorkerMessage;
+    private reply;
+    /**
+     * The authoritative half of every cap. Checked in this order, deliberately:
+     *   1. the TOTAL cap, before the semaphore -- a run pinned at capacity must fail fast rather than
+     *      queue behind work that can never help it (Norma's original ordering, kept);
+     *   2. the BUDGET ceiling, for the same reason;
+     *   3. only then a slot.
+     */
+    private serviceAgent;
+    /**
+     * Spawns one child and resolves what `agent()` should see.
+     *
+     * NULL, not a throw, for every terminal child OUTCOME (WS-11 §1.6: "Resolves `null` when the user
+     * skips the agent or it dies on a terminal error") -- a failed child, a stopped child, a child
+     * whose text does not validate.
+     *
+     * A `spawnAgent` that THROWS is NOT one of those (whole-branch m5). It means the HOST could not
+     * start an agent at all -- `tools/impl/workflow.ts` throws exactly that when the session has no
+     * child-spawn capability -- and `script-api.ts`'s own contract lists "no spawn capability at all"
+     * beside the agent cap and the budget ceiling as the refusals a script must not be able to
+     * swallow. This used to fold it into the same `null`, so a workflow in a session with no spawn
+     * capability "completed" with `.filter(Boolean)`-swallowed empties and the real cause appeared
+     * nowhere. It now comes back as a refusal, which `serviceAgent` turns into the same
+     * teardown-then-`ok:false` the caps use. Nothing escapes as an unhandled rejection either way.
+     */
+    private spawnAndAwaitChild;
+    /**
+     * `agent({schema})` rides `SpawnChildRequest.outputFormat` (T3's Lane W item 5) -- the child is put
+     * on the identical `StructuredOutput` mechanism the top-level session uses, never a second one.
+     *
+     * CLOSED by RULING P5-I (Phase 5 fix wave). `ChildResult.structuredOutput` now carries the child's
+     * own validated object, so `agent({schema})` returns it directly. This function is the FALLBACK
+     * for a child that produced none: it parses the child's text and re-validates it through
+     * `host.structured` -- the same validator, so no second opinion is introduced -- and resolves NULL
+     * when there is nothing valid, which is the "died on a terminal error" arm of the same rule.
+     *
+     * The gap it used to be: `child-engine.ts`'s `observe` read `message.result`, which the engine's
+     * structured SUCCESS variant does not set (it carries `structured_output` and no `result`), so a
+     * child forced onto `StructuredOutput` -- which is every schema'd call -- resolved `null`.
+     */
+    private validateStructured;
+    private buildSpawnRequest;
+    /**
+     * `agentType` and `effort` BOTH arrive as the child's DEFINITION, because that is the only route
+     * either has: `SpawnChildRequest` carries `definition` and no `effort` at all, and engine.ts's own
+     * `buildChildInheritance` reads effort exclusively from `req.definition?.effort` (engine.ts:1236,
+     * whose comment says so outright: "AgentInput/SpawnChildRequest carry no effort field at all").
+     *
+     * With `effort` and no `agentType`, a MINIMAL definition is synthesized. That is safe rather than
+     * clever: `buildChildInheritance`'s base for a bare child is already `systemPrompt: ""`, an absent
+     * `tools` inherits the parent's whole advertised pool, and an absent `permissionMode` changes
+     * nothing -- so the synthesized definition differs from a bare child in exactly the one field it
+     * exists to carry.
+     */
+    private resolveChildDefinition;
+    /** A nested `workflow(nameOrRef)`: resolved PARENT-side, because the worker can read no files. */
+    private serviceNestedWorkflow;
+    /**
+     * `phase` is the group this progress report belongs to (F2): an agent's own `opts.phase` when it
+     * supplied one, otherwise the run's current global phase. Passing it explicitly is the whole point
+     * -- WS-11 §1.6 gives `opts.phase` the job of "avoiding races on the global `phase()` state inside
+     * `pipeline`/`parallel` stages", and reading the ambient phase here would reintroduce exactly that
+     * race for two agents running concurrently under different phases.
+     */
+    private syncCounts;
+    /**
+     * `usage` is filled on EVERY progress report, not just where it is convenient. `WorkflowProgress`
+     * types it optional, but the pinned `task_progress` message it lands on makes the triple REQUIRED
+     * (frames.ts) -- so a host mapping this to the wire would otherwise have to invent the numbers.
+     * All three are real readings: tokens from the session accountant, `tool_uses` from this run's own
+     * agent count, `duration_ms` from the parent's wall clock (the worker has no clock -- `Date.now` is
+     * withheld inside it by design).
+     */
+    private emitProgress;
+    private teardown;
+    private finish;
+}

package/dist/workflows/sandbox.d.ts

@@ -0,0 +1,49 @@
+import { type SandboxBrand } from "../sandbox/profile.js";
+import { WORKFLOW_WORKER_ARGV_FLAG, WORKFLOW_WORKER_BRIDGE_FLAG } from "./subprocess-entry.js";
+export { WORKFLOW_WORKER_ARGV_FLAG, WORKFLOW_WORKER_BRIDGE_FLAG };
+declare const SANDBOX_EXEC_PATH = "/usr/bin/sandbox-exec";
+export interface WorkerCommand {
+    file: string;
+    args: string[];
+}
+export interface ResolveWorkerCommandOptions {
+    /**
+     * Overridable for tests; defaults to a real detection of the single-file `$bunfs` executable.
+     * Stating either field bypasses a host command installed by `setHostWorkflowWorkerCommand`.
+     */
+    compiled?: boolean;
+    execPath?: string;
+}
+/** True inside a `bun build --compile` single-file executable. */
+export declare function isCompiledBinary(): boolean;
+/**
+ * Install the host's workflow-worker command for this realm; returns a restore function. `undefined`
+ * clears it (the default applies again). The command is copied, so a caller mutating its own object
+ * afterwards changes nothing here.
+ */
+export declare function setHostWorkflowWorkerCommand(command: WorkerCommand | undefined): () => void;
+export declare function resolveWorkerCommand(opts?: ResolveWorkerCommandOptions): WorkerCommand;
+export interface BuildWorkerSpawnOptions {
+    command: WorkerCommand;
+    /**
+     * The session's WINTER HOME. Supplying it is what emits the run-directory read-deny (R5-5);
+     * `undefined` opts out EXPLICITLY, which is the only way to opt out now that the profile builder's
+     * own argument is required. Every production call site passes a real value, and worker.test.ts pins
+     * the difference between the two profiles.
+     */
+    home?: string;
+    /**
+     * The RESOLVED Winter home (fix wave I1, the resolved-home class): when it is not
+     * `<home>/<homeDirName>`, the profile ALSO denies `<winterHome>/run` -- a `<PREFIX>HOME` pointing
+     * at a differently-named root is otherwise unprotected. Both anchors are emitted; overlapping
+     * denies cost nothing.
+     */
+    winterHome?: string;
+    /** P7a (D19): the session's brand -- the dot-dir names the worker profile fences. */
+    brand?: SandboxBrand;
+}
+/** The actual `(file, args)` to spawn: sandbox-exec wrapping the worker command under the tight profile. */
+export declare function buildWorkerSpawn(opts: BuildWorkerSpawnOptions): WorkerCommand;
+/** WS-12 §3's own availability rule, reused rather than re-derived. */
+export declare function workflowSandboxAvailable(): boolean;
+export { SANDBOX_EXEC_PATH };

package/dist/workflows/script-api.d.ts

@@ -0,0 +1,58 @@
+import { type JournalEntry } from "./journal.js";
+import type { BudgetSnapshot } from "./budget.js";
+import type { AgentOpts } from "./types.js";
+import type { WorkflowRef } from "./bridge.js";
+/**
+ * What the bridge answers for one `agent()` call.
+ *
+ * The `ok: true, value: null` / `ok: false` split IS the WS-11 §1.6 contract, expressed in the type:
+ * a skipped or terminally-failed agent RESOLVES null (so `.filter(Boolean)` works, which is what the
+ * spec tells authors to write), while a refusal the script must not be able to swallow -- the agent
+ * cap, the budget ceiling, no spawn capability at all -- comes back `ok: false` and THROWS.
+ */
+export type AgentBridgeResult = {
+    ok: true;
+    value: unknown;
+    budget?: BudgetSnapshot;
+} | {
+    ok: false;
+    error: string;
+    budget?: BudgetSnapshot;
+};
+export type WorkflowResolveResult = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface ScriptApiDeps {
+    source: string;
+    args: unknown;
+    concurrency: number;
+    totalAgentCap: number;
+    maxItemsPerCall: number;
+    budget: BudgetSnapshot;
+    agent(prompt: string, opts?: AgentOpts): Promise<AgentBridgeResult>;
+    /** Resolves a nested `workflow(nameOrRef)` to its SOURCE. Parent-side: the worker cannot read the project workflows dir. */
+    resolveWorkflow(ref: WorkflowRef, args: unknown): Promise<WorkflowResolveResult>;
+    phase(title: string): void;
+    log(message: string): void;
+    /** F8: called ONCE, with how many leading `agent()` calls replayed from the resume journal. */
+    reportCachedPrefix?(count: number): void;
+    /** WS-11 §1.5: the prior run's ordered `agent()` results. Absent/empty for a fresh run. */
+    resumeJournal?: JournalEntry[];
+}
+export interface ScriptRunResult {
+    meta: unknown;
+    result: unknown;
+}
+/**
+ * Compiles and runs one workflow body, returning its captured `meta` and its `return` value.
+ *
+ * Throws only for the conditions WS-11 §1.6/§1.8 say must throw: a syntax error, a determinism-guard
+ * violation, a cap breach, a budget ceiling, an unresolvable or over-nested `workflow()`, or whatever
+ * the body itself threw. Everything a script is meant to be able to absorb (`parallel`'s failing
+ * thunk, a skipped agent) resolves instead.
+ */
+export declare function runWorkflowScript(deps: ScriptApiDeps): Promise<ScriptRunResult>;

package/dist/workflows/seam.d.ts

@@ -0,0 +1,92 @@
+import type { ContextAccountant } from "../engine.js";
+import type { ChildHandle, SpawnChildRequest } from "../subagents/child-handle.js";
+import type { StructuredOutputSeam } from "../structured/seam.js";
+/**
+ * A running workflow's progress. WINTER-DEFINED (the pinned surface has no workflow-progress type),
+ * but shaped to land on the pinned `task_progress` message without a second mapping: that message's
+ * `usage` triple is REQUIRED and is `{total_tokens, tool_uses, duration_ms}`, so a progress report
+ * that could not fill all three would produce a frame the pin cannot accept.
+ *
+ * `running`/`completed`/`total` are WS-11 §1.8's own step counters.
+ */
+export interface WorkflowProgress {
+    running: number;
+    completed: number;
+    total: number;
+    /** Free-form, model-facing; lands on `task_progress.summary`. */
+    summary?: string;
+    /** Lands on `task_progress.last_tool_name`. */
+    lastToolName?: string;
+    /**
+     * Phase 5 Task 8 (rider 27): the PHASE GROUP this report belongs to, structurally.
+     *
+     * Lane W's NEEDS_CONTEXT 7: WS-11 §1.2's "an unmatched `phase()` gets its own group" was honoured
+     * in the runtime's own state and reflected in the progress TEXT (`"Title: detail"` for a declared
+     * phase versus a bare `"Title"` for an ad-hoc one), but a host rendering a progress tree could not
+     * reconstruct the grouping -- it had to parse prose, and a declared phase whose entry carries no
+     * `detail` renders identically to an ad-hoc one, so the prose is not even a reliable signal.
+     *
+     * `declaredPhase` distinguishes the two cases the text cannot.
+     *
+     * WHAT THIS DOES NOT DO, stated at the field because a reader will look for it: neither value
+     * reaches the WIRE. The pinned `task_progress` message (WS-06 §3.5) carries
+     * `summary`/`last_tool_name`/`usage` and no phase field, and putting a Winter-invented key on a
+     * pinned frame is precisely the divergence class this phase refuses. So the grouping is legible to
+     * a host that consumes the SEAM, and on the wire it remains prose. Closing that half needs either
+     * a captured pinned field or a deliberate disclosed extension -- neither of which T8 may invent.
+     */
+    phase?: string;
+    /** True when `phase` matched a declared `meta.phases` entry rather than being an ad-hoc `phase()` call. */
+    declaredPhase?: boolean;
+    usage?: {
+        total_tokens: number;
+        tool_uses: number;
+        duration_ms: number;
+    };
+}
+/**
+ * The handle one workflow RUN holds. `complete`/`fail` are terminal and idempotent -- a worker that
+ * crashes after reporting completion must not be able to re-fail its own task (WS-11 §1.8's
+ * `running -> completed | failed | stopped` is a one-way lifecycle).
+ */
+export interface WorkflowTaskHandle {
+    taskId: string;
+    emit(progress: WorkflowProgress): void;
+    complete(result: unknown): void;
+    fail(error: string): void;
+}
+export interface WorkflowRunHost {
+    /**
+     * Registers this run as a background task. `kind` is the single literal `"workflow"` -- Winter's
+     * INTERNAL `BackgroundTaskKind` spelling. It is NOT what goes on the wire: capture (3) and item (g)
+     * both pin `task_started.task_type` / `WorkflowOutput.taskType` as `"local_workflow"`, and
+     * `tools/background-tasks.ts`'s own `wireTaskType(kind)` is the one mapping between them. A lane
+     * that hand-writes either spelling at an emission site is the drift this split exists to prevent.
+     */
+    createTask(kind: "workflow", meta: {
+        runId: string;
+        name: string;
+    }): WorkflowTaskHandle;
+    /** Spawns a child agent -- the SAME path the Agent tool uses, so `agent({schema})` rides `outputFormat` through `SpawnChildRequest` rather than a parallel mechanism. */
+    spawnAgent(req: SpawnChildRequest): Promise<ChildHandle>;
+    /** Schema validation, borrowed from Lane K (R5-12's named W->K coupling) -- never a second validator. */
+    structured: StructuredOutputSeam;
+    /** The session's context accounting -- what a workflow's `budget` ceiling reads. */
+    accountant: ContextAccountant;
+}
+/**
+ * The spine's test double: an in-memory host recording tasks, progress and terminal calls. It spawns
+ * no processes and creates no files, so a lane can exercise its orchestration logic long before its
+ * real subprocess runtime works.
+ */
+export declare function fakeWorkflowRunHost(deps: {
+    structured: StructuredOutputSeam;
+    accountant: ContextAccountant;
+    spawnAgent?: (req: SpawnChildRequest) => Promise<ChildHandle>;
+    log?: Array<{
+        kind: string;
+        taskId: string;
+        event: "created" | "progress" | "complete" | "fail";
+        detail?: unknown;
+    }>;
+}): WorkflowRunHost;

package/dist/workflows/semaphore.d.ts

@@ -0,0 +1,16 @@
+/** The ceiling half of `min(16, CPUs - 2)`. Exported so a test asserts the CONSTANT, not a re-derived literal. */
+export declare const DEFAULT_MAX_CONCURRENCY = 16;
+/**
+ * WS-11 §1.6: "concurrent `agent()` calls `min(16, CPUs - 2)` per run (excess queue and run as slots
+ * free)".
+ *
+ * Floored at 1: on a 1- or 2-core machine `CPUs - 2` is 0 or negative, and a semaphore with zero
+ * permits deadlocks every run that calls `agent()` even once -- silently, with no error, forever.
+ * The floor is the difference between "slow on a small machine" and "broken on a small machine".
+ */
+export declare function resolveConcurrencyCap(cpuCount?: number): number;
+export interface Semaphore {
+    acquire(): Promise<void>;
+    release(): void;
+}
+export declare function makeSemaphore(max: number): Semaphore;

package/dist/workflows/store.d.ts

@@ -0,0 +1,177 @@
+import { type BrandProfile, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import { type WorkflowMetaPhase } from "./meta.js";
+/** The project workflows directory for a brand -- `<brand.projectDirName>/workflows`. */
+export declare function projectWorkflowsDir(brand?: Pick<BrandProfile, "projectDirName">): string;
+/** Winter's own value, for every caller that has not threaded a brand. */
+export declare const PROJECT_WORKFLOWS_DIR: string;
+export type ResolvedWorkflowSource = {
+    ok: true;
+    source: string;
+    path: string | undefined;
+    source_kind: "project" | "user" | "builtin" | "plugin";
+} | {
+    ok: false;
+    error: string;
+};
+/** A minimal projection of `plugins/bundle.ts`'s `PluginBundle` -- only the fields workflow resolution needs. */
+export interface PluginWorkflowSource {
+    name: string;
+    workflowsPath?: string;
+    /**
+     * Fix round 4 (minors, M-3's last bullet): the manifest's own `workflows` override -- see
+     * `PluginBundle.workflowsPaths`'s own comment for why this is mutually exclusive with
+     * `workflowsPath` above rather than additive to it. `pluginWorkflowSourcePaths` below is where the
+     * two are combined into the single list every scan actually walks.
+     */
+    workflowsPaths?: readonly string[];
+}
+/**
+ * Shared by `resolveWorkflowByName` and `listWorkflowsForListing` -- resolution and listing read the
+ * SAME tiers under the SAME gates, so they can never disagree about what exists.
+ */
+export interface WorkflowDiscoveryOptions {
+    cwd: string;
+    /**
+     * TRUST-GATED, deliberately, and this is a disclosed judgment call (see the lane report).
+     *
+     * A project `workflows/*.js` file is EXECUTABLE CODE a project supplies and the model runs -- the
+     * same category as a project `agents/*.md`, which RULING R4-7 keeps trust-gated, and not the
+     * category of skills/commands/instructions, which P5-T1 capture (b) makes merely SOURCE-gated. Norma
+     * trust-gated its own project workflow directory for the same reason. The consequence is real and
+     * worth stating: in an untrusted workspace `name` resolves nothing, so a freshly-cloned repo's
+     * workflows do not run until the workspace is trusted. `script`/`scriptPath` are unaffected.
+     *
+     * A PLUGIN workflow (below) is DELIBERATELY NOT gated on this bit, for the identical reason every
+     * other plugin-contributed resource in this codebase (skills, agents, commands, output styles,
+     * MCP servers) is not: a plugin is loaded because the HOST or the USER already decided to, outside
+     * the repository, so gating it on workspace trust would make plugin behaviour depend on which
+     * directory the session happens to be in. The USER tier (below) is not gated on this bit either,
+     * for the same reason skills' user tier is not (skills/store.ts's header).
+     */
+    trustedWorkspace: boolean;
+    /** P7a (D19): the session's brand -- the project dot-dir workflows live under. Omitted = `WINTER_BRAND`. */
+    brand?: Pick<BrandProfile, "projectDirName">;
+    /**
+     * WS-21 §6.3 item 1 (fix round 2): the session's ENABLED plugins that ship a `workflows/`
+     * directory. Omitted (every pre-fix-round-2 caller) means a `<plugin>:<name>` name simply falls
+     * through to "unknown workflow", exactly as it did before this field existed.
+     */
+    pluginWorkflows?: readonly PluginWorkflowSource[];
+    /**
+     * SV-5 fix round 3: the RESOLVED winter root (`SkillIndexOptions.winterHome`'s identical
+     * convention and identical naming rationale) -- `<winterHome>/workflows` is the user tier.
+     * Omitted means no user tier is read (every pre-fix-round-3 caller), not an error.
+     */
+    winterHome?: string | undefined;
+    /**
+     * Fix round 3 (I-4): source gating, mirroring `skills/store.ts`'s `sourcesAllow` exactly.
+     * Omitted = all tiers allowed (claude's own `settingSources` default). A caller that wants the
+     * project workflows directory (`projectWorkflowsDir`) un-read when the run's `settingSources`
+     * excludes `"project"` -- e.g. a `settingSources:["user"]` run that is ALSO
+     * `trustedWorkspace:true` -- must pass it; nothing derives it from `trustedWorkspace`, which is a
+     * different, narrower gate (R4-7) than this one.
+     */
+    settingSources?: readonly SettingSource[] | undefined;
+}
+export interface ResolveWorkflowByNameOptions extends WorkflowDiscoveryOptions {
+    /** Injectable for the test that proves built-ins are consulted first; production passes nothing. */
+    builtins?: Record<string, string>;
+}
+export declare function listBuiltinWorkflows(): string[];
+/** Built-ins first, then a plugin (WS-21 §6.3 item 1), the trusted project directory, or the user directory. Never throws. */
+export declare function resolveWorkflowByName(name: string, opts: ResolveWorkflowByNameOptions): ResolvedWorkflowSource;
+export interface WorkflowListingEntry {
+    name: string;
+    description: string;
+    source: "project" | "user" | "plugin";
+    /** The script's real filesystem path -- carried through so a caller building a `SkillMeta`-shaped synthetic entry (production-wiring.ts) never has to invent one. */
+    path: string;
+    /** Fix round 4 (I-E): carried through for a synthetic skill/command prompt's own structure -- claude's own `m()` includes both alongside name/description. */
+    whenToUse?: string;
+    phases?: WorkflowMetaPhase[];
+}
+/**
+ * SV-5 (batch-2, second round, extended in fix round 3) -- the router same-view test: the pinned
+ * binary lists EVERY discovered workflow (user + project + plugin; built-in excluded, the pinned
+ * binary's own `d()`/`Ru()` gate that separately and Winter ships none -- see `BUILTIN_WORKFLOWS`)
+ * in the init `skills`/`slash_commands` fields and the model-facing Skill listing, named
+ * `<plugin>:<meta.name>` for a plugin workflow or bare `<meta.name>` for a user/project one --
+ * `getWorkflowCommands` in the pinned binary's own workflow-discovery module maps its FULL discovery
+ * result through a `{type:"prompt", name: o.name, description: o.description, ...}` projection,
+ * `o.name` already being the qualified/bare identity discovery assigned. `production-wiring.ts` is
+ * the one caller, folding this into all three listing surfaces.
+ *
+ * ORDER matches claude's own final merge in `j()`/`QX()`: plugin entries first (builtins would lead,
+ * but Winter has none to list), then user+project merged and name-sorted -- a project entry
+ * overriding a user entry of the same name the same way resolution above does, so listing and
+ * resolution can never disagree about which tier's copy is "the" workflow of that name.
+ */
+export declare function listWorkflowsForListing(opts: WorkflowDiscoveryOptions): WorkflowListingEntry[];
+/**
+ * Fix round 4 (I-E, the router same-view test): claude's own `m()` (dump-confirmed) turns every
+ * discovered workflow into a `{type:"prompt", kind:"workflow", ...}` command whose PROMPT runs the
+ * named workflow and carries the description, `whenToUse` and phases, ending with an instruction to
+ * invoke the Workflow tool by name. `SkillMeta` has no dedicated "workflow" shape, so this builds the
+ * BODY TEXT `SkillIndex`'s own synthetic-entry seam (`SkillIndexOptions.syntheticSkills`) stores for
+ * `Skill("<name>")` to return -- the WS-11 §2.3 contract ("invocation inserts the resolved skill
+ * instructions into the main conversation") applied to a workflow instead of a SKILL.md body.
+ *
+ * THE PROMPT TEXT IS WINTER-AUTHORED, per the user's own ruling that prompts stay Winter's own
+ * wording while INTERFACE strings (a field name, a listing label, an error message) may ship
+ * verbatim from the pinned binary -- this is prompt content the model reads and acts on, not an
+ * interface string, so it is worded fresh here rather than reproduced from the dump. The
+ * STRUCTURE claude's own `m()` carries (name, description, `whenToUse`, phases, then the invoke
+ * instruction) is preserved; the wording is not claude's.
+ *
+ * Fix round 5 (promoted minor, the re-review of 57e7fef..20b623e): `/plugin:name some args` must
+ * carry `some args` into the invoke line as `Workflow({ name, args })`, matching claude. This
+ * body is a SINGLE static string shared by BOTH the `Skill` tool door and the `/name args`
+ * slash-command door -- and only the LATTER substitutes `$ARGUMENTS`/`$ARGUMENTS_JSON`
+ * (`commands/resolver.ts`'s own "DISCLOSED ASYMMETRY" header: the Skill tool hands a body over
+ * verbatim, never substituting). Baking an args token into the ONE unconditional invoke line would
+ * leave it literal, unsubstituted, in what the model sees through the Skill-tool door, which is
+ * worse than dropping args entirely. So the args-carrying line is a SECOND, explicitly CONDITIONAL
+ * sentence: it still contains the literal token (nothing else can make the slash-command door's
+ * substitution reach it), but is worded so a model reading it unsubstituted (the Skill-tool door, or
+ * a bare `/name` with nothing after it, where the tokens substitute to `""`/`'""'`) recognises it
+ * does not apply and falls back to the first, unconditional line instead.
+ *
+ * Fix round 6 (a promoted minor, the re-review against the pinned 2.1.250 dump): the args value must
+ * be ESCAPED the way claude's own `S(e)` does, matching `createWorkflowCommand`'s
+ * `getPromptForCommand` (dump-confirmed: `a=e?\`{ name: ${i}, args: ${S(e)} }\`:...\`, i=S(o.name)`
+ * -- inferred to be JSON-string-quoting from the call-site shape: applied to a plain, always-defined
+ * string, used with no additional quotes around it). Using the RAW `$ARGUMENTS` token inside
+ * hand-written quotes (round 5's own shape) would let a literal `"` or `\` in the typed args break
+ * out of the quoted literal. `$ARGUMENTS_JSON` (`commands/resolver.ts`'s new second token) substitutes
+ * with `JSON.stringify(args)` instead -- already quoted and escaped -- so this line writes NO quotes
+ * of its own around it.
+ */
+export declare function buildWorkflowSkillPrompt(entry: WorkflowListingEntry): string;
+export interface SessionScriptLocation {
+    /** The resolved winter root in production (`resolveWinterHome()`), whose `projects/` child this addresses. */
+    winterHome: string;
+    projectKey: string;
+    /** The session UUID -- the `<session-uuid>` segment of capture (3)'s path. */
+    sessionId: string;
+}
+export interface PersistWorkflowScriptInput extends SessionScriptLocation {
+    /** `meta.name` (capture (3): `<meta.name>-<runId>.js`). */
+    name: string;
+    runId: string;
+    source: string;
+}
+/** Writes the script and returns its absolute path. Overwrites for the same run, so one run keeps one path. */
+export declare function persistWorkflowScript(input: PersistWorkflowScriptInput): string;
+/** Capture (3)'s sibling: `<session>/subagents/workflows/<runId>` -- what `WorkflowOutput.transcriptDir` reports. */
+export declare function workflowTranscriptDir(input: SessionScriptLocation & {
+    runId: string;
+}): string;
+/**
+ * The JOURNAL root -- under the SESSION TEMP directory, not the durable projects area.
+ *
+ * Deliberate, and disclosed. `resumeFromRunId` is SAME-SESSION-ONLY by contract (WS-11 §1.5,
+ * `sdk-tools.d.ts:2786`), so a journal has no job to do once the session ends; capture (3) pinned the
+ * durable location of the SCRIPT and says nothing about a journal; and WS-01 forbids inventing a new
+ * durable directory name. Session temp is the D18 layout's own answer for per-session working state.
+ */
+export declare function workflowRunsDir(sessionTempDir: string): string;