@wrenai/genbi 0.0.5 → 0.0.6

package/dist-server/server/fold.js

@@ -1,5 +1,6 @@
 import { BUILD_DASHBOARD_TOOL_NAME, extractEnvelopeFromText, WREN_QUERY_TOOL_NAME } from "../harness/index.js";
-import { groundCodexLocalEnvelope } from "./codex-local-grounding.js";
+import { extractJsonCandidateFromText } from "../harness/render/envelope.js";
+import { groundOnHostEvidence } from "./host-evidence-grounding.js";
 /**
  * Canned remediation text for a refusal. `RefusalAgentEvent`/`RefusalResult`
  * carry no remediation hint from the agent runtime — the UI's `fix` field is
@@ -77,27 +78,31 @@ export function toAnswerOrRefusalEvent(id, result, worklog = []) {
  * The one place a subscription answer's `verified` is decided; a `verified`
  * field in model-written text is never kept.
  *
- * - `codex-local`: the model's `run_sql` executes through this turn's host
- *   query service, so the answer is grounded against that turn's observations
- *   ({@link groundCodexLocalEnvelope}): verified only when every query it
- *   cites is one the host ran this turn and that read a table, and then its
- *   tables and definitions are the observed ones. Otherwise it stays as
- *   written, badged "Unverified".
- * - `agent-sdk`: the host runs none of its queries and holds no evidence, so
- *   it is always `false`, with the rest of the envelope kept as-is.
+ * - `codex-local` and `agent-sdk`: the model's host query tool (codex:local's
+ *   `run_sql`, the agent-sdk host MCP's `run_sql`) executes through this turn's
+ *   host query service, so the answer is grounded against that turn's
+ *   observations ({@link groundOnHostEvidence}): verified only when every
+ *   query it cites is one the host ran this turn and that read a table, and
+ *   then its tables and definitions are the observed ones. Otherwise it stays
+ *   as written, badged "Unverified" — including any answer whose data came
+ *   another way (agent-sdk's Bash `wren` stays available and yields no host
+ *   evidence).
  *
  * Other backends pass through.
  */
 export function withHostVerification(result, envelope) {
-    if (result.backend === "codex-local")
-        return groundCodexLocalEnvelope(envelope, result.finalText, result.hostObservations ?? []);
-    return result.backend === "agent-sdk" ? { ...envelope, verified: false } : envelope;
+    if (result.backend === "codex-local" || result.backend === "agent-sdk") {
+        return groundOnHostEvidence(envelope, extractJsonCandidateFromText(result.finalText), result.hostObservations ?? []);
+    }
+    return envelope;
 }
 /** In-process's native in-process tool names that constitute an actual data claim — schema browsing / artifact saving don't count. */
 const DATA_ACCESS_TOOL_NAMES = new Set([
     WREN_QUERY_TOOL_NAME,
     BUILD_DASHBOARD_TOOL_NAME,
     "wren.run_sql",
+    // The agent-sdk Ask's host MCP query tool (see `harness/route/dispatched.ts`).
+    "mcp__wren_host__run_sql",
 ]);
 /**
  * Dispatched never produces those native tool names — the dispatched agent's `answer_query`/

package/dist-server/server/host-evidence-grounding.d.ts

@@ -0,0 +1,21 @@
+import type { HostQueryObservation } from "../harness/route/host-query.js";
+import type { RenderEnvelope } from "../harness/render/envelope.js";
+/**
+ * Grounds an answer against the queries the host executed for its scope (one codex:local or
+ * agent-sdk Ask turn, or one native session), with the component path's predicate
+ * (`citedGroundedQuery`: a tool-proven definition that reads at least one table, cited by
+ * `query_id`, else by whitespace-insensitive SQL).
+ *
+ * Verified only when the answer cites at least one query and every citation grounds. The
+ * envelope is then rebuilt from the observations alone: one `table` and one `definition` block
+ * (carrying the observed `query_id`) per cited query, plus the model's `summary` text as written.
+ * A cited result the host saw truncated still grounds the rows it shows; the host then appends
+ * a note to `summary`, the only place the render contract carries such text. Anything else stays the model's answer with
+ * `verified: false`: no citation, a citation to a query this scope never ran (including one from
+ * another turn or session), a query that read no table, or chart / KPI blocks the host cannot rebuild.
+ *
+ * `raw` is the answer as written, before envelope normalization (see `citations`).
+ */
+export declare function groundOnHostEvidence(envelope: RenderEnvelope, raw: unknown, observations: readonly HostQueryObservation[]): RenderEnvelope;
+/** Host-written, never model-written: a cited table that is only the first rows of its result. */
+export declare function truncationNote(shown: number): string;

package/dist-server/server/{codex-local-grounding.js → host-evidence-grounding.js}

@@ -1,5 +1,4 @@
 import { citedGroundedQuery } from "../harness/components/normalize.js";
-import { extractJsonCandidateFromText } from "../harness/render/envelope.js";
 import { namedAnswerQueryId, namedAnswerSql, sqlKey } from "../harness/render/answering-query.js";
 /** Blocks whose values the host cannot rebuild from one observed table; their presence leaves an answer unverified. */
 const UNREBUILDABLE_DATA_BLOCKS = new Set(["chart", "kpi_card"]);
@@ -7,13 +6,12 @@ function record(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
 }
 /**
- * The queries a codex:local answer names. A `{blocks}` answer cites through its `definition`
- * blocks; a flat or query-result answer through its own `definition` / top-level fields, read
- * from the raw text because envelope normalization drops a cited `query_id`. A host id wins over
- * SQL, like the component path.
+ * The queries an answer names. A `{blocks}` answer cites through its `definition` blocks; a flat
+ * or query-result answer through its own `definition` / top-level fields, read from `raw` (the
+ * answer as the model wrote it) because envelope normalization drops a cited `query_id`. A host
+ * id wins over SQL, like the component path.
  */
-function citations(envelope, finalText) {
-    const raw = extractJsonCandidateFromText(finalText);
+function citations(envelope, raw) {
     if (!Array.isArray(record(raw)?.blocks)) {
         const queryId = namedAnswerQueryId(raw);
         if (queryId !== undefined)
@@ -41,26 +39,29 @@ function citations(envelope, finalText) {
     return found;
 }
 /**
- * Grounds a codex:local answer against the queries this turn's host query service executed,
- * with the component path's predicate (`citedGroundedQuery`: a tool-proven definition that
- * reads at least one table, cited by `query_id`, else by whitespace-insensitive SQL).
+ * Grounds an answer against the queries the host executed for its scope (one codex:local or
+ * agent-sdk Ask turn, or one native session), with the component path's predicate
+ * (`citedGroundedQuery`: a tool-proven definition that reads at least one table, cited by
+ * `query_id`, else by whitespace-insensitive SQL).
  *
  * Verified only when the answer cites at least one query and every citation grounds. The
  * envelope is then rebuilt from the observations alone: one `table` and one `definition` block
  * (carrying the observed `query_id`) per cited query, plus the model's `summary` text as written.
  * A cited result the host saw truncated still grounds the rows it shows; the host then appends
  * a note to `summary`, the only place the render contract carries such text. Anything else stays the model's answer with
- * `verified: false`: no citation, a citation to a query this turn never ran (including one from
- * an earlier turn), a query that read no table, or chart / KPI blocks the host cannot rebuild.
+ * `verified: false`: no citation, a citation to a query this scope never ran (including one from
+ * another turn or session), a query that read no table, or chart / KPI blocks the host cannot rebuild.
+ *
+ * `raw` is the answer as written, before envelope normalization (see `citations`).
  */
-export function groundCodexLocalEnvelope(envelope, finalText, observations) {
+export function groundOnHostEvidence(envelope, raw, observations) {
     const unverified = { ...envelope, verified: false };
     if (observations.length === 0)
         return unverified;
     const blocks = Array.isArray(envelope.blocks) ? envelope.blocks : [];
     if (blocks.some((block) => UNREBUILDABLE_DATA_BLOCKS.has(String(record(block)?.type))))
         return unverified;
-    const cited = citations(envelope, finalText);
+    const cited = citations(envelope, raw);
     if (cited.length === 0)
         return unverified;
     const rebuilt = [];

package/dist-server/server/native-artifacts.d.ts

@@ -1,8 +1,10 @@
 import { type NativeSessionRow, type NativeStructuredAnswerRow, type Store } from "./db.js";
 import type { EnrichmentBinding } from "./enrichment.js";
+import type { ComponentAccess } from "../harness/components/broker.js";
 export declare const NATIVE_MCP_CREDENTIAL_ENV_VAR = "WARBLE_MCP_CONNECTION_CREDENTIAL";
 export declare const NATIVE_MCP_TOOL_NAME = "save_dashboard";
 export declare const NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME = "persist_answer";
+export declare const NATIVE_MCP_QUERY_TOOL_NAME = "query";
 export declare const NATIVE_MCP_SERVER_LABEL = "GenBI MCP";
 export declare const NATIVE_MCP_ARTIFACTS_LABEL = "GenBI Artifacts";
 /**
@@ -98,7 +100,7 @@ export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
             readonly properties: {
                 readonly verified: {
                     readonly type: "boolean";
-                    readonly description: "Ignored: the host records verified only for an answer it produced from a grounded component run; anything submitted here is stored as unverified.";
+                    readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                 };
                 readonly summary: {
                     readonly anyOf: readonly [{
@@ -286,6 +288,15 @@ export declare const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA: {
                                         };
                                     };
                                 };
+                                readonly query_id: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                    readonly maxLength: 64;
+                                    readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                };
                             };
                         }, {
                             readonly type: "object";
@@ -350,7 +361,7 @@ export declare const NATIVE_PERSIST_ANSWER_INPUT_SCHEMA: {
             readonly properties: {
                 readonly verified: {
                     readonly type: "boolean";
-                    readonly description: "Ignored: the host records verified only for an answer it produced from a grounded component run; anything submitted here is stored as unverified.";
+                    readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                 };
                 readonly blocks: {
                     readonly type: "array";
@@ -434,6 +445,15 @@ export declare const NATIVE_PERSIST_ANSWER_INPUT_SCHEMA: {
                                         };
                                     };
                                 };
+                                readonly query_id: {
+                                    readonly type: "string";
+                                    readonly not: {
+                                        readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                    };
+                                    readonly minLength: 1;
+                                    readonly maxLength: 64;
+                                    readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                };
                             };
                         }];
                     };
@@ -590,7 +610,7 @@ export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
                 readonly properties: {
                     readonly verified: {
                         readonly type: "boolean";
-                        readonly description: "Ignored: the host records verified only for an answer it produced from a grounded component run; anything submitted here is stored as unverified.";
+                        readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                     };
                     readonly summary: {
                         readonly anyOf: readonly [{
@@ -778,6 +798,15 @@ export declare const NATIVE_SAVE_DASHBOARD_CONTRACT: {
                                             };
                                         };
                                     };
+                                    readonly query_id: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                        readonly maxLength: 64;
+                                        readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                    };
                                 };
                             }, {
                                 readonly type: "object";
@@ -851,7 +880,7 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
                 readonly properties: {
                     readonly verified: {
                         readonly type: "boolean";
-                        readonly description: "Ignored: the host records verified only for an answer it produced from a grounded component run; anything submitted here is stored as unverified.";
+                        readonly description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps.";
                     };
                     readonly blocks: {
                         readonly type: "array";
@@ -935,6 +964,15 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
                                             };
                                         };
                                     };
+                                    readonly query_id: {
+                                        readonly type: "string";
+                                        readonly not: {
+                                            readonly pattern: "<\\s*\\/?(?:[sS][cC][rR][iI][pP][tT]|[hH][tT][mM][lL])\\b|[jJ][aA][vV][aA][sS][cC][rR][iI][pP][tT]\\s*:";
+                                        };
+                                        readonly minLength: 1;
+                                        readonly maxLength: 64;
+                                        readonly description: "Optional: the query_id the query tool returned for the query this definition describes.";
+                                    };
                                 };
                             }];
                         };
@@ -956,6 +994,29 @@ export declare const NATIVE_PERSIST_ANSWER_CONTRACT: {
     };
     readonly semanticConstraint: "The envelope contains exactly one typed table block and at most one typed definition block, with no presentation-only fields.";
 };
+/** The session `query` tool: one read-only SQL query run by the host through governed access. */
+export declare const NATIVE_QUERY_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["sql"];
+    readonly properties: {
+        readonly sql: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "One read-only SELECT over the bound semantic models.";
+        };
+        readonly limit: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Maximum rows to return (default 1000).";
+        };
+    };
+};
+export interface NativeQueryResult {
+    readonly isError: boolean;
+    readonly text: string;
+    readonly result?: unknown;
+}
 export interface NativeArtifactServiceOptions {
     readonly store: Store;
     readonly artifactsRoot: string;
@@ -964,6 +1025,11 @@ export interface NativeArtifactServiceOptions {
     /** Optional override, accepted only when it is the expected local endpoint. */
     readonly mcpUrl: string;
     readonly getBinding: () => EnrichmentBinding | undefined;
+    /**
+     * Opens governed Wren access for one native analysis session's `query` tool, against the
+     * session's bound project. Without it, the tool is not offered.
+     */
+    readonly openQueryAccess?: (binding: EnrichmentBinding, signal: AbortSignal) => Promise<ComponentAccess>;
     /** Test-only seam; production writes one contained JSON file atomically. */
     readonly writeAtomic?: (target: string, contents: string) => void;
     /** Test-only seam for a persistence outage; production uses the typed Store method. */
@@ -982,11 +1048,32 @@ export interface NativeArtifactServiceOptions {
 export declare class NativeArtifactService {
     private readonly options;
     private readonly credentials;
+    /** One host query recorder per native session: its observations are never shared across sessions. */
+    private readonly queryRecorders;
+    private readonly queryClosing;
     constructor(options: NativeArtifactServiceOptions);
     /** Validate the exact local BFF endpoint before advertising or issuing it. */
     readiness(): NativeMcpReadiness;
     issue(session: NativeSessionRow, binding: EnrichmentBinding | undefined): NativeMcpDescriptor;
     revoke(credential: string | undefined): void;
+    /** Whether native analysis sessions are offered the host `query` tool. */
+    queryAvailable(): boolean;
+    /** Resolves once every session query recorder closed so far has released its governed access. */
+    queriesClosed(): Promise<void>;
+    private closeQueries;
+    /**
+     * The session `query` tool: runs one read-only query through governed access against the
+     * session's bound project, records it as this session's observation and returns its rows with
+     * a session-tagged host `query_id` that a later persist_answer or save_dashboard may cite.
+     */
+    query(credential: string | undefined, input: unknown): Promise<NativeQueryResult>;
+    /**
+     * The host's grounding decision for a model-written envelope: the same envelope rebuilt from
+     * this session's query observations when every query it cites grounds on them (see
+     * `groundOnHostEvidence`), else `undefined`. Only this decision reaches a grounded entry from
+     * the MCP surface.
+     */
+    private groundedEnvelope;
     /** Releases opaque credentials when the owning BFF service shuts down. */
     dispose(): void;
     hasCredential(credential: string | undefined): boolean;
@@ -1016,5 +1103,7 @@ export declare class NativeArtifactService {
      * MCP). The caller must already have checked verified provenance.
      */
     saveGrounded(credential: string | undefined, input: unknown): SavedNativeArtifact;
+    /** The credential, session and binding checks every save runs before it reads its payload. */
+    private authorizeSave;
     private saveArtifact;
 }

package/dist-server/server/native-artifacts.js

@@ -7,6 +7,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { newId } from "./db.js";
+import { createHostQueryRecorder } from "../harness/route/host-query.js";
+import { groundOnHostEvidence } from "./host-evidence-grounding.js";
 const MAX_DASHBOARD_BYTES = 256 * 1024;
 const MAX_NAME_LENGTH = 120;
 const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
@@ -14,6 +16,7 @@ const ANSWER_REFERENCE_PATTERN = /^answer-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{
 export const NATIVE_MCP_CREDENTIAL_ENV_VAR = "WARBLE_MCP_CONNECTION_CREDENTIAL";
 export const NATIVE_MCP_TOOL_NAME = "save_dashboard";
 export const NATIVE_MCP_PERSIST_ANSWER_TOOL_NAME = "persist_answer";
+export const NATIVE_MCP_QUERY_TOOL_NAME = "query";
 export const NATIVE_MCP_SERVER_LABEL = "GenBI MCP";
 export const NATIVE_MCP_ARTIFACTS_LABEL = "GenBI Artifacts";
 // Keep this JSON Schema compatible with the ECMA-262 regular-expression
@@ -53,7 +56,8 @@ const POSITIONAL_ROWS_SCHEMA = {
     items: { type: "array", items: SCALAR_SCHEMA },
 };
 /** The exact public MCP shape advertised to native clients and accepted by the host. */
-const VERIFIED_FIELD_SCHEMA = { type: "boolean", description: "Ignored: the host records verified only for an answer it produced from a grounded component run; anything submitted here is stored as unverified." };
+const VERIFIED_FIELD_SCHEMA = { type: "boolean", description: "Ignored: the host decides verified itself. It records verified only for an answer it grounded: a grounded component run, or an answer whose every definition cites a query this session ran through the query tool. Anything submitted here is not a claim the host keeps." };
+const QUERY_ID_SCHEMA = { ...SAFE_TEXT_SCHEMA, minLength: 1, maxLength: 64, description: "Optional: the query_id the query tool returned for the query this definition describes." };
 export const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -79,7 +83,7 @@ export const NATIVE_SAVE_DASHBOARD_INPUT_SCHEMA = {
                             { type: "object", additionalProperties: false, required: ["type", "label", "value"], properties: { type: { const: "kpi_card" }, label: SAFE_TEXT_SCHEMA, value: SAFE_TEXT_OR_NUMBER_SCHEMA, unit: NULLABLE_SAFE_TEXT_SCHEMA, delta: { type: ["number", "null"] } } },
                             { type: "object", additionalProperties: false, required: ["type", "columns", "rows"], properties: { type: { const: "table" }, columns: { type: "array", minItems: 1, uniqueItems: true, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, rows: { ...POSITIONAL_ROWS_SCHEMA, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.table.positionalRows } } },
                             { type: "object", additionalProperties: false, required: ["type", "chart_type", "x", "series", "rows"], properties: { type: { const: "chart" }, chart_type: { enum: ["bar", "line", "pie", "area", "scatter"] }, x: { ...SAFE_TEXT_SCHEMA, minLength: 1, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.x }, series: { type: "array", minItems: 1, uniqueItems: true, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.series, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, rows: { ...POSITIONAL_ROWS_SCHEMA, description: NATIVE_SAVE_DASHBOARD_SEMANTIC_CONSTRAINTS.chart.positionalRows } } },
-                            { type: "object", additionalProperties: false, required: ["type", "sql", "source_tables", "filters"], properties: { type: { const: "definition" }, sql: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, source_tables: { type: "array", minItems: 1, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, filters: { type: "array", items: SAFE_TEXT_SCHEMA } } },
+                            { type: "object", additionalProperties: false, required: ["type", "sql", "source_tables", "filters"], properties: { type: { const: "definition" }, sql: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, source_tables: { type: "array", minItems: 1, items: { ...SAFE_TEXT_SCHEMA, minLength: 1 } }, filters: { type: "array", items: SAFE_TEXT_SCHEMA }, query_id: QUERY_ID_SCHEMA } },
                             { type: "object", additionalProperties: false, required: ["type", "text"], properties: { type: { const: "narrative" }, text: { ...SAFE_TEXT_SCHEMA, minLength: 1 }, title: NULLABLE_SAFE_TEXT_SCHEMA } },
                         ] },
                 },
@@ -163,6 +167,30 @@ export const NATIVE_PERSIST_ANSWER_CONTRACT = {
     inputSchema: NATIVE_PERSIST_ANSWER_INPUT_SCHEMA,
     semanticConstraint: "The envelope contains exactly one typed table block and at most one typed definition block, with no presentation-only fields.",
 };
+/** The session `query` tool: one read-only SQL query run by the host through governed access. */
+export const NATIVE_QUERY_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["sql"],
+    properties: {
+        sql: { type: "string", minLength: 1, description: "One read-only SELECT over the bound semantic models." },
+        limit: { type: "integer", minimum: 1, description: "Maximum rows to return (default 1000)." },
+    },
+};
+/** The sentence the model sees per host error class; nothing from the governed transport is forwarded. */
+const NATIVE_QUERY_ERROR_TEXT = {
+    invalid_request: "The request did not match the query contract: pass a non-empty sql string and an optional positive integer limit.",
+    model_not_found: "The query references a table that is not a model in the bound semantic context; query only the models it defines.",
+    policy_rejected: "The read-only analytical policy rejected the query: use one SELECT that reads at least one bound model.",
+    invalid_sql: "The SQL could not be parsed or planned against the semantic context.",
+    execution_failed: "The data source rejected the query at execution time, for example an unknown column or a type mismatch.",
+    timeout: "The query exceeded the statement time limit.",
+    datasource_unavailable: "The bound data source could not be reached.",
+    result_too_large: "The result exceeded the governed byte limit; narrow the query.",
+    budget_exhausted: "This session's query budget is exhausted; answer from the results you already have.",
+    internal: "The governed query failed for an unclassified reason.",
+    transport: "The host query service is unavailable.",
+};
 function rejectsExecutableText(value) {
     if (typeof value === "string")
         return /<\s*\/?(?:script|html)\b|javascript\s*:/i.test(value);
@@ -202,7 +230,7 @@ function validBlock(block) {
                 // Existing object rows remain exactly bound to x + series.
                 : isRecord(row) && scalar(row[x]) && series.every((item) => scalar(row[item])) && Object.keys(row).every((key) => key === x || series.includes(key)));
         case "definition":
-            return onlyKeys(block, ["type", "sql", "source_tables", "filters"]) && typeof block.sql === "string" && block.sql.length > 0 && Array.isArray(block.source_tables) && block.source_tables.length > 0 && block.source_tables.every((source) => typeof source === "string" && source.length > 0) && Array.isArray(block.filters) && block.filters.every((filter) => typeof filter === "string");
+            return (onlyKeys(block, ["type", "sql", "source_tables", "filters"]) || (onlyKeys(block, ["type", "sql", "source_tables", "filters", "query_id"]) && typeof block.query_id === "string" && block.query_id.length > 0 && block.query_id.length <= 64)) && typeof block.sql === "string" && block.sql.length > 0 && Array.isArray(block.source_tables) && block.source_tables.length > 0 && block.source_tables.every((source) => typeof source === "string" && source.length > 0) && Array.isArray(block.filters) && block.filters.every((filter) => typeof filter === "string");
         case "narrative":
             return (onlyKeys(block, ["type", "text"]) || onlyKeys(block, ["type", "text", "title"])) && typeof block.text === "string" && block.text.length > 0 && (block.title === undefined || block.title === null || typeof block.title === "string");
         default:
@@ -259,6 +287,24 @@ function validateInput(value) {
         throw new NativeArtifactError("invalid Save to Artifacts payload: answer_selection must be latest");
     return { version: "1", name: value.name, answer_selection: "latest", idempotency_key: value.idempotency_key };
 }
+function isValidSaveInput(value) {
+    try {
+        validateInput(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidPersistedStructuredAnswer(value) {
+    try {
+        validatePersistedStructuredAnswer(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function validatePersistedStructuredAnswer(value) {
     if (!isRecord(value) || !onlyKeys(value, ["version", "idempotency_key", "envelope"]))
         throw new NativeArtifactError("invalid structured answer payload: expected exactly version, idempotency_key, and envelope");
@@ -305,6 +351,9 @@ function validateStoredStructuredAnswer(source, nativeSessionId) {
 export class NativeArtifactService {
     options;
     credentials = new Map();
+    /** One host query recorder per native session: its observations are never shared across sessions. */
+    queryRecorders = new Map();
+    queryClosing = new Set();
     constructor(options) {
         this.options = options;
     }
@@ -336,7 +385,78 @@ export class NativeArtifactService {
     revoke(credential) {
         if (!credential)
             return;
+        const context = this.credentials.get(credential);
         this.credentials.delete(credential);
+        // A session can hold more than one credential (a Codex session's terminal and its component
+        // runtime each get one). Its query recorder lives until the session ends: the last credential
+        // for the session is revoked, which every session end and `dispose()` do.
+        if (context && ![...this.credentials.values()].some((other) => other.session.id === context.session.id))
+            this.closeQueries(context.session.id);
+    }
+    /** Whether native analysis sessions are offered the host `query` tool. */
+    queryAvailable() { return this.options.openQueryAccess !== undefined; }
+    /** Resolves once every session query recorder closed so far has released its governed access. */
+    async queriesClosed() { await Promise.allSettled([...this.queryClosing]); }
+    closeQueries(sessionId) {
+        const recorder = this.queryRecorders.get(sessionId);
+        if (!recorder)
+            return;
+        this.queryRecorders.delete(sessionId);
+        const closing = recorder.close();
+        this.queryClosing.add(closing);
+        void closing.finally(() => this.queryClosing.delete(closing));
+    }
+    /**
+     * The session `query` tool: runs one read-only query through governed access against the
+     * session's bound project, records it as this session's observation and returns its rows with
+     * a session-tagged host `query_id` that a later persist_answer or save_dashboard may cite.
+     */
+    async query(credential, input) {
+        const session = this.authorize(credential);
+        const binding = this.credentials.get(credential)?.binding;
+        const openQueryAccess = this.options.openQueryAccess;
+        if (session.purpose !== "analysis" || !binding || !openQueryAccess)
+            throw new NativeArtifactError("the query tool is unavailable for this native session", 409);
+        const args = isRecord(input) ? input : {};
+        if (!isRecord(input) || !Object.keys(input).every((key) => key === "sql" || key === "limit"))
+            return { isError: true, text: NATIVE_QUERY_ERROR_TEXT.invalid_request };
+        let recorder = this.queryRecorders.get(session.id);
+        if (!recorder) {
+            recorder = createHostQueryRecorder({ openAccess: (signal) => openQueryAccess(binding, signal) });
+            this.queryRecorders.set(session.id, recorder);
+        }
+        const outcome = await recorder.execute(args.sql, args.limit);
+        if ("error" in outcome)
+            return { isError: true, text: `Governed Wren query failed [${outcome.error}]: ${NATIVE_QUERY_ERROR_TEXT[outcome.error] ?? NATIVE_QUERY_ERROR_TEXT.internal}` };
+        return { isError: false, text: JSON.stringify(outcome.result), result: outcome.result };
+    }
+    /**
+     * The host's grounding decision for a model-written envelope: the same envelope rebuilt from
+     * this session's query observations when every query it cites grounds on them (see
+     * `groundOnHostEvidence`), else `undefined`. Only this decision reaches a grounded entry from
+     * the MCP surface.
+     */
+    groundedEnvelope(credential, envelope) {
+        const context = credential === undefined ? undefined : this.credentials.get(credential);
+        const recorder = context ? this.queryRecorders.get(context.session.id) : undefined;
+        if (!recorder || !isRecord(envelope))
+            return undefined;
+        // The host rebuilds only table and definition blocks. Any other block (narrative, chart, KPI)
+        // or an `estimate` flag would be dropped by the rebuild, so such an envelope is never grounded:
+        // it is kept intact and stored unverified rather than losing content silently.
+        if (envelope.estimate !== undefined && envelope.estimate !== null)
+            return undefined;
+        if (!Array.isArray(envelope.blocks) || envelope.blocks.some((block) => !isRecord(block) || (block.type !== "table" && block.type !== "definition")))
+            return undefined;
+        const grounded = groundOnHostEvidence(envelope, envelope, recorder.observations());
+        if (grounded.verified !== true)
+            return undefined;
+        // The rebuild emits one table and one definition per cited query. If it has fewer of either
+        // than the envelope did (an extra uncited table, say), content would be lost: keep it intact.
+        const count = (value, type) => Array.isArray(value.blocks) ? value.blocks.filter((block) => isRecord(block) && block.type === type).length : 0;
+        if (count(grounded, "table") !== count(envelope, "table") || count(grounded, "definition") !== count(envelope, "definition"))
+            return undefined;
+        return grounded;
     }
     /** Releases opaque credentials when the owning BFF service shuts down. */
     dispose() { for (const credential of [...this.credentials.keys()])
@@ -386,6 +506,20 @@ export class NativeArtifactService {
      * a later follow-up can only reference this stored result, never recompute.
      */
     persistAnswer(credential, input) {
+        // Authorize before validating, as `persistStructured` does: a bad credential is a 401 and a
+        // non-analysis session a 409 whatever the payload.
+        const session = this.authorize(credential);
+        if (session.purpose !== "analysis")
+            throw new NativeArtifactError("structured answer persistence is unavailable for this native session", 409);
+        const payload = validatePersistedStructuredAnswer(input);
+        const grounded = this.groundedEnvelope(credential, payload.envelope);
+        if (grounded) {
+            const candidate = { ...payload, envelope: grounded };
+            // A rebuilt envelope the persist contract cannot hold (a truncation note needs a summary,
+            // which this contract has no field for) is persisted unverified, as written.
+            if (isValidPersistedStructuredAnswer(candidate))
+                return this.persistStructured(credential, candidate, true);
+        }
         return this.persistStructured(credential, input, false);
     }
     /**
@@ -428,6 +562,16 @@ export class NativeArtifactService {
         }
     }
     save(credential, input) {
+        // Authorize before validating, as `saveArtifact` does.
+        this.authorizeSave(credential);
+        const payload = validateInput(input);
+        // Only an envelope save is grounded here; a save by reference inherits the retained answer's provenance.
+        const grounded = "envelope" in payload ? this.groundedEnvelope(credential, payload.envelope) : undefined;
+        if (grounded) {
+            const candidate = { ...payload, envelope: grounded };
+            if (isValidSaveInput(candidate))
+                return this.saveArtifact(credential, candidate, true);
+        }
         return this.saveArtifact(credential, input, false);
     }
     /**
@@ -437,7 +581,8 @@ export class NativeArtifactService {
     saveGrounded(credential, input) {
         return this.saveArtifact(credential, input, true);
     }
-    saveArtifact(credential, input, grounded) {
+    /** The credential, session and binding checks every save runs before it reads its payload. */
+    authorizeSave(credential) {
         const context = credential === undefined ? undefined : this.credentials.get(credential);
         if (!context)
             throw new NativeArtifactError("GenBI MCP bearer credential is invalid. Restart this native session to refresh its GenBI MCP connection.", 401);
@@ -447,6 +592,10 @@ export class NativeArtifactService {
             this.revoke(credential);
             throw new NativeArtifactError("GenBI MCP session binding is stale. Start a new native session.", 409);
         }
+        return { session, binding };
+    }
+    saveArtifact(credential, input, grounded) {
+        const { session, binding } = this.authorizeSave(credential);
         const payload = validateInput(input);
         const source = "answer_ref" in payload
             ? this.options.store.getNativeStructuredAnswer(payload.answer_ref)

package/dist-server/server/turn.js

@@ -604,7 +604,10 @@ async function executeSetupTurn(deps, session, turn, emit, signal) {
             ? undefined
             : deps.store.getSetupContextLifecycleEvidence(session.id, identityFingerprint)?.completed;
         if (identityFingerprint !== undefined) {
-            const recorded = recordedContextLifecyclePrefix(worklog, prior ?? "none");
+            const recorded = recordedContextLifecyclePrefix(worklog, prior ?? "none", {
+                root: workspaceRoot,
+                projectDir: path.join(workspaceRoot, form.projectName),
+            });
             // A build command is not retained by itself: only a successful terminal
             // parse has independently checked target/mdl.json. Discovery/validate
             // remain useful across an interrupted turn, but build includes artifact

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrenai/genbi",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Wren GenBI — the web UI for WrenAI: ask questions of your data and get dashboards back",
   "license": "Apache-2.0",
   "keywords": [
@@ -39,7 +39,7 @@
     "@warble/cli": "0.17.0",
     "@warble/codex-local": "0.17.0",
     "@warble/ir-spec": "0.9.0",
-    "@wrenai/context-loader": "0.1.3",
+    "@wrenai/context-loader": "0.1.4",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "ai": "~7.0.28",