@wrenai/genbi 0.0.1

package/dist-server/harness/events/emitter.d.ts

@@ -0,0 +1,34 @@
+import type { AgentEvent } from "./types.js";
+/**
+ * Plain `Omit<AgentEvent, K>` does NOT distribute over the `AgentEvent`
+ * union — `Omit` is `Pick<T, Exclude<keyof T, K>>`, and `keyof` of a union
+ * only yields the keys common to every member, collapsing every variant-
+ * specific field (`stepId`, `tool`, `envelope`, ...) down to nothing.
+ * Distributing over each member first (via the naked `T extends any`
+ * conditional) preserves each variant's own fields and its `kind` literal.
+ */
+export type DistributiveOmit<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+/**
+ * What an emission site (`runAgent`, `executeAgent`) actually knows: an
+ * `AgentEvent` minus the `runId`/`seq` bookkeeping that only the emitter
+ * that owns the run's counter can stamp.
+ */
+export type AgentEventInput = DistributiveOmit<AgentEvent, "runId" | "seq">;
+export interface AgentEventEmitter {
+    readonly runId: string;
+    /** Stamps `runId`/`seq` onto `event` and forwards it to the sink. No-op (and never throws) when no sink was given. */
+    emit(event: AgentEventInput): void;
+}
+/**
+ * Owns one run's `runId` + monotonic `seq` counter, so two independent
+ * emission sites (`runAgent` for run/answer/refusal/run.finish/error;
+ * `executeAgent` for step/tool/artifact) can each describe *what happened*
+ * without needing to coordinate numbering themselves. `runAgent` is the
+ * natural sole owner: it creates one `AgentEventEmitter` per call and passes
+ * `emit` down as `ExecuteAgentContext.onEvent`.
+ *
+ * `sink` is the outward-facing seam (`RunAgentContext.onEvent`/
+ * `RouteOptions.onEvent`), typed `(e: AgentEvent) => void` exactly as the
+ * contract specifies — callers never see the bookkeeping split.
+ */
+export declare function createAgentEventEmitter(sink: ((event: AgentEvent) => void) | undefined, runId?: string): AgentEventEmitter;

package/dist-server/harness/events/emitter.js

@@ -0,0 +1,25 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Owns one run's `runId` + monotonic `seq` counter, so two independent
+ * emission sites (`runAgent` for run/answer/refusal/run.finish/error;
+ * `executeAgent` for step/tool/artifact) can each describe *what happened*
+ * without needing to coordinate numbering themselves. `runAgent` is the
+ * natural sole owner: it creates one `AgentEventEmitter` per call and passes
+ * `emit` down as `ExecuteAgentContext.onEvent`.
+ *
+ * `sink` is the outward-facing seam (`RunAgentContext.onEvent`/
+ * `RouteOptions.onEvent`), typed `(e: AgentEvent) => void` exactly as the
+ * contract specifies — callers never see the bookkeeping split.
+ */
+export function createAgentEventEmitter(sink, runId = randomUUID()) {
+    let seq = 0;
+    return {
+        runId,
+        emit(event) {
+            if (!sink)
+                return;
+            seq += 1;
+            sink({ ...event, runId, seq });
+        },
+    };
+}

package/dist-server/harness/events/index.d.ts

@@ -0,0 +1,4 @@
+export { createAgentEventEmitter } from "./emitter.js";
+export type { AgentEventEmitter, AgentEventInput } from "./emitter.js";
+export { MalformedSseFrameError, parseAgentEvent, serializeAgentEvent } from "./sse.js";
+export type { AgentEvent, AgentEventBase, AgentEventKind, AnswerAgentEvent, ArtifactAgentEvent, ArtifactKind, ErrorAgentEvent, RefusalAgentEvent, RunFinishEvent, RunStartEvent, StepFinishEvent, StepStartEvent, StepTrace, TokenEvent, ToolCallEvent, ToolResultEvent, TraceStep, } from "./types.js";

package/dist-server/harness/events/index.js

@@ -0,0 +1,2 @@
+export { createAgentEventEmitter } from "./emitter.js";
+export { MalformedSseFrameError, parseAgentEvent, serializeAgentEvent } from "./sse.js";

package/dist-server/harness/events/sse.d.ts

@@ -0,0 +1,20 @@
+import type { AgentEvent } from "./types.js";
+/**
+ * Serializes one `AgentEvent` as a single `text/event-stream` frame per the
+ * harness→BFF wire format: `event: <kind>\ndata:
+ * <json>\n\n`. The harness itself never opens a socket — the BFF runs it
+ * In-process and consumes `AgentEvent`s directly via `onEvent` — this is
+ * only for the documented "if a future out-of-process split is wanted"
+ * fallback, defined + unit-tested here so it exists when needed.
+ */
+export declare function serializeAgentEvent(event: AgentEvent): string;
+export declare class MalformedSseFrameError extends Error {
+    constructor(reason: string, frame: string);
+}
+/**
+ * The round-trip counterpart to `serializeAgentEvent`. Not a general SSE-
+ * stream parser (no multi-frame buffering, no comment/retry-field support)
+ * — the wire format here is always exactly one `event:` line + one `data:`
+ * line per frame, so this only ever needs to split a single frame in two.
+ */
+export declare function parseAgentEvent(frame: string): AgentEvent;

package/dist-server/harness/events/sse.js

@@ -0,0 +1,48 @@
+/**
+ * Serializes one `AgentEvent` as a single `text/event-stream` frame per the
+ * harness→BFF wire format: `event: <kind>\ndata:
+ * <json>\n\n`. The harness itself never opens a socket — the BFF runs it
+ * In-process and consumes `AgentEvent`s directly via `onEvent` — this is
+ * only for the documented "if a future out-of-process split is wanted"
+ * fallback, defined + unit-tested here so it exists when needed.
+ */
+export function serializeAgentEvent(event) {
+    return `event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`;
+}
+export class MalformedSseFrameError extends Error {
+    constructor(reason, frame) {
+        super(`malformed SSE AgentEvent frame (${reason}): ${JSON.stringify(frame)}`);
+        this.name = "MalformedSseFrameError";
+    }
+}
+/**
+ * The round-trip counterpart to `serializeAgentEvent`. Not a general SSE-
+ * stream parser (no multi-frame buffering, no comment/retry-field support)
+ * — the wire format here is always exactly one `event:` line + one `data:`
+ * line per frame, so this only ever needs to split a single frame in two.
+ */
+export function parseAgentEvent(frame) {
+    const trimmed = frame.endsWith("\n\n") ? frame.slice(0, -2) : frame;
+    const lines = trimmed.split("\n");
+    const eventLine = lines.find((line) => line.startsWith("event: "));
+    const dataLine = lines.find((line) => line.startsWith("data: "));
+    if (!eventLine || !dataLine) {
+        throw new MalformedSseFrameError("missing event: or data: line", frame);
+    }
+    const kind = eventLine.slice("event: ".length);
+    let parsed;
+    try {
+        parsed = JSON.parse(dataLine.slice("data: ".length));
+    }
+    catch {
+        throw new MalformedSseFrameError("data: line is not valid JSON", frame);
+    }
+    if (typeof parsed !== "object" || parsed === null || !("kind" in parsed)) {
+        throw new MalformedSseFrameError("data payload has no kind field", frame);
+    }
+    const data = parsed;
+    if (data.kind !== kind) {
+        throw new MalformedSseFrameError(`event: "${kind}" does not match data.kind "${data.kind}"`, frame);
+    }
+    return data;
+}

package/dist-server/harness/events/types.d.ts

@@ -0,0 +1,131 @@
+import type { RenderEnvelope } from "../render/index.js";
+/**
+ * The mode-agnostic, back-end-emitted event union. Both in-process (the
+ * Vercel AI SDK) and dispatched (shelled `warble-agent-sdk chat`) emit this same
+ * shape; the BFF (out of scope here) folds it into the UI's own SSE wire
+ * frames.
+ *
+ * `parent`/`depth` (on `step.*`/`tool.*`) model sub-agent nesting. In-process has
+ * no Task mechanism — `executeAgent` runs a flat in-process DAG — so its
+ * events always carry `depth: 0` and never set `parent`. Only dispatched can
+ * populate them (this harness does not currently parse dispatched's own nesting;
+ * see `route/dispatched.ts`'s doc comment for the gap).
+ */
+export type AgentEventKind = "run.start" | "step.start" | "step.finish" | "tool.call" | "tool.result" | "token" | "answer" | "refusal" | "artifact" | "run.finish" | "error";
+/** Every `AgentEvent` carries these — stamped by `createAgentEventEmitter`, never by an emission site itself. */
+export interface AgentEventBase {
+    readonly runId: string;
+    readonly seq: number;
+}
+export interface RunStartEvent extends AgentEventBase {
+    readonly kind: "run.start";
+    readonly mode: "A" | "B";
+    readonly agentId: string;
+}
+export interface StepStartEvent extends AgentEventBase {
+    readonly kind: "step.start";
+    readonly stepId: string;
+    readonly name: string;
+    readonly tier: string;
+    readonly parent?: string;
+    readonly depth: number;
+}
+export interface StepFinishEvent extends AgentEventBase {
+    readonly kind: "step.finish";
+    readonly stepId: string;
+    readonly name: string;
+    readonly status: "ok" | "error";
+    /**
+     * The step's own reasoning/output: on `"ok"` this is
+     * `summarizeToolOutput(text)` (the step's produced artifact text, bounded);
+     * on `"error"` it's the best available description of what went wrong.
+     * Optional/additive — a step.finish with no `detail` behaves exactly as it
+     * did before this field existed.
+     */
+    readonly detail?: string;
+}
+export interface ToolCallEvent extends AgentEventBase {
+    readonly kind: "tool.call";
+    readonly stepId: string;
+    readonly callId: string;
+    readonly tool: string;
+    readonly input?: unknown;
+    readonly parent?: string;
+    readonly depth: number;
+    readonly status: "running";
+}
+export interface ToolResultEvent extends AgentEventBase {
+    readonly kind: "tool.result";
+    readonly stepId: string;
+    readonly callId: string;
+    readonly tool: string;
+    readonly status: "success" | "error";
+    /**
+     * Optional late-bound input for back-ends that only receive a safe tool
+     * payload when the call completes. LiveWorkLog merges this onto the
+     * matching tool.call entry before persisting the result.
+     */
+    readonly input?: unknown;
+    readonly summary?: string;
+    readonly error?: string;
+}
+export interface TokenEvent extends AgentEventBase {
+    readonly kind: "token";
+    readonly text: string;
+}
+/** `envelope` is in-process's shape (`RenderEnvelope`); `text` is dispatched's (`finalText`). Never both. */
+export interface AnswerAgentEvent extends AgentEventBase {
+    readonly kind: "answer";
+    readonly envelope?: RenderEnvelope;
+    readonly text?: string;
+}
+export interface RefusalAgentEvent extends AgentEventBase {
+    readonly kind: "refusal";
+    readonly reason: string;
+    readonly envelope?: RenderEnvelope;
+}
+export type ArtifactKind = "dashboard" | "report" | "chart";
+export interface ArtifactAgentEvent extends AgentEventBase {
+    readonly kind: "artifact";
+    readonly name: string;
+    readonly artifactKind: ArtifactKind;
+    readonly location: string;
+}
+export interface RunFinishEvent extends AgentEventBase {
+    readonly kind: "run.finish";
+    readonly status: "answer" | "refusal" | "error";
+}
+export interface ErrorAgentEvent extends AgentEventBase {
+    readonly kind: "error";
+    readonly message: string;
+}
+export type AgentEvent = RunStartEvent | StepStartEvent | StepFinishEvent | ToolCallEvent | ToolResultEvent | TokenEvent | AnswerAgentEvent | RefusalAgentEvent | ArtifactAgentEvent | RunFinishEvent | ErrorAgentEvent;
+/**
+ * The minimal, deliberately-scoped trace floor. Built from the existing
+ * `onToolCallOutcome` seam with zero new emission infrastructure:
+ * terminal-only (no `running` state), flat (no `parent`/`depth`), ordered by
+ * fire order. See `runAgent`'s doc comment.
+ */
+export interface TraceStep {
+    readonly id: string;
+    readonly tool: string;
+    readonly outcome: "success" | "error";
+    readonly ordinal: number;
+    /**
+     * The tool call's input (e.g. the `query` tool's `{sql}`), so the UI's
+     * work-log can expand a step to show what it ran. Sourced straight from
+     * `ToolCallOutcome.input`; `unknown` because tool inputs are arbitrary
+     * per-tool shapes.
+     */
+    readonly input?: unknown;
+    /**
+     * A compact, bounded human summary of what happened: on `"success"` this
+     * is `summarizeToolOutput(outcome.output)`; on `"error"` it's
+     * `outcome.error`. Never the full result payload — always short enough to
+     * render inline in a collapsed work-log row.
+     */
+    readonly detail?: string;
+}
+export interface StepTrace {
+    readonly steps: readonly TraceStep[];
+}

package/dist-server/harness/events/types.js

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

package/dist-server/harness/exec/errors.d.ts

@@ -0,0 +1,16 @@
+/** Thrown when a requested path resolves outside its granted scope (directory traversal). */
+export declare class PathTraversalError extends Error {
+    constructor(requestedPath: string, scope: string);
+}
+/** Thrown by `writeFile` when the policy grants no `artifactWriteScope` at all. */
+export declare class WriteScopeNotGrantedError extends Error {
+    constructor(requestedPath: string);
+}
+/** Thrown by `exec` when a `mode: "write"` command runs under a read-only policy. */
+export declare class ReadOnlyViolationError extends Error {
+    constructor(command: string);
+}
+/** Thrown by `fetch` when the target host isn't in the policy's egress allowlist. */
+export declare class EgressNotAllowedError extends Error {
+    constructor(host: string);
+}

package/dist-server/harness/exec/errors.js

@@ -0,0 +1,29 @@
+/** Thrown when a requested path resolves outside its granted scope (directory traversal). */
+export class PathTraversalError extends Error {
+    constructor(requestedPath, scope) {
+        super(`path "${requestedPath}" escapes the scoped workspace "${scope}"`);
+        this.name = "PathTraversalError";
+    }
+}
+/** Thrown by `writeFile` when the policy grants no `artifactWriteScope` at all. */
+export class WriteScopeNotGrantedError extends Error {
+    constructor(requestedPath) {
+        super(`write to "${requestedPath}" rejected: the enforcement policy grants no artifactWriteScope ` +
+            `(the agent has no locked scoped_write guardrail)`);
+        this.name = "WriteScopeNotGrantedError";
+    }
+}
+/** Thrown by `exec` when a `mode: "write"` command runs under a read-only policy. */
+export class ReadOnlyViolationError extends Error {
+    constructor(command) {
+        super(`command "${command}" declares mode: "write" but the enforcement policy is read-only`);
+        this.name = "ReadOnlyViolationError";
+    }
+}
+/** Thrown by `fetch` when the target host isn't in the policy's egress allowlist. */
+export class EgressNotAllowedError extends Error {
+    constructor(host) {
+        super(`fetch to host "${host}" is not in the egress allowlist`);
+        this.name = "EgressNotAllowedError";
+    }
+}

package/dist-server/harness/exec/index.d.ts

@@ -0,0 +1,5 @@
+export type { ExecCommand, ExecMode, ExecResult, ExecutionEnv, FetchRequest, FetchResponse } from "./types.js";
+export type { ExecutionPolicy } from "./policy.js";
+export { EgressNotAllowedError, PathTraversalError, ReadOnlyViolationError, WriteScopeNotGrantedError, } from "./errors.js";
+export { createLocalExecutionEnv } from "./local.js";
+export type { FetchImpl, LocalExecutionEnvOptions, RawFetchResponse } from "./local.js";

package/dist-server/harness/exec/index.js

@@ -0,0 +1,2 @@
+export { EgressNotAllowedError, PathTraversalError, ReadOnlyViolationError, WriteScopeNotGrantedError, } from "./errors.js";
+export { createLocalExecutionEnv } from "./local.js";

package/dist-server/harness/exec/local.d.ts

@@ -0,0 +1,32 @@
+import type { ExecCommand, ExecResult, ExecutionEnv } from "./types.js";
+/** The minimal shape `local.ts` needs from a fetch response — matches the global `Response`. */
+export interface RawFetchResponse {
+    readonly status: number;
+    text(): Promise<string>;
+}
+export type FetchImpl = (url: string, init: {
+    readonly method: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}) => Promise<RawFetchResponse>;
+export interface LocalExecutionEnvOptions {
+    /** Base directory `artifactWriteScope` (and any relative path) resolves against. Defaults to `process.cwd()`. */
+    readonly rootDir?: string;
+    /** Overridable for hermetic tests; defaults to the global `fetch`. */
+    readonly fetchImpl?: FetchImpl;
+    /** Overridable for hermetic tests; defaults to spawning `cmd.command` with `cmd.args` (no shell). */
+    readonly execImpl?: (cmd: ExecCommand) => Promise<ExecResult>;
+    /** Overridable for hermetic tests; defaults to 32 MiB (matches compile/pipeline.ts + route/dispatched.ts). */
+    readonly maxBufferBytes?: number;
+}
+/**
+ * The v1 `local` `ExecutionEnv` backend: in-process file I/O confined
+ * to a scoped workspace, a no-shell subprocess runner gated by
+ * `policy.readOnly`, and a basic host allowlist for `fetch`. This is not a
+ * sandbox — it adds exactly the checks the guardrail mapping
+ * (`harness/guardrails/`) requires so a locked `read_only_execution` or
+ * `scoped_write` guardrail has real teeth here, not just prose in a prompt.
+ * No microVM/delegated/egress-proxy/credential-broker backend exists yet
+ * (out of scope for this milestone).
+ */
+export declare function createLocalExecutionEnv(options?: LocalExecutionEnvOptions): ExecutionEnv;

package/dist-server/harness/exec/local.js

@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile as readFileAsync, writeFile as writeFileAsync } from "node:fs/promises";
+import path from "node:path";
+import { EgressNotAllowedError, PathTraversalError, ReadOnlyViolationError, WriteScopeNotGrantedError } from "./errors.js";
+const DEFAULT_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/**
+ * The v1 `local` `ExecutionEnv` backend: in-process file I/O confined
+ * to a scoped workspace, a no-shell subprocess runner gated by
+ * `policy.readOnly`, and a basic host allowlist for `fetch`. This is not a
+ * sandbox — it adds exactly the checks the guardrail mapping
+ * (`harness/guardrails/`) requires so a locked `read_only_execution` or
+ * `scoped_write` guardrail has real teeth here, not just prose in a prompt.
+ * No microVM/delegated/egress-proxy/credential-broker backend exists yet
+ * (out of scope for this milestone).
+ */
+export function createLocalExecutionEnv(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const fetchImpl = options.fetchImpl ?? ((url, init) => fetch(url, init));
+    const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+    const execImpl = options.execImpl ?? ((cmd) => runSubprocess(cmd, maxBufferBytes));
+    return {
+        async exec(cmd, policy) {
+            if (cmd.mode === "write" && policy.readOnly) {
+                throw new ReadOnlyViolationError(cmd.command);
+            }
+            return execImpl(cmd);
+        },
+        async readFile(filePath, policy) {
+            const resolved = resolveWithinScope(rootDir, policy.artifactWriteScope, filePath);
+            return readFileAsync(resolved, "utf-8");
+        },
+        async writeFile(filePath, data, policy) {
+            // read_only_execution and a locked scoped_write guardrail coexist by
+            // design (see EnforcementPolicy's doc comment) — writing the output
+            // artifact is gated purely on artifactWriteScope, never on readOnly.
+            if (policy.artifactWriteScope === undefined) {
+                throw new WriteScopeNotGrantedError(filePath);
+            }
+            const resolved = resolveWithinScope(rootDir, policy.artifactWriteScope, filePath);
+            await mkdir(path.dirname(resolved), { recursive: true });
+            await writeFileAsync(resolved, data, "utf-8");
+        },
+        async fetch(req, policy) {
+            const host = new URL(req.url).host;
+            const allowed = policy.allowedHosts ?? [];
+            if (!allowed.includes(host)) {
+                throw new EgressNotAllowedError(host);
+            }
+            const response = await fetchImpl(req.url, {
+                method: req.method ?? "GET",
+                ...(req.headers ? { headers: req.headers } : {}),
+                ...(req.body !== undefined ? { body: req.body } : {}),
+            });
+            const body = await response.text();
+            return { status: response.status, body };
+        },
+    };
+}
+/**
+ * Resolves `requestedPath` against `scope` (itself resolved against
+ * `rootDir` when relative) and rejects anything that escapes it — the
+ * directory-traversal check `writeFile`/`readFile` both rely on. A
+ * `scope` of `undefined` confines reads to `rootDir` directly; `writeFile`
+ * rejects that case itself before ever reaching here.
+ */
+function resolveWithinScope(rootDir, scope, requestedPath) {
+    const scopeAbs = path.resolve(rootDir, scope ?? ".");
+    const targetAbs = path.resolve(scopeAbs, requestedPath);
+    const relative = path.relative(scopeAbs, targetAbs);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new PathTraversalError(requestedPath, scopeAbs);
+    }
+    return targetAbs;
+}
+function runSubprocess(cmd, maxBufferBytes) {
+    return new Promise((resolve) => {
+        const options = {
+            maxBuffer: maxBufferBytes,
+            ...(cmd.cwd !== undefined ? { cwd: cmd.cwd } : {}),
+            ...(cmd.timeoutMs !== undefined ? { timeout: cmd.timeoutMs } : {}),
+        };
+        const child = execFile(cmd.command, cmd.args ? [...cmd.args] : [], options, (error, stdout, stderr) => {
+            // A spawn failure (the binary isn't on PATH/doesn't exist)
+            // reports its error as `error.code === "ENOENT"` — a STRING. The old
+            // `typeof error.code === "number"` check treated that as "not a real
+            // exit code" and fell through to the generic `error ? 1 : 0`,
+            // flattening a missing-binary condition into an indistinguishable
+            // `exitCode: 1` with empty `stderr` (the process never ran, so it
+            // never wrote anything) — laundering a clear "not found" into what
+            // looks like an ordinary command failure.
+            if (error && error.code === "ENOENT") {
+                resolve({ stdout, stderr, exitCode: 1, notFound: true });
+                return;
+            }
+            // guardrail-enforcement fix: `statementTimeoutSec` is only real
+            // enforcement if a hung `wren`/`warble` subprocess actually gets killed
+            // and reported distinguishably, rather than left to run forever. Node
+            // sets `error.killed === true` for its own `timeout` option; `stderr`
+            // is often empty in this case (the process was killed mid-run, not
+            // given a chance to explain itself), so a fallback message is supplied.
+            if (error && error.killed === true) {
+                resolve({
+                    stdout,
+                    stderr: stderr.length > 0 ? stderr : `subprocess "${cmd.command}" timed out after ${cmd.timeoutMs}ms`,
+                    exitCode: 1,
+                    timedOut: true,
+                });
+                return;
+            }
+            // Same rationale as above, for the other silent-killer: an oversized
+            // result set previously died on execFile's default 1 MiB `maxBuffer`
+            // as an opaque exit-1 with empty stderr, indistinguishable from any
+            // other failure.
+            if (error && error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+                resolve({
+                    stdout,
+                    stderr: stderr.length > 0 ? stderr : `subprocess "${cmd.command}" exceeded the ${maxBufferBytes}-byte output buffer`,
+                    exitCode: 1,
+                    maxBufferExceeded: true,
+                });
+                return;
+            }
+            const exitCode = error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+            resolve({ stdout, stderr, exitCode });
+        });
+        // ExecCommand has no stdin/input field: every command routed through this
+        // backend is deliberately non-interactive. Leaving execFile's writable
+        // stdin pipe open falsely promises that input may arrive later, so a bare
+        // interpreter or any other stdin reader waits forever. End it immediately
+        // to deliver EOF; if a future caller needs input, that must become an
+        // explicit ExecCommand contract which writes the payload and then ends.
+        child.stdin?.end();
+    });
+}

package/dist-server/harness/exec/policy.d.ts

@@ -0,0 +1,12 @@
+import type { EnforcementPolicy } from "../guardrails/index.js";
+/**
+ * The policy every `ExecutionEnv` method receives: the guardrail-derived
+ * `EnforcementPolicy` (`harness/guardrails/`) plus an egress allowlist. The
+ * allowlist has no bundle representation in v1 — the golden bundle never
+ * declares a host/dataset egress guardrail — so callers supply it directly
+ * (see `RunAgentContext.allowedHosts` in `harness/session/run.ts`). Omitting it
+ * means "no hosts allowed", the safe default.
+ */
+export interface ExecutionPolicy extends EnforcementPolicy {
+    readonly allowedHosts?: readonly string[];
+}

package/dist-server/harness/exec/policy.js

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

package/dist-server/harness/exec/types.d.ts

@@ -0,0 +1,63 @@
+import type { ExecutionPolicy } from "./policy.js";
+/**
+ * A command's declared read/write intent. The harness does not parse or
+ * sniff shell commands to infer this — the caller (a native tool) states it
+ * up front, and a read-only policy rejects `"write"` commands outright.
+ */
+export type ExecMode = "read" | "write";
+export interface ExecCommand {
+    readonly mode: ExecMode;
+    readonly command: string;
+    readonly args?: readonly string[];
+    /** Working directory the command runs in. Defaults to the process's cwd when omitted. */
+    readonly cwd?: string;
+    /** Maximum time (ms) the subprocess may run before being killed. Omitted means no timeout. */
+    readonly timeoutMs?: number;
+}
+export interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    /**
+     * Set (`true`) when `cmd.command` itself could not be launched — a spawn
+     * `ENOENT` (the binary isn't on `PATH`/doesn't exist), as opposed to the
+     * command running and exiting non-zero on its own. Node's spawn error
+     * carries this as the *string* `"ENOENT"` on `error.code`, not a number,
+     * so callers must check `notFound` rather than inferring it from
+     * `exitCode` — `exitCode` is set to `1` in this case only as a
+     * conservative "not success" fallback for code that ignores `notFound`,
+     * never as the real signal. Omitted (not just `false`) on an ordinary
+     * exit so existing structural equality checks on `ExecResult` are
+     * unaffected. See `createLocalExecutionEnv`'s `runSubprocess`.
+     */
+    readonly notFound?: boolean;
+    /** Set (`true`) when the subprocess was killed because it exceeded `ExecCommand.timeoutMs`. Node's `execFile` sets `error.killed === true` for its own `timeout` option (and NOT for maxBuffer-exceeded — verified: `error.code` is `null` for timeout, not a number, not `"ENOENT"`). Omitted (not `false`) on an ordinary exit, same convention as `notFound`. */
+    readonly timedOut?: boolean;
+    /** Set (`true`) when the subprocess's combined stdout/stderr exceeded the exec backend's `maxBuffer` and was killed. Node reports this as `error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"` (verified on Node 23), distinct from both `notFound` and `timedOut`. Omitted (not `false`) on an ordinary exit. */
+    readonly maxBufferExceeded?: boolean;
+}
+export interface FetchRequest {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+export interface FetchResponse {
+    readonly status: number;
+    readonly body: string;
+}
+/**
+ * The pluggable seam side-effecting native tools execute through instead of
+ * touching the filesystem/network/subprocess directly — mirroring the
+ * "injectable, defaulted" shape of `ProviderRegistry` and
+ * `NativeToolRegistry`. v1 ships exactly one backend
+ * ({@link createLocalExecutionEnv} in `./local.js`); no microVM / delegated /
+ * egress-proxy / credential-broker backend exists yet (out of scope for
+ * this milestone — tracked separately as hosted-runtime hardening).
+ */
+export interface ExecutionEnv {
+    exec(cmd: ExecCommand, policy: ExecutionPolicy): Promise<ExecResult>;
+    readFile(path: string, policy: ExecutionPolicy): Promise<string>;
+    writeFile(path: string, data: string, policy: ExecutionPolicy): Promise<void>;
+    fetch(req: FetchRequest, policy: ExecutionPolicy): Promise<FetchResponse>;
+}

package/dist-server/harness/exec/types.js

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

package/dist-server/harness/guardrails/index.d.ts

@@ -0,0 +1,2 @@
+export { deriveEnforcement } from "./policy.js";
+export type { EnforcementPolicy } from "./policy.js";

package/dist-server/harness/guardrails/index.js

@@ -0,0 +1 @@
+export { deriveEnforcement } from "./policy.js";

package/dist-server/harness/guardrails/policy.d.ts

@@ -0,0 +1,45 @@
+import type { Agent } from "../bundle/schema.js";
+/**
+ * The enforcement policy derived from an agent's `guardrails` map: a
+ * machine-readable summary an `ExecutionEnv`
+ * (`harness/exec/`) can act on directly. Deliberately excludes `gated_check`
+ * (`deterministic_gate` / `additivity_guard`) — `harness/session/gate.ts`
+ * already owns that guardrail's enforcement against the rendered envelope,
+ * and duplicating it here would just be two places to keep in sync.
+ *
+ * For `mcp:<server>/<name>` tools (e.g. `query`), the harness never executes
+ * the tool in-process — the MCP server does — so `rowLimit` /
+ * `statementTimeoutSec` (and `readOnly` for SQL access) are *not* enforced
+ * by this policy directly. They must be passed to the MCP server via its
+ * connection config (`McpServerConfig`, `harness/tools/mcp.ts`) or honored by
+ * the server's own semantics (e.g. a read-only DB role, a statement
+ * timeout on the connection). This module only derives the values; wiring
+ * them into a real server's connection is a caller/deployment concern this
+ * harness does not — and should not pretend to — enforce on the server's
+ * behalf.
+ */
+export interface EnforcementPolicy {
+    readonly readOnly: boolean;
+    readonly artifactWriteScope?: string;
+    readonly rowLimit?: number;
+    readonly statementTimeoutSec?: number;
+    readonly drillDepthLimit?: number;
+}
+/**
+ * Maps an agent's `guardrails` to the harness's enforcement seams: a locked
+ * `read_only` guardrail sets `readOnly`; a locked `scoped_write` guardrail
+ * (with a `scope`) sets `artifactWriteScope`; `threshold_limit` / `generic`
+ * guardrails are matched by guardrail *key* (not just `enforcement`, since
+ * `row_limit` and `drill_depth_limit` share the `threshold_limit`
+ * enforcement kind) onto named numeric limits.
+ *
+ * `read_only_execution` and a locked `scoped_write` guardrail coexisting
+ * (`generate_dashboard`, `explain_change` in the golden bundle) is not a
+ * contradiction: the former restricts *data access* (no write-capable
+ * SQL/tool becomes active), the latter grants a narrow, separate permission
+ * to write the rendered *output artifact* inside `scope`. This is exactly
+ * why the two fields are independent here rather than one overriding the
+ * other — `LocalExecutionEnv.writeFile` (`harness/exec/local.ts`) reflects this
+ * directly, consulting only `artifactWriteScope`, never `readOnly`.
+ */
+export declare function deriveEnforcement(agent: Agent): EnforcementPolicy;