@polycode-projects/the-mechanical-code-talker 4.0.1 → 4.1.1

package/src/tools/handlers/tmct-ask.mjs

@@ -1,14 +1,19 @@
 // tmct_ask — a plain-English structural question answered from the graph in one
 // mechanical, zero-model-call round-trip. See src/domain/ask.mjs.
 
-import { ToolError } from "../../adapters/config.mjs";
 import { ask } from "../../domain/ask.mjs";
-import { requiredArg } from "./kit.mjs";
+import { requiredArg, toolResult } from "./kit.mjs";
+
+/** The flat string a dispatchTool caller gets carries the envelope in-band, behind this
+ *  delimiter, because a string is all that entry can hand back. Exported so the surfaces
+ *  that still read that string split it on the one constant rather than their own copy. */
+export const ASK_ENVELOPE_DELIM = "\n\n---tmct_ask---\n";
 
 export function tmct_ask(args, { graph }) {
   const { content, tmct_ask: envelope } = ask(graph, requiredArg(args, "query"));
-  // Every dispatchTool caller (the chat surface, the CLI fallback) expects a plain string —
-  // append the structured envelope as a delimited, machine-parseable block rather than
-  // changing that shared contract for one tool.
-  return `${content}\n\n---tmct_ask---\n${JSON.stringify(envelope, null, 2)}`;
+  return toolResult({
+    content,
+    data: envelope,
+    text: `${content}${ASK_ENVELOPE_DELIM}${JSON.stringify(envelope, null, 2)}`,
+  });
 }

package/src/tools/handlers/tmct-ingest.mjs

@@ -16,6 +16,7 @@
 
 import { dirname } from "node:path";
 import { openConfiguredMemoryBackend } from "../../adapters/memory/core.mjs";
+import { toolResult } from "./kit.mjs";
 
 export async function tmct_ingest(args, { config, ingest }) {
   const text = String(args?.text ?? "");
@@ -31,7 +32,10 @@ export async function tmct_ingest(args, { config, ingest }) {
     const header = `${result.sentences} sentence(s), ${result.recognized} recognized`
       + (optimistic ? `, ${result.optimistic.length} optimistic candidate(s)` : "")
       + `, ${result.skipped} skipped — ${grounded} fact(s) grounded.`;
-    return grounded ? `${header}\n${result.canonical.join("\n")}` : header;
+    return toolResult({
+      content: grounded ? `${header}\n${result.canonical.join("\n")}` : header,
+      data: { ...result, grounded },
+    });
   } finally {
     await close();
   }

package/src/tools/handlers/tmct-related.mjs

@@ -6,11 +6,11 @@
 import { ToolError } from "../../adapters/config.mjs";
 import { relatedForTerm } from "../../domain/skos-view.mjs";
 import { memoryFactRows } from "../memory-fallthrough.mjs";
-import { requiredArg } from "./kit.mjs";
+import { requiredArg, toolResult } from "./kit.mjs";
 
-export async function tmct_related(args, { config }) {
+export async function tmct_related(args, { config, memoryBackend = null }) {
   const term = requiredArg(args, "term");
-  const hit = relatedForTerm(await memoryFactRows(config), term);
+  const hit = relatedForTerm(await memoryFactRows(config, memoryBackend), term);
   if (!hit) {
     throw new ToolError(
       `no synonym or related facts for "${term}" in the memory graph. ` +
@@ -21,7 +21,7 @@ export async function tmct_related(args, { config }) {
   if (hit.synonyms.length) lines.push(`synonyms (skos:altLabel): ${hit.synonyms.join(", ")}`);
   if (hit.related.length) lines.push(`related (skos:related): ${hit.related.map((c) => c.prefLabel).join(", ")}`);
   lines.push("(from the memory graph's mgx:synonym / mgx:relatedTo / mgx:similarTo facts)");
-  return lines.join("\n");
+  return toolResult({ content: lines.join("\n"), data: hit });
 }
 
 // The memory graph is this tool's only source — it answers with or without a

package/src/tools/handlers/tmct-sprite.mjs

@@ -0,0 +1,147 @@
+// tmct_sprite — the sprite markup for a class, resolved through the memory
+// graph's own rdfs:subClassOf taxonomy, with the expression and size the caller
+// asked for and the chain the resolver walked to find it.
+//
+// The resolution itself is sprite-request.mjs's pure core (the same function the
+// spider-and-fly page splices into its script), so this module only does the
+// three things a tool has to: read the real state, hold the miss wall, and say
+// the answer twice — once as a sentence, once as data.
+//
+// The MISS WALL, since the resolver underneath never refuses (it falls through
+// to the root sprite by design, which is right for a page painting a board and
+// wrong for a question):
+//   - an expression outside sprite-expressions.mjs's palette, or a size outside
+//     sprite-size.mjs's scale table, is refused before anything is resolved;
+//   - a class no term of whose ancestor chain carries a sprite is refused rather
+//     than answered with the generic root sprite;
+//   - an expression the resolved template does not actually take is refused
+//     rather than silently dropped from an otherwise plausible answer.
+//
+// WHICH SENSE OF "LARGE" `size` CARRIES: the taught size PROPERTY, resolved to a
+// numeric render scale (sprite-size.mjs's `sizeScaleFor` — small 0.8, large 1.3,
+// long 1.2, tall 1.25), not the template TIER. Two reasons. It is a fact-shaped
+// question: `mgx:hasProperty large` is a real predicate the memory store can
+// carry and the resolver already consults, so the tool's `memoryFacts`
+// precondition and its resolution chain stay one mechanism, where a tier is the
+// caller's render target rather than anything true of the thing being drawn.
+// And the tier a request could name is a packaging accident: data/sprites-large/
+// is excluded from the npm package, so a tier-selecting `size` would answer
+// differently depending on how tmct was installed, while a scale multiplier
+// answers the same everywhere. The tier in play is still REPORTED in `data.tier`
+// — observed, never asked for.
+
+import { ToolError } from "../../adapters/config.mjs";
+import { classAncestorChain, SPRITE_REGISTRY } from "../../domain/sprite-map.mjs";
+import { resolveSpriteAsset } from "../../domain/sprite-templates.mjs";
+import { EXPRESSION_PALETTE } from "../../domain/sprite-expressions.mjs";
+import { sizeScaleFor } from "../../domain/sprite-size.mjs";
+import { resolveSpriteRequest } from "../../domain/sprite-request.mjs";
+import { ICON_TIER_NAME, SPRITE_TIER_NAME } from "../../domain/sprite-facts.mjs";
+import { readSpriteTemplateFiles } from "../../adapters/corpus/sprite-template-files.mjs";
+import { readSpriteLargeTemplateFiles } from "../../adapters/corpus/sprite-large-template-files.mjs";
+import { memoryFactRows } from "../memory-fallthrough.mjs";
+import { requiredArg, toolResult } from "./kit.mjs";
+
+/** The property predicate sprite-size.mjs reads a size word off. Used to PROBE
+ *  its own closed scale table rather than restate it: a word is a size word
+ *  exactly when it moves the scale, so a word that module gains is a word this
+ *  tool gains. */
+const SIZE_FACT_PREDICATE = "mgx:hasProperty";
+
+/** The expression words a sprite can be asked for — sprite-expressions.mjs's own
+ *  palette, sorted, never a hand-kept copy. */
+export const spriteExpressionWords = () => Object.keys(EXPRESSION_PALETTE).sort();
+
+/** True iff `word` is a size sprite-size.mjs's scale table recognises. */
+export const isSpriteSizeWord = (word) =>
+  Boolean(word) && sizeScaleFor([{ predicate: SIZE_FACT_PREDICATE, object: String(word) }]) !== 1;
+
+/** The template set to resolve against: the sprite tier when this installation
+ *  can read it (a git checkout, or the demo site's own build), the icon tier
+ *  otherwise. Reported alongside the answer so a caller never has to guess which
+ *  one it got. */
+function templateTier() {
+  const large = readSpriteLargeTemplateFiles();
+  if (large.length) return { templates: large, tier: SPRITE_TIER_NAME };
+  return { templates: readSpriteTemplateFiles(), tier: ICON_TIER_NAME };
+}
+
+function chainSentence(chain) {
+  return chain.map((step) => step.term).join(" -> ");
+}
+
+export async function tmct_sprite(args, { config, memoryBackend = null }) {
+  const className = requiredArg(args, "class").toLowerCase();
+  const expression = String(args?.expression || "").trim().toLowerCase();
+  const size = String(args?.size || "").trim().toLowerCase();
+
+  if (expression && !Object.hasOwn(EXPRESSION_PALETTE, expression)) {
+    throw new ToolError(
+      `"${expression}" is not a sprite expression. The palette holds: ${spriteExpressionWords().join(", ")}.`,
+    );
+  }
+  if (size && !isSpriteSizeWord(size)) {
+    throw new ToolError(
+      `"${size}" is not a size the sprite scale recognises — it reads a taught mgx:hasProperty size word off the individual, and has no entry for this one.`,
+    );
+  }
+
+  const { templates, tier } = templateTier();
+  const factRows = await memoryFactRows(config, memoryBackend);
+  const resolution = resolveSpriteRequest({ class: className, expression, size }, {
+    factRows,
+    templates,
+    spriteRegistry: SPRITE_REGISTRY,
+    resolveSpriteAsset,
+    classAncestorChain,
+    sizeScaleFor,
+    expressionPalette: EXPRESSION_PALETTE,
+  });
+
+  if (!resolution.svg || resolution.fellBackToRoot) {
+    throw new ToolError(
+      `no sprite for "${className}" — neither it nor any rdfs:subClassOf ancestor the memory graph knows ` +
+        `(${chainSentence(resolution.chain)}) carries one in the ${tier}. Teach the class its superclass first, or ask for a class the catalog draws.`,
+    );
+  }
+  if (expression && !resolution.expressionApplied) {
+    throw new ToolError(
+      `the ${tier} draws "${className}" (matched at "${resolution.matched.term}") but that template takes no expression, ` +
+        `so "${expression}" would not show. Ask for the plain sprite, or a class whose template carries an emotion parameter.`,
+    );
+  }
+
+  const asked = [expression ? `expression ${expression}` : "", size ? `size ${size}` : ""].filter(Boolean);
+  const lines = [
+    `sprite for "${className}"${asked.length ? ` (${asked.join(", ")})` : ""}, from the ${tier}`,
+    resolution.matched.hops === 0
+      ? `matched at "${resolution.matched.term}", the class itself, via its own ${resolution.matched.via}`
+      : `matched at "${resolution.matched.term}", ${resolution.matched.hops} hop(s) up the ancestor chain, via its ${resolution.matched.via}`,
+    `ancestor chain walked: ${chainSentence(resolution.chain)}`,
+  ];
+  if (resolution.matched.template?.parameters.length) {
+    lines.push(`template parameters: ${resolution.matched.template.parameters.join(", ")}`);
+  }
+  if (size) lines.push(`render scale: ${resolution.scale} (from the taught mgx:hasProperty "${size}")`);
+  lines.push(`${resolution.svg.length} characters of SVG markup`);
+
+  return toolResult({
+    content: lines.join("\n"),
+    data: {
+      class: resolution.class,
+      expression: resolution.expression,
+      size: resolution.size,
+      tier,
+      scale: resolution.scale,
+      svg: resolution.svg,
+      chain: resolution.chain,
+      matched: resolution.matched,
+      expressionApplied: resolution.expressionApplied,
+    },
+  });
+}
+
+// The sprite catalog and the conversational-memory taxonomy are this tool's only
+// sources — it answers with or without a code-map graph, so the shared code-graph
+// load (which refuses an empty graph) must not gate it.
+tmct_sprite.ownsGraphLoad = true;

package/src/tools/memory-fallthrough.mjs

@@ -17,9 +17,16 @@ const MEMORY_LIST_CAP = 40;
  *  the dir that CONTAINS .tmct/ (graphFile = <repo>/.tmct/graph.json). The read goes through
  *  the repo's CONFIGURED memory backend — the same store chat's taught facts land in — opened
  *  fresh per call and closed before returning, never the retired flat-file store off a raw
- *  repo path. */
-export async function memoryFactRows(config) {
+ *  repo path.
+ *
+ *  `memoryBackend` is dispatchTool's seam for a caller that already holds an open store
+ *  handle (a chat session's own `memoryDir`). When it is supplied the read goes straight to
+ *  that handle and the caller keeps ownership of closing it. That is the only route to the
+ *  store for a session whose store was never derived from a config at all — a browser page's
+ *  in-memory one, where `config` is null and deriving a backend would find nothing. */
+export async function memoryFactRows(config, memoryBackend = null) {
   try {
+    if (memoryBackend) return readFactRows(await loadMemory(memoryBackend));
     const { dir, close } = await openConfiguredMemoryBackend(dirname(dirname(config.graphFile)));
     try {
       return readFactRows(await loadMemory(dir));

package/src/tools/server.mjs

@@ -9,6 +9,10 @@
 // typed service object (the Repository Interface) and hands both to the handler.
 // Each tool answers one question in ONE compact call so the caller need not
 // Read/Grep. Errors reach the caller as clean tool errors — message only, never a stack.
+//
+// Two entries, one dispatch: dispatchTool hands back the caller-facing string, and
+// dispatchToolStructured hands back { content, data } for a caller that wants the
+// answer's structure rather than its sentence (a page rendering rows, the router).
 
 import { readFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -19,6 +23,7 @@ import { ask } from "../domain/ask.mjs";
 import { createGraphService } from "../adapters/providers/graph-service.mjs";
 import { loadGraph } from "./graph-load.mjs";
 import { HANDLERS } from "./handlers/index.mjs";
+import { isToolResult } from "./handlers/kit.mjs";
 import { setDefaultNlpAdapter } from "../domain/interpret/nlp-registry.mjs";
 import { setConstructionBanks } from "../domain/interpret/strategies/constructions.mjs";
 import { nlpAdapter } from "../adapters/ask-nlp.mjs";
@@ -32,6 +37,7 @@ setConstructionBanks(readConstructionFiles);
 
 export { loadGraph } from "./graph-load.mjs";
 export { buildContextBundle } from "./handlers/tmct-context.mjs";
+export { ASK_ENVELOPE_DELIM } from "./handlers/tmct-ask.mjs";
 
 // Tiered tool surface: the hot tools carry full descriptions/schemas in this
 // catalog; every COLD tool (describe/members/impact/history/…) is still served
@@ -44,7 +50,7 @@ export const TOOLS = HOT_TOOLS.map(({ name, agentDescription, inputSchema }) =>
   inputSchema,
 }));
 
-export async function dispatchTool(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null } = {}) {
+async function runHandler(name, args, { config, source = defaultSource, tel = null, ingest = null, memoryBackend = null, graph: suppliedGraph = null } = {}) {
   // Reject an unknown tool BEFORE touching the graph — an unknown name never
   // triggers a load. hasOwn, so an inherited name ("constructor", "toString")
   // is unknown rather than a callable found on the prototype chain.
@@ -58,12 +64,37 @@ export async function dispatchTool(name, args, { config, source = defaultSource,
   // conversational memory store (tmct_export) prefers it over re-deriving a
   // backend from config when one is supplied; every other caller leaves it null
   // and gets today's re-derive-from-config behaviour unchanged.
-  if (handle.ownsGraphLoad) return handle(args, { config, source, tel, ingest, memoryBackend });
-  const graph = await loadGraph(config, source);
+  if (handle.ownsGraphLoad) return handle(args, { config, source, tel, ingest, memoryBackend, graph: suppliedGraph });
+  // `graph` is the third seam of the same kind: a caller that ALREADY holds a
+  // parsed graph hands it over instead of making the tool layer load one. A
+  // browser session is the case that needs it — its graph is built in memory
+  // (a seed payload, or a live board projected through worldRelationGraphPayload)
+  // and there is no config or file behind it to load from.
+  const graph = suppliedGraph || await loadGraph(config, source);
   // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json). Passed to
   // createGraphService so svc.snippet()/svc.context() are usable directly, and on to the
-  // handlers that do their own safe source reads.
-  const repoRoot = dirname(dirname(config.graphFile));
-  const svc = createGraphService(graph, { sourceAccess: true, repoRoot, readFile, tel, ask });
+  // handlers that do their own safe source reads. A supplied graph has no repo on
+  // disk behind it, so those reads are off rather than pointed at a path that
+  // isn't there.
+  const repoRoot = config?.graphFile ? dirname(dirname(config.graphFile)) : null;
+  const svc = createGraphService(graph, { sourceAccess: Boolean(repoRoot), repoRoot, readFile, tel, ask });
   return handle(args, { graph, svc, config, repoRoot, memoryBackend });
 }
+
+/** The caller-facing string for one tool call. A handler that returns a structured
+ *  result is flattened to its `text` here, so every existing string caller (the chat
+ *  surface, the CLI `cli <tool>` route, the HTTP shim) is unaffected by a handler
+ *  gaining structure. */
+export async function dispatchTool(name, args, ctx = {}) {
+  const out = await runHandler(name, args, ctx);
+  return isToolResult(out) ? out.text : out;
+}
+
+/** The same call, answered as `{ content, data }`: `content` is the prose, `data` the
+ *  render-ready structure the handler already computed on its way to it. `data` is
+ *  undefined for a tool whose answer is prose and nothing else, which is most of the
+ *  cold set — an absent `data` is a real answer, not a failure. */
+export async function dispatchToolStructured(name, args, ctx = {}) {
+  const out = await runHandler(name, args, ctx);
+  return isToolResult(out) ? { content: out.content, data: out.data } : { content: out, data: undefined };
+}