indusagi-coding-agent 0.2.2 → 0.2.4

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

@@ -0,0 +1,124 @@
+/**
+ * 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, type SessionPermissionPolicy } 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;
+    /**
+     * Resolve the current server-tier gateway routing map (provider -> gateway
+     * base url). Called FRESH on every `run()` — never cached — so a mid-session
+     * `/login` (to "Indus Server") is always picked up on the very next subagent
+     * call. Mirrors {@link getApiKey}, which is likewise invoked per-request
+     * rather than resolved once at construction.
+     */
+    readonly getGatewayBaseUrls?: () => Promise<Record<string, string>>;
+    /**
+     * The parent session's live permission policy: the SAME mutable rule list the
+     * parent gate reads plus a live getter onto the conductor's current mode. When
+     * present, every spawned workflow subagent runs under a RESOLVER-LESS gate
+     * built from it — deny/ask rules, plan-mode enforcement, and the
+     * catastrophic-bash blocklist apply per inner tool call, and a mid-run mode
+     * switch (Shift+Tab) retargets the very next subagent tool call. A subagent
+     * cannot prompt, so an `ask` decision deterministically denies. Absent (a bare
+     * test construction), the subagent runs ungated as before.
+     */
+    readonly permissionPolicy?: SessionPermissionPolicy;
+}
+/**
+ * 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";

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

@@ -0,0 +1,64 @@
+/**
+ * Workflow script parser — extract and validate the leading `meta` export,
+ * enforce determinism, and hand back the runnable sandbox body.
+ *
+ * A workflow script is plain JavaScript whose FIRST statement must be
+ * `export const meta = { ... }` (an object literal). This module:
+ *
+ *   1. locates that leading export with a lexer-free, dependency-free scan,
+ *   2. evaluates ONLY the `{ ... }` literal in a frozen, empty Node `vm`
+ *      sandbox (no globals reachable, so the literal cannot call into
+ *      anything), capturing the resulting plain object as {@link WorkflowMeta},
+ *   3. validates the meta shape (name/description required, optional
+ *      whenToUse/phases),
+ *   4. enforces the determinism guard over the WHOLE script source —
+ *      `Date.now()`, `Math.random()`, and `new Date()` are rejected so a
+ *      workflow always produces the same orchestration plan, and
+ *   5. strips the `export const meta = …;` statement so the remaining `body`
+ *      runs as an ordinary async function body inside the engine sandbox.
+ *
+ * This is a dependency-free port of pi's acorn-based `parseWorkflowScript`
+ * (pi-dynamic-workflows/src/workflow.ts). It deliberately does NOT pull in
+ * `acorn`: the only thing the engine needs to read out of the source is the
+ * leading literal, which a sandboxed `Function`/`vm` evaluation of that one
+ * expression handles safely, and the determinism guard is a source string-scan
+ * over the call/`new` forms pi's AST walk rejected.
+ */
+/** One declared phase in the upfront `meta.phases` outline. */
+export interface WorkflowMetaPhase {
+    /** Human title for the phase row. */
+    title: string;
+    /** Optional one-line elaboration of what the phase does. */
+    detail?: string;
+    /** Optional model hint the phase prefers (documentation only). */
+    model?: string;
+}
+/** The validated `export const meta = { … }` header of a workflow script. */
+export interface WorkflowMeta {
+    /** Short snake_case identifier for the workflow. */
+    name: string;
+    /** Non-empty human description of what the workflow accomplishes. */
+    description: string;
+    /** Optional guidance on when a model should reach for this workflow. */
+    whenToUse?: string;
+    /** Optional upfront outline; live progress is still driven by `phase()`. */
+    phases?: WorkflowMetaPhase[];
+}
+/** The result of {@link parseWorkflowScript}: validated meta + runnable body. */
+export interface ParsedWorkflow {
+    /** The validated workflow header. */
+    meta: WorkflowMeta;
+    /** The script with the leading `export const meta = …` statement removed. */
+    body: string;
+}
+/** Message raised when a script reaches for a non-deterministic primitive. */
+export declare const NONDETERMINISM_ERROR = "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable";
+/**
+ * Parse a workflow script into its validated {@link WorkflowMeta} and the
+ * runnable `body` (the script with the meta export removed).
+ *
+ * @param script the raw workflow JavaScript source
+ * @throws if the first statement is not `export const meta = {literal}`, if the
+ *   meta fails validation, or if the source uses a non-deterministic primitive
+ */
+export declare function parseWorkflowScript(script: string): ParsedWorkflow;

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * structured_output — the per-subagent "final answer channel" tool.
+ *
+ * A workflow subagent that needs to return a machine-readable result is given a
+ * tool named `structured_output` whose `parameters` ARE the caller-supplied
+ * TypeBox schema. When the subagent calls it, the framework has already
+ * validated the arguments against that schema, so `execute` simply records the
+ * validated value into a shared {@link StructuredOutputCapture} and returns a
+ * normal {@link AgentToolResult}.
+ *
+ * Difference from pi's version (pi-dynamic-workflows/src/structured-output.ts):
+ * the indus-code-rebuild framework `AgentToolResult` has NO `terminate` flag
+ * (see {@link "indusagi/agent"} `AgentToolResult`), so this tool does NOT end
+ * the subagent's loop early. The stage-2 runner instead runs the subagent to
+ * completion and reads `capture.value` afterward. This file is therefore a
+ * plain {@link AgentTool} object literal (no `defineTool`, no `terminate`).
+ */
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { AgentTool } from "../capability-deck";
+/**
+ * Mutable sink the {@link createStructuredOutputTool} tool writes into. The
+ * runner constructs one per subagent run, passes it in, and reads `value` after
+ * the subagent finishes.
+ */
+export interface StructuredOutputCapture<T = unknown> {
+    /** The last validated payload the subagent submitted, if any. */
+    value: T | undefined;
+    /** Whether `structured_output` was ever called during the run. */
+    called: boolean;
+}
+/** Options for {@link createStructuredOutputTool}. */
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+    /** The TypeBox schema the subagent's result must satisfy. */
+    schema: TSchemaDef;
+    /** The capture sink the validated result is recorded into. */
+    capture: StructuredOutputCapture<Static<TSchemaDef>>;
+    /** Override the tool name (defaults to `structured_output`). */
+    name?: string;
+}
+/**
+ * Build the `structured_output` capture tool for one subagent run.
+ *
+ * The returned tool's `parameters` are exactly `schema`, so the framework
+ * validates the subagent's arguments before `execute` runs; `execute` then
+ * records them into `capture` and acknowledges. Idempotent in the sense that a
+ * second call simply overwrites `capture.value` with the newer payload.
+ *
+ * @param options the result schema, the capture sink, and an optional name
+ * @returns an {@link AgentTool} whose parameters mirror the caller schema
+ */
+export declare function createStructuredOutputTool<TSchemaDef extends TSchema>({ schema, capture, name, }: StructuredOutputToolOptions<TSchemaDef>): AgentTool<TSchemaDef, Static<TSchemaDef>>;

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

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

package/dist/types/workspace/brand.d.ts

@@ -23,4 +23,4 @@ export declare const BRAND: Brand;
  * Single source of truth: bump this one line per release. Co-located with the
  * brand so `boot` reads it without importing the index barrel.
  */
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.2.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indusagi-coding-agent",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Indusagi coding agent — a terminal-first AI coding agent, built from scratch on the indusagi framework.",
   "author": "Varun Israni",
   "license": "MIT",
@@ -57,7 +57,7 @@
     "@sinclair/typebox": "^0.34.49",
     "chalk": "^5.6.2",
     "highlight.js": "^11.11.1",
-    "indusagi": "^0.13.1",
+    "indusagi": "^0.13.3",
     "ink": "^5.2.1",
     "jiti": "^2.7.0",
     "marked": "^18.0.4",