@wrenai/genbi 0.0.4 → 0.0.5

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

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+export const HOST_FEATURES = [
+    "immutable_step_authority", "isolated_component_tools", "fresh_child_context",
+    "verified_context_preconditions", "component_owned_bindings", "exact_step_tiers",
+    "exact_dataflow", "bounded_repair", "shared_admission_ledger",
+    "deadline_and_descendant_cancellation", "normalized_child_results",
+    "root_only_persistence", "redacted_usage_trace",
+];
+export const VERCEL_HOST_CONTRACT = Object.freeze({
+    protocol: "warble-component-host/1", bundle_version: "0.2", features: HOST_FEATURES,
+    guardrails: ["read_only_execution", "row_limit", "statement_timeout", "deterministic_gate", "artifact_write", "drill_depth_limit", "additivity_guard"],
+    tool_authority: {
+        query: { source: "native", capabilities: ["sql_execution:read_only"] },
+        semantic_introspect: { source: "native", capabilities: ["semantic_introspection"] },
+    },
+});
+const limits = z.object({
+    max_depth: z.literal(8), max_attempts: z.literal(32), max_steps: z.literal(40),
+    max_steps_per_child: z.literal(12), max_in_flight: z.literal(1),
+    max_request_bytes: z.literal(65536), max_result_bytes: z.literal(1048576), timeout_ms: z.literal(120000),
+}).strict();
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const strings = z.array(z.string());
+const record = z.record(z.string(), z.unknown());
+const calls = z.array(z.object({ alias: z.string(), component: z.string() }).strict());
+const when = z.object({ guard: z.literal("on_failure"), target: z.string() }).strict();
+const tool = z.object({ name: z.string(), source: z.string() }).strict();
+const irStep = z.object({
+    name: z.string(), tier: z.string(), consumes: strings, produces: z.string(),
+    prompt: z.string(), conditional: z.boolean(), when: when.nullable().optional(),
+    produces_exclusive: z.boolean().optional(), capabilities: strings.optional(),
+    component_calls: calls.optional(),
+}).strict();
+const declaration = z.object({
+    id: z.string(), verb: z.string(), type: z.literal("analytical"), realization_kind: z.literal("skill"),
+    trigger: z.object({ kind: z.literal("one_shot") }).strict(),
+    effect: z.object({ outcome: z.object({ kind: z.literal("none") }).strict(), render_blocks: z.array(record).optional() }).strict(),
+    entrypoint: z.boolean().optional(), brief: z.string().optional(), description: z.string().optional(),
+    llm_calls: z.array(irStep), required_capabilities: strings,
+    guardrails: z.array(record), borrowed_actions: strings, context_binding: record,
+    context_requirements: strings, context_precondition: z.array(record).optional(),
+    precondition_result: record, params: z.array(record).optional(), binds: record.nullable().optional(),
+    prompt_fragment: z.string().optional(), examples: strings.optional(), eval: record.optional(), eval_ref: z.string().optional(),
+}).strict();
+const realization = z.union([
+    z.object({ kind: z.literal("independent") }).strict(),
+    z.object({ kind: z.literal("repair_fold"), fold_into: z.string(), max_attempts: z.literal(1),
+        failure_input: z.string().optional(), on_exhaustion: z.literal("fail").optional() }).strict(),
+]);
+const shared = {
+    warble_ir_version: z.literal("0.9"), protocol: z.literal("warble-component-host/1"),
+    execution_status: z.literal("not_executed"), profile: z.string(),
+    input_ir_sha256: digest, context_binding: record, system_prompt: z.string().nullable().optional(),
+    limits, model_turn_hard_limit: z.literal(false), monetary_hard_limit: z.literal(false),
+};
+const vercel = z.object({
+    ...shared, vercel_bundle_version: z.literal("0.2"), target: z.literal("vercel:headless"),
+    entries: strings, required_host: record, bundle_sha256: digest,
+    components: z.record(z.string(), z.object({
+        declaration,
+        steps: z.array(z.object({ name: z.string(), effective_capabilities: strings, tools: z.array(tool), realization }).strict()),
+        capabilities: z.unknown(),
+    }).strict()),
+}).strict();
+const sessionComponent = z.object({
+    session_plan_version: z.literal("2"), producer_version: z.string(), warble_ir_version: z.literal("0.9"),
+    input_ir_sha256: digest, host_contract_sha256: digest, context_identity_sha256: digest, plan_sha256: digest,
+    profile: z.string(), component: z.string(), declaration,
+    instructions: z.object({ brief: z.string().nullable() }).strict(),
+    steps: z.array(z.object({ name: z.string(), tier: z.string(), consumes: strings, produces: z.string(),
+        produces_exclusive: z.boolean(), instructions: z.string(), capabilities: strings, tools: strings,
+        when: when.nullable(), realization, product_availability: z.enum(["after_attempt", "if_executed"]), component_calls: calls }).strict()),
+    slot_supply: record, capability_bindings: z.record(z.string(), z.object({ tool: z.string().optional() }).strict()),
+    required_host_capabilities: strings, required_capabilities: strings, guardrails: z.array(record), borrowed_actions: strings,
+    context_requirements: strings, context_precondition: z.array(record), precondition_result: record, render_blocks: z.array(record),
+    required_execution: strings, authority: z.literal("host_owned"), execution_status: z.literal("not_executed"),
+}).strict();
+const session = z.object({
+    ...shared, session_plan_version: z.literal("2"), producer_version: z.string(), authority: z.literal("host_owned"),
+    host_contract_sha256: digest, entry: z.string(), required_execution: strings,
+    components: z.record(z.string(), sessionComponent), plan_sha256: digest,
+}).strict();
+/** SHA over recursively sorted JSON, matching the producer's documented digest form. */
+export function canonicalPlanJson(value) {
+    const sort = (item) => {
+        if (Array.isArray(item))
+            return item.map(sort);
+        if (item && typeof item === "object")
+            return Object.fromEntries(Object.keys(item).sort().map((key) => [key, sort(item[key])]));
+        return item;
+    };
+    return JSON.stringify(sort(value));
+}
+export function planDigest(value) { return `sha256:${createHash("sha256").update(canonicalPlanJson(value)).digest("hex")}`; }
+function checkDigest(value, key, expected) {
+    const { [key]: claimed, ...payload } = value;
+    if (claimed !== planDigest(payload) || (expected !== undefined && claimed !== expected))
+        throw new Error("Component plan identity mismatch");
+}
+function assertEqual(left, right) {
+    if (!isDeepStrictEqual(left, right))
+        throw new Error("Component plan projection mismatch");
+}
+function commonStep(source, derived) {
+    if (source.conditional !== (derived.kind === "repair_fold"))
+        throw new Error("Unsupported step realization");
+    if (derived.kind === "repair_fold" && (source.when?.target !== derived.fold_into || source.when.guard !== "on_failure"))
+        throw new Error("Invalid repair target");
+    return { name: source.name, tier: source.tier, prompt: source.prompt, consumes: source.consumes,
+        produces: source.produces, tools: [], calls: source.component_calls ?? [],
+        ...(derived.kind === "repair_fold" ? { repairOf: derived.fold_into } : {}) };
+}
+export function readExecutionPlan(document, receipt) {
+    if (Buffer.byteLength(document) > 4 * 1024 * 1024)
+        throw new Error("Component plan exceeds byte limit");
+    const raw = JSON.parse(document);
+    const components = Object.create(null);
+    if (raw && typeof raw === "object" && "vercel_bundle_version" in raw) {
+        const bundle = vercel.parse(raw);
+        checkDigest(raw, "bundle_sha256", receipt.digest);
+        assertEqual(bundle.input_ir_sha256, receipt.inputIrDigest);
+        assertEqual(bundle.context_binding, receipt.contextBinding);
+        assertEqual(bundle.required_host, VERCEL_HOST_CONTRACT);
+        for (const [id, node] of Object.entries(bundle.components)) {
+            assertEqual(id, node.declaration.id);
+            assertEqual(node.declaration, receipt.declarations[id]);
+            assertEqual(node.steps.length, node.declaration.llm_calls.length);
+            const steps = node.steps.map((step, index) => {
+                const source = node.declaration.llm_calls[index];
+                assertEqual(step.name, source.name);
+                assertEqual(step.effective_capabilities, source.capabilities ?? node.declaration.required_capabilities);
+                for (const grant of step.tools) {
+                    const authority = VERCEL_HOST_CONTRACT.tool_authority[grant.name];
+                    if (!authority || authority.source !== grant.source || authority.capabilities.some((cap) => !step.effective_capabilities.includes(cap)))
+                        throw new Error("Unsupported tool authority");
+                }
+                return { ...commonStep(source, step.realization), tools: step.tools };
+            });
+            components[id] = { id, declaration: node.declaration, steps, ...(node.declaration.brief !== undefined ? { brief: node.declaration.brief } : {}) };
+        }
+        return { identity: bundle.bundle_sha256, entries: bundle.entries, components, contextBinding: bundle.context_binding,
+            ...(bundle.system_prompt ? { systemPrompt: bundle.system_prompt } : {}) };
+    }
+    const plan = session.parse(raw);
+    checkDigest(raw, "plan_sha256", receipt.digest);
+    assertEqual(plan.input_ir_sha256, receipt.inputIrDigest);
+    assertEqual(plan.context_binding, receipt.contextBinding);
+    if (!receipt.directHostDocument)
+        throw new Error("Missing direct host receipt");
+    assertEqual(plan.host_contract_sha256, `sha256:${createHash("sha256").update(receipt.directHostDocument).digest("hex")}`);
+    assertEqual(plan.required_execution, HOST_FEATURES);
+    for (const [id, node] of Object.entries(plan.components)) {
+        checkDigest(raw.components[id], "plan_sha256");
+        assertEqual(id, node.component);
+        assertEqual(id, node.declaration.id);
+        assertEqual(node.declaration, receipt.declarations[id]);
+        assertEqual(node.input_ir_sha256, plan.input_ir_sha256);
+        assertEqual(node.profile, plan.profile);
+        assertEqual(node.context_identity_sha256, planDigest(receipt.contextBinding));
+        assertEqual(node.context_precondition, node.declaration.context_precondition ?? []);
+        assertEqual(node.precondition_result, node.declaration.precondition_result);
+        assertEqual(node.guardrails, node.declaration.guardrails);
+        assertEqual(node.render_blocks, node.declaration.effect.render_blocks ?? []);
+        assertEqual(node.required_capabilities, node.declaration.required_capabilities);
+        assertEqual(node.steps.length, node.declaration.llm_calls.length);
+        const steps = node.steps.map((step, index) => {
+            const source = node.declaration.llm_calls[index];
+            assertEqual([step.name, step.tier, step.consumes, step.produces, step.instructions, step.component_calls], [source.name, source.tier, source.consumes, source.produces, source.prompt, source.component_calls ?? []]);
+            assertEqual(step.capabilities, source.capabilities ?? node.declaration.required_capabilities);
+            const tools = step.tools.map((name) => {
+                const owners = Object.entries(node.capability_bindings).filter(([, binding]) => binding.tool === name);
+                if (owners.length !== 1 || !step.capabilities.includes(owners[0][0]) || !["semantic_introspection", "sql_execution:read_only"].includes(owners[0][0]))
+                    throw new Error("Unsupported session tool authority");
+                return { name, source: `host:${owners[0][0]}` };
+            });
+            return { ...commonStep(source, step.realization), tools };
+        });
+        components[id] = { id, declaration: node.declaration, steps, ...(node.instructions.brief !== null ? { brief: node.instructions.brief } : {}) };
+    }
+    return { identity: plan.plan_sha256, entries: [plan.entry], components, contextBinding: plan.context_binding,
+        ...(plan.system_prompt ? { systemPrompt: plan.system_prompt } : {}) };
+}

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

@@ -0,0 +1,207 @@
+import { type ComponentInvocationResult } from "@warble/claude-agent-sdk";
+import { z } from "zod";
+import type { DisclosedAnswer, EgressProvenance } from "./egress.js";
+import type { ComponentEvidence, ComponentPlan } from "./runner.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 declare const BLOCK_SHAPES: {
+    readonly kpi_card: "scalar";
+    readonly chart: "series";
+    readonly table: "table";
+    readonly narrative: "narrative";
+};
+export type DataBlockType = keyof typeof BLOCK_SHAPES;
+declare const chartTypeSchema: z.ZodEnum<{
+    area: "area";
+    bar: "bar";
+    line: "line";
+    pie: "pie";
+    scatter: "scatter";
+}>;
+/** Unknown keys are stripped: a number the planner copied into a placeholder is dropped, never read. */
+declare const layoutBlockSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        chart: "chart";
+        kpi_card: "kpi_card";
+        narrative: "narrative";
+        table: "table";
+    }>;
+    label: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    chart_type: z.ZodOptional<z.ZodEnum<{
+        area: "area";
+        bar: "bar";
+        line: "line";
+        pie: "pie";
+        scatter: "scatter";
+    }>>;
+    slot_id: z.ZodString;
+}, z.core.$strip>;
+export declare const reportPlanSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    preamble: z.ZodDefault<z.ZodObject<{
+        period: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+        filters: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    slots: z.ZodArray<z.ZodObject<{
+        slot_id: z.ZodString;
+        block_type: z.ZodEnum<{
+            chart: "chart";
+            kpi_card: "kpi_card";
+            narrative: "narrative";
+            table: "table";
+        }>;
+        expected_shape: z.ZodEnum<{
+            narrative: "narrative";
+            scalar: "scalar";
+            series: "series";
+            table: "table";
+        }>;
+        question: z.ZodString;
+        unit: z.ZodOptional<z.ZodString>;
+        max_rows: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    blocks: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            chart: "chart";
+            kpi_card: "kpi_card";
+            narrative: "narrative";
+            table: "table";
+        }>;
+        label: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        chart_type: z.ZodOptional<z.ZodEnum<{
+            area: "area";
+            bar: "bar";
+            line: "line";
+            pie: "pie";
+            scatter: "scatter";
+        }>>;
+        slot_id: z.ZodString;
+    }, z.core.$strip>>;
+    summary_brief: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportPlan = z.infer<typeof reportPlanSchema>;
+export type LayoutBlock = z.infer<typeof layoutBlockSchema>;
+declare const cell: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+type Cell = z.infer<typeof cell>;
+export interface SlotEntry {
+    readonly answer: DisclosedAnswer;
+    /** Host-only: never handed to a model. */
+    readonly provenance?: EgressProvenance;
+}
+export type SlotTable = ReadonlyMap<string, SlotEntry>;
+/**
+ * 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 declare function buildSlotTable(children: readonly ComponentInvocationResult[], provenance?: readonly EgressProvenance[]): SlotTable;
+export type MaterialisedBlock = {
+    readonly type: "kpi_card";
+    readonly label: string;
+    readonly slot_id: string;
+    readonly value: number | string;
+    readonly unit?: string;
+} | {
+    readonly type: "chart";
+    readonly title: string;
+    readonly chart_type: z.infer<typeof chartTypeSchema>;
+    readonly slot_id: string;
+    readonly x: string;
+    readonly series: readonly string[];
+    readonly rows: readonly Cell[][];
+} | {
+    readonly type: "table";
+    readonly title: string;
+    readonly slot_id: string;
+    readonly columns: readonly string[];
+    readonly rows: readonly Cell[][];
+} | {
+    readonly type: "narrative";
+    readonly title: string;
+    readonly slot_id: string;
+    readonly text: string;
+} | {
+    readonly type: DataBlockType;
+    readonly label: string;
+    readonly slot_id: string;
+    readonly status: "unavailable";
+    readonly reason_category: string;
+};
+export interface MaterialisedPlan {
+    readonly title?: string;
+    readonly preamble: ReportPlan["preamble"];
+    readonly blocks: readonly MaterialisedBlock[];
+    readonly summary_brief?: string;
+}
+/**
+ * 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 declare function materialiseReportPlan(plan: ReportPlan, table: SlotTable): MaterialisedPlan;
+/** Parses a step product (string or object) as a report plan; undefined when it is not one. */
+export declare function parseReportPlan(product: unknown): ReportPlan | undefined;
+export interface NarratorText {
+    readonly summary?: string;
+    readonly notes: ReadonlyMap<string, {
+        readonly note?: string;
+        readonly label?: string;
+    }>;
+}
+/** Reads the narrator's text out of its output; the values it may have written are not looked at. */
+export declare function readNarratorText(product: unknown): NarratorText | undefined;
+export interface SynthesisedReport {
+    readonly blocks: readonly Record<string, unknown>[];
+    readonly summary?: string;
+    /** True only when at least one cell is filled and every filled cell came from a verified answer. */
+    readonly verified: boolean;
+    /** Slot ids whose provenance was attached as `definition` blocks. */
+    readonly definitions: readonly string[];
+}
+/**
+ * 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 declare function synthesiseReport(plan: ReportPlan, table: SlotTable, narrator: NarratorText | undefined): SynthesisedReport;
+/** A component whose render contract declares an `unavailable` cell is a report: the host synthesises its envelope. */
+export declare function isReportComponent(component: ComponentPlan): boolean;
+/** The step that lays the report out (owns the call edge) and the one that narrates it (consumes the layout). */
+export declare function reportSteps(component: ComponentPlan): {
+    layout: ComponentPlan["steps"][number];
+    narrate?: ComponentPlan["steps"][number];
+} | undefined;
+/**
+ * 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 declare function normalizeReportEvidence(component: ComponentPlan, evidence: ComponentEvidence): ComponentInvocationResult;
+export {};