@wrenai/genbi 0.0.1

package/dist-server/harness/render/validate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A minimal, structural validator for the JSON Schema subset an
+ * `agent.output_schema` document actually uses (`type`, `properties`,
+ * `required`, `items`, `const`, and a `type` array for nullable unions like
+ * `["string", "null"]`). This is deliberately not a general-purpose JSON
+ * Schema engine — `jsonSchema()` from the AI SDK performs *no* runtime
+ * validation on its own unless given a `validate` callback (confirmed by
+ * reading `safeValidateTypes`: a schema with no `.validate` always reports
+ * success), so this is what gives the envelope stage real teeth: a
+ * malformed model response is rejected, not silently passed through.
+ */
+export type JsonSchemaDocument = Record<string, unknown>;
+export declare function collectJsonSchemaErrors(schema: JsonSchemaDocument, value: unknown): string[];

package/dist-server/harness/render/validate.js

@@ -0,0 +1,88 @@
+export function collectJsonSchemaErrors(schema, value) {
+    const errors = [];
+    validateNode(schema, value, "$", errors);
+    return errors;
+}
+function validateNode(schema, value, path, errors) {
+    if ("const" in schema) {
+        if (value !== schema.const) {
+            errors.push(`${path}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+        }
+        return;
+    }
+    const type = schema.type;
+    if (type !== undefined && !matchesType(type, value)) {
+        errors.push(`${path}: expected type ${JSON.stringify(type)}, got ${describeType(value)}`);
+        return;
+    }
+    if (includesType(type, "object") && isPlainObject(value)) {
+        validateObjectShape(schema, value, path, errors);
+    }
+    if (includesType(type, "array") && Array.isArray(value)) {
+        validateArrayItems(schema, value, path, errors);
+    }
+}
+function validateObjectShape(schema, value, path, errors) {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of required) {
+        if (typeof key === "string" && !(key in value)) {
+            errors.push(`${path}: missing required property "${key}"`);
+        }
+    }
+    const properties = isPlainObject(schema.properties) ? schema.properties : undefined;
+    if (!properties)
+        return;
+    for (const [key, propSchema] of Object.entries(properties)) {
+        if (key in value && isPlainObject(propSchema)) {
+            validateNode(propSchema, value[key], `${path}.${key}`, errors);
+        }
+    }
+}
+function validateArrayItems(schema, value, path, errors) {
+    if (!isPlainObject(schema.items))
+        return;
+    const itemsSchema = schema.items;
+    value.forEach((item, index) => validateNode(itemsSchema, item, `${path}[${index}]`, errors));
+}
+function matchesType(type, value) {
+    if (Array.isArray(type)) {
+        return type.some((candidate) => matchesSingleType(candidate, value));
+    }
+    return matchesSingleType(type, value);
+}
+function includesType(type, candidate) {
+    if (type === undefined)
+        return true;
+    return Array.isArray(type) ? type.includes(candidate) : type === candidate;
+}
+function matchesSingleType(type, value) {
+    switch (type) {
+        case "object":
+            return isPlainObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "number":
+        case "integer":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            // Unknown/unsupported schema type keyword — don't fail closed on
+            // something this minimal validator doesn't understand.
+            return true;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}

package/dist-server/harness/route/adapter-spec.d.ts

@@ -0,0 +1,40 @@
+import type { AuthChoice } from "../auth/index.js";
+import type { AdapterSpec } from "../providers/index.js";
+/** Default local endpoint used when a `LocalAuthChoice` omits `endpoint` (Ollama's default OpenAI-compatible port). */
+export declare const DEFAULT_LOCAL_ENDPOINT = "http://localhost:11434/v1";
+/**
+ * Default local model used when neither `LocalAuthChoice` (which has no
+ * `model` field of its own — see the API-surface mismatch note in this
+ * ticket's report) nor `InProcessOptions.model` supplies one.
+ */
+export declare const DEFAULT_LOCAL_MODEL = "llama3.1";
+export interface DeriveAdapterSpecOptions {
+    /** Only consulted for `authChoice.mode === "local"`. See `DEFAULT_LOCAL_MODEL`. */
+    readonly model?: string;
+}
+/**
+ * Derives a concrete `AdapterSpec` (adapter id + config) for in-process's three
+ * `AuthChoice` variants:
+ *
+ * - `api-key` — passed straight through: `authChoice.adapter`/`config` already
+ *   name a `ProviderRegistry` adapter id and its config (70a's `toAuthChoice`
+ *   only emits a placeholder `adapter: ""`; a real choice is expected to name
+ *   a registered adapter such as `"anthropic"`).
+ * - `local` — mapped onto the built-in `openai-compatible` adapter, since
+ *   "a model served on the local machine/network" (70a's doc comment) is
+ *   exactly what that adapter targets. `endpoint` becomes `baseURL`; `model`
+ *   comes from `options.model` (falling back to `DEFAULT_LOCAL_MODEL`) since
+ *   `LocalAuthChoice` itself carries no model field.
+ * - `gateway` — also mapped onto `openai-compatible` (an operator-managed
+ *   gateway is, from this adapter's point of view, just another OpenAI-compatible
+ *   endpoint); `authChoice.config` must already carry `baseURL`/`model`
+ *   (and optionally `apiKey`) matching `OpenAICompatibleAdapterConfig` — 70a
+ *   leaves this config shape unspecified, so this is this ticket's own
+ *   assumption, not a contract 70a promises. Unlike `local` (which defaults
+ *   endpoint/model), `gateway` has no sensible default, so a missing/empty
+ *   `baseURL`/`model` is a loud `wren-harness`-level error here rather than a
+ *   bare "Invalid URL" deep inside the adapter.
+ */
+export declare function deriveAdapterSpec(authChoice: Extract<AuthChoice, {
+    mode: "api-key" | "local" | "gateway";
+}>, options?: DeriveAdapterSpecOptions): AdapterSpec;

package/dist-server/harness/route/adapter-spec.js

@@ -0,0 +1,61 @@
+import { OPENAI_COMPATIBLE_ADAPTER_ID } from "../providers/index.js";
+/** Default local endpoint used when a `LocalAuthChoice` omits `endpoint` (Ollama's default OpenAI-compatible port). */
+export const DEFAULT_LOCAL_ENDPOINT = "http://localhost:11434/v1";
+/**
+ * Default local model used when neither `LocalAuthChoice` (which has no
+ * `model` field of its own — see the API-surface mismatch note in this
+ * ticket's report) nor `InProcessOptions.model` supplies one.
+ */
+export const DEFAULT_LOCAL_MODEL = "llama3.1";
+/**
+ * Derives a concrete `AdapterSpec` (adapter id + config) for in-process's three
+ * `AuthChoice` variants:
+ *
+ * - `api-key` — passed straight through: `authChoice.adapter`/`config` already
+ *   name a `ProviderRegistry` adapter id and its config (70a's `toAuthChoice`
+ *   only emits a placeholder `adapter: ""`; a real choice is expected to name
+ *   a registered adapter such as `"anthropic"`).
+ * - `local` — mapped onto the built-in `openai-compatible` adapter, since
+ *   "a model served on the local machine/network" (70a's doc comment) is
+ *   exactly what that adapter targets. `endpoint` becomes `baseURL`; `model`
+ *   comes from `options.model` (falling back to `DEFAULT_LOCAL_MODEL`) since
+ *   `LocalAuthChoice` itself carries no model field.
+ * - `gateway` — also mapped onto `openai-compatible` (an operator-managed
+ *   gateway is, from this adapter's point of view, just another OpenAI-compatible
+ *   endpoint); `authChoice.config` must already carry `baseURL`/`model`
+ *   (and optionally `apiKey`) matching `OpenAICompatibleAdapterConfig` — 70a
+ *   leaves this config shape unspecified, so this is this ticket's own
+ *   assumption, not a contract 70a promises. Unlike `local` (which defaults
+ *   endpoint/model), `gateway` has no sensible default, so a missing/empty
+ *   `baseURL`/`model` is a loud `wren-harness`-level error here rather than a
+ *   bare "Invalid URL" deep inside the adapter.
+ */
+export function deriveAdapterSpec(authChoice, options = {}) {
+    switch (authChoice.mode) {
+        case "api-key":
+            return { adapter: authChoice.adapter, config: authChoice.config ?? {} };
+        case "local":
+            return {
+                adapter: OPENAI_COMPATIBLE_ADAPTER_ID,
+                config: {
+                    baseURL: authChoice.endpoint ?? DEFAULT_LOCAL_ENDPOINT,
+                    model: options.model ?? DEFAULT_LOCAL_MODEL,
+                },
+            };
+        case "gateway": {
+            const config = authChoice.config ?? {};
+            const missing = [];
+            if (!isNonEmptyString(config["baseURL"]))
+                missing.push("baseURL");
+            if (!isNonEmptyString(config["model"]))
+                missing.push("model");
+            if (missing.length > 0) {
+                throw new Error(`gateway mode requires ${missing.join(" and ")} in config (pass --endpoint and --model)`);
+            }
+            return { adapter: OPENAI_COMPATIBLE_ADAPTER_ID, config };
+        }
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist-server/harness/route/agent-sdk-cli.d.ts

@@ -0,0 +1,30 @@
+/** A resolved CLI invocation: the executable plus any args that must precede the caller's own args (e.g. a script path for a `tsx <script>` dev-mode invocation). */
+export interface ResolvedCli {
+    readonly command: string;
+    readonly prefixArgs: readonly string[];
+}
+export declare class AgentSdkCliNotFoundError extends Error {
+    constructor(attempts: readonly string[]);
+}
+/**
+ * Resolves the warble `claude-agent-sdk` dispatcher CLI (dispatched's back-end)
+ * in four tiers, mirroring `resolveWarbleBinary`:
+ *
+ * 1. `explicit` — if given, treated as a ready-to-run command with no args
+ *    prefix (no existence check — a bare name is trusted to resolve on
+ *    `PATH` at spawn time, matching a documented override).
+ * 2. The pinned `@warble/claude-agent-sdk` npm package this workspace depends on, run via
+ *    `node <dist/cli.js>` rather than relying on the file's own shebang/executable bit.
+ * 3. `PATH` — a bare `"warble-agent-sdk"` that `warble-agent-sdk --help` succeeds against. Kept as
+ *    a fallback for a standalone install on a machine that hasn't run `pnpm install`.
+ * 4. A sibling `warble` repo's dev-mode invocation, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` opt-in (see
+ *    `isWarbleSiblingCheckoutDevModeEnabled`):
+ *    `<ancestor's parent>/warble/dispatcher/claude-agent-sdk`'s
+ *    `node_modules/.bin/tsx src/cli.ts`. Like `resolveWarbleBinary`'s equivalent tier, this only
+ *    resolves in a local development layout with a `warble` checkout next to this repo, and must
+ *    not silently win over the pinned package now that tier 2 exists.
+ *
+ * Throws {@link AgentSdkCliNotFoundError} (loud-fail) if none of the four work.
+ */
+export declare function resolveAgentSdkCli(explicit?: string): Promise<ResolvedCli>;

package/dist-server/harness/route/agent-sdk-cli.js

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isWarbleSiblingCheckoutDevModeEnabled, resolveInstalledPackageBin } from "../npm-package-resolve.js";
+export class AgentSdkCliNotFoundError extends Error {
+    constructor(attempts) {
+        super(`could not resolve the warble-agent-sdk CLI:\n${attempts.map((attempt) => `  - ${attempt}`).join("\n")}`);
+        this.name = "AgentSdkCliNotFoundError";
+    }
+}
+/**
+ * Resolves the warble `claude-agent-sdk` dispatcher CLI (dispatched's back-end)
+ * in four tiers, mirroring `resolveWarbleBinary`:
+ *
+ * 1. `explicit` — if given, treated as a ready-to-run command with no args
+ *    prefix (no existence check — a bare name is trusted to resolve on
+ *    `PATH` at spawn time, matching a documented override).
+ * 2. The pinned `@warble/claude-agent-sdk` npm package this workspace depends on, run via
+ *    `node <dist/cli.js>` rather than relying on the file's own shebang/executable bit.
+ * 3. `PATH` — a bare `"warble-agent-sdk"` that `warble-agent-sdk --help` succeeds against. Kept as
+ *    a fallback for a standalone install on a machine that hasn't run `pnpm install`.
+ * 4. A sibling `warble` repo's dev-mode invocation, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` opt-in (see
+ *    `isWarbleSiblingCheckoutDevModeEnabled`):
+ *    `<ancestor's parent>/warble/dispatcher/claude-agent-sdk`'s
+ *    `node_modules/.bin/tsx src/cli.ts`. Like `resolveWarbleBinary`'s equivalent tier, this only
+ *    resolves in a local development layout with a `warble` checkout next to this repo, and must
+ *    not silently win over the pinned package now that tier 2 exists.
+ *
+ * Throws {@link AgentSdkCliNotFoundError} (loud-fail) if none of the four work.
+ */
+export async function resolveAgentSdkCli(explicit) {
+    if (explicit !== undefined) {
+        return { command: explicit, prefixArgs: [] };
+    }
+    const attempts = [];
+    const packageBin = resolveInstalledPackageBin("@warble/claude-agent-sdk", "warble-agent-sdk");
+    if (packageBin !== undefined) {
+        return { command: process.execPath, prefixArgs: [packageBin] };
+    }
+    attempts.push(`"@warble/claude-agent-sdk" is not installed (or declares no "warble-agent-sdk" bin) in this workspace`);
+    if (await isExecutableOnPath("warble-agent-sdk")) {
+        return { command: "warble-agent-sdk", prefixArgs: [] };
+    }
+    attempts.push('not found on PATH (tried running "warble-agent-sdk --help")');
+    if (isWarbleSiblingCheckoutDevModeEnabled()) {
+        const sibling = findSiblingDevInvocation();
+        if (sibling !== undefined) {
+            return sibling;
+        }
+        attempts.push('no sibling "warble/dispatcher/claude-agent-sdk" package found with a built tsx binary ' +
+            '(searched ancestors of this package for "<ancestor\'s parent>/warble/dispatcher/claude-agent-sdk")');
+    }
+    else {
+        attempts.push(`sibling "warble" checkout dev mode is disabled (set WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1 to enable it)`);
+    }
+    throw new AgentSdkCliNotFoundError(attempts);
+}
+function isExecutableOnPath(bin) {
+    return new Promise((resolve) => {
+        execFile(bin, ["--help"], (error) => resolve(!error));
+    });
+}
+/**
+ * Walks up from this package's own directory (two levels below the package
+ * root, same convention as `resolveWarbleBinary`'s sibling lookup) looking
+ * for `warble/dispatcher/claude-agent-sdk`'s dev-mode `tsx` entry point.
+ */
+function findSiblingDevInvocation() {
+    let dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const maxDepth = 10;
+    for (let i = 0; i < maxDepth; i += 1) {
+        const parent = path.dirname(dir);
+        const pkgDir = path.join(parent, "warble", "dispatcher", "claude-agent-sdk");
+        const tsx = path.join(pkgDir, "node_modules", ".bin", "tsx");
+        const entry = path.join(pkgDir, "src", "cli.ts");
+        if (existsSync(tsx) && existsSync(entry)) {
+            return { command: tsx, prefixArgs: [entry] };
+        }
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return undefined;
+}

package/dist-server/harness/route/agent-sdk-manifest.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedCli } from "./agent-sdk-cli.js";
+export interface AgentSdkManifestCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface BuildAgentSdkManifestArgsOptions {
+    readonly irPath: string;
+    /** Omitted for a raw bootstrap profile, which has no bound project yet. */
+    readonly userProject?: string;
+}
+/**
+ * Builds the argv for a `warble-agent-sdk manifest` invocation without
+ * spawning anything: `<agent-sdk-cli> manifest <ir.json> --project
+ * <userProject> --include-unavailable`. The display-only flag keeps an
+ * unsupported declared component visible without making it executable.
+ * Omitting `--out` is deliberate — the dispatcher's
+ * `manifest` subcommand writes the manifest JSON to stdout only when no
+ * `--out` is given (resolution summaries always go to stderr), so stdout
+ * stays pure JSON for `runAgentSdkManifest` to parse.
+ */
+export declare function buildAgentSdkManifestArgs(cli: ResolvedCli, options: BuildAgentSdkManifestArgsOptions): AgentSdkManifestCommand;
+/**
+ * Runs a `warble-agent-sdk manifest` invocation (built by
+ * {@link buildAgentSdkManifestArgs}) to completion and returns its stdout — a
+ * single JSON blob, not a stream, so this mirrors `compile/pipeline.ts`'s
+ * buffered `runWarble` rather than `dispatched.ts`'s streaming `spawnChat`
+ * (there's no incremental per-step output to relay for a describe/introspect
+ * call). Reuses `WarbleCommandFailedError` since it's already the generic
+ * "an external warble-family CLI exited non-zero" error shape.
+ */
+export declare function runAgentSdkManifest(command: string, args: readonly string[]): Promise<string>;

package/dist-server/harness/route/agent-sdk-manifest.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { WarbleCommandFailedError } from "../compile/errors.js";
+// Mirrors `compile/pipeline.ts`'s `WARBLE_COMMAND_TIMEOUT_MS` — a generous
+// ceiling for a local, normally-sub-second command; guards against a hang,
+// not meant to ever fire in normal operation.
+const AGENT_SDK_MANIFEST_TIMEOUT_MS = 2 * 60 * 1000;
+/**
+ * Builds the argv for a `warble-agent-sdk manifest` invocation without
+ * spawning anything: `<agent-sdk-cli> manifest <ir.json> --project
+ * <userProject> --include-unavailable`. The display-only flag keeps an
+ * unsupported declared component visible without making it executable.
+ * Omitting `--out` is deliberate — the dispatcher's
+ * `manifest` subcommand writes the manifest JSON to stdout only when no
+ * `--out` is given (resolution summaries always go to stderr), so stdout
+ * stays pure JSON for `runAgentSdkManifest` to parse.
+ */
+export function buildAgentSdkManifestArgs(cli, options) {
+    return {
+        command: cli.command,
+        args: [
+            ...cli.prefixArgs,
+            "manifest",
+            options.irPath,
+            "--include-unavailable",
+            ...(options.userProject !== undefined ? ["--project", options.userProject] : []),
+        ],
+    };
+}
+/**
+ * Runs a `warble-agent-sdk manifest` invocation (built by
+ * {@link buildAgentSdkManifestArgs}) to completion and returns its stdout — a
+ * single JSON blob, not a stream, so this mirrors `compile/pipeline.ts`'s
+ * buffered `runWarble` rather than `dispatched.ts`'s streaming `spawnChat`
+ * (there's no incremental per-step output to relay for a describe/introspect
+ * call). Reuses `WarbleCommandFailedError` since it's already the generic
+ * "an external warble-family CLI exited non-zero" error shape.
+ */
+export function runAgentSdkManifest(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, [...args], { maxBuffer: 32 * 1024 * 1024, timeout: AGENT_SDK_MANIFEST_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error) {
+                const exitCode = typeof error.code === "number" ? error.code : 1;
+                const clarifiedStderr = stderr.length > 0
+                    ? stderr
+                    : error.killed === true
+                        ? `warble-agent-sdk manifest subprocess timed out after ${AGENT_SDK_MANIFEST_TIMEOUT_MS}ms`
+                        : error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                            ? "warble-agent-sdk manifest subprocess exceeded the 32 MiB output buffer"
+                            : stderr;
+                reject(new WarbleCommandFailedError(command, args, exitCode, clarifiedStderr, stdout));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}

package/dist-server/harness/route/artifact-content.d.ts

@@ -0,0 +1,53 @@
+import type { RenderEnvelope } from "../render/envelope.js";
+export type ArtifactContentUnavailableReason = "missing" | "unreadable" | "outside_root" | "too_large";
+/**
+ * `GET /api/artifacts/:id/content`'s response shape. An artifact's
+ * `location` is read back and classified into exactly one of these forms —
+ * never a fabricated fourth shape:
+ * - `envelope`: the file parses as JSON and is envelope-shaped (has a
+ *   `blocks` array) — this is what dispatched (`generate_dashboard`/report/chart
+ *   agents) always persists.
+ * - `text`: the file exists and is readable but isn't envelope-shaped JSON —
+ *   this is the common case for in-process's `write_artifact` tool, which lets
+ *   the model write arbitrary content (HTML, markdown, plain JSON, ...).
+ * - `unavailable`: nothing could be read back; `reason` says why. Every
+ *   `unavailable` is a caller-visible degrade to metadata-only, never a
+ *   thrown error — a missing/unreadable/outside-root/too-large artifact is
+ *   an expected, honestly-reported state, not a route failure.
+ */
+export type ArtifactContentDto = {
+    readonly form: "envelope";
+    readonly envelope: RenderEnvelope;
+} | {
+    readonly form: "text";
+    readonly text: string;
+    readonly truncated: boolean;
+} | {
+    readonly form: "unavailable";
+    readonly reason: ArtifactContentUnavailableReason;
+};
+/**
+ * Resolves an `ArtifactRow.location` back to its on-disk content, scoped to
+ * `artifactsRoot` (the same root `resolveArtifactsDir` computes for in-process/B
+ * writes — see `in-process.ts` and `turn.ts`'s `maybeCreateDispatchedArtifact`).
+ * `location` may be relative (in-process, written under the model's chosen
+ * `write_artifact` path, itself scoped to `artifactsRoot` at write time — see
+ * `resolveWithinScope` in `exec/local.ts`) or absolute (dispatched always writes
+ * an absolute `location`).
+ *
+ * Containment is checked twice, mirroring `resolveWithinScope`'s
+ * `path.relative()`-based escape check (never `startsWith`, which a sibling
+ * directory that merely shares the root as a string prefix — e.g.
+ * `<root>-evil` — would defeat):
+ *
+ * 1. On the nominal (pre-existence) resolved path — so a location that's
+ *    outside the root by construction (`../../etc/passwd`, or the sibling-
+ *    prefix case above) is refused with zero filesystem access.
+ * 2. On the `realpath`-resolved path — so a symlink that lives inside the
+ *    root but *points* outside it is also refused, after resolving the
+ *    symlink (metadata only) but still before any content read.
+ *
+ * The read size is capped (`MAX_CONTENT_BYTES`) via `statSync` before the
+ * file is ever read or parsed.
+ */
+export declare function resolveArtifactContent(artifactsRoot: string, location: string): ArtifactContentDto;

package/dist-server/harness/route/artifact-content.js

@@ -0,0 +1,83 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+/** Read-size cap applied before any read/parse — an artifact past
+ * this is refused as `too_large` rather than loaded whole into memory. */
+const MAX_CONTENT_BYTES = 2 * 1024 * 1024; // 2 MiB
+/**
+ * Resolves an `ArtifactRow.location` back to its on-disk content, scoped to
+ * `artifactsRoot` (the same root `resolveArtifactsDir` computes for in-process/B
+ * writes — see `in-process.ts` and `turn.ts`'s `maybeCreateDispatchedArtifact`).
+ * `location` may be relative (in-process, written under the model's chosen
+ * `write_artifact` path, itself scoped to `artifactsRoot` at write time — see
+ * `resolveWithinScope` in `exec/local.ts`) or absolute (dispatched always writes
+ * an absolute `location`).
+ *
+ * Containment is checked twice, mirroring `resolveWithinScope`'s
+ * `path.relative()`-based escape check (never `startsWith`, which a sibling
+ * directory that merely shares the root as a string prefix — e.g.
+ * `<root>-evil` — would defeat):
+ *
+ * 1. On the nominal (pre-existence) resolved path — so a location that's
+ *    outside the root by construction (`../../etc/passwd`, or the sibling-
+ *    prefix case above) is refused with zero filesystem access.
+ * 2. On the `realpath`-resolved path — so a symlink that lives inside the
+ *    root but *points* outside it is also refused, after resolving the
+ *    symlink (metadata only) but still before any content read.
+ *
+ * The read size is capped (`MAX_CONTENT_BYTES`) via `statSync` before the
+ * file is ever read or parsed.
+ */
+export function resolveArtifactContent(artifactsRoot, location) {
+    const nominal = path.isAbsolute(location) ? path.resolve(location) : path.resolve(artifactsRoot, location);
+    if (escapesRoot(artifactsRoot, nominal))
+        return { form: "unavailable", reason: "outside_root" };
+    let realRoot;
+    let realTarget;
+    try {
+        realRoot = realpathSync(artifactsRoot);
+        realTarget = realpathSync(nominal);
+    }
+    catch {
+        return { form: "unavailable", reason: "missing" };
+    }
+    if (escapesRoot(realRoot, realTarget))
+        return { form: "unavailable", reason: "outside_root" };
+    let size;
+    try {
+        size = statSync(realTarget).size;
+    }
+    catch {
+        return { form: "unavailable", reason: "unreadable" };
+    }
+    if (size > MAX_CONTENT_BYTES)
+        return { form: "unavailable", reason: "too_large" };
+    let raw;
+    try {
+        raw = readFileSync(realTarget, "utf-8");
+    }
+    catch {
+        return { form: "unavailable", reason: "unreadable" };
+    }
+    const envelope = tryParseEnvelope(raw);
+    return envelope ? { form: "envelope", envelope } : { form: "text", text: raw, truncated: false };
+}
+/** Same escape condition as `exec/local.ts`'s `resolveWithinScope`. */
+function escapesRoot(root, target) {
+    const relative = path.relative(root, target);
+    return relative.startsWith("..") || path.isAbsolute(relative);
+}
+function tryParseEnvelope(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return hasBlocksArray(parsed) ? parsed : undefined;
+}
+/** Mirrors the private `hasBlocksArray` shape-check in `render/envelope.ts` — reimplemented
+ * locally rather than exported from there, to keep that module's blast radius unchanged. */
+function hasBlocksArray(value) {
+    return typeof value === "object" && value !== null && Array.isArray(value.blocks);
+}

package/dist-server/harness/route/chat-event-mapper.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Dispatched's own mapping FROM warble's `chat --stream-json` NDJSON stream TO this harness's
+ * mode-agnostic `AgentEvent` union (`harness/events/types.ts`). Two things live here:
+ *
+ *  - `WarbleChatEventLike` — a LOCAL structural mirror of warble's own `WarbleChatEvent` vocabulary
+ *    (`dispatcher/claude-agent-sdk/src/events.ts` in the warble repo). It is intentionally NOT
+ *    imported from warble: warble is a separate process/package this harness only ever talks to
+ *    over a subprocess's stdout, never a library dependency, so the wire contract is re-declared
+ *    here by hand rather than crossing that boundary with a type import. Keep it in sync with
+ *    warble's vocabulary if that ever changes.
+ *  - `mapChatEventToAgentEvent` — a PURE function turning one parsed `WarbleChatEventLike` plus a
+ *    small piece of running state (the current enclosing step id, and callId/stepId -> name
+ *    memory) into zero or one `AgentEventInput`. Pure so it's unit-testable with plain data, no
+ *    process/stream involved.
+ *
+ * Step/tool id mapping: warble's own mapper emits ONE enclosing `step_start` per turn (id = the
+ * Dispatched component's verb) and groups every `tool_call`/`tool_result` under it — see that
+ * module's doc comment for why. This function carries that same single `stepId` forward onto
+ * every `tool.call`/`tool.result` it produces (`ToolCallEvent`/`ToolResultEvent` both require a
+ * `stepId`), tracked in `state.currentStepId` as `step_start` events arrive.
+ *
+ * `answer` is deliberately mapped to `undefined` — the turn's final answer text is handled by the
+ * caller (`runDispatchedDefault`'s existing `answer`/`run.finish` emission), not duplicated here. `session`
+ * is likewise mapped to `undefined` for the same reason: it is session-resume metadata (the SDK's
+ * `session_id`, forwarded on both a successful AND a failed/`error_max_turns` turn), not a work-log
+ * event, and `spawnChat` intercepts it directly rather than routing it through this mapper.
+ */
+import type { AgentEventInput } from "../events/index.js";
+export type WarbleChatEventLike = {
+    readonly t: "step_start";
+    readonly id: string;
+    readonly name: string;
+    readonly parent: string | null;
+    readonly depth: number;
+} | {
+    readonly t: "step_finish";
+    readonly id: string;
+    readonly ok: boolean;
+    readonly detail?: string;
+} | {
+    readonly t: "tool_call";
+    readonly id: string;
+    readonly name: string;
+    readonly input?: unknown;
+    readonly parent: string | null;
+    readonly depth: number;
+} | {
+    readonly t: "tool_result";
+    readonly id: string;
+    readonly ok: boolean;
+    readonly summary?: string;
+    readonly error?: string;
+} | {
+    readonly t: "answer";
+    readonly text: string;
+} | {
+    /**
+     * The turn's SDK session id (multi-turn resume anchor), emitted once per turn by
+     * `warble-agent-sdk chat --stream-json` on success AND on a failed turn (e.g.
+     * `error_max_turns`) — mirrors warble's own `WarbleChatEvent`'s `session` variant
+     * (`dispatcher/claude-agent-sdk/src/events.ts`). `id` is null only if the SDK never
+     * produced a session id at all.
+     */
+    readonly t: "session";
+    readonly id: string | null;
+};
+/**
+ * Parse + structurally validate one NDJSON line from `warble-agent-sdk chat --stream-json`.
+ * Returns `undefined` for a blank line, invalid JSON, or a shape that doesn't match any known
+ * `WarbleChatEventLike` variant — the caller drops such lines rather than failing the whole turn
+ * over one malformed/forward-incompatible line.
+ */
+export declare function parseWarbleChatEventLine(line: string): WarbleChatEventLike | undefined;
+/**
+ * Running state threaded across a turn's whole NDJSON stream. `currentStepId` is warble's single
+ * enclosing step for the turn (set on `step_start`); `stepNames`/`toolNames` remember the
+ * human-readable name for a given step/call id so a later `step_finish`/`tool_result` — which
+ * carry no name of their own in warble's vocabulary — can still populate `StepFinishEvent.name` /
+ * `ToolResultEvent.tool`.
+ */
+export interface ChatEventMapperState {
+    currentStepId: string | undefined;
+    readonly stepNames: Map<string, string>;
+    readonly toolNames: Map<string, string>;
+}
+export declare function createChatEventMapperState(): ChatEventMapperState;
+/**
+ * Maps one parsed warble chat event to the harness's `AgentEvent` vocabulary, mutating `state` as
+ * it goes (remembering step/tool names, tracking the current enclosing step). Returns `undefined`
+ * for `answer` (handled by the caller) and for a `tool_call`/`tool_result` this mapper cannot
+ * place under any known step — that should never happen given warble always opens its enclosing
+ * step before emitting a tool event, but falling back to the raw id rather than throwing keeps a
+ * single malformed/reordered line from crashing an otherwise-healthy live stream.
+ */
+export declare function mapChatEventToAgentEvent(raw: WarbleChatEventLike, state: ChatEventMapperState): AgentEventInput | undefined;