@wrenai/genbi 0.0.4 → 0.0.5

package/dist-server/harness/components/report.js

@@ -0,0 +1,309 @@
+import { normalizeComponentResult } from "@warble/claude-agent-sdk";
+import { z } from "zod";
+import { answerShapeSchema } from "../providers/zone.js";
+/**
+ * The two-stage report: host-side slot materialisation and synthesis.
+ *
+ * A report component (the Hub `plan_report`) runs two model steps. The first
+ * lays out blocks whose data cells are `{slot_id}` placeholders and asks the
+ * callee for every answer in one batched call; the second writes the summary
+ * and per-block notes. Neither step is allowed to type a value into the
+ * report: this module is where the values come from.
+ *
+ * - {@link buildSlotTable} turns the disclosed child results (what the caller
+ *   was allowed to see, after egress) and the provenance the egress step kept
+ *   aside into one table keyed by slot id.
+ * - {@link materialiseReportPlan} fills the layout from that table for the
+ *   narrator to read: filled cells carry their values, refused or unanswered
+ *   cells carry `status: unavailable` and a reason category. Provenance
+ *   (SQL, source tables) is withheld here; the narrator runs on a public tier.
+ * - {@link synthesiseReport} builds the final render envelope from the layout,
+ *   the slot table and only the narrator's text (summary, notes, titles). A
+ *   value the narrator retyped is never read. Provenance is attached here, by
+ *   the host, from the child run.
+ *
+ * Every value in the rendered report therefore traces to a disclosed answer,
+ * and every disclosed answer traces to an observed query result in the child.
+ */
+export const BLOCK_SHAPES = { kpi_card: "scalar", chart: "series", table: "table", narrative: "narrative" };
+const dataBlockTypeSchema = z.enum(["kpi_card", "chart", "table", "narrative"]);
+const chartTypeSchema = z.enum(["bar", "line", "pie", "area", "scatter"]);
+const layoutSlotSchema = z.object({
+    slot_id: z.string().min(1).max(128),
+    block_type: dataBlockTypeSchema,
+    expected_shape: answerShapeSchema,
+    question: z.string().min(1),
+    unit: z.string().optional(),
+    max_rows: z.number().int().positive().optional(),
+});
+/** Unknown keys are stripped: a number the planner copied into a placeholder is dropped, never read. */
+const layoutBlockSchema = z.object({
+    type: dataBlockTypeSchema,
+    label: z.string().optional(),
+    title: z.string().optional(),
+    chart_type: chartTypeSchema.optional(),
+    slot_id: z.string().min(1).max(128),
+});
+export const reportPlanSchema = z.object({
+    title: z.string().optional(),
+    preamble: z.object({ period: z.string().optional(), currency: z.string().optional(), filters: z.array(z.string()).default([]) }).default({ filters: [] }),
+    slots: z.array(layoutSlotSchema).max(64),
+    blocks: z.array(layoutBlockSchema).min(1).max(64),
+    summary_brief: z.string().optional(),
+});
+const cell = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const disclosedAnswerSchema = z.object({
+    slot_id: z.string().min(1),
+    status: z.enum(["ok", "partial", "refused"]),
+    shape: answerShapeSchema.optional(),
+    columns: z.array(z.string()).optional(),
+    rows: z.array(z.unknown()).optional(),
+    value: z.unknown().optional(),
+    text: z.string().optional(),
+    unit: z.string().optional(),
+    summary: z.string().optional(),
+    reason_category: z.string().optional(),
+}).strict();
+const disclosedBatchSchema = z.object({ answers: z.array(disclosedAnswerSchema) }).passthrough();
+/**
+ * One row per slot from the disclosed child results (first answer per slot id
+ * wins; a follow-up call adds new ids). Provenance is joined by slot id.
+ */
+export function buildSlotTable(children, provenance = []) {
+    const table = new Map();
+    const kept = new Map();
+    for (const item of provenance)
+        if (!kept.has(item.slot_id))
+            kept.set(item.slot_id, item);
+    for (const child of children) {
+        if (child.status !== "ok" || child.output.kind !== "value")
+            continue;
+        const batch = disclosedBatchSchema.safeParse(child.output.value);
+        if (!batch.success)
+            continue;
+        for (const answer of batch.data.answers) {
+            if (table.has(answer.slot_id))
+                continue;
+            const aside = kept.get(answer.slot_id);
+            table.set(answer.slot_id, { answer: answer, ...(aside ? { provenance: aside } : {}) });
+        }
+    }
+    return table;
+}
+/** Positional rows for the render contract's `row[]`; object rows are projected through `columns`. */
+function positionalRows(columns, rows) {
+    const out = [];
+    for (const row of rows) {
+        const values = Array.isArray(row) ? row : row && typeof row === "object" ? columns.map((column) => row[column]) : undefined;
+        if (values === undefined || values.length !== columns.length)
+            return undefined;
+        const parsed = z.array(cell).safeParse(values.map((value) => value === undefined ? null : value));
+        if (!parsed.success)
+            return undefined;
+        out.push(parsed.data);
+    }
+    return out;
+}
+function labelOf(block) { return block.label ?? block.title ?? block.slot_id; }
+function unavailable(block, reason) {
+    return { type: block.type, label: labelOf(block), slot_id: block.slot_id, status: "unavailable", reason_category: reason };
+}
+/** Fills one layout block from its slot entry, or marks it unavailable with the reason. */
+function fillBlock(block, slot, entry) {
+    if (!slot)
+        return unavailable(block, "not_declared");
+    if (BLOCK_SHAPES[block.type] !== slot.expected_shape)
+        return unavailable(block, "shape_mismatch");
+    if (!entry)
+        return unavailable(block, "not_requested");
+    const answer = entry.answer;
+    if (answer.status === "refused")
+        return unavailable(block, answer.reason_category ?? "refused");
+    const unit = slot.unit ?? answer.unit;
+    const columns = answer.columns ?? [];
+    const rows = answer.rows ?? [];
+    switch (block.type) {
+        case "kpi_card": {
+            const raw = answer.value !== undefined ? answer.value : positionalRows(columns, rows)?.[0]?.[0];
+            if (typeof raw !== "number" && typeof raw !== "string")
+                return unavailable(block, "invalid_answer");
+            if (typeof raw === "number" && !Number.isFinite(raw))
+                return unavailable(block, "invalid_answer");
+            return { type: "kpi_card", label: labelOf(block), slot_id: block.slot_id, value: raw, ...(unit !== undefined ? { unit } : {}) };
+        }
+        case "chart": {
+            const positional = columns.length >= 2 ? positionalRows(columns, rows) : undefined;
+            if (!positional)
+                return unavailable(block, "invalid_answer");
+            return { type: "chart", title: labelOf(block), chart_type: block.chart_type ?? "bar", slot_id: block.slot_id, x: columns[0], series: columns.slice(1), rows: positional };
+        }
+        case "table": {
+            const positional = columns.length >= 1 ? positionalRows(columns, rows) : undefined;
+            if (!positional)
+                return unavailable(block, "invalid_answer");
+            return { type: "table", title: labelOf(block), slot_id: block.slot_id, columns: [...columns], rows: positional };
+        }
+        case "narrative": {
+            const text = answer.text ?? answer.summary;
+            if (typeof text !== "string" || text.length === 0)
+                return unavailable(block, "invalid_answer");
+            return { type: "narrative", title: labelOf(block), slot_id: block.slot_id, text };
+        }
+    }
+}
+/**
+ * The layout with every data cell resolved from the slot table. This is what
+ * the narrator consumes as `report_plan`: values it must copy, never compute.
+ * No `definition` block is included; provenance stays host-side until
+ * {@link synthesiseReport}.
+ */
+export function materialiseReportPlan(plan, table) {
+    const slots = new Map(plan.slots.map((slot) => [slot.slot_id, slot]));
+    return {
+        ...(plan.title !== undefined ? { title: plan.title } : {}),
+        preamble: plan.preamble,
+        blocks: plan.blocks.map((block) => fillBlock(block, slots.get(block.slot_id), table.get(block.slot_id))),
+        ...(plan.summary_brief !== undefined ? { summary_brief: plan.summary_brief } : {}),
+    };
+}
+/** Parses a step product (string or object) as a report plan; undefined when it is not one. */
+export function parseReportPlan(product) {
+    let value = product;
+    if (typeof product === "string") {
+        try {
+            value = JSON.parse(extractJsonObject(product));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const parsed = reportPlanSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function extractJsonObject(text) {
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = (fenced?.[1] ?? text).trim();
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        throw new Error("no JSON object");
+    return candidate.slice(start, end + 1);
+}
+/** The only fields the narrator contributes: prose. Bounded so a runaway narrator cannot bloat the artifact. */
+const NOTE_LIMIT = 4_000;
+const TITLE_LIMIT = 200;
+const SUMMARY_LIMIT = 20_000;
+const narratorBlockSchema = z.object({
+    slot_id: z.string().min(1).optional(),
+    note: z.string().max(NOTE_LIMIT).optional(),
+    label: z.string().min(1).max(TITLE_LIMIT).optional(),
+    title: z.string().min(1).max(TITLE_LIMIT).optional(),
+}).passthrough();
+const narratorOutputSchema = z.object({
+    blocks: z.array(narratorBlockSchema),
+    summary: z.string().max(SUMMARY_LIMIT).optional(),
+}).passthrough();
+/** Reads the narrator's text out of its output; the values it may have written are not looked at. */
+export function readNarratorText(product) {
+    let value = product;
+    if (typeof product === "string") {
+        try {
+            value = JSON.parse(extractJsonObject(product));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const parsed = narratorOutputSchema.safeParse(value);
+    if (!parsed.success)
+        return undefined;
+    const notes = new Map();
+    for (const block of parsed.data.blocks) {
+        if (block.slot_id === undefined || notes.has(block.slot_id))
+            continue;
+        const label = block.label ?? block.title;
+        notes.set(block.slot_id, { ...(block.note !== undefined ? { note: block.note } : {}), ...(label !== undefined ? { label } : {}) });
+    }
+    return { ...(parsed.data.summary !== undefined ? { summary: parsed.data.summary } : {}), notes };
+}
+const definitionSchema = z.object({ sql: z.string().min(1), source_tables: z.array(z.string()).default([]), filters: z.array(z.string()).default([]) }).passthrough();
+/**
+ * The rendered report. Values come from the slot table through the same
+ * materialisation the narrator read; the narrator contributes summary, notes
+ * and adjusted labels only; the host appends one `definition` block per
+ * filled slot whose provenance carries SQL. The narrator cannot add, drop or
+ * reorder blocks, and a number it emitted is never read.
+ */
+export function synthesiseReport(plan, table, narrator) {
+    const materialised = materialiseReportPlan(plan, table);
+    const blocks = [];
+    const definitions = [];
+    let filled = 0;
+    let verified = true;
+    for (const block of materialised.blocks) {
+        const text = narrator?.notes.get(block.slot_id);
+        if ("status" in block) {
+            blocks.push({ type: "unavailable", label: text?.label ?? block.label, block_type: block.type, reason_category: block.reason_category,
+                slot_id: block.slot_id, ...(text?.note !== undefined ? { note: text.note } : {}) });
+            continue;
+        }
+        filled += 1;
+        const entry = table.get(block.slot_id);
+        if (entry?.provenance?.verified !== true)
+            verified = false;
+        const named = block.type === "kpi_card"
+            ? { ...block, label: text?.label ?? block.label }
+            : { ...block, title: text?.label ?? block.title };
+        blocks.push({ ...named, ...(text?.note !== undefined && block.type !== "narrative" ? { note: text.note } : {}) });
+        const source = entry?.provenance?.definition ?? (entry?.provenance?.sql !== undefined
+            ? { sql: entry.provenance.sql, source_tables: entry.provenance.source_tables ?? [] } : undefined);
+        const definition = definitionSchema.safeParse(source);
+        if (definition.success) {
+            blocks.push({ type: "definition", sql: definition.data.sql, source_tables: [...definition.data.source_tables], filters: [...definition.data.filters], slot_id: block.slot_id });
+            definitions.push(block.slot_id);
+        }
+    }
+    return { blocks, ...(narrator?.summary !== undefined ? { summary: narrator.summary } : {}), verified: filled > 0 && verified, definitions };
+}
+/** A component whose render contract declares an `unavailable` cell is a report: the host synthesises its envelope. */
+export function isReportComponent(component) {
+    const render = component.declaration.effect?.render_blocks;
+    return Array.isArray(render) && render.some((block) => block?.type === "unavailable")
+        && component.steps.some((step) => step.calls.length > 0);
+}
+/** The step that lays the report out (owns the call edge) and the one that narrates it (consumes the layout). */
+export function reportSteps(component) {
+    const layout = component.steps.find((step) => step.calls.length > 0);
+    if (!layout)
+        return undefined;
+    const narrate = component.steps.find((step) => !step.repairOf && step !== layout && step.consumes.includes(layout.produces));
+    return { layout, ...(narrate ? { narrate } : {}) };
+}
+function refused(message) {
+    return { status: "refused", code: "callee_refused", message };
+}
+/**
+ * Root normalization for a report component: the host-owned synthesis. The
+ * produced envelope is validated against the component's declared render
+ * contract exactly as a model-authored one would be.
+ */
+export function normalizeReportEvidence(component, evidence) {
+    const steps = reportSteps(component);
+    if (!steps)
+        return refused("The report component declares no layout step.");
+    const plan = parseReportPlan(evidence.steps[steps.layout.produces]);
+    if (!plan)
+        return refused("The planner did not produce a report layout.");
+    const narrator = steps.narrate ? readNarratorText(evidence.steps[steps.narrate.produces]) : undefined;
+    if (steps.narrate && !narrator)
+        return refused("The narrator did not produce a report.");
+    const table = buildSlotTable(evidence.children, evidence.egress ?? []);
+    const report = synthesiseReport(plan, table, narrator);
+    const contract = z.array(z.object({ type: z.string(), fields: z.record(z.string(), z.string()) }).strict())
+        .parse(component.declaration.effect.render_blocks ?? []);
+    const envelope = { blocks: report.blocks, ...(report.summary !== undefined ? { summary: report.summary } : {}), verified: report.verified };
+    const normalized = normalizeComponentResult(JSON.stringify(envelope), contract).value;
+    if (normalized.status !== "ok")
+        return normalized;
+    return { ...normalized, provenance: { verified: report.verified } };
+}

package/dist-server/harness/components/runner.d.ts

@@ -0,0 +1,193 @@
+import { type ComponentInvocationResult } from "@warble/claude-agent-sdk";
+import { type EgressDecision, type EgressProvenance } from "./egress.js";
+import { type StepUsage } from "./usage.js";
+export type { StepUsage } from "./usage.js";
+export interface ComponentTool {
+    readonly name: string;
+    readonly source: string;
+}
+/** A grant that executes SQL: its successful results carry a host-assigned `query_id`. */
+export declare function isQueryGrant(grant: ComponentTool): boolean;
+export interface ComponentStep {
+    readonly name: string;
+    readonly tier: string;
+    readonly prompt: string;
+    readonly consumes: readonly string[];
+    readonly produces: string;
+    readonly tools: readonly ComponentTool[];
+    readonly calls: readonly {
+        readonly alias: string;
+        readonly component: string;
+    }[];
+    readonly repairOf?: string;
+}
+export interface ComponentPlan {
+    readonly id: string;
+    readonly brief?: string;
+    readonly steps: readonly ComponentStep[];
+    /** Preserved compiler declaration, for host context/guardrail/render validation. */
+    readonly declaration: Readonly<Record<string, unknown>>;
+}
+export interface ExecutionPlan {
+    readonly identity: string;
+    readonly contextBinding?: Readonly<Record<string, unknown>>;
+    readonly systemPrompt?: string;
+    readonly entries: readonly string[];
+    readonly components: Readonly<Record<string, ComponentPlan>>;
+}
+export declare const COMPONENT_LIMITS: Readonly<{
+    depth: 8;
+    calls: 32;
+    steps: 40;
+    childSteps: 12;
+    requestBytes: 65536;
+    resultBytes: 1048576;
+    timeoutMs: 120000;
+}>;
+export interface StepResponse {
+    readonly value: unknown;
+    readonly failed?: boolean;
+    readonly usage?: StepUsage;
+}
+export interface BoundTool {
+    readonly name: string;
+    readonly source: string;
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    execute(input: unknown, signal: AbortSignal): Promise<unknown>;
+}
+export interface ToolEvidence {
+    readonly step: string;
+    readonly tool: string;
+    readonly input: unknown;
+    readonly output: unknown;
+}
+export interface ComponentEvidence {
+    readonly steps: Readonly<Record<string, unknown>>;
+    readonly tools: readonly ToolEvidence[];
+    /** Child results exactly as the caller saw them, i.e. after egress verification. */
+    readonly children: readonly ComponentInvocationResult[];
+    /** Provenance the egress step kept aside (definition, SQL); host-only, never model input. */
+    readonly egress?: readonly EgressProvenance[];
+}
+/** Where a child result is about to cross back into its caller. */
+export interface ChildVerificationContext {
+    readonly caller: string;
+    readonly step: string;
+    readonly alias: string;
+    readonly callee: string;
+    /** The callee's invocation depth (the caller's depth plus one). */
+    readonly depth: number;
+    /** The normalized alias-call request (request text plus `input`), as the child received it. */
+    readonly request: {
+        readonly request: string;
+        readonly input: Readonly<Record<string, unknown>>;
+    };
+}
+export interface ChildVerification {
+    /** What the caller receives; may only be narrower than the child result. */
+    readonly disclosed: ComponentInvocationResult;
+    readonly decisions: readonly EgressDecision[];
+    readonly provenance: readonly EgressProvenance[];
+}
+/** Host-created after exact context, model, account and tool authority validation. */
+export interface ComponentBinding {
+    readonly tools: readonly BoundTool[];
+    /** Tests identity/revocation, including after close() has released step resources. */
+    isCurrent(): boolean;
+    /** Pure result validation/normalization; must never persist child artifacts. */
+    normalize(evidence: ComponentEvidence, signal: AbortSignal): Promise<ComponentInvocationResult>;
+    close(): Promise<void>;
+}
+/** Transport gets a fresh request each time; no previous component/step transcript. */
+export interface StepRun {
+    readonly terminal?: boolean;
+    readonly tier: string;
+    readonly request: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly brief?: string;
+    readonly prompt: string;
+    readonly consumes: Readonly<Record<string, unknown>>;
+    /** Child results of this invocation so far, exactly as the caller saw them (after egress); host material for consumed artifacts. */
+    readonly children: readonly ComponentInvocationResult[];
+    readonly tools: Readonly<Record<string, (input: unknown) => Promise<unknown>>>;
+    readonly toolSchemas: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    readonly toolDescriptions: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+    /**
+     * True when the alias-call request declares per-slot answers (`input.slots`, the same
+     * declaration the egress seam verifies against). A tool error is then one slot's outcome,
+     * which the model reports as `{slot_id, status: "unanswerable"}` while answering the other
+     * slots, not a step failure. A request without slots keeps the single-answer rule: any tool
+     * error fails the step, its repair step runs, and an unrepaired failure ends the child.
+     */
+    readonly perSlot?: boolean;
+}
+export interface RunnerHost {
+    prepare(component: ComponentPlan, signal: AbortSignal): Promise<ComponentBinding>;
+    runStep(run: StepRun, binding: ComponentBinding): Promise<StepResponse>;
+    /** Separate root-only sink, invoked once after successful closure execution. */
+    persistRoot?(result: Extract<ComponentInvocationResult, {
+        status: "ok";
+    }>, binding: ComponentBinding, signal: AbortSignal): Promise<void>;
+    /**
+     * The egress verification seam: every child result passes through here,
+     * after the child invocation and before the alias resolves for the caller.
+     * The caller never sees `result`, only `disclosed`. Optional so a single-zone
+     * composition keeps today's pass-through; a host with a disclosure policy
+     * installs one.
+     */
+    verifyChild?(context: ChildVerificationContext, result: ComponentInvocationResult, signal: AbortSignal): Promise<ChildVerification>;
+    onEvent?(event: ComponentEvent): void;
+}
+export interface ComponentEvent {
+    readonly kind: "step.start" | "step.finish" | "call.start" | "call.finish" | "tool.start" | "tool.finish" | "egress" | "usage";
+    readonly invocation: string;
+    readonly parent: string | null;
+    readonly component: string;
+    readonly step?: string;
+    readonly tool?: string;
+    readonly callId?: string;
+    readonly depth: number;
+    readonly status?: "ok" | "error" | "cancelled";
+    /** `egress` events: slot id and outcome only, never the payload. */
+    readonly slot?: string;
+    readonly egress?: EgressDecision["status"];
+    readonly reason?: string;
+    /** `usage` events: one per completed step call, zeros when the transport reported none. */
+    readonly usage?: StepUsage;
+}
+/** Immutable, root-scoped execution. Constructed only from a validated producer adapter. */
+export declare class ComponentRunner {
+    private readonly host;
+    private readonly plan;
+    private readonly controller;
+    private readonly bindings;
+    private readonly releases;
+    private used;
+    private cleanupFailure;
+    get cleanupFailed(): boolean;
+    private calls;
+    private steps;
+    private usage;
+    private deadline;
+    constructor(plan: ExecutionPlan, host: RunnerHost);
+    cancel(): void;
+    get observedUsage(): Readonly<StepUsage>;
+    run(entry: string, request: unknown, signal?: AbortSignal): Promise<ComponentInvocationResult>;
+    /** Runs the host's egress seam, or passes the result through when the host installed none. */
+    private verifyChild;
+    private release;
+    private check;
+    private wait;
+    /**
+     * A per-slot child behind an egress seam that throws `callee_failed` (an unrepaired step) reaches
+     * the seam as a `callee_failed` result instead of failing the caller, so the seam can answer every
+     * slot unavailable. A grandchild's seam-narrowing violation thrown as `callee_failed` inside the
+     * child lands here too and renders all-unavailable (fails closed). Cancellation, budget, invalid
+     * results and any other error keep propagating, as does every failure of a child without slots
+     * or without a seam. A refused child is returned as is; the seam discloses it with its own category.
+     */
+    private invokeChild;
+    private invoke;
+    private validate;
+}