indusagi-coding-agent 0.2.2 → 0.2.3

package/dist/types/console/input/keymap.d.ts

@@ -82,7 +82,7 @@ export interface KeyChord {
  *     - `flow:cycleModel`  — rotate to the next model.
  *
  *   Model / reasoning
- *     - `model:cycleThinking` — advance the reasoning-effort ladder one step.
+ *     - `model:cycleThinking` — advance the reasoning-effort ladder one step (via /thinking command).
  *
  *   Permission mode
  *     - `mode:cyclePermission` — cycle through ALL permission modes (Shift+Tab),

package/dist/types/console/input/paste.d.ts

@@ -24,8 +24,8 @@
  * the whole paste pipeline is unit-tested in isolation. The component owns only
  * the live vault value and the burst-coalescing timer; the decisions are here.
  *
- * The marker format is the console's own: `‹clip N · K lines›`, where `N` is the
- * 1-based mint order and `K` is the hidden line count. It is chosen to be
+ * The marker format is the console's own: `[Pasted text #N +K lines]`, where `N` is the
+ * 1-based mint order and `K` is the hidden line count. Matches induscode style:
  * visually distinct in the composer, unambiguous to match, and trivial to strip.
  */
 /**
@@ -69,14 +69,14 @@ export declare function classifyPaste(chunk: string, thresholds?: PasteThreshold
 /**
  * The immutable marker → body store.
  *
- * `bodies` maps each minted marker token to the exact text it hides; `minted`
+ * `bodies` maps each ordinal number to the exact text it hides; `minted`
  * is the running count that drives the next ordinal. The store is replaced (not
  * mutated) on every coalesce, so the surface holds it as a plain value and React
  * reconciliation stays correct.
  */
 export interface PasteVault {
-    /** Marker token → the original pasted text it stands for. */
-    readonly bodies: ReadonlyMap<string, string>;
+    /** Ordinal number → the original pasted text it stands for. */
+    readonly bodies: ReadonlyMap<number, string>;
     /** How many markers have been minted so far (the next ordinal is this + 1). */
     readonly minted: number;
 }

package/dist/types/console/overlays/boards.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Saffron picker boards — the themed `/settings` and `/model` overlays styled to
+ * the "IndusCode Saffron · Settings · Config" design.
+ *
+ * The framework ships plain (un-themed) `SettingsDialog` / `ModelDialog`. These
+ * boards are the console's own theme-aware replacements for those two pickers: a
+ * saffron tab-pill header, a teal-bordered search box with a magnifier and a
+ * block caret, a two-column list whose values are tinted by kind (on/true →
+ * green, off/false → dim, everything else → teal), a windowed "↓ N more" hint,
+ * and a top-ruled footer of key hints. They reuse the framework's pure
+ * {@link matchesSearchQuery} / {@link wrapSelectionIndex} helpers (and the
+ * {@link SettingsDialogItem} shape) so only the *presentation* is re-authored,
+ * not the filter/navigation logic.
+ *
+ * All colour comes through the framework {@link InkThemeAdapter} the overlay
+ * group already holds, so the boards recolour with the active scheme; the one
+ * raw-hex touch is the chalk tab-pill (dark text on the accent fill), which has
+ * no theme role to resolve against.
+ */
+import { type InkThemeAdapter, type SettingsDialogItem } from "indusagi/react-ink";
+import type { Model } from "indusagi/ai";
+/** What the {@link SettingsBoard} renders. */
+export interface SettingsBoardProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The settings rows to present and cycle. */
+    readonly items: readonly SettingsDialogItem[];
+    /** Invoked when the board is dismissed. */
+    readonly onClose: () => void;
+}
+/**
+ * The saffron `/settings` board: a filterable, value-cycling settings list in the
+ * design's look. Up/Down move (wrapping), Left/Right or Enter cycle the value,
+ * typing filters, Ctrl+U clears, Esc closes.
+ */
+export declare function SettingsBoard({ theme, items, onClose }: SettingsBoardProps): JSX.Element;
+/** What the {@link ModelBoard} renders. */
+export interface ModelBoardProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The selectable models. */
+    readonly models: readonly Model<any>[];
+    /** Optional initial search query. */
+    readonly search?: string;
+    /** Invoked with the chosen model. */
+    readonly onSelect: (model: Model<any>) => void | Promise<void>;
+    /** Invoked when the board is dismissed. */
+    readonly onClose: () => void;
+}
+/**
+ * The saffron `/model` board: a filterable model list in the design's look.
+ * Up/Down move (wrapping), Enter selects, typing filters, Ctrl+U clears, Esc
+ * closes.
+ */
+export declare function ModelBoard({ theme, models, onClose, onSelect, search }: ModelBoardProps): JSX.Element;

package/dist/types/console/theme/adapter.d.ts

@@ -34,7 +34,7 @@ import type { InkThemeAdapter, ThemeTokens } from "../contract";
  *   accent          ← signal        (primary accent the components highlight in)
  *   borderMuted     ← quietFrame    (de-emphasised borders/separators)
  *   bashBorder      ← frame         (the bash-block border tone)
- *   userMessage     ← promptSurface (user-turn background tint)
+ *   userMessage     ← "" (no background, plain text)
  *   customMessage   ← cardAccent    (custom/plugin message background tint)
  *   success         ← affirm
  *   warning         ← caution

package/dist/types/console/theme/index.d.ts

@@ -12,7 +12,7 @@
  * Consumers import from `src/console/theme` and never reach into the individual
  * palette/tokens/adapter/resolve modules.
  */
-export { MIDNIGHT_PALETTE, DAYLIGHT_PALETTE, MIDNIGHT_CB_PALETTE, DAYLIGHT_CB_PALETTE, PALETTES, } from "./palette";
+export { SAFFRON_PALETTE, MIDNIGHT_PALETTE, DAYLIGHT_PALETTE, MIDNIGHT_CB_PALETTE, DAYLIGHT_CB_PALETTE, PALETTES, } from "./palette";
 export { deriveTokens } from "./tokens";
 export { themeAdapter, frameworkColors } from "./adapter";
 export { THEMES, THEME_SCHEMES, resolveTheme } from "./resolve";

package/dist/types/console/theme/palette.d.ts

@@ -33,6 +33,16 @@ export declare const MIDNIGHT_PALETTE: ThemePalette;
  * to a dark-on-light slate.
  */
 export declare const DAYLIGHT_PALETTE: ThemePalette;
+/**
+ * The "IndusCode Saffron" dark-terminal ramp — the brand scheme.
+ *
+ * The console's signature look: a warm saffron primary (borders, headings, the
+ * brand wordmark) against a cream neutral gradient, with a cool teal secondary
+ * for the interactive accents (the prompt caret, chips, bullets) — the two hues
+ * the IndusCode masthead is built from. The status hues stay warm-leaning so the
+ * whole scheme reads as one saffron identity rather than a recoloured midnight.
+ */
+export declare const SAFFRON_PALETTE: ThemePalette;
 /**
  * The dark-terminal color-blind-safe ramp.
  *

package/dist/types/workflow-engine/agent-runner.d.ts

@@ -0,0 +1,105 @@
+/**
+ * createWorkflowAgentRunner — the live {@link WorkflowAgentRunner} that makes the
+ * `workflow` tool's `agent()` global spawn real subagents.
+ *
+ * The pure {@link "./engine"} engine delegates every `agent(prompt, opts)` call
+ * to an injected {@link WorkflowAgentRunner}; this module supplies the production
+ * implementation. Each subagent run spins a *fresh, isolated* framework
+ * {@link Agent} — the same `facade/bot` Agent the conductor and the `task`
+ * delegate-runner drive — bound to the parent's model id and credential
+ * resolver, given the `'authoring'` capability deck.
+ *
+ * Two properties matter:
+ *
+ *   1. **Recursion guard.** The deck is built via `provisionDeck("authoring", …)`,
+ *      whose profile EXCLUDES the app-novel cards — including the new `workflow`
+ *      card (registered all-profile-only in {@link "../capability-deck"}). A
+ *      workflow subagent therefore cannot itself call `workflow` (nor `task`).
+ *
+ *   2. **Structured output.** When the script passes `opts.schema`, the runner
+ *      adds the {@link createStructuredOutputTool} `structured_output` tool to the
+ *      deck and appends the pi "final action MUST be structured_output" contract
+ *      to the prompt. Because the framework `AgentToolResult` has no `terminate`
+ *      flag, the tool does NOT end the loop early — the runner instead runs the
+ *      subagent to completion, then returns `capture.value` (throwing if the
+ *      subagent never called it). With no schema it returns the final assistant
+ *      text (the {@link finalAssistantText} pattern, identical to delegate-runner).
+ *
+ * Cancellation is forwarded: an already-aborted signal short-circuits and an
+ * abort raised mid-run calls `agent.abort()`.
+ *
+ * The model catalog/matcher is built ONCE at create time (the conductor pattern);
+ * each `run()` resolves the per-call `opts.model` (falling back to the runner's
+ * default `modelId`) against that single matcher. The `spawn` option is a pure
+ * test seam — a unit test drives the runner with an in-memory fake instead of a
+ * real network round-trip.
+ */
+import { type AgentMessage } from "../conductor";
+import { type AgentTool } from "../capability-deck";
+import { type AgentEvent } from "indusagi/agent";
+import type { WorkflowAgentRunner } from "./engine";
+/**
+ * The minimal subagent surface the runner drives.
+ *
+ * A real framework {@link Agent} satisfies this structurally; a test passes a
+ * lightweight fake via {@link WorkflowAgentRunnerOptions.spawn}. Only the pieces
+ * the runner touches are named.
+ */
+export interface WorkflowSubAgent {
+    prompt(input: string): Promise<void>;
+    abort(): void;
+    /**
+     * Subscribe to the framework `Agent` event stream; returns an unsubscribe
+     * thunk. Optional on the structural fake — when absent the runner simply skips
+     * live activity reporting (the run still completes and returns its result).
+     */
+    subscribe?(fn: (event: AgentEvent) => void): () => void;
+    readonly state: {
+        messages: readonly AgentMessage[];
+        error?: string;
+        usage?: unknown;
+    };
+}
+/** The deck of tools handed to a spawned subagent. */
+export interface WorkflowSpawnContext {
+    /** The base tools for this run (the `'authoring'` deck, recursion-guarded). */
+    readonly tools: AgentTool[];
+    /** The resolved system prompt for this subagent. */
+    readonly systemPrompt: string;
+}
+/** Configuration for {@link createWorkflowAgentRunner}. */
+export interface WorkflowAgentRunnerOptions {
+    /** The default model id a subagent runs under when the script names none. */
+    readonly modelId: string;
+    /** The working directory the subagent's deck is scoped to. */
+    readonly cwd: string;
+    /**
+     * Per-call credential resolver, forwarded to the framework `Agent` unchanged.
+     * Omitted from the agent options entirely when undefined so the framework
+     * env-var lookup still wins.
+     */
+    readonly getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * The base system prompt prepended to every subagent. A sensible default is
+     * used when omitted.
+     */
+    readonly system?: string;
+    /**
+     * Test seam: build the subagent instead of constructing a real framework
+     * `Agent`. When omitted the runner uses `new Agent`.
+     */
+    readonly spawn?: (prompt: string, context: WorkflowSpawnContext) => WorkflowSubAgent;
+}
+/**
+ * Build a live {@link WorkflowAgentRunner} the host wires into the deck context.
+ *
+ * The model catalog/matcher is built once up front (the conductor pattern); each
+ * `run()` resolves `opts.model ?? modelId` against it. A schema request wires the
+ * `structured_output` capture tool and the structured contract; a model that does
+ * not resolve throws out of `run()` so the engine maps it to an `agent ... failed`
+ * log + a `null` branch (the engine's per-branch failure-to-null semantics).
+ *
+ * @param opts the model id, cwd, credential/system, and optional test seam
+ * @returns a runner satisfying the engine's {@link WorkflowAgentRunner} contract
+ */
+export declare function createWorkflowAgentRunner(opts: WorkflowAgentRunnerOptions): WorkflowAgentRunner;

package/dist/types/workflow-engine/agent-runner.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * createWorkflowAgentRunner — focused unit tests driven through the `spawn` seam.
+ *
+ * No model is resolved and no network is touched: each test passes an in-memory
+ * fake subagent via `opts.spawn`, so the test exercises the runner's prompt
+ * assembly, structured-output capture, final-text extraction, and abort wiring.
+ */
+export {};

package/dist/types/workflow-engine/display.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Workflow progress snapshot model + text renderer.
+ *
+ * The engine emits lifecycle callbacks (phase started, agent started/ended,
+ * log) which a host folds into a {@link WorkflowSnapshot}. This module owns the
+ * snapshot's pure data shape, the two pure recompute helpers, and the
+ * `renderWorkflowText` / `renderWorkflowLines` renderers that turn a snapshot
+ * into the `◆ Workflow:` progress tree shown live in the tool result.
+ *
+ * The renderer is a verbatim behavioral port of pi-dynamic-workflows'
+ * `src/display.ts` — same `◆ Workflow: name (x/y done)` header, same per-phase
+ * `▶/✓` markers with `done/total · running · errors · skipped` counts, same
+ * `    #id <glyph> label` subagent rows, same status glyphs
+ * (`○ queued`, `● running`, `✓ done`, `✗ error`, `- skipped`), same "Unphased"
+ * group, same trailing `log:` lines.
+ *
+ * Unlike pi, this file carries NO framework-UI bindings (no `ExtensionContext`,
+ * no widget display). The card/console wiring that consumes these renderers
+ * lands in stage 2; here we expose only the pure snapshot + string surface.
+ */
+import type { WorkflowMeta } from "./parse";
+/** Lifecycle status of a single workflow subagent row. */
+export type WorkflowAgentStatus = "queued" | "running" | "done" | "error" | "skipped";
+/** One subagent's row in the live progress tree. */
+export interface WorkflowAgentSnapshot {
+    /** 1-based id, the order the agent started in. */
+    id: number;
+    /** Short human label for the agent (defaulted from phase + index if absent). */
+    label: string;
+    /** The phase the agent belongs to, if any. */
+    phase?: string;
+    /** The task prompt the agent was given. */
+    prompt: string;
+    /** Current lifecycle status. */
+    status: WorkflowAgentStatus;
+    /** Optional short preview of the agent's result. */
+    resultPreview?: string;
+    /** Optional error summary when the agent failed or was skipped. */
+    error?: string;
+    /** Wall-clock ms when the subagent started (for the live elapsed counter). */
+    startedAt?: number;
+    /** Wall-clock ms when the subagent settled (caps the elapsed counter). */
+    endedAt?: number;
+    /** Cumulative input tokens the subagent has spent. */
+    tokensIn?: number;
+    /** Cumulative output tokens the subagent has spent. */
+    tokensOut?: number;
+    /** How many tool calls the subagent has started. */
+    toolCount?: number;
+    /** The tool the subagent is running right now, if any. */
+    currentTool?: string;
+    /** The last tool the subagent finished (when nothing is running). */
+    lastTool?: string;
+}
+/** The full live progress model for one workflow run. */
+export interface WorkflowSnapshot {
+    /** Workflow name (from `meta.name`). */
+    name: string;
+    /** Workflow description (from `meta.description`). */
+    description?: string;
+    /** Declared/observed phase titles, in order. */
+    phases: string[];
+    /** The phase currently active (last `phase()` call). */
+    currentPhase?: string;
+    /** Log lines emitted via `log()`. */
+    logs: string[];
+    /** Every subagent row, in start order. */
+    agents: WorkflowAgentSnapshot[];
+    /** Total agents seen. */
+    agentCount: number;
+    /** Agents currently running. */
+    runningCount: number;
+    /** Agents finished successfully. */
+    doneCount: number;
+    /** Agents that errored. */
+    errorCount: number;
+    /** Total run duration once complete. */
+    durationMs?: number;
+    /** The workflow's final returned value once complete. */
+    result?: unknown;
+}
+/** Tunables for the text renderer (how much of the tree to show). */
+export interface WorkflowDisplayOptions {
+    /** Max subagent rows shown per phase (most recent kept). Default 8. */
+    maxAgents?: number;
+    /** Max trailing log lines shown. Default 2. */
+    maxLogs?: number;
+    /** Append a short result preview to each agent row. Default false. */
+    showResultPreviews?: boolean;
+    /**
+     * Soft cap on total tree lines for the LIVE render. Default 9 — headroom under
+     * the framework `TaskPanel` 10-line clamp so a running agent is never cut off
+     * by a trailing `…`. Completed phases collapse to one line each, and if the
+     * tree is still over budget the OLDEST completed phases collapse into a single
+     * `… N earlier phases done` line (running/current phases are never collapsed).
+     * Pass a large value (e.g. the settled/final render, or Ctrl+O expand) to show
+     * everything in full.
+     */
+    maxLines?: number;
+}
+/**
+ * Build an empty snapshot for a freshly parsed workflow `meta`.
+ *
+ * @param meta the workflow header
+ */
+export declare function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot;
+/**
+ * Recompute the derived counts (`agentCount`/`runningCount`/`doneCount`/
+ * `errorCount`) from the `agents` array. Pure — returns a new snapshot.
+ *
+ * @param snapshot the snapshot whose counts to refresh
+ */
+export declare function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot;
+/**
+ * Render the snapshot as the `◆ Workflow:` progress tree (array of lines).
+ *
+ * The per-agent metrics segment (elapsed seconds, token spend, tool activity) is
+ * computed at render time from `now` so the seconds tick on every render even
+ * during a long silent tool call. Keep `now` an explicit param so the renderer
+ * stays pure and testable.
+ *
+ * @param snapshot the progress model
+ * @param options render tunables
+ * @param now the current wall-clock ms used to compute live elapsed seconds
+ */
+export declare function renderWorkflowLines(snapshot: WorkflowSnapshot, options?: WorkflowDisplayOptions, now?: number): string[];
+/**
+ * Render the snapshot as a single string for the tool result.
+ *
+ * For the LIVE (not-completed) render the `◆ Workflow:` header already says the
+ * run is in progress, so no extra header line is added — this saves a line under
+ * the framework `TaskPanel` 10-line clamp. The final (completed) render keeps the
+ * explicit `Workflow completed` header.
+ *
+ * @param snapshot the progress model
+ * @param completed whether the run has finished
+ * @param options render tunables
+ * @param now the current wall-clock ms used to compute live elapsed seconds
+ */
+export declare function renderWorkflowText(snapshot: WorkflowSnapshot, completed?: boolean, options?: WorkflowDisplayOptions, now?: number): string;
+/**
+ * One-line preview of an arbitrary result value (string passthrough, else
+ * JSON), truncated to `max` chars. Used to fill `resultPreview`.
+ *
+ * @param value the result to preview
+ * @param max max preview length
+ */
+export declare function preview(value: unknown, max?: number): string;

package/dist/types/workflow-engine/display.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-engine/engine.d.ts

@@ -0,0 +1,183 @@
+/**
+ * runWorkflow — the deterministic workflow orchestration engine.
+ *
+ * A workflow script is plain JavaScript (parsed by {@link parseWorkflowScript})
+ * that orchestrates a fan-out of subagents. The engine evaluates the script's
+ * body inside a Node `vm` sandbox seeded with a small, frozen global surface:
+ *
+ *   - `agent(prompt, opts?)`  — spawn one subagent, awaitable, returns its
+ *                               result (string, or the validated `opts.schema`
+ *                               object). Runs under a FIFO concurrency limiter.
+ *   - `parallel(thunks)`      — run an array of `() => Promise` thunks and wait
+ *                               for ALL of them (a barrier); results in input
+ *                               order; a failed branch logs and yields `null`.
+ *   - `pipeline(items, …st)`  — run each item through the stages sequentially,
+ *                               while different items proceed independently
+ *                               (NO cross-item barrier); a failed stage logs and
+ *                               yields `null` for that item.
+ *   - `phase(title)`          — open/activate a named progress group.
+ *   - `log(message)`          — append a log line.
+ *   - `args`                  — the caller-supplied JSON value.
+ *   - `budget`                — `{ total, spent(), remaining() }` token budget.
+ *   - `cwd`                   — the working directory string.
+ *   - frozen `console`        — routed into `log`.
+ *
+ * The actual subagent spawn is NOT owned here: the engine delegates each
+ * `agent()` call to an injected {@link WorkflowAgentRunner} (stage 2 supplies a
+ * real one backed by a fresh framework `Agent`; tests pass an in-memory fake).
+ * This is the spawn seam that keeps the engine pure and network-free.
+ *
+ * Behavioral port of pi-dynamic-workflows' `runWorkflow`
+ * (pi-dynamic-workflows/src/workflow.ts): same concurrency cap formula, same
+ * FIFO limiter, same pending-run tracking + final `Promise.allSettled`, same
+ * per-branch failure-to-null semantics, same budget loop, same abort handling,
+ * same structured-clone guard on the result, same default agent labels.
+ */
+import { type WorkflowMeta } from "./parse";
+/**
+ * Live activity metrics for one running subagent.
+ *
+ * Folded by the {@link WorkflowAgentRunner} from the framework `Agent`'s event
+ * stream and forwarded — via {@link WorkflowAgentRunOptions.onActivity} → the
+ * engine's {@link WorkflowRunOptions.onAgentActivity} — into that agent's row in
+ * the live `◆ Workflow:` progress tree.
+ */
+export interface WorkflowAgentActivity {
+    /** Cumulative input tokens spent so far. */
+    tokensIn: number;
+    /** Cumulative output tokens spent so far. */
+    tokensOut: number;
+    /** How many tool calls the subagent has started. */
+    toolCount: number;
+    /** The tool the subagent is running right now, if any. */
+    currentTool?: string;
+    /** The last tool the subagent finished (when nothing is running). */
+    lastTool?: string;
+}
+/** Options the engine hands a {@link WorkflowAgentRunner} for one subagent. */
+export interface WorkflowAgentRunOptions {
+    /** The resolved, human-readable label for this subagent run. */
+    label: string;
+    /** The phase this subagent belongs to, if any. */
+    phase?: string;
+    /**
+     * Optional JSON-Schema / TypeBox schema the subagent's result must satisfy.
+     * When present the runner returns the validated object; when absent it returns
+     * the subagent's final assistant text as a string. Left as `unknown` so the
+     * engine stays decoupled from any particular schema library.
+     */
+    schema?: unknown;
+    /** Extra system guidance the engine derived (phase/model/type/isolation). */
+    instructions?: string;
+    /** Requested model id, if the script passed `opts.model`. */
+    model?: string;
+    /** Requested subagent profile/type, if the script passed `opts.agentType`. */
+    agentType?: string;
+    /** Requested isolation mode, if the script passed `opts.isolation`. */
+    isolation?: "worktree";
+    /** Abort signal forwarded from the workflow run. */
+    signal?: AbortSignal;
+    /**
+     * Called whenever the subagent's live activity changes (a tool starts/ends or
+     * a turn settles with token spend). The runner folds this from the framework
+     * `Agent` event stream; the engine forwards it to
+     * {@link WorkflowRunOptions.onAgentActivity}. Optional — a test fake may omit it.
+     */
+    onActivity?: (metrics: WorkflowAgentActivity) => void;
+}
+/**
+ * The minimal contract the engine needs to spawn a subagent.
+ *
+ * Stage 2 implements this against a fresh, isolated framework `Agent` (the
+ * delegate-runner spawn pattern): resolve the model, build the authoring deck,
+ * prompt to completion, then read either the structured-output capture or the
+ * final assistant text. Tests implement it with an in-memory fake so the engine
+ * can be exercised with no network.
+ */
+export interface WorkflowAgentRunner {
+    /**
+     * Run one subagent task and resolve with its result.
+     *
+     * @param prompt the task prompt
+     * @param options the resolved run options (label, schema, signal, …)
+     * @returns the subagent's result — a string, or the validated schema object
+     */
+    run(prompt: string, options: WorkflowAgentRunOptions): Promise<unknown>;
+}
+/** Per-subagent option bag accepted by the in-sandbox `agent()` global. */
+export interface AgentOptions {
+    /** Short unique label for the run (2-5 words); defaulted when absent. */
+    label?: string;
+    /** Override the phase this agent is attributed to. */
+    phase?: string;
+    /** Result schema; when present the agent returns the validated object. */
+    schema?: unknown;
+    /** Requested model id. */
+    model?: string;
+    /** Requested isolation mode. */
+    isolation?: "worktree";
+    /** Requested subagent profile/type. */
+    agentType?: string;
+}
+/** Options for {@link runWorkflow}. */
+export interface WorkflowRunOptions {
+    /** The injected subagent runner (required to actually spawn). */
+    agentRunner: WorkflowAgentRunner;
+    /** The JSON value exposed to the script as global `args`. */
+    args?: unknown;
+    /** The working directory exposed to the script as `cwd`/`process.cwd()`. */
+    cwd?: string;
+    /** Max concurrent subagents; clamped to `[1, 16]`. */
+    concurrency?: number;
+    /** Optional token budget; `null`/absent means unbounded. */
+    tokenBudget?: number | null;
+    /** Abort signal — aborts pending and future subagent spawns. */
+    signal?: AbortSignal;
+    /** Called for each `log()` / console line. */
+    onLog?: (message: string) => void;
+    /** Called when a new phase is activated. */
+    onPhase?: (title: string) => void;
+    /** Called just before a subagent starts. */
+    onAgentStart?: (event: {
+        id: number;
+        label: string;
+        phase?: string;
+        prompt: string;
+    }) => void;
+    /** Called when a subagent ends (`result === null` means it failed). */
+    onAgentEnd?: (event: {
+        id: number;
+        label: string;
+        phase?: string;
+        result: unknown;
+    }) => void;
+    /**
+     * Called whenever a running subagent's live activity changes (tool start/end,
+     * settled turn token spend). `id` is the 1-based start-order id that matches
+     * the `id` on the corresponding {@link onAgentStart} / {@link onAgentEnd} event.
+     */
+    onAgentActivity?: (id: number, metrics: WorkflowAgentActivity) => void;
+}
+/** The structured result of a completed workflow run. */
+export interface WorkflowRunResult<T = unknown> {
+    /** The validated workflow header. */
+    meta: WorkflowMeta;
+    /** The script's returned value (structured-clone checked). */
+    result: T;
+    /** All log lines emitted during the run, in order. */
+    logs: string[];
+    /** All phases observed during the run, in order. */
+    phases: string[];
+    /** Total subagents spawned. */
+    agentCount: number;
+    /** Wall-clock duration of the run. */
+    durationMs: number;
+}
+/**
+ * Parse and run a deterministic workflow script to completion.
+ *
+ * @param script the raw workflow JavaScript (first statement: `export const meta`)
+ * @param options the injected runner plus run configuration / callbacks
+ * @returns the meta, the script's returned value, and run telemetry
+ */
+export declare function runWorkflow<T = unknown>(script: string, options: WorkflowRunOptions): Promise<WorkflowRunResult<T>>;

package/dist/types/workflow-engine/engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/workflow-engine/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * workflow-engine — the pure, network-free orchestration core for the `workflow`
+ * dynamic-workflow tool.
+ *
+ * This barrel exposes the engine subsystem only: the deterministic script
+ * parser, the `structured_output` capture tool, the progress snapshot model +
+ * text renderer, and the `runWorkflow` engine with its injectable
+ * {@link WorkflowAgentRunner} spawn seam. The card and console wiring (the real
+ * runner backed by a fresh framework `Agent`, the `tool_update` product signal,
+ * and `APP_NOVEL_CARDS` registration) live in stage 2 and consume these exports.
+ */
+export type { ParsedWorkflow, WorkflowMeta, WorkflowMetaPhase, } from "./parse";
+export { NONDETERMINISM_ERROR, parseWorkflowScript } from "./parse";
+export type { StructuredOutputCapture, StructuredOutputToolOptions, } from "./structured-output";
+export { createStructuredOutputTool } from "./structured-output";
+export type { WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowDisplayOptions, WorkflowSnapshot, } from "./display";
+export { createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display";
+export type { AgentOptions, WorkflowAgentActivity, WorkflowAgentRunner, WorkflowAgentRunOptions, WorkflowRunOptions, WorkflowRunResult, } from "./engine";
+export { runWorkflow } from "./engine";
+export type { WorkflowAgentRunnerOptions, WorkflowSubAgent, WorkflowSpawnContext, } from "./agent-runner";
+export { createWorkflowAgentRunner } from "./agent-runner";