@konneal/engine 0.2.136 → 0.2.138

package/workers/worker_public/src/tools.ts

@@ -17,19 +17,21 @@ export interface ToolResult {
   output: string;
 }
 
-/** 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). */
+/** The strict protocol: a line `TOOL <name> {…json…}`. Line-anchored,
+ *  case-sensitive (prose never trips it); the args are the WHOLE rest
+ *  of the line parsed as JSON — nested objects (db.find predicates)
+ *  are legal, and a malformed or unterminated object is not a 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_.]+)[ \t]*(\{.*)?$/m.exec(String(text ?? ""));
   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 ?? ""))) {
-    return null; // a malformed call (opened, never closed) is not a call
+  const rest = (m[2] ?? "").trim();
+  if (!rest) return { name: m[1].toLowerCase(), args: {} };
+  if (!rest.startsWith("{")) return null;
+  try {
+    return { name: m[1].toLowerCase(), args: JSON.parse(rest) };
+  } catch {
+    return null;
   }
-  return { name: m[1].toLowerCase(), args };
 }
 
 // ── the tool registry (OCP, the owner's 2026-10-04 direction) ────────
@@ -65,19 +67,63 @@ const certificatesSearch: ToolSpec = {
 };
 
 import { unitsGet, graphCites, docsSection, glossaryLookup, documentsFamily, licensedSection, verdictEvaluate, conditionsCheck, bibEntry, unitsLookup, unitsConvert } from "./tools-content.ts";
+import { runFind, runSchema } from "./dbtools.ts";
+
+// the data-plane grammar (dbtools.ts): the model composes typed
+// predicates over the PUBLISHED schema — no operation menus, no raw SQL
+const dbSchema: ToolSpec = {
+  name: "db.schema",
+  description:
+    "The published data map: every queryable table (the certificate register, the document registry, the citation graph, the model plane, typed units, the corpus chunks) with its columns, types, and meanings. Call this first whenever a question turns on structured data; then compose db.find.",
+  params: [{ key: "table", required: false, description: "one table's detail; omit for the whole catalog" }],
+  audiences: ["agent", "mcp"],
+  handler: async (_env, args) => {
+    const t = args?.table ? String(args.table) : undefined;
+    return runSchema(t);
+  },
+};
+
+const dbFind: ToolSpec = {
+  name: "db.find",
+  description:
+    "Query a published table with typed predicates you compose: where: [{col, op, value}] with ops eq|ne|lt|le|gt|ge|in|like|between, optional select, order_by {col, dir}, limit (≤25), group_by + agg {fn: count|sum|avg|min|max, col}. Values bind safely; identifiers validate against the schema (errors name the valid columns). Returns the matching rows or aggregate with the query echoed.",
+  params: [
+    { key: "table", required: true, description: "a published table (db.schema lists them)" },
+    { key: "where", required: false, description: "[{col, op, value}] predicates, ANDed" },
+    { key: "select", required: false, description: "columns to return; default per table" },
+    { key: "order_by", required: false, description: "{col, dir: asc|desc}" },
+    { key: "limit", required: false, description: "row cap, ≤25" },
+    { key: "agg", required: false, description: "{fn, col?} aggregate instead of rows; with group_by: [cols]" },
+  ],
+  audiences: ["agent", "mcp"],
+  handler: async (env, args) => {
+    const findArgs = {
+      table: String(args?.table ?? ""),
+      where: Array.isArray(args?.where) ? args.where : [],
+      select: Array.isArray(args?.select) ? args.select : undefined,
+      order_by: args?.order_by && typeof args.order_by === "object" ? (args.order_by as { col: string; dir?: "asc" | "desc" }) : undefined,
+      limit: args?.limit != null ? Number(args.limit) : undefined,
+      group_by: Array.isArray(args?.group_by) ? args.group_by : undefined,
+      agg: args?.agg && typeof args.agg === "object" ? (args.agg as { fn: "count" | "sum" | "avg" | "min" | "max"; col?: string }) : undefined,
+    };
+    if (!findArgs.table) return null;
+    return runFind(env, findArgs);
+  },
+};
+
+export const TOOLS_REGISTRY: ToolSpec[] = [dbSchema, dbFind, certificatesSearch, unitsGet, graphCites, docsSection, glossaryLookup, documentsFamily, licensedSection, verdictEvaluate, conditionsCheck, bibEntry, unitsLookup, unitsConvert];
 
-export const TOOLS_REGISTRY: ToolSpec[] = [certificatesSearch, unitsGet, graphCites, docsSection, glossaryLookup, documentsFamily, licensedSection, verdictEvaluate, conditionsCheck, bibEntry, unitsLookup, unitsConvert];
 
 /** 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:",
+  "You may query data before answering, by writing ONE line per call:",
   ...TOOLS_REGISTRY.filter((t) => t.audiences.includes("agent")).map((t) => {
-    const shape = `{${t.params.map((p) => `"${p.key}": "<${p.description}>"`).join(", ")}}`;
+    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.",
+  "The worker runs each call and returns the result attributed; you may issue up to three calls across the turns, one per turn, each on its own single line (compact JSON, no line breaks). Structured questions — counts, latest, filters, per-holder or per-year breakdowns over the register, document editions, model-plane requirements — start from TOOL db.schema (it lists the queryable tables and their columns), then compose TOOL db.find predicates. Each result arrives attributed: phrase it as what the tool returned, with your query visible in the answer. When you have enough, answer WITHOUT a TOOL line; if no tool helps, answer directly.",
 ].join("\n");
 
 /** Dispatch by LOOKUP — a tool name is never hard-coded at a call site.