@wrenai/genbi 0.0.1

package/dist-server/server/enrichment.js

@@ -0,0 +1,199 @@
+/**
+ * Host-owned contract for optional post-bind enrichment.
+ *
+ * This is intentionally a GenBI contract, not an import of any runtime's
+ * implementation.  A runtime may inspect and draft, but only this host keeps
+ * the revision lock, risk classification, approvals and completion ledger.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+export class EnrichmentContractError extends Error {
+}
+/**
+ * Identifies a project directory without requiring it to be built. This is
+ * the only resolution `bindProject` may use: binding must succeed for a
+ * freshly connected, not-yet-compiled project, so it can never read or
+ * require `target/mdl.json`.
+ */
+export function resolveProjectIdentity(projectPath) {
+    const canonicalPath = realpathSync(projectPath);
+    const stats = statSync(canonicalPath);
+    return {
+        path: canonicalPath,
+        // `dev` and `ino` are the portable subset Node exposes on POSIX and are
+        // stringified so SQLite/JSON never loses precision on a large inode.
+        identity: `dev:${String(stats.dev)}:ino:${String(stats.ino)}`,
+    };
+}
+/**
+ * Identifies a project directory *and* proves it is built. Only enrichment
+ * call sites may use this: they need a concrete revision to lock a run
+ * against or to fence an in-flight operation, and it is legitimate for them
+ * to refuse (via `EnrichmentContractError`) when the project isn't built.
+ */
+export function resolveEnrichmentBinding(projectPath) {
+    const identity = resolveProjectIdentity(projectPath);
+    return { ...identity, revision: computeBoundProjectRevision(identity.path) };
+}
+export function sameEnrichmentBinding(left, right) {
+    return left.path === right.path
+        && left.identity === right.identity
+        && left.generation === right.generation
+        && left.revision === right.revision;
+}
+export function computeBoundProjectRevision(projectPath) {
+    const required = ["wren_project.yml", path.join("target", "mdl.json")];
+    const hash = createHash("sha256");
+    for (const relative of required) {
+        const file = path.join(projectPath, relative);
+        if (!existsSync(file))
+            throw new EnrichmentContractError("bound project is not built; compile and bind before enriching context");
+        hash.update(relative);
+        hash.update(readFileSync(file));
+    }
+    return `sha256:${hash.digest("hex")}`;
+}
+// Sink paths are project-relative to the bound Wren project root. These must match the real
+// project file layout this codebase already uses everywhere else (see server/context-files.ts:
+// `models/<name>/metadata.yml`, `views/<name>/metadata.yml`, `cubes/<name>/metadata.yml`, a single
+// top-level `relationships.yml`) and, for knowledge, the layout `wren context init` actually
+// creates on disk (core/wren's `_KNOWLEDGE_SUBDIRS` skeleton: `knowledge/knowledge.yml` plus a
+// `knowledge/{rules,glossary,metrics,caveats,sql}/` subdirectory per category — never a flat
+// `knowledge/<file>.md`). A previous edit here fixed a `mdl/`-prefixed shape that could never
+// match a real sink, and introduced this flat `knowledge/*.md` shape in the same breath — which
+// is exactly as unreal: it accepts a path the real layout never produces (`knowledge/general.md`)
+// and rejects the one every project ships with (`knowledge/rules/general.md`). See
+// `test/enrichment-sink-real-layout.test.ts`, which checks these patterns against a project a
+// real `wren context init` produced, not a hand-written string, so this cannot drift again
+// unnoticed.
+const KNOWLEDGE_CATEGORIES = ["rules", "glossary", "metrics", "caveats", "sql"];
+const SINKS = { knowledge_append: new RegExp(`^knowledge/(?:${KNOWLEDGE_CATEGORIES.join("|")})/[a-z0-9_-]+\\.md$`, "i"), new_cube: /^cubes\/[a-z0-9_-]+\/metadata\.yml$/, new_view: /^views\/[a-z0-9_-]+\/metadata\.yml$/, new_relationship: /^relationships\.yml$/, mdl_metric: /^models\/[a-z0-9_-]+\/metadata\.yml$/, calculated_column: /^models\/[a-z0-9_-]+\/metadata\.yml$/, conflict: /^(?:models|views|cubes|knowledge)\/|^relationships\.yml$/, ambiguous: /^(?:models|views|cubes|knowledge)\/|^relationships\.yml$/ };
+function riskFor(kind) { if (kind === "conflict")
+    return "conflict"; if (kind === "ambiguous")
+    return "ambiguous"; return kind === "knowledge_append" ? "low" : "high"; }
+const MAX_OPERATIONS = 20;
+const MAX_SUMMARY_LENGTH = 512;
+const MAX_DRAFT_LENGTH = 4096;
+const DISPLAY_SECRET = /\b(?:api[_ -]?key|access[_ -]?key|password|secret|token|authorization|bearer)\b\s*[:=]\s*[^\s,;]+|\b(?:sk|sess)_[A-Za-z0-9_-]+/gi;
+const DISPLAY_INTERNAL = /(?:\/Users\/|\/home\/|[A-Za-z]:\\\\)[^\s,;]+|\b(?:resume[_ -]?session(?:[_ -]?id)?|sdk[_ -]?session(?:[_ -]?id)?|session[_ -]?id|provider|model|prompt)\b\s*[:=]\s*[^\s,;]+|\b(?:openai|anthropic|gemini|claude|codex)\b/gi;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * Names which check failed so a future occurrence is diagnosable without
+ * reading this source \u2014 but never echoes `value` itself: a value failing
+ * exactly because it's a raw path or credential is the one case the
+ * `DISPLAY_INTERNAL`/`DISPLAY_SECRET` redaction below exists to strip, so
+ * putting it back into the message would defeat that redaction.
+ */
+function display(value, maxLength, field) {
+    if (typeof value !== "string")
+        throw new EnrichmentContractError(`enrichment operation's ${field} must be a string`);
+    if (value.length === 0)
+        throw new EnrichmentContractError(`enrichment operation's ${field} is empty`);
+    if (value.length > maxLength)
+        throw new EnrichmentContractError(`enrichment operation's ${field} exceeds the ${maxLength}-character limit`);
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(value))
+        throw new EnrichmentContractError(`enrichment operation's ${field} contains control characters`);
+    const redacted = value.replace(DISPLAY_SECRET, "[REDACTED]").replace(DISPLAY_INTERNAL, "[REDACTED]").trim();
+    if (redacted.length === 0)
+        throw new EnrichmentContractError(`enrichment operation's ${field} was empty after redaction`);
+    return redacted;
+}
+/**
+ * Converts untrusted model confidence into bounded UI text without making it
+ * an operation-validity gate. Unsafe, missing, or structured values become a
+ * neutral label instead of costing an otherwise valid proposal.
+ */
+export function normalizeEnrichmentConfidence(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "Not provided";
+    if (typeof value !== "string")
+        return "Not provided";
+    try {
+        const label = display(value, 64, "confidence");
+        return label.includes("[REDACTED]") ? "Not provided" : label;
+    }
+    catch {
+        return "Not provided";
+    }
+}
+export function hashEnrichmentOperation(operation) {
+    // Confidence is model-authored display text, so it must not change the
+    // approval-bound identity of an otherwise identical operation.
+    return `sha256:${createHash("sha256").update(JSON.stringify([operation.id, operation.sink, operation.risk, operation.changeKind, operation.summary, operation.draft])).digest("hex")}`;
+}
+export function canonicalizeProposal(draft, revision) {
+    const input = record(draft);
+    if (!input || !Array.isArray(input.operations))
+        throw new EnrichmentContractError("enrichment proposal must be an object with an operations array");
+    if (input.operations.length === 0)
+        throw new EnrichmentContractError("enrichment proposal has no operations");
+    if (input.operations.length > MAX_OPERATIONS)
+        throw new EnrichmentContractError(`enrichment proposal exceeds the ${MAX_OPERATIONS}-operation limit`);
+    const ids = new Set();
+    const operations = input.operations.map((rawOperation) => {
+        const operation = record(rawOperation);
+        if (!operation)
+            throw new EnrichmentContractError("enrichment operation must be an object");
+        if (typeof operation.changeKind !== "string" || !Object.prototype.hasOwnProperty.call(SINKS, operation.changeKind)) {
+            throw new EnrichmentContractError("enrichment operation has an unknown changeKind");
+        }
+        if (typeof operation.sink !== "string" || operation.sink.length === 0 || operation.sink.length > 160) {
+            throw new EnrichmentContractError("enrichment operation's sink is missing, empty, or exceeds the 160-character limit");
+        }
+        if (!SINKS[operation.changeKind].test(operation.sink)) {
+            throw new EnrichmentContractError(`enrichment operation's sink does not match the required layout for changeKind "${operation.changeKind}"`);
+        }
+        const summary = display(operation.summary, MAX_SUMMARY_LENGTH, "summary");
+        const operationDraft = display(operation.draft, MAX_DRAFT_LENGTH, "draft");
+        const changeKind = operation.changeKind;
+        const confidence = normalizeEnrichmentConfidence(operation.confidence);
+        const id = `op-${createHash("sha256").update(JSON.stringify([operation.sink, changeKind, summary, operationDraft])).digest("hex").slice(0, 24)}`;
+        if (ids.has(id))
+            throw new EnrichmentContractError("runtime returned duplicate enrichment operations");
+        ids.add(id);
+        return { id, sink: operation.sink, changeKind, risk: riskFor(changeKind), summary, draft: operationDraft, confidence };
+    });
+    const authoritativeOperations = operations.map(({ id, sink, risk, summary, draft: operationDraft, changeKind }) => ({ id, sink, risk, summary, draft: operationDraft, changeKind }));
+    const hash = `sha256:${createHash("sha256").update(JSON.stringify({ revision, operations: authoritativeOperations })).digest("hex")}`;
+    return { id: `proposal-${hash.slice(7, 31)}`, hash, projectRevision: revision, operations };
+}
+export function requiresApproval(mode, risk) {
+    return risk !== "low" || mode === "grill";
+}
+/**
+ * The host-mediated MCP tool a native `context_enrichment` session uses to
+ * hand a drafted proposal to the host. The agent never writes into the bound
+ * project directly: this tool only carries the proposal *document* through
+ * to the same canonicalize -> shadow-verify -> finalize pipeline `POST
+ * /api/context/enrichment/start` already uses (see `server/app.ts`'s
+ * `settleEnrichmentDraft`). The schema below is deliberately permissive --
+ * `canonicalizeProposal` above is the single source of truth for shape and
+ * content validation, so this schema must not duplicate or drift from it.
+ */
+export const NATIVE_ENRICHMENT_SUBMIT_MCP_TOOL_NAME = "submit_context_proposal";
+export const NATIVE_ENRICHMENT_SUBMIT_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["operations"],
+    properties: {
+        operations: {
+            type: "array",
+            minItems: 1,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["sink", "changeKind", "summary", "draft"],
+                properties: {
+                    sink: { type: "string" },
+                    changeKind: { enum: ["knowledge_append", "new_cube", "new_view", "new_relationship", "mdl_metric", "calculated_column", "conflict", "ambiguous"] },
+                    summary: { type: "string" },
+                    draft: { type: "string" },
+                    confidence: {},
+                },
+            },
+        },
+    },
+};

package/dist-server/server/env-detect.d.ts

@@ -0,0 +1,8 @@
+import type { AdapterEnvStatus } from "./wire-types.js";
+/**
+ * Reports which api-key adapters have their required credential env var present on the BFF
+ * process — booleans only. The key values themselves (or any prefix/suffix/length derived
+ * from them) must never be exposed to the frontend; this is the only shape `GET
+ * /api/config/env-detect` (`server/app.ts`) is allowed to return.
+ */
+export declare function detectAdapterEnv(): AdapterEnvStatus;

package/dist-server/server/env-detect.js

@@ -0,0 +1,17 @@
+/** True iff the named env var is set to a non-empty (non-whitespace-only) value. */
+function isNonEmptyEnv(name) {
+    const value = process.env[name];
+    return value !== undefined && value.trim().length > 0;
+}
+/**
+ * Reports which api-key adapters have their required credential env var present on the BFF
+ * process — booleans only. The key values themselves (or any prefix/suffix/length derived
+ * from them) must never be exposed to the frontend; this is the only shape `GET
+ * /api/config/env-detect` (`server/app.ts`) is allowed to return.
+ */
+export function detectAdapterEnv() {
+    return {
+        anthropic: isNonEmptyEnv("ANTHROPIC_API_KEY"),
+        openaiCompatible: isNonEmptyEnv("OPENAI_API_KEY"),
+    };
+}

package/dist-server/server/env-field-hints.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gives each key in a scaffolded `.env` template the description wren already
+ * publishes for it.
+ *
+ * The credential form is field-key-driven: it renders one input per `KEY=` line
+ * the connect turn wrote, and until now that was all it knew — a name in caps
+ * and whether it looked secret. So `BIGQUERY_TYPE` arrived as an empty box with
+ * no way to know it is a fixed discriminator, and `BIGQUERY_CREDENTIALS` gave
+ * no hint that it wants base64 of a service-account file.
+ *
+ * None of that had to be invented: `wren docs connection-info` already carries a
+ * title, prose, a worked example, required-ness and, for discriminators, the
+ * `const` value. This joins the two.
+ */
+import type { CatalogSource } from "./source-catalog.js";
+export interface EnvFieldHint {
+    readonly key: string;
+    readonly secret: boolean;
+    /** wren's human title, e.g. "Dataset Id". Absent when the key matched no field. */
+    readonly label?: string;
+    readonly description?: string;
+    readonly example?: string;
+    readonly required?: boolean;
+    /**
+     * Set when wren fixes this field's value. The form shows it rather than
+     * asking, since a discriminator's value is decided by the variant, not by
+     * the user.
+     */
+    readonly fixedValue?: string;
+    readonly defaultValue?: string;
+    /**
+     * True when the field wants base64 of a file's contents — wren says so in its
+     * own description. The form offers a file picker for these instead of
+     * expecting a hand-encoded blob.
+     */
+    readonly fileEncoded?: boolean;
+}
+/**
+ * Annotates env keys with their source's field metadata. Keys that match
+ * nothing are returned unchanged rather than dropped: the template is the
+ * agent's output, and a key we cannot explain still has to be fillable.
+ */
+export declare function annotateEnvFields(fields: readonly {
+    readonly key: string;
+    readonly secret: boolean;
+}[], source: CatalogSource | undefined): readonly EnvFieldHint[];

package/dist-server/server/env-field-hints.js

@@ -0,0 +1,48 @@
+/** wren describes these as "Base64 encode `<file>`"; nothing else marks them. */
+function wantsFileUpload(field) {
+    return /base64\s+encode/i.test(field.description ?? "");
+}
+/**
+ * The connect turn writes `.env` keys from the field names, upper-cased and
+ * usually prefixed with the source. Both shapes occur — `BIGQUERY_PROJECT_ID`
+ * for `project_id`, and `BIGQUERY_TYPE` for `bigquery_type`, where the prefix
+ * would otherwise be doubled — so match the unprefixed name first and fall back
+ * to the prefixed one.
+ */
+function matchField(key, sourceKey, fields) {
+    const upper = key.toUpperCase();
+    const prefix = `${sourceKey.toUpperCase()}_`;
+    const unprefixed = upper.startsWith(prefix) ? upper.slice(prefix.length) : upper;
+    return (fields.find((field) => field.name.toUpperCase() === upper) ??
+        fields.find((field) => field.name.toUpperCase() === unprefixed));
+}
+/**
+ * Annotates env keys with their source's field metadata. Keys that match
+ * nothing are returned unchanged rather than dropped: the template is the
+ * agent's output, and a key we cannot explain still has to be fillable.
+ */
+export function annotateEnvFields(fields, source) {
+    if (source === undefined)
+        return fields;
+    // Variants are alternative authentication shapes for the same source; the
+    // template only ever reflects one, so search them all and take the first hit.
+    const all = source.variants.flatMap((variant) => variant.fields);
+    return fields.map((field) => {
+        const matched = matchField(field.key, source.key, all);
+        if (matched === undefined)
+            return field;
+        return {
+            key: field.key,
+            // wren's `format: password` is the authority on whether a value is a
+            // credential; the route's name heuristic is only a fallback.
+            secret: field.secret || matched.secret,
+            label: matched.label,
+            required: matched.required,
+            ...(matched.description !== undefined ? { description: matched.description } : {}),
+            ...(matched.example !== undefined ? { example: matched.example } : {}),
+            ...(matched.fixedValue !== undefined ? { fixedValue: matched.fixedValue } : {}),
+            ...(matched.defaultValue !== undefined ? { defaultValue: matched.defaultValue } : {}),
+            ...(wantsFileUpload(matched) ? { fileEncoded: true } : {}),
+        };
+    });
+}

package/dist-server/server/fold.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Folds the harness's `AgentEvent`/`StepTrace` runtime types down
+ * into the UI's `ToolStep[]` work-log shape and its terminal `SessionEvent`.
+ *
+ * Two paths:
+ *  - Floor (always available): `RunAgentResult.trace` is populated
+ *    unconditionally by `runAgent` regardless of whether `onEvent` is wired,
+ *    so `foldTrace` alone is enough to produce one work-log snapshot even
+ *    with no live event stream.
+ *  - Live (best-effort): if the caller wires `onEvent`, `LiveWorkLog`
+ *    accumulates an incrementally-growing `ToolStep[]` as `step.*`/`tool.*`
+ *    events arrive, for a richer in-flight work log. In-process never populates
+ *    `parent`/`depth` today, so this never invents fake nesting — it only
+ *    forwards whatever the runtime actually reports.
+ */
+import type { AgentEvent, RouteResult, StepTrace } from "../harness/index.js";
+import type { AnswerEvent, ArtifactEvent, ArtifactKind, RefusalEvent, ToolStep } from "./wire-types.js";
+/**
+ * Canned remediation text for a refusal. `RefusalAgentEvent`/`RefusalResult`
+ * carry no remediation hint from the agent runtime — the UI's `fix` field is
+ * synthesized here as a fixed, hand-written string.
+ */
+export declare const REFUSAL_FIX_HINT = "Ask a workspace admin to grant access, or rephrase the question to use an aggregate that does not expose restricted values.";
+/** Floor path: one work-log snapshot from a resolved run's final `StepTrace`. */
+export declare function foldTrace(trace: StepTrace): ToolStep[];
+/** Extracts the floor `StepTrace` from a route() result, if the backend produced one (in-process only). */
+export declare function extractTrace(result: RouteResult): StepTrace | undefined;
+/**
+ * Maps a resolved route() result to the UI's terminal answer/refusal event
+ * (id assigned by the caller).
+ *
+ * Dispatched (`backend: "agent-sdk"`) has no structured `RenderEnvelope` of its
+ * own — `runDispatchedDefault` only returns the dispatcher's final stdout text
+ * (`finalText`) — but the dispatched agent still emits its final structured
+ * answer as a (possibly fenced) JSON envelope inside that text (this was the
+ * root cause of the bug this handles: that envelope was previously dropped
+ * on the floor and the raw text always went out as `form: "text"`,
+ * `verified: false`). `extractEnvelopeFromText` recovers it — including
+ * `answer_query`'s flat `{columns, rows}` tool-contract shape, normalized
+ * into a `table` block — and `verified` is whatever the recovered envelope
+ * actually carries, never hardcoded. Only when no envelope can be recovered
+ * at all does the raw text fall back to `form: "text"`.
+ *
+ * That `form: "text"` fallback is the one case where "verified: false" is
+ * ambiguous between two very different situations: a pure conversational
+ * reply (no data claim at all — the UI should hide the badge) and a data
+ * task that ran but whose result the model chose not to render as an
+ * envelope (the UI should still show "Unverified" — that's meaningful).
+ * `worklog` (the turn's already-folded `ToolStep[]`, live or floor) is
+ * inspected for a data-access tool call to disambiguate the two; schema
+ * introspection and artifact-saving tool calls don't count as a data claim.
+ */
+export declare function toAnswerOrRefusalEvent(id: string, result: RouteResult, worklog?: readonly ToolStep[]): AnswerEvent | RefusalEvent;
+/** Maps a `RunFinishEvent`'s companion `ArtifactAgentEvent` straight through — no BFF-side transformation needed. */
+export declare function toArtifactEvent(id: string, name: string, artifactKind: ArtifactKind, location: string, artifactId: string): ArtifactEvent;
+export declare const DECISION_ROUTE_ID = "decision-route";
+export declare const DECISION_CLARIFY_ID = "decision-clarify";
+export declare const DECISION_GATE_ID = "decision-gate";
+/** The intent-routing decision — always prepended to a turn's work log. */
+export declare function routeDecisionStep(agentId: string, reason: string): ToolStep;
+/** The clarify decision — only present when the turn short-circuits to a clarify prompt. */
+export declare function clarifyDecisionStep(detail: string): ToolStep;
+/**
+ * The trailing verify-gate verdict, derived from the resolved `route()` result:
+ *  - a verified ANSWER (`envelope.verified === true`) -> a "done" verdict;
+ *  - a REFUSAL -> an "error" verdict carrying the refusal reason;
+ *  - a non-verified answer (or dispatched, which has no envelope/verify signal)
+ *    -> `undefined`, so no gate entry is appended.
+ */
+export declare function gateDecisionStep(result: RouteResult): ToolStep | undefined;
+/**
+ * A failure verdict for a turn whose execution THREW (the error path) — appended
+ * to the partial work log so a failed turn's persisted trace ends with why it
+ * failed. Detail is the bounded error message.
+ */
+export declare function gateFailureStep(errorMessage: string): ToolStep;
+/**
+ * A BFF-owned setup-contract rejection. This deliberately reuses the
+ * established `ToolStep.kind: "decision"` wire shape, so the frontend can
+ * render recovery evidence without an SSE schema addition.
+ */
+export declare function hostContractRecoveryStep(detail: string): ToolStep;
+/** Redacts URLs, credentials, and arbitrary local absolute paths from setup text. */
+export declare function redactSetupText(text: string): string;
+/** Strict public setup diagnostic redaction shared by SSE, SQLite, and recovery. */
+export declare function redactPublicSetupText(text: string, internalValues?: readonly string[]): string;
+/**
+ * Explicit, strict public worklog allowlist shared by all Setup boundaries.
+ * Raw agent `input` and `detail` never cross this boundary: the BFF derives a
+ * bounded inspection projection instead, so reload/recovery cannot revive a
+ * broader historical trace.
+ */
+export declare function sanitizePublicSetupWorklog(value: unknown, internalValues?: readonly string[]): ToolStep[];
+/**
+ * Live-frame variant of `sanitizePublicSetupWorklog`, for a subscription-mode
+ * setup turn's in-flight progress stream (see `server/turn.ts`'s
+ * `executeSetupTurn`). The end-of-turn snapshot can redact by KNOWN VALUE —
+ * `sanitizePublicSetupWorklog(..., knownInternalValues)` — once an attempt has
+ * actually returned its session anchor. A live frame can't: the anchor a
+ * rotating subscription attempt will settle on isn't known until it resolves
+ * or throws, so falling back to by-SHAPE redaction (this module's
+ * `SETUP_INTERNAL_DIAGNOSTIC`/`SETUP_PROVIDER_NAME`
+ * patterns) is the only option that can run before then.
+ *
+ * That fallback is a genuine, accepted weakening: a pattern only catches an
+ * anchor that looks the way these patterns anticipate, not any anchor shape a
+ * future provider might introduce. To bound that risk, this also drops raw
+ * `input`/`detail` and the derived `inspection` outright rather than merely
+ * redacting them — a step's raw tool input or diagnostic text is exactly where
+ * an unanticipated anchor shape would hide, and a field never sent cannot
+ * leak. `WorkLog.tsx` only needs `label`/`state`/`kind`/`parent`/`depth` to
+ * render progress; a step becomes expandable with its safe inspection
+ * projection once the end-of-turn snapshot replaces this live one.
+ */
+export declare function sanitizeLiveSetupWorklog(worklog: readonly ToolStep[]): ToolStep[];
+/** Short text used for `turns.answer_summary` — feeds `server/compose.ts`'s D3 context composition. Never the full envelope. */
+export declare function summarizeResult(result: RouteResult): string;
+/**
+ * Live path accumulator: call `ingest` for each `AgentEvent` as it arrives
+ * from `onEvent`; each call returns a fresh immutable snapshot of the
+ * work log so far, or `undefined` for event kinds that don't affect it
+ * (`run.start`, `token`, `answer`, `refusal`, `artifact`, `run.finish`,
+ * `error` — those are terminal/non-worklog events handled elsewhere).
+ */
+export declare class LiveWorkLog {
+    private readonly order;
+    private readonly steps;
+    ingest(event: AgentEvent): ToolStep[] | undefined;
+    snapshot(): ToolStep[];
+    private upsert;
+    private setState;
+    private setInput;
+}