@wrenai/genbi 0.0.1

package/dist-server/harness/route/chat-event-mapper.js

@@ -0,0 +1,164 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isStringOrNull(value) {
+    return typeof value === "string" || value === 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 function parseWarbleChatEventLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(raw) || typeof raw["t"] !== "string")
+        return undefined;
+    switch (raw["t"]) {
+        case "step_start":
+            if (typeof raw["id"] === "string" &&
+                typeof raw["name"] === "string" &&
+                isStringOrNull(raw["parent"]) &&
+                typeof raw["depth"] === "number") {
+                return { t: "step_start", id: raw["id"], name: raw["name"], parent: raw["parent"], depth: raw["depth"] };
+            }
+            return undefined;
+        case "step_finish":
+            if (typeof raw["id"] === "string" && typeof raw["ok"] === "boolean") {
+                return {
+                    t: "step_finish",
+                    id: raw["id"],
+                    ok: raw["ok"],
+                    ...(typeof raw["detail"] === "string" ? { detail: raw["detail"] } : {}),
+                };
+            }
+            return undefined;
+        case "tool_call":
+            if (typeof raw["id"] === "string" &&
+                typeof raw["name"] === "string" &&
+                isStringOrNull(raw["parent"]) &&
+                typeof raw["depth"] === "number") {
+                return {
+                    t: "tool_call",
+                    id: raw["id"],
+                    name: raw["name"],
+                    ...(raw["input"] !== undefined ? { input: raw["input"] } : {}),
+                    parent: raw["parent"],
+                    depth: raw["depth"],
+                };
+            }
+            return undefined;
+        case "tool_result":
+            if (typeof raw["id"] === "string" && typeof raw["ok"] === "boolean") {
+                return {
+                    t: "tool_result",
+                    id: raw["id"],
+                    ok: raw["ok"],
+                    ...(typeof raw["summary"] === "string" ? { summary: raw["summary"] } : {}),
+                    ...(typeof raw["error"] === "string" ? { error: raw["error"] } : {}),
+                };
+            }
+            return undefined;
+        case "answer":
+            if (typeof raw["text"] === "string")
+                return { t: "answer", text: raw["text"] };
+            return undefined;
+        case "session":
+            if (isStringOrNull(raw["id"]))
+                return { t: "session", id: raw["id"] };
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+export function createChatEventMapperState() {
+    return { currentStepId: undefined, stepNames: new Map(), toolNames: new Map() };
+}
+/** `AgentEvent.parent` is `string | undefined`; warble's own `parent` field is `string | null`. */
+function toOptionalParent(parent) {
+    return parent !== null ? { parent } : {};
+}
+/**
+ * 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 function mapChatEventToAgentEvent(raw, state) {
+    switch (raw.t) {
+        case "step_start": {
+            state.currentStepId = raw.id;
+            state.stepNames.set(raw.id, raw.name);
+            return {
+                kind: "step.start",
+                stepId: raw.id,
+                name: raw.name,
+                // Dispatched's NDJSON stream carries no per-step tier info (warble doesn't expose it in
+                // `WarbleChatEvent`); `LiveWorkLog.ingest` never reads `tier` when folding to `ToolStep`,
+                // so this placeholder has no observable effect on the UI's work log.
+                tier: "unknown",
+                ...toOptionalParent(raw.parent),
+                depth: raw.depth,
+            };
+        }
+        case "step_finish": {
+            const name = state.stepNames.get(raw.id) ?? raw.id;
+            // Clear the current step once it closes so any stray tool event arriving after it falls back
+            // to its own id rather than being attributed to the already-finished step.
+            if (state.currentStepId === raw.id)
+                state.currentStepId = undefined;
+            return {
+                kind: "step.finish",
+                stepId: raw.id,
+                name,
+                status: raw.ok ? "ok" : "error",
+                ...(raw.detail !== undefined ? { detail: raw.detail } : {}),
+            };
+        }
+        case "tool_call": {
+            state.toolNames.set(raw.id, raw.name);
+            const stepId = state.currentStepId ?? raw.id;
+            return {
+                kind: "tool.call",
+                stepId,
+                callId: raw.id,
+                tool: raw.name,
+                ...(raw.input !== undefined ? { input: raw.input } : {}),
+                ...toOptionalParent(raw.parent),
+                depth: raw.depth,
+                status: "running",
+            };
+        }
+        case "tool_result": {
+            const tool = state.toolNames.get(raw.id) ?? raw.id;
+            const stepId = state.currentStepId ?? raw.id;
+            return {
+                kind: "tool.result",
+                stepId,
+                callId: raw.id,
+                tool,
+                status: raw.ok ? "success" : "error",
+                ...(raw.ok ? (raw.summary !== undefined ? { summary: raw.summary } : {}) : {}),
+                ...(!raw.ok && raw.error !== undefined ? { error: raw.error } : {}),
+            };
+        }
+        case "answer":
+            return undefined;
+        case "session":
+            // Session metadata, not a work-log event — the caller (`spawnChat`) intercepts this line
+            // directly (mirroring its existing `t === "answer"` interception) rather than routing it
+            // through here.
+            return undefined;
+    }
+}

package/dist-server/harness/route/codex-ask-events.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEventInput } from "../events/index.js";
+import type { CodexAskComponent, CodexManifestModels } from "./codex-local-manifest.js";
+export declare class CodexAskEventMapper {
+    private readonly models;
+    private readonly component;
+    private sessionStarted;
+    private parentThreadId;
+    private parentTurnId;
+    private turnStarted;
+    private turnCompleted;
+    private finalText;
+    private readonly started;
+    private readonly finished;
+    private readonly agentThreads;
+    private readonly mcpEvidence;
+    private renderState;
+    private renderArtifact;
+    constructor(models: CodexManifestModels, component?: CodexAskComponent);
+    nextLine(line: string): AgentEventInput[];
+    result(): string;
+    private validateStepOutcome;
+    private stepContract;
+    private validateDashboardAnswer;
+    private hasSuccessfulDashboardEvidence;
+}

package/dist-server/harness/route/codex-ask-events.js

@@ -0,0 +1,395 @@
+const COMPONENT_STEPS = {
+    answer_query: [
+        { name: "resolve_intent", tier: "cheap", tool: "get_context" },
+        { name: "generate_sql", tier: "strong", tool: "run_sql" },
+        { name: "repair_sql", tier: "strong", tool: "run_sql" },
+    ],
+    generate_dashboard: [
+        { name: "plan_dashboard", tier: "strong", tool: "get_context" },
+        { name: "compose_layout", tier: "cheap", tool: "run_sql" },
+    ],
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseEvent(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        throw new Error("warble-codex-local Ask emitted non-JSON output");
+    }
+    if (!isRecord(value) || typeof value["t"] !== "string") {
+        throw new Error("warble-codex-local Ask emitted a malformed event");
+    }
+    return value;
+}
+function expectedRole(step) {
+    return `warble_${step}`;
+}
+export class CodexAskEventMapper {
+    models;
+    component;
+    sessionStarted = false;
+    parentThreadId = "";
+    parentTurnId = "";
+    turnStarted = false;
+    turnCompleted = false;
+    finalText;
+    started = [];
+    finished = new Map();
+    agentThreads = new Map();
+    mcpEvidence = new Map();
+    renderState;
+    renderArtifact;
+    constructor(models, component = "answer_query") {
+        this.models = models;
+        this.component = component;
+    }
+    nextLine(line) {
+        const event = parseEvent(line);
+        switch (event.t) {
+            case "session_started":
+                if (this.sessionStarted || event.session?.target !== "codex:local" || !event.session.threadId) {
+                    throw new Error("warble-codex-local Ask emitted an invalid session start");
+                }
+                this.sessionStarted = true;
+                this.parentThreadId = event.session.threadId;
+                return [];
+            case "turn_started":
+                if (!this.sessionStarted ||
+                    this.turnStarted ||
+                    event.turn?.status !== "in_progress" ||
+                    event.turn.threadId !== this.parentThreadId ||
+                    !event.turn.turnId) {
+                    throw new Error("warble-codex-local Ask emitted an invalid turn start");
+                }
+                this.turnStarted = true;
+                this.parentTurnId = event.turn.turnId;
+                return [];
+            case "agent_started": {
+                const step = this.stepContract(event.step);
+                if (!this.turnStarted || this.turnCompleted || step === undefined) {
+                    throw new Error("warble-codex-local Ask emitted an invalid agent start");
+                }
+                const expected = COMPONENT_STEPS[this.component][this.started.length];
+                const previous = COMPONENT_STEPS[this.component][this.started.length - 1];
+                if (event.step !== expected?.name ||
+                    (previous !== undefined && !this.finished.has(previous.name)) ||
+                    (step.name === "repair_sql"
+                        ? this.finished.get("generate_sql") !== false
+                        : previous !== undefined && this.finished.get(previous.name) !== true) ||
+                    event.agentRole !== expectedRole(step.name) ||
+                    !event.agentThreadId ||
+                    event.parentThreadId !== this.parentThreadId ||
+                    event.parentTurnId !== this.parentTurnId) {
+                    throw new Error("warble-codex-local Ask agent order or attribution did not match the IR");
+                }
+                if (event.model !== this.models[step.tier]) {
+                    throw new Error(`warble-codex-local Ask step "${event.step}" ran on the wrong model`);
+                }
+                this.started.push(step.name);
+                this.agentThreads.set(step.name, event.agentThreadId);
+                return [{
+                        kind: "step.start",
+                        stepId: step.name,
+                        name: step.name,
+                        tier: step.tier,
+                        parent: event.parentThreadId,
+                        depth: 1,
+                    }];
+            }
+            case "artifact": {
+                const reference = event.reference;
+                const step = this.stepContract(reference?.step);
+                if (step === undefined ||
+                    this.finished.has(step.name)) {
+                    throw new Error("warble-codex-local Ask emitted an artifact outside an active step");
+                }
+                const threadId = this.agentThreads.get(step.name);
+                if (threadId === undefined ||
+                    reference.agentThreadId !== threadId ||
+                    reference.parentThreadId !== this.parentThreadId ||
+                    reference.parentTurnId !== this.parentTurnId ||
+                    reference.agentRole !== expectedRole(step.name) ||
+                    reference.server !== "wren" ||
+                    !reference.itemId ||
+                    reference.tool !== step.tool) {
+                    throw new Error("warble-codex-local Ask artifact attribution did not match the allowed Wren MCP surface");
+                }
+                if (this.component === "generate_dashboard") {
+                    const previousEvidence = this.mcpEvidence.get(step.name);
+                    this.mcpEvidence.set(step.name, {
+                        count: (previousEvidence?.count ?? 0) + 1,
+                        allOk: (previousEvidence?.allOk ?? true) && reference.ok,
+                    });
+                }
+                const callId = `${reference.step}:${reference.itemId}`;
+                const tool = `${reference.server}.${reference.tool}`;
+                return [
+                    {
+                        kind: "tool.call",
+                        stepId: reference.step,
+                        callId,
+                        tool,
+                        parent: reference.agentThreadId,
+                        depth: 2,
+                        status: "running",
+                    },
+                    {
+                        kind: "tool.result",
+                        stepId: reference.step,
+                        callId,
+                        tool,
+                        status: reference.ok ? "success" : "error",
+                        ...(!reference.ok ? { error: "allowlisted Wren MCP tool failed" } : {}),
+                    },
+                ];
+            }
+            case "render_artifact": {
+                const reference = event.reference;
+                const composeThread = this.agentThreads.get("compose_layout");
+                const allowedBlockTypes = new Set(["kpi_card", "chart", "table", "definition"]);
+                // Protocol shape: a violation here means warble-codex-local emitted
+                // something structurally wrong (bad envelope-protocol fields, or a
+                // `verified` claim unsupported by tool evidence) -- always a target
+                // bug, so it stays loud.
+                if (this.component !== "generate_dashboard" ||
+                    this.renderState !== undefined ||
+                    this.finished.get("compose_layout") !== true ||
+                    reference?.version !== "0.1" ||
+                    reference.kind !== "render_envelope" ||
+                    reference.parentThreadId !== this.parentThreadId ||
+                    reference.parentTurnId !== this.parentTurnId ||
+                    reference.step !== "compose_layout" ||
+                    reference.agentRole !== expectedRole("compose_layout") ||
+                    reference.agentThreadId !== composeThread ||
+                    typeof reference.verified !== "boolean" ||
+                    (reference.verified && !this.hasSuccessfulDashboardEvidence()) ||
+                    !Array.isArray(reference.blockTypes) ||
+                    reference.blockTypes.length === 0 ||
+                    reference.blockTypes.some((type) => !allowedBlockTypes.has(type))) {
+                    throw new Error("warble-codex-local Ask emitted an invalid dashboard render artifact");
+                }
+                // Dashboard CONTENT requirement: genbi owns the product
+                // shape of a dashboard -- a rendered dashboard must carry at least
+                // one data panel (`kpi_card`/`chart`/`table`) and one `definition`.
+                // This is the guarantee's owner now that warble-codex-local no
+                // longer enforces it in `render_contract.ts`. A shortfall here is a
+                // genbi-product-shape problem, not a protocol bug, so it degrades
+                // exactly like a `render_degraded` event (terminal answer retained,
+                // artifact suppressed) instead of failing the whole Ask request.
+                const blockTypes = new Set(reference.blockTypes);
+                const hasDataPanel = reference.blockTypes.some((type) => ["kpi_card", "chart", "table"].includes(type));
+                if (!hasDataPanel || !blockTypes.has("definition")) {
+                    this.renderState = "degraded";
+                    return [];
+                }
+                this.renderState = "artifact";
+                this.renderArtifact = reference;
+                return [];
+            }
+            case "render_degraded":
+                if (this.component !== "generate_dashboard" ||
+                    this.renderState !== undefined ||
+                    this.finished.get("compose_layout") !== true ||
+                    event.parentThreadId !== this.parentThreadId ||
+                    event.parentTurnId !== this.parentTurnId ||
+                    event.reason !== "invalid_render_envelope") {
+                    throw new Error("warble-codex-local Ask emitted an invalid dashboard render degradation");
+                }
+                this.renderState = "degraded";
+                return [];
+            case "step_finished": {
+                const step = this.stepContract(event.step);
+                if (step === undefined || this.finished.has(step.name)) {
+                    throw new Error("warble-codex-local Ask emitted an invalid step finish");
+                }
+                const expected = COMPONENT_STEPS[this.component][this.finished.size];
+                if (event.step !== expected?.name ||
+                    !this.started.includes(step.name) ||
+                    event.agentRole !== expectedRole(step.name) ||
+                    event.agentThreadId !== this.agentThreads.get(step.name) ||
+                    event.parentThreadId !== this.parentThreadId ||
+                    event.parentTurnId !== this.parentTurnId) {
+                    throw new Error("warble-codex-local Ask step completion order or attribution did not match the IR");
+                }
+                if (this.component === "generate_dashboard") {
+                    const evidence = this.mcpEvidence.get(step.name);
+                    if (evidence === undefined || evidence.count === 0) {
+                        throw new Error(`warble-codex-local Ask step "${step.name}" finished without required Wren MCP evidence`);
+                    }
+                    if (event.ok !== evidence.allOk) {
+                        throw new Error(`warble-codex-local Ask step "${step.name}" outcome contradicted its Wren MCP evidence`);
+                    }
+                }
+                this.finished.set(step.name, event.ok);
+                return [{
+                        kind: "step.finish",
+                        stepId: event.step,
+                        name: event.step,
+                        status: event.ok ? "ok" : "error",
+                        ...(!event.ok ? { detail: `${event.step} failed` } : {}),
+                    }];
+            }
+            case "turn_completed":
+                if (!this.turnStarted ||
+                    this.turnCompleted ||
+                    event.turn?.status !== "completed" ||
+                    event.turn.threadId !== this.parentThreadId ||
+                    event.turn.turnId !== this.parentTurnId ||
+                    this.finished.size !== this.started.length) {
+                    throw new Error("warble-codex-local Ask emitted an invalid turn completion");
+                }
+                this.validateStepOutcome();
+                this.turnCompleted = true;
+                return [];
+            case "answer":
+                if (!this.turnCompleted || this.finalText !== undefined || typeof event.text !== "string" || !event.text.trim()) {
+                    throw new Error("warble-codex-local Ask emitted an invalid terminal answer");
+                }
+                if (this.component === "generate_dashboard" && this.renderState === "artifact") {
+                    this.validateDashboardAnswer(event.text);
+                }
+                this.finalText = this.component === "generate_dashboard" && this.renderState === "degraded"
+                    ? degradedDashboardText(event.text)
+                    : event.text;
+                return [{ kind: "answer", text: this.finalText }];
+            case "session_recoverable":
+            case "session_failed":
+                throw new Error(`warble-codex-local Ask session failed: ${event.reason}`);
+            default:
+                throw new Error("warble-codex-local Ask emitted an unknown event");
+        }
+    }
+    result() {
+        if (!this.sessionStarted || !this.turnStarted || !this.turnCompleted) {
+            throw new Error("warble-codex-local Ask ended with a partial lifecycle");
+        }
+        if (this.finalText === undefined) {
+            throw new Error("warble-codex-local Ask ended without a final answer");
+        }
+        return this.finalText;
+    }
+    validateStepOutcome() {
+        if (this.component === "generate_dashboard") {
+            if (this.finished.get("plan_dashboard") !== true ||
+                this.finished.get("compose_layout") !== true ||
+                this.started.length !== 2 ||
+                !this.hasSuccessfulDashboardEvidence() ||
+                this.renderState === undefined) {
+                throw new Error("warble-codex-local Ask did not complete the required dashboard steps and render contract");
+            }
+            return;
+        }
+        const resolveOk = this.finished.get("resolve_intent");
+        const generateOk = this.finished.get("generate_sql");
+        const repairOk = this.finished.get("repair_sql");
+        if (resolveOk !== true || generateOk === undefined) {
+            throw new Error("warble-codex-local Ask did not complete the required resolve/generate steps");
+        }
+        if (generateOk) {
+            if (repairOk !== undefined || this.started.length !== 2) {
+                throw new Error("warble-codex-local Ask ran repair after successful generation");
+            }
+            return;
+        }
+        if (repairOk !== true || this.started.length !== 3) {
+            throw new Error("warble-codex-local Ask did not complete its single bounded repair");
+        }
+    }
+    stepContract(value) {
+        return COMPONENT_STEPS[this.component].find((step) => step.name === value);
+    }
+    validateDashboardAnswer(text) {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            throw new Error("warble-codex-local Ask dashboard answer was not valid JSON");
+        }
+        if (!isDashboardEnvelope(value)) {
+            throw new Error("warble-codex-local Ask dashboard answer did not match its render artifact");
+        }
+        const blockTypes = value["blocks"].map((block) => isRecord(block) && typeof block["type"] === "string" ? block["type"] : "");
+        if (this.renderArtifact === undefined ||
+            (value["verified"] && !this.hasSuccessfulDashboardEvidence()) ||
+            value["verified"] !== this.renderArtifact.verified ||
+            JSON.stringify(blockTypes) !== JSON.stringify(this.renderArtifact.blockTypes)) {
+            throw new Error("warble-codex-local Ask dashboard answer did not match its render artifact");
+        }
+    }
+    hasSuccessfulDashboardEvidence() {
+        return this.mcpEvidence.size === 2 &&
+            this.mcpEvidence.get("plan_dashboard")?.allOk === true &&
+            this.mcpEvidence.get("compose_layout")?.allOk === true;
+    }
+}
+function isDashboardEnvelope(value) {
+    if (!isRecord(value) ||
+        !Array.isArray(value["blocks"]) ||
+        value["blocks"].length === 0 ||
+        typeof value["verified"] !== "boolean" ||
+        ("summary" in value && typeof value["summary"] !== "string")) {
+        return false;
+    }
+    let hasDataPanel = false;
+    let hasDefinition = false;
+    for (const block of value["blocks"]) {
+        if (!isRecord(block) || typeof block["type"] !== "string")
+            return false;
+        switch (block["type"]) {
+            case "kpi_card":
+                if (typeof block["label"] !== "string" ||
+                    (typeof block["value"] !== "string" && typeof block["value"] !== "number") ||
+                    ("unit" in block && typeof block["unit"] !== "string") ||
+                    ("delta" in block && typeof block["delta"] !== "number"))
+                    return false;
+                hasDataPanel = true;
+                break;
+            case "table":
+                if (!isStringArray(block["columns"]) || !isObjectArray(block["rows"]))
+                    return false;
+                hasDataPanel = true;
+                break;
+            case "chart":
+                if (!["bar", "line", "pie", "area", "scatter"].includes(String(block["chart_type"])) ||
+                    typeof block["x"] !== "string" ||
+                    !isStringArray(block["series"]) ||
+                    !isObjectArray(block["rows"]))
+                    return false;
+                hasDataPanel = true;
+                break;
+            case "definition":
+                if (typeof block["sql"] !== "string" ||
+                    !isStringArray(block["source_tables"]) ||
+                    !isStringArray(block["filters"]))
+                    return false;
+                hasDefinition = true;
+                break;
+            default:
+                return false;
+        }
+    }
+    return hasDataPanel && hasDefinition;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isObjectArray(value) {
+    return Array.isArray(value) && value.every(isRecord);
+}
+function degradedDashboardText(text) {
+    try {
+        const value = JSON.parse(text);
+        if (isRecord(value) && typeof value["summary"] === "string" && value["summary"].trim()) {
+            return value["summary"].trim();
+        }
+    }
+    catch {
+        // A degraded renderer may already have emitted a plain-text best effort.
+    }
+    return text;
+}

package/dist-server/harness/route/codex-ask.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedCli } from "./agent-sdk-cli.js";
+import { type CodexAskComponent, type CodexManifestModels } from "./codex-local-manifest.js";
+import type { CodexAskOptions, CodexAskResult } from "./types.js";
+export declare function buildCodexAskArgs(cli: ResolvedCli, options: {
+    readonly irPath: string;
+    readonly question: string;
+    readonly userProject: string;
+    readonly codexHome: string;
+    readonly models: CodexManifestModels;
+    readonly mcpServer: ResolvedCli;
+    readonly codexBin?: string;
+    readonly timeoutMs: number;
+    readonly component?: CodexAskComponent;
+}): readonly string[];
+export declare function runCodexAskDefault(options: CodexAskOptions): Promise<CodexAskResult>;