@wrenai/genbi 0.0.4 → 0.0.6

package/dist-server/harness/providers/index.js

@@ -1,16 +1,21 @@
 export { UnknownAdapterError, UnknownTierError } from "./errors.js";
 export { createProviderRegistry } from "./registry.js";
-export { resolveStepModel, resolveTierModel } from "./binding.js";
+export { isZoneAwareBinding, parseTierBindingKey, resolveStepModel, resolveTierModel, resolveTierSpec, tierBindingKey, } from "./binding.js";
+export { ANSWER_SHAPES, ZONES, answerShapeSchema, disclosurePolicySchema, parseDisclosurePolicy, parseTierBindingDocument, readTierBindingFile, TierBindingParseError, tierBindingDocumentSchema, zoneRolesSchema, zoneSchema, } from "./zone.js";
 export { createMockAdapter, MOCK_ADAPTER_ID } from "./adapters/mock.js";
-export { createOpenAICompatibleAdapter, OPENAI_COMPATIBLE_ADAPTER_ID, } from "./adapters/openai-compatible.js";
+export { createOpenAICompatibleAdapter, mergeRequestBody, OPENAI_COMPATIBLE_ADAPTER_ID, } from "./adapters/openai-compatible.js";
 export { ANTHROPIC_ADAPTER_ID, createAnthropicAdapter } from "./adapters/anthropic.js";
+export { createOpenAIAdapter, OPENAI_ADAPTER_ID } from "./adapters/openai.js";
+export { createPiAiAdapter, listPiAiCatalog, PI_AI_ADAPTER_ID } from "./adapters/pi-ai.js";
 import { createAnthropicAdapter, ANTHROPIC_ADAPTER_ID } from "./adapters/anthropic.js";
 import { createMockAdapter, MOCK_ADAPTER_ID } from "./adapters/mock.js";
+import { createOpenAIAdapter, OPENAI_ADAPTER_ID } from "./adapters/openai.js";
 import { createOpenAICompatibleAdapter, OPENAI_COMPATIBLE_ADAPTER_ID, } from "./adapters/openai-compatible.js";
+import { createPiAiAdapter, PI_AI_ADAPTER_ID } from "./adapters/pi-ai.js";
 import { createProviderRegistry } from "./registry.js";
 /**
  * A provider registry pre-populated with the built-in adapters
- * (`mock`, `openai-compatible`, `anthropic`). Callers can still
+ * (`mock`, `openai-compatible`, `anthropic`, `openai`, `pi-ai`). Callers can still
  * `register()` additional adapter ids onto the returned registry.
  */
 export function createDefaultProviderRegistry() {
@@ -18,5 +23,7 @@ export function createDefaultProviderRegistry() {
     registry.register(MOCK_ADAPTER_ID, createMockAdapter);
     registry.register(OPENAI_COMPATIBLE_ADAPTER_ID, createOpenAICompatibleAdapter);
     registry.register(ANTHROPIC_ADAPTER_ID, createAnthropicAdapter);
+    registry.register(OPENAI_ADAPTER_ID, createOpenAIAdapter);
+    registry.register(PI_AI_ADAPTER_ID, createPiAiAdapter);
     return registry;
 }

package/dist-server/harness/providers/zone.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import type { TierBinding } from "./binding.js";
+/**
+ * Where a tier's model runs. `private` is a deployment the operator trusts
+ * with project data (rows, SQL, the semantic context); `public` is anything
+ * else, typically a cloud API. A deployment fact declared on the binding —
+ * never derived from an endpoint host, a model id or an adapter kind.
+ */
+export declare const ZONES: readonly ["private", "public"];
+export type Zone = (typeof ZONES)[number];
+export declare const zoneSchema: z.ZodEnum<{
+    private: "private";
+    public: "public";
+}>;
+/** The answer shapes a planner may declare for a slot and the policy may allow. */
+export declare const ANSWER_SHAPES: readonly ["scalar", "series", "table", "narrative"];
+export type AnswerShape = (typeof ANSWER_SHAPES)[number];
+export declare const answerShapeSchema: z.ZodEnum<{
+    narrative: "narrative";
+    scalar: "scalar";
+    series: "series";
+    table: "table";
+}>;
+/**
+ * The egress disclosure policy: what a verified callee answer may look like
+ * before it is disclosed to a public-zone caller. `max_rows` is required and
+ * must be a positive integer — a policy that forgets it would otherwise
+ * silently allow any table through, which is the wrong default for a gate.
+ */
+export declare const disclosurePolicySchema: z.ZodObject<{
+    allowed_shapes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        narrative: "narrative";
+        scalar: "scalar";
+        series: "series";
+        table: "table";
+    }>>>;
+    max_rows: z.ZodNumber;
+    min_group_size: z.ZodDefault<z.ZodNumber>;
+    sensitive_column_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    pii_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    judge_timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type DisclosurePolicy = z.infer<typeof disclosurePolicySchema>;
+/**
+ * Non-step tiers the zone gate must check by role. Each value is a binding
+ * key (a bare tier or `<mount>/<tier>`) that must resolve in `tiers`.
+ */
+export declare const zoneRolesSchema: z.ZodObject<{
+    judge: z.ZodOptional<z.ZodString>;
+    render: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ZoneRoles = z.infer<typeof zoneRolesSchema>;
+/**
+ * The on-disk tier binding document (`--tier-binding <file>`), the file
+ * counterpart of the `--tier-adapter` flags. Keys of `tiers` are bare tier
+ * names or `<mount>/<tier>`; `disclosure_policy` and `roles` are the hybrid
+ * split's additions. Credentials belong in the adapter's environment, not in
+ * this file, but nothing here forbids `config.apiKey` for a local dev setup.
+ */
+export declare const tierBindingDocumentSchema: z.ZodObject<{
+    tiers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        adapter: z.ZodString;
+        config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        zone: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            public: "public";
+        }>>;
+    }, z.core.$strict>>;
+    disclosure_policy: z.ZodOptional<z.ZodObject<{
+        allowed_shapes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            narrative: "narrative";
+            scalar: "scalar";
+            series: "series";
+            table: "table";
+        }>>>;
+        max_rows: z.ZodNumber;
+        min_group_size: z.ZodDefault<z.ZodNumber>;
+        sensitive_column_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        pii_patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        judge_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    roles: z.ZodOptional<z.ZodObject<{
+        judge: z.ZodOptional<z.ZodString>;
+        render: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TierBindingDocument = z.infer<typeof tierBindingDocumentSchema>;
+export declare class TierBindingParseError extends Error {
+    constructor(message: string);
+}
+/** Parses a tier binding document into the runtime `TierBinding`, loud-failing on any schema violation. */
+export declare function parseTierBindingDocument(value: unknown): TierBinding;
+/** Parses a disclosure policy on its own (the shape the egress verification step consumes). */
+export declare function parseDisclosurePolicy(value: unknown): DisclosurePolicy;
+/** Reads and parses a JSON tier binding file. */
+export declare function readTierBindingFile(filePath: string): Promise<TierBinding>;

package/dist-server/harness/providers/zone.js

@@ -0,0 +1,112 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+/**
+ * Where a tier's model runs. `private` is a deployment the operator trusts
+ * with project data (rows, SQL, the semantic context); `public` is anything
+ * else, typically a cloud API. A deployment fact declared on the binding —
+ * never derived from an endpoint host, a model id or an adapter kind.
+ */
+export const ZONES = ["private", "public"];
+export const zoneSchema = z.enum(ZONES);
+/** The answer shapes a planner may declare for a slot and the policy may allow. */
+export const ANSWER_SHAPES = ["scalar", "series", "table", "narrative"];
+export const answerShapeSchema = z.enum(ANSWER_SHAPES);
+/**
+ * The egress disclosure policy: what a verified callee answer may look like
+ * before it is disclosed to a public-zone caller. `max_rows` is required and
+ * must be a positive integer — a policy that forgets it would otherwise
+ * silently allow any table through, which is the wrong default for a gate.
+ */
+export const disclosurePolicySchema = z.object({
+    allowed_shapes: z.array(answerShapeSchema).min(1).default([...ANSWER_SHAPES]),
+    max_rows: z.number().int().positive(),
+    min_group_size: z.number().int().nonnegative().default(1),
+    sensitive_column_patterns: z.array(z.string().min(1)).default([]),
+    /** Regexes matched against string cells; the built-in PII set applies as well. */
+    pii_patterns: z.array(z.string().min(1)).default([]),
+    /** Judge wall-clock budget; a judge that exceeds it refuses the slot. */
+    judge_timeout_ms: z.number().int().positive().default(30_000),
+}).strict();
+/**
+ * Non-step tiers the zone gate must check by role. Each value is a binding
+ * key (a bare tier or `<mount>/<tier>`) that must resolve in `tiers`.
+ */
+export const zoneRolesSchema = z.object({
+    judge: z.string().min(1).optional(),
+    render: z.string().min(1).optional(),
+}).strict();
+const adapterSpecSchema = z.object({
+    adapter: z.string().min(1),
+    config: z.record(z.string(), z.unknown()).default({}),
+    zone: zoneSchema.optional(),
+}).strict();
+/**
+ * The on-disk tier binding document (`--tier-binding <file>`), the file
+ * counterpart of the `--tier-adapter` flags. Keys of `tiers` are bare tier
+ * names or `<mount>/<tier>`; `disclosure_policy` and `roles` are the hybrid
+ * split's additions. Credentials belong in the adapter's environment, not in
+ * this file, but nothing here forbids `config.apiKey` for a local dev setup.
+ */
+export const tierBindingDocumentSchema = z.object({
+    tiers: z.record(z.string().min(1), adapterSpecSchema),
+    disclosure_policy: disclosurePolicySchema.optional(),
+    roles: zoneRolesSchema.optional(),
+}).strict();
+export class TierBindingParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TierBindingParseError";
+    }
+}
+function describeIssues(error) {
+    return error.issues.map((issue) => `${issue.path.map(String).join(".") || "<root>"}: ${issue.message}`).join("; ");
+}
+/** Parses a tier binding document into the runtime `TierBinding`, loud-failing on any schema violation. */
+export function parseTierBindingDocument(value) {
+    const parsed = tierBindingDocumentSchema.safeParse(value);
+    if (!parsed.success)
+        throw new TierBindingParseError(`tier binding is invalid — ${describeIssues(parsed.error)}`);
+    const tiers = {};
+    for (const [key, spec] of Object.entries(parsed.data.tiers)) {
+        if (key.startsWith("/") || key.endsWith("/") || key.split("/").length > 2) {
+            throw new TierBindingParseError(`tier binding key "${key}" must be "<tier>" or "<mount>/<tier>"`);
+        }
+        tiers[key] = { adapter: spec.adapter, config: spec.config, ...(spec.zone !== undefined ? { zone: spec.zone } : {}) };
+    }
+    const binding = {
+        tiers,
+        ...(parsed.data.disclosure_policy !== undefined ? { disclosurePolicy: parsed.data.disclosure_policy } : {}),
+        ...(parsed.data.roles !== undefined ? { roles: parsed.data.roles } : {}),
+    };
+    for (const [role, key] of Object.entries(binding.roles ?? {})) {
+        if (key !== undefined && binding.tiers[key] === undefined) {
+            throw new TierBindingParseError(`roles.${role} names tier "${key}", which is not in tiers`);
+        }
+    }
+    return binding;
+}
+/** Parses a disclosure policy on its own (the shape the egress verification step consumes). */
+export function parseDisclosurePolicy(value) {
+    const parsed = disclosurePolicySchema.safeParse(value);
+    if (!parsed.success)
+        throw new TierBindingParseError(`disclosure_policy is invalid — ${describeIssues(parsed.error)}`);
+    return parsed.data;
+}
+/** Reads and parses a JSON tier binding file. */
+export async function readTierBindingFile(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        throw new TierBindingParseError(`cannot read tier binding file "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new TierBindingParseError(`tier binding file "${filePath}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseTierBindingDocument(value);
+}

package/dist-server/harness/render/answering-query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Which executed query answers the question. A step may run several successful
+ * queries (an exploratory count, then the real one, then a stray check), so
+ * "the last successful table" is not a safe choice: a chatty model produces a
+ * grounded but wrong answer. The model names the query it answered with in the
+ * terminal value's `definition`: by the `query_id` the host attached to the
+ * tool result, or by the exact SQL it ran; the host then selects that observed
+ * table, and never the model's own copy of the rows.
+ */
+/** Whitespace- and terminator-insensitive identity for one SQL text. */
+export declare function sqlKey(sql: string): string;
+/**
+ * The host-assigned query id (`q<N>`) a terminal value cites as its answer, if any. An id is
+ * preferred over SQL: the model names the executed query instead of re-typing it.
+ */
+export declare function namedAnswerQueryId(value: unknown): string | undefined;
+/** The SQL a terminal value names as its answer, if it names exactly one. */
+export declare function namedAnswerSql(value: unknown): string | undefined;
+/**
+ * Picks the answering entry among candidates that each carry the SQL they ran.
+ * Named and observed: the last observation of that SQL. Named but never run:
+ * `undefined`, so the caller refuses rather than substitute another table.
+ * Unnamed: the last candidate, the historical rule, kept only for values that
+ * do not name a query at all.
+ */
+export declare function selectAnsweringCandidate<T extends {
+    readonly sql?: string | undefined;
+    readonly queryId?: string | undefined;
+}>(candidates: readonly T[], terminalValue: unknown): T | undefined;

package/dist-server/harness/render/answering-query.js

@@ -0,0 +1,62 @@
+/**
+ * Which executed query answers the question. A step may run several successful
+ * queries (an exploratory count, then the real one, then a stray check), so
+ * "the last successful table" is not a safe choice: a chatty model produces a
+ * grounded but wrong answer. The model names the query it answered with in the
+ * terminal value's `definition`: by the `query_id` the host attached to the
+ * tool result, or by the exact SQL it ran; the host then selects that observed
+ * table, and never the model's own copy of the rows.
+ */
+/** Whitespace- and terminator-insensitive identity for one SQL text. */
+export function sqlKey(sql) {
+    return sql.replace(/\s+/g, " ").replace(/;\s*$/, "").trim();
+}
+/**
+ * The host-assigned query id (`q<N>`) a terminal value cites as its answer, if any. An id is
+ * preferred over SQL: the model names the executed query instead of re-typing it.
+ */
+export function namedAnswerQueryId(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const definition = record.definition;
+    if (typeof definition === "object" && definition !== null && !Array.isArray(definition)) {
+        const id = definition.query_id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return typeof record.query_id === "string" && record.query_id.length > 0 ? record.query_id : undefined;
+}
+/** The SQL a terminal value names as its answer, if it names exactly one. */
+export function namedAnswerSql(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const definition = record.definition;
+    if (typeof definition === "object" && definition !== null && !Array.isArray(definition)) {
+        const sql = definition.sql;
+        if (typeof sql === "string" && sql.trim())
+            return sql;
+    }
+    return typeof record.sql === "string" && record.sql.trim() ? record.sql : undefined;
+}
+/**
+ * Picks the answering entry among candidates that each carry the SQL they ran.
+ * Named and observed: the last observation of that SQL. Named but never run:
+ * `undefined`, so the caller refuses rather than substitute another table.
+ * Unnamed: the last candidate, the historical rule, kept only for values that
+ * do not name a query at all.
+ */
+export function selectAnsweringCandidate(candidates, terminalValue) {
+    // Cited by id among candidates that carry host ids: that candidate or none, never a fallback
+    // to the SQL text or the last table. Candidates with no ids at all (the session loop's seeds)
+    // cannot resolve an id, so the citation falls through to the SQL and last-table rules.
+    const id = namedAnswerQueryId(terminalValue);
+    if (id !== undefined && candidates.some((candidate) => candidate.queryId !== undefined))
+        return candidates.find((candidate) => candidate.queryId === id);
+    const named = namedAnswerSql(terminalValue);
+    if (named === undefined)
+        return candidates.at(-1);
+    const key = sqlKey(named);
+    return [...candidates].reverse().find((candidate) => candidate.sql !== undefined && sqlKey(candidate.sql) === key);
+}

package/dist-server/harness/render/envelope.d.ts

@@ -143,3 +143,9 @@ export declare function isTableOnlySchema(outputSchema: Record<string, unknown>)
  * `form: "text"` instead of fabricating an envelope.
  */
 export declare function extractEnvelopeFromText(text: string): RenderEnvelope | undefined;
+/**
+ * The raw JSON object a model's final text carries (fence- and prose-tolerant, see
+ * `extractJsonObjectText`), before any envelope normalization, else `undefined`. Fields the
+ * normalization drops, such as a cited `query_id`, are still present here.
+ */
+export declare function extractJsonCandidateFromText(text: string): unknown;

package/dist-server/harness/render/envelope.js

@@ -351,14 +351,21 @@ function extractJsonObjectText(text) {
  * `form: "text"` instead of fabricating an envelope.
  */
 export function extractEnvelopeFromText(text) {
-    let candidate;
+    const candidate = extractJsonCandidateFromText(text);
+    return candidate === undefined ? undefined : normalizeExtractedCandidate(candidate);
+}
+/**
+ * The raw JSON object a model's final text carries (fence- and prose-tolerant, see
+ * `extractJsonObjectText`), before any envelope normalization, else `undefined`. Fields the
+ * normalization drops, such as a cited `query_id`, are still present here.
+ */
+export function extractJsonCandidateFromText(text) {
     try {
-        candidate = JSON.parse(extractJsonObjectText(text));
+        return JSON.parse(extractJsonObjectText(text));
     }
     catch {
         return undefined;
     }
-    return normalizeExtractedCandidate(candidate);
 }
 /** Bounded: at most one MCP `CallToolResult` unwrap, so a pathological/self-referential payload can't recurse forever. */
 const MAX_UNWRAP_DEPTH = 2;

package/dist-server/harness/route/adapter-spec.d.ts

@@ -25,15 +25,14 @@ export interface DeriveAdapterSpecOptions {
  *   exactly what that adapter targets. `endpoint` becomes `baseURL`; `model`
  *   comes from `options.model` (falling back to `DEFAULT_LOCAL_MODEL`) since
  *   `LocalAuthChoice` itself carries no model field.
- * - `gateway` — also mapped onto `openai-compatible` (an operator-managed
- *   gateway is, from this adapter's point of view, just another OpenAI-compatible
- *   endpoint); `authChoice.config` must already carry `baseURL`/`model`
- *   (and optionally `apiKey`) matching `OpenAICompatibleAdapterConfig` — 70a
- *   leaves this config shape unspecified, so this is this ticket's own
- *   assumption, not a contract 70a promises. Unlike `local` (which defaults
- *   endpoint/model), `gateway` has no sensible default, so a missing/empty
- *   `baseURL`/`model` is a loud `wren-harness`-level error here rather than a
- *   bare "Invalid URL" deep inside the adapter.
+ * - `gateway` — mapped onto the `pi-ai` adapter, pi-ai's unified client for
+ *   an operator-chosen provider (a built-in pi-ai provider id such as
+ *   `openrouter` or `amazon-bedrock`, or a custom OpenAI-compatible endpoint
+ *   when `baseUrl` is set). `authChoice.config` must carry `provider` and
+ *   `model`, and may carry `apiKey`, `baseUrl` and `headers`
+ *   (`PiAiAdapterConfig`). `gateway` has no sensible default, so a
+ *   missing/empty `provider`/`model` is a loud `wren-harness`-level error here
+ *   rather than a failure deep inside the adapter on the first call.
  */
 export declare function deriveAdapterSpec(authChoice: Extract<AuthChoice, {
     mode: "api-key" | "local" | "gateway";

package/dist-server/harness/route/adapter-spec.js

@@ -1,4 +1,4 @@
-import { OPENAI_COMPATIBLE_ADAPTER_ID } from "../providers/index.js";
+import { OPENAI_COMPATIBLE_ADAPTER_ID, PI_AI_ADAPTER_ID } from "../providers/index.js";
 /** Default local endpoint used when a `LocalAuthChoice` omits `endpoint` (Ollama's default OpenAI-compatible port). */
 export const DEFAULT_LOCAL_ENDPOINT = "http://localhost:11434/v1";
 /**
@@ -20,15 +20,14 @@ export const DEFAULT_LOCAL_MODEL = "llama3.1";
  *   exactly what that adapter targets. `endpoint` becomes `baseURL`; `model`
  *   comes from `options.model` (falling back to `DEFAULT_LOCAL_MODEL`) since
  *   `LocalAuthChoice` itself carries no model field.
- * - `gateway` — also mapped onto `openai-compatible` (an operator-managed
- *   gateway is, from this adapter's point of view, just another OpenAI-compatible
- *   endpoint); `authChoice.config` must already carry `baseURL`/`model`
- *   (and optionally `apiKey`) matching `OpenAICompatibleAdapterConfig` — 70a
- *   leaves this config shape unspecified, so this is this ticket's own
- *   assumption, not a contract 70a promises. Unlike `local` (which defaults
- *   endpoint/model), `gateway` has no sensible default, so a missing/empty
- *   `baseURL`/`model` is a loud `wren-harness`-level error here rather than a
- *   bare "Invalid URL" deep inside the adapter.
+ * - `gateway` — mapped onto the `pi-ai` adapter, pi-ai's unified client for
+ *   an operator-chosen provider (a built-in pi-ai provider id such as
+ *   `openrouter` or `amazon-bedrock`, or a custom OpenAI-compatible endpoint
+ *   when `baseUrl` is set). `authChoice.config` must carry `provider` and
+ *   `model`, and may carry `apiKey`, `baseUrl` and `headers`
+ *   (`PiAiAdapterConfig`). `gateway` has no sensible default, so a
+ *   missing/empty `provider`/`model` is a loud `wren-harness`-level error here
+ *   rather than a failure deep inside the adapter on the first call.
  */
 export function deriveAdapterSpec(authChoice, options = {}) {
     switch (authChoice.mode) {
@@ -45,14 +44,14 @@ export function deriveAdapterSpec(authChoice, options = {}) {
         case "gateway": {
             const config = authChoice.config ?? {};
             const missing = [];
-            if (!isNonEmptyString(config["baseURL"]))
-                missing.push("baseURL");
+            if (!isNonEmptyString(config["provider"]))
+                missing.push("provider");
             if (!isNonEmptyString(config["model"]))
                 missing.push("model");
             if (missing.length > 0) {
-                throw new Error(`gateway mode requires ${missing.join(" and ")} in config (pass --endpoint and --model)`);
+                throw new Error(`gateway mode requires provider and model in config, missing ${missing.join(" and ")} (pass --provider and --model)`);
             }
-            return { adapter: OPENAI_COMPATIBLE_ADAPTER_ID, config };
+            return { adapter: PI_AI_ADAPTER_ID, config };
         }
     }
 }

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

@@ -1,6 +1,6 @@
 const COMPONENT_STEPS = {
     answer_query: [
-        { name: "resolve_intent", tier: "cheap", tool: "get_context" },
+        { name: "resolve_intent", tier: "cheap", tool: null },
         { name: "generate_sql", tier: "strong", tool: "run_sql" },
         { name: "repair_sql", tier: "strong", tool: "run_sql" },
     ],
@@ -115,6 +115,7 @@ export class CodexAskEventMapper {
                     reference.agentRole !== expectedRole(step.name) ||
                     reference.server !== "wren" ||
                     !reference.itemId ||
+                    step.tool === null ||
                     reference.tool !== step.tool) {
                     throw new Error("warble-codex-local Ask artifact attribution did not match the allowed Wren MCP surface");
                 }

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

@@ -8,6 +8,10 @@ export declare function buildCodexAskArgs(cli: ResolvedCli, options: {
     readonly codexHome: string;
     readonly models: CodexManifestModels;
     readonly mcpServer: ResolvedCli;
+    /** The genbi stdio proxy Codex starts as its `wren` MCP server (see `wren-host-proxy.ts`). */
+    readonly proxy: ResolvedCli;
+    /** This turn's host query credential file; the proxy reads it, its path carries no secret. */
+    readonly credentialFile: string;
     readonly codexBin?: string;
     readonly timeoutMs: number;
     readonly component?: CodexAskComponent;

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

@@ -1,13 +1,15 @@
 import { spawn } from "node:child_process";
-import { accessSync, constants as fsConstants } from "node:fs";
 import { createInterface } from "node:readline";
 import path from "node:path";
+import { hashDirectory } from "../compile/fingerprint.js";
+import { openWrenComponentAccess } from "../components/wren-access.js";
 import { enforceCompliance } from "../compliance/index.js";
 import { compileProfile } from "../compile/pipeline.js";
 import { createAgentEventEmitter } from "../events/index.js";
 import { CodexAskEventMapper } from "./codex-ask-events.js";
+import { defaultWrenHostProxy, openHostQueryService, resolveExecutableOnPath, singleWrenExecutable, wrenHostProxyArgs, } from "./host-query.js";
 import { resolveCodexLocalCli } from "./codex-local-cli.js";
-import { CODEX_ASK_COMPONENTS, } from "./codex-local-manifest.js";
+import { CODEX_ASK_COMPONENTS, codexAnalysisToolArgs, } from "./codex-local-manifest.js";
 const CODEX_BILLING_ENV_KEYS = new Set([
     "OPENAI_API_KEY",
     "CODEX_API_KEY",
@@ -21,6 +23,7 @@ const DEFAULT_CODEX_ASK_TIMEOUT_MS = 10 * 60 * 1000;
 export function buildCodexAskArgs(cli, options) {
     if (!options.question.trim())
         throw new Error("Codex Ask question must not be empty");
+    const serverArgs = wrenHostProxyArgs(options);
     return [
         ...cli.prefixArgs,
         "dispatch",
@@ -41,20 +44,9 @@ export function buildCodexAskArgs(cli, options) {
         "--server",
         "wren",
         "--server-command",
-        options.mcpServer.command,
-        ...options.mcpServer.prefixArgs.flatMap((arg) => arg.startsWith("-") ? [`--server-arg=${arg}`] : ["--server-arg", arg]),
-        "--server-arg",
-        "serve",
-        "--server-arg",
-        "mcp",
-        "--server-arg=--project",
-        "--server-arg",
-        options.userProject,
-        "--server-arg=--quiet",
-        "--inspect-tool",
-        "get_context",
-        "--query-tool",
-        "run_sql",
+        options.proxy.command,
+        ...serverArgs.flatMap((arg) => arg.startsWith("-") ? [`--server-arg=${arg}`] : ["--server-arg", arg]),
+        ...codexAnalysisToolArgs(options.component ?? "answer_query"),
         "--timeout",
         String(options.timeoutMs),
         ...(options.codexBin ? ["--codex-bin", options.codexBin] : []),
@@ -97,21 +89,42 @@ export async function runCodexAskDefault(options) {
         if (options.signal?.aborted)
             throw new Error("warble-codex-local Ask was cancelled during preparation");
         const timeoutMs = options.timeoutMs ?? DEFAULT_CODEX_ASK_TIMEOUT_MS;
-        const args = buildCodexAskArgs(cli, {
-            irPath,
-            question: options.question,
-            userProject: options.userProject,
-            codexHome,
-            models,
-            mcpServer,
-            timeoutMs,
-            component,
-            ...(options.codexBin !== undefined ? { codexBin: options.codexBin } : {}),
+        const userProject = options.userProject;
+        // This turn's host query service: the only place codex:local's run_sql executes and the
+        // only evidence its answer can be grounded on. Closed (and its observations discarded)
+        // when the turn ends, whatever the outcome.
+        const hostQueries = await openHostQueryService({
+            openAccess: async (signal) => openWrenComponentAccess({
+                executable: singleWrenExecutable(mcpServer),
+                project: userProject,
+                fingerprint: await hashDirectory(userProject),
+                signal,
+            }),
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
         });
-        const mapper = new CodexAskEventMapper(models, component);
-        const finalText = await spawnCodexAsk(cli.command, args, mapper, emitter.emit, options.processTimeoutMs ?? timeoutMs + 5_000, options.signal);
-        emitter.emit({ kind: "run.finish", status: "answer" });
-        return { finalText };
+        try {
+            const args = buildCodexAskArgs(cli, {
+                irPath,
+                question: options.question,
+                userProject,
+                codexHome,
+                models,
+                mcpServer,
+                proxy: defaultWrenHostProxy(),
+                credentialFile: hostQueries.credentialFile,
+                timeoutMs,
+                component,
+                ...(options.codexBin !== undefined ? { codexBin: options.codexBin } : {}),
+            });
+            const mapper = new CodexAskEventMapper(models, component);
+            const finalText = await spawnCodexAsk(cli.command, args, mapper, emitter.emit, options.processTimeoutMs ?? timeoutMs + 5_000, options.signal);
+            const hostObservations = hostQueries.observations();
+            emitter.emit({ kind: "run.finish", status: "answer" });
+            return { finalText, hostObservations };
+        }
+        finally {
+            await hostQueries.close();
+        }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -127,21 +140,6 @@ function resolveModels(value) {
     }
     return models;
 }
-function resolveExecutableOnPath(name) {
-    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
-        if (!directory)
-            continue;
-        const candidate = path.join(directory, name);
-        try {
-            accessSync(candidate, fsConstants.X_OK);
-            return candidate;
-        }
-        catch {
-            // Keep searching.
-        }
-    }
-    throw new Error(`could not find the "${name}" executable on PATH`);
-}
 function sanitizedCodexEnvironment() {
     return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => value !== undefined && !CODEX_BILLING_ENV_KEYS.has(key.toUpperCase())));
 }

package/dist-server/harness/route/codex-local-manifest.d.ts

@@ -9,10 +9,18 @@ export declare const CODEX_ASK_COMPONENTS: readonly ["answer_query", "generate_d
 export type CodexAskComponent = (typeof CODEX_ASK_COMPONENTS)[number];
 export declare const CODEX_ENRICH_COMPONENTS: readonly ["inspect_context", "draft_enrichment"];
 export type CodexManifestPurpose = "analysis" | "setup" | "context_enrichment";
+export declare function codexAnalysisToolArgs(component: CodexAskComponent): string[];
 export declare function buildCodexAskManifestArgs(cli: ResolvedCli, irPath: string, models: CodexManifestModels, component?: CodexAskComponent): readonly string[];
 export declare function buildCodexBootstrapManifestArgs(cli: ResolvedCli, irPath: string): readonly string[];
 export declare function buildCodexEnrichmentManifestArgs(cli: ResolvedCli, irPath: string, models: CodexManifestModels, component: (typeof CODEX_ENRICH_COMPONENTS)[number]): readonly string[];
-export declare function describeCodexAskManifest(cli: ResolvedCli, irPath: string, models: CodexManifestModels): Promise<Bundle>;
+export declare function describeCodexAskManifest(cli: ResolvedCli, irPath: string, models: CodexManifestModels, context?: CodexManifestContext): Promise<Bundle>;
+export interface CodexManifestContext {
+    readonly warbleBin: string;
+    readonly contexts: Readonly<Record<string, {
+        readonly binding: unknown;
+        readonly snapshot: unknown;
+    }>>;
+}
 /**
  * Setup is a raw/bootstrap profile, not an Ask profile. Its dispatcher has a
  * dedicated whole-profile `manifest` command that neither needs nor accepts a