@konneal/engine 0.2.83 → 0.2.85

package/dist/{ask-IAJDX2YY.js → ask-52JUHGUG.js}

@@ -1,6 +1,6 @@
 import {
   handleAsk
-} from "./chunk-TWK46PU2.js";
+} from "./chunk-R3KA6S3E.js";
 import "./chunk-7HWJOFTQ.js";
 import "./chunk-SPKPH54J.js";
 import "./chunk-A3QHHUN5.js";

package/dist/{chunk-TWK46PU2.js → chunk-R3KA6S3E.js}

@@ -1875,7 +1875,7 @@ function exactCacheKey(indexVersion, gen, ns, queryHash) {
 
 // workers/worker_public/src/tools.ts
 function parseToolCall(text) {
-  const m = /^TOOL\s+([a-z_]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? ""));
+  const m = /^TOOL\s+([a-z_.]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? ""));
   if (!m) return null;
   let args = {};
   if (m[2]) {
@@ -1884,22 +1884,38 @@ function parseToolCall(text) {
     } catch {
       return null;
     }
-  } else if (/^TOOL\s+[a-z_]+\s*\{/m.test(String(text ?? ""))) {
+  } else if (/^TOOL\s+[a-z_.]+\s*\{/m.test(String(text ?? ""))) {
     return null;
   }
   return { name: m[1].toLowerCase(), args };
 }
-var TOOL_DECLARATION = `You may use one tool before answering, by writing a single line:
-TOOL register_search {"query": "manufacturer and model to look up"}
-The worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known \u2014 including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.`;
+var certificatesSearch = {
+  name: "certificates.search",
+  description: "Search the certificate register (a snapshot) by holder name, model designation, or a printed certificate number. Returns the matching rows \u2014 number, holder, model, issue year, status, and document links where on file \u2014 or the exact no-match statement for the string asked.",
+  params: [{ key: "query", required: true, description: "the holder, model, or printed certificate number to look up" }],
+  audiences: ["agent", "mcp"],
+  handler: async (db, args) => {
+    const query = String(args?.query ?? "").trim().slice(0, 160);
+    if (!query) return null;
+    const { searchRegister: searchRegister2, registerNote: registerNote2, certificateLinks: certificateLinks2 } = await import("./certificates-CO7KX2S2.js");
+    const reg = await searchRegister2(db, query, true);
+    const output = reg?.rows?.length ? [registerNote2(reg.rows), certificateLinks2(reg.rows)].filter(Boolean).join("\n") : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
+    return { name: "certificates.search", query, output };
+  }
+};
+var TOOLS_REGISTRY = [certificatesSearch];
+var TOOL_DECLARATION = [
+  "You may use one tool before answering, by writing a single line:",
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("agent")).map((t) => {
+    const shape = `{${t.params.map((p) => `"${p.key}": "<${p.description}>"`).join(", ")}}`;
+    return `TOOL ${t.name} ${shape}`;
+  }),
+  "The worker runs it and returns the result attributed \u2014 phrase the tool's result as what it returned, with the searched string visible in your answer. Use a tool when the question turns on what it answers (including from a photograph). If you do not need it, answer directly without the line."
+].join("\n");
 async function runTool(db, call) {
-  if (call.name !== "register_search") return null;
-  const query = String(call.args?.query ?? "").trim().slice(0, 160);
-  if (!query) return null;
-  const { searchRegister: searchRegister2, registerNote: registerNote2 } = await import("./certificates-CO7KX2S2.js");
-  const reg = await searchRegister2(db, query, true);
-  const output = reg?.rows?.length ? registerNote2(reg.rows) : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
-  return { name: call.name, query, output };
+  const spec = TOOLS_REGISTRY.find((t) => t.name === call.name && t.audiences.includes("agent"));
+  if (!spec) return null;
+  return spec.handler(db, call.args ?? {});
 }
 function toolNote(r) {
   return `The ${r.name} tool returned, for the query "${r.query}":
@@ -2310,6 +2326,11 @@ async function handleAsk(env, ctx, req, tier, key) {
   if (await env.CACHE.get("sys:generation") === "off") {
     return err(503, "generation_disabled", "Generation is temporarily paused; search remains available.");
   }
+  const agentSteps = [];
+  const mark = (step) => {
+    agentSteps.push(step);
+    console.log(`agent-step: ${step}`);
+  };
   const service = env.INTERNAL_SERVICE;
   const fedAuth = {
     cookie: req.headers.get("cookie") ?? "",
@@ -2488,6 +2509,7 @@ async function handleAsk(env, ctx, req, tier, key) {
   let register = await searchRegister(env.DB, q.query);
   const bridgeImage = userImage ?? storedImage;
   if (bridgeImage && /certificate|certified|certification/i.test(q.query)) {
+    mark("Reading the nameplate photograph");
     const np = await extractNameplate(env.AI, MODELS.member, bridgeImage);
     if (np?.manufacturer) {
       const bridged = await searchRegister(env.DB, nameplateRegisterQuery(np, q.query), true);
@@ -2878,6 +2900,7 @@ Answer account questions from these records ONLY: name the record when you use i
   if (/certificate|certified|certification/i.test(q.query) && env.DB) {
     try {
       const imageTurn = typeof withImage === "string";
+      if (imageTurn) mark("Reading the photograph to identify the instrument");
       const probeMessages = [...messages.slice(0, -1), { role: "user", content: `${TOOL_DECLARATION}
 
 ${imageTurn ? "A photograph of the instrument is attached after this message. Transcribe the maker, model and any printed certificate number you can read FROM THE PHOTOGRAPH ITSELF, then emit the TOOL line with those tokens as the query \u2014 never invented, and never tokens taken from any register content elsewhere in the context (a register row's holder is not the plate's maker; observed live 2026-10-04)." : ""}
@@ -2892,6 +2915,7 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
       const probeText = typeof probe?.response === "string" ? probe.response : probe?.choices?.[0]?.message?.content ?? "";
       const call = parseToolCall(probeText);
       if (call) {
+        mark(`Searching the certificate register for \u201C${String(call.args?.query ?? "")}\u201D`);
         const result = await runTool(env.DB, call);
         if (result) {
           messages.push({ role: "system", content: toolNote(result) });
@@ -2926,6 +2950,12 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
           const send = (obj) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}
 
 `));
+          for (const step of agentSteps) {
+            try {
+              send({ type: "agent", step });
+            } catch {
+            }
+          }
           for (const t of pendingTools) {
             try {
               send({ type: "tool", name: t.name, query: t.query });
@@ -3085,6 +3115,7 @@ ${q.query}`.replace("\n\n\n\n", "\n\n") }];
   completionBlocks.push(...await completeFigures(env.DB, answer, [...c2ns.blocks, ...completionBlocks], used));
   if (withImage && register?.rows?.length && answer.includes(refusalAnswer())) {
     console.log("blind-answer: the register note carried rows but the answer refused \u2014 regenerating once");
+    mark("Re-answering from the register results");
     const regen = await generateOnce(env, model, [
       ...messages.slice(0, -1),
       { role: "user", content: "The photograph was attached and the register note lists actual matching certificate rows. Present those rows \u2014 number, holder, model, status, and every document link \u2014 as the answer. Do not claim that nothing was provided." },
@@ -3148,5 +3179,6 @@ export {
   bindModelNode,
   modelGroundingBlock,
   scoreJudge,
+  TOOLS_REGISTRY,
   handleAsk
 };

package/dist/tools.d.ts

@@ -7,11 +7,28 @@ export interface ToolResult {
     query: string;
     output: string;
 }
-/** The strict protocol: a line `TOOL register_search {"query": "…"}`.
+/** The strict protocol: a line `TOOL certificates.search {"query": "…"}`.
  *  Plain regex parse — no JSON mode needed, tolerant of surrounding
  *  prose (the model may talk around the call). */
 export declare function parseToolCall(text: string): ToolCall | null;
-export declare const TOOL_DECLARATION = "You may use one tool before answering, by writing a single line:\nTOOL register_search {\"query\": \"manufacturer and model to look up\"}\nThe worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known \u2014 including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.";
+export interface ToolSpec {
+    /** canonical on every surface */
+    name: string;
+    description: string;
+    params: {
+        key: string;
+        required: boolean;
+        description: string;
+    }[];
+    audiences: ("agent" | "mcp")[];
+    handler: (db: any, args: Record<string, unknown>) => Promise<ToolResult | null>;
+}
+export declare const TOOLS_REGISTRY: ToolSpec[];
+/** The agent loop's protocol declaration, GENERATED from the registry —
+ *  the model's tool vocabulary is always the registry's, never a
+ *  hand-maintained literal. */
+export declare const TOOL_DECLARATION: string;
+/** Dispatch by LOOKUP — a tool name is never hard-coded at a call site. */
 export declare function runTool(db: any, call: ToolCall): Promise<ToolResult | null>;
 /** The attributed injection: the answer model sees what the tool
  *  returned, for the string it asked — never a standing claim. */

package/dist/worker_public/src/index.js

@@ -1,4 +1,5 @@
 import {
+  TOOLS_REGISTRY,
   bindModelNode,
   checkQuoteAnchors,
   handleAsk,
@@ -6,7 +7,7 @@ import {
   modelGroundingBlock,
   scoreFaithfulness,
   scoreJudge
-} from "../../chunk-TWK46PU2.js";
+} from "../../chunk-R3KA6S3E.js";
 import {
   handleSearch
 } from "../../chunk-KO6DRI7C.js";
@@ -922,7 +923,16 @@ var TOOLS = [
       },
       required: ["query"]
     }
-  }
+  },
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("mcp")).map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: {
+      type: "object",
+      properties: Object.fromEntries(t.params.map((p) => [p.key, { type: "string", description: p.description }])),
+      required: t.params.filter((p) => p.required).map((p) => p.key)
+    }
+  }))
 ];
 function dispatch(method, params, callTool) {
   switch (method) {
@@ -959,7 +969,7 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-IAJDX2YY.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-LVUQLA3C.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-52JUHGUG.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-LVUQLA3C.js")).handleSearch(env, ctx, inner, tier, key);
     return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
   });
   if (out.ok && "accepted" in out) return new Response(null, { status: 202 });

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.83",
+  "version": "0.2.85",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/src/ask.ts

@@ -364,6 +364,16 @@ async function handleAsk(
     return err(503, "generation_disabled", "Generation is temporarily paused; search remains available.");
   }
 
+  // the agent's rounds, visible to the user as they happen: each step the
+  // assistant takes before and during the answer streams as an event (the
+  // owner's 2026-10-04 direction — the user must see the system-to-model
+  // questioning sessions, not stare at a spinner)
+  const agentSteps: string[] = [];
+  const mark = (step: string) => {
+    agentSteps.push(step);
+    console.log(`agent-step: ${step}`);
+  };
+
   // Members get federated retrieval (OIML + ISO/IEC) merged into the same
   // pipeline via the service binding; rag-public never touches the
   // internal index itself, and generation/rerank stay in ONE pipeline.
@@ -666,6 +676,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   // holder, and the photograph's own reading is authoritative over them.
   const bridgeImage = userImage ?? storedImage;
   if (bridgeImage && /certificate|certified|certification/i.test(q.query)) {
+    mark("Reading the nameplate photograph");
     const np = await extractNameplate((env as any).AI, MODELS.member, bridgeImage);
     if (np?.manufacturer) {
       const bridged = await searchRegister(env.DB, nameplateRegisterQuery(np, q.query), true);
@@ -1216,7 +1227,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   await attachFigureImages(env, messages, usedHits, q.query);
   // the agent loop (the owner's 2026-09-28 direction): ONE bounded tool
   // round, armed only where a tool can help. The model may call
-  // register_search through the strict line protocol; the worker
+  // the registry tools through the strict line protocol; the worker
   // executes it deterministically and the ATTRIBUTED result joins the
   // messages — what the tool returned, for the string it asked. The
   // invocations record into pendingTools; the stream emits them as its
@@ -1230,6 +1241,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   if (/certificate|certified|certification/i.test(q.query) && env.DB) {
     try {
       const imageTurn = typeof withImage === "string";
+      if (imageTurn) mark("Reading the photograph to identify the instrument");
       const probeMessages: any[] = [...messages.slice(0, -1), { role: "user", content: `${TOOL_DECLARATION}\n\n${imageTurn ? "A photograph of the instrument is attached after this message. Transcribe the maker, model and any printed certificate number you can read FROM THE PHOTOGRAPH ITSELF, then emit the TOOL line with those tokens as the query — never invented, and never tokens taken from any register content elsewhere in the context (a register row's holder is not the plate's maker; observed live 2026-10-04)." : ""}\n\n${q.query}`.replace("\n\n\n\n", "\n\n") }];
       if (imageTurn) probeMessages.push({ role: "user", content: [{ type: "image_url", image_url: { url: withImage } }] });
       const probe = await (env as any).AI.run(model, {
@@ -1240,6 +1252,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       const probeText = typeof probe?.response === "string" ? probe.response : probe?.choices?.[0]?.message?.content ?? "";
       const call = parseToolCall(probeText);
       if (call) {
+        mark(`Searching the certificate register for “${String(call.args?.query ?? "")}”`);
         const result = await runTool(env.DB, call);
         if (result) {
           messages.push({ role: "system", content: toolNote(result) });
@@ -1292,8 +1305,12 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
       const sse = new ReadableStream({
         async start(controller) {
           const send = (obj: unknown) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(obj)}\n\n`));
-          // the reading arrives first: the interpretation that steered
-          // retrieval, before a single token of the answer
+          // the agent trace arrives first: every questioning round the
+          // assistant ran — the photograph read, the register search, any
+          // re-answer — so the user watched what happened, not a spinner
+          for (const step of agentSteps) {
+            try { send({ type: "agent", step }); } catch { /* never block the answer */ }
+          }
           for (const t of pendingTools) {
             try { send({ type: "tool", name: t.name, query: t.query }); } catch { /* never block the answer */ }
           }
@@ -1522,6 +1539,7 @@ let convEntities: Array<{ entity: string; kind: string }> = [];
   // that exact signature; the retry carries a sterner ground instruction.
   if (withImage && register?.rows?.length && answer.includes(refusalAnswer())) {
     console.log("blind-answer: the register note carried rows but the answer refused — regenerating once");
+    mark("Re-answering from the register results");
     const regen = await generateOnce(env, model, [
       ...messages.slice(0, -1),
       { role: "user", content: "The photograph was attached and the register note lists actual matching certificate rows. Present those rows — number, holder, model, status, and every document link — as the answer. Do not claim that nothing was provided." },

package/workers/worker_public/src/mcp-proto.ts

@@ -1,6 +1,7 @@
 // The MCP protocol surface (JSON-RPC 2.0, streamable HTTP 2025-06-18),
 // dependency-free so plain node can load it for unit tests — the
 // route adapter (mcp.ts) owns the handler wiring.
+import { TOOLS_REGISTRY } from "./tools.ts";
 export const PROTOCOL_VERSION = "2025-06-18";
 
 export interface McpTool {
@@ -9,6 +10,8 @@ export interface McpTool {
   inputSchema: { type: "object"; properties: Record<string, unknown>; required: string[] };
 }
 
+// the registry's MCP-audience tools are GENERATED here (OCP: adding a
+// tool registers it; this list is never hand-extended for them)
 export const TOOLS: McpTool[] = [
   {
     name: "ask",
@@ -34,6 +37,17 @@ export const TOOLS: McpTool[] = [
       required: ["query"],
     },
   },
+  ...TOOLS_REGISTRY
+    .filter((t) => t.audiences.includes("mcp"))
+    .map((t): McpTool => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: {
+        type: "object",
+        properties: Object.fromEntries(t.params.map((p) => [p.key, { type: "string", description: p.description }])),
+        required: t.params.filter((p) => p.required).map((p) => p.key),
+      },
+    })),
 ];
 
 export type McpResult =

package/workers/worker_public/src/tools.ts

@@ -17,35 +17,72 @@ export interface ToolResult {
   output: string;
 }
 
-/** The strict protocol: a line `TOOL register_search {"query": "…"}`.
+/** The strict protocol: a line `TOOL certificates.search {"query": "…"}`.
  *  Plain regex parse — no JSON mode needed, tolerant of surrounding
  *  prose (the model may talk around the call). */
 export function parseToolCall(text: string): ToolCall | null {
-  const m = /^TOOL\s+([a-z_]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? "")); // line-anchored, case-sensitive: prose never trips it
+  const m = /^TOOL\s+([a-z_.]+)\s*(\{[^\n}]*\})?/m.exec(String(text ?? "")); // line-anchored, case-sensitive: prose never trips it
   if (!m) return null;
   let args: Record<string, unknown> = {};
   if (m[2]) {
     try { args = JSON.parse(m[2]); } catch { return null; }
-  } else if (/^TOOL\s+[a-z_]+\s*\{/m.test(String(text ?? ""))) {
+  } else if (/^TOOL\s+[a-z_.]+\s*\{/m.test(String(text ?? ""))) {
     return null; // a malformed call (opened, never closed) is not a call
   }
   return { name: m[1].toLowerCase(), args };
 }
 
-export const TOOL_DECLARATION = `You may use one tool before answering, by writing a single line:
-TOOL register_search {"query": "manufacturer and model to look up"}
-The worker runs it against the certificate register (a snapshot) and returns the matching rows, or the exact no-match statement for the string you asked. Use it when the question turns on certification standing and the holder is known — including from a photograph. Then answer, phrasing the tool's result as what it returned (the searched string stays visible in your answer). If you do not need the tool, answer directly without the line.`;
+// ── the tool registry (OCP, the owner's 2026-10-04 direction) ────────
+// ONE declared table is the single source of the tool surface: the agent
+// loop's declaration is GENERATED from it, runTool dispatches by lookup,
+// and the MCP server's tools/list is generated from the same entries.
+// Adding a tool = adding one registration; no call site is edited.
+export interface ToolSpec {
+  /** canonical on every surface */
+  name: string;
+  description: string;
+  params: { key: string; required: boolean; description: string }[];
+  audiences: ("agent" | "mcp")[];
+  handler: (db: any, args: Record<string, unknown>) => Promise<ToolResult | null>;
+}
+
+const certificatesSearch: ToolSpec = {
+  name: "certificates.search",
+  description:
+    "Search the certificate register (a snapshot) by holder name, model designation, or a printed certificate number. Returns the matching rows — number, holder, model, issue year, status, and document links where on file — or the exact no-match statement for the string asked.",
+  params: [{ key: "query", required: true, description: "the holder, model, or printed certificate number to look up" }],
+  audiences: ["agent", "mcp"],
+  handler: async (db, args) => {
+    const query = String(args?.query ?? "").trim().slice(0, 160);
+    if (!query) return null;
+    const { searchRegister, registerNote, certificateLinks } = await import("./certificates");
+    const reg = await searchRegister(db, query, true); // the tool decided — no shaping gate
+    const output = reg?.rows?.length
+      ? [registerNote(reg.rows), certificateLinks(reg.rows)].filter(Boolean).join("\n")
+      : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
+    return { name: "certificates.search", query, output };
+  },
+};
+
+export const TOOLS_REGISTRY: ToolSpec[] = [certificatesSearch];
+
+/** The agent loop's protocol declaration, GENERATED from the registry —
+ *  the model's tool vocabulary is always the registry's, never a
+ *  hand-maintained literal. */
+export const TOOL_DECLARATION = [
+  "You may use one tool before answering, by writing a single line:",
+  ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("agent")).map((t) => {
+    const shape = `{${t.params.map((p) => `"${p.key}": "<${p.description}>"`).join(", ")}}`;
+    return `TOOL ${t.name} ${shape}`;
+  }),
+  "The worker runs it and returns the result attributed — phrase the tool's result as what it returned, with the searched string visible in your answer. Use a tool when the question turns on what it answers (including from a photograph). If you do not need it, answer directly without the line.",
+].join("\n");
 
+/** Dispatch by LOOKUP — a tool name is never hard-coded at a call site. */
 export async function runTool(db: any, call: ToolCall): Promise<ToolResult | null> {
-  if (call.name !== "register_search") return null;
-  const query = String(call.args?.query ?? "").trim().slice(0, 160);
-  if (!query) return null;
-  const { searchRegister, registerNote } = await import("./certificates");
-  const reg = await searchRegister(db, query, true); // the tool decided — no shaping gate
-  const output = reg?.rows?.length
-    ? registerNote(reg.rows)
-    : `No certificate was found for "${query}" in the certificates database (the register snapshot). State this as the search's result, with the searched string visible.`;
-  return { name: call.name, query, output };
+  const spec = TOOLS_REGISTRY.find((t) => t.name === call.name && t.audiences.includes("agent"));
+  if (!spec) return null;
+  return spec.handler(db, call.args ?? {});
 }
 
 /** The attributed injection: the answer model sees what the tool