@polycode-projects/the-mechanical-code-talker 4.0.0 → 4.1.0

package/src/surfaces/web/turn-session.mjs

@@ -0,0 +1,120 @@
+// turn-session.mjs — the turn-dispatch wrapper nine near-identical browser
+// sessions each hand-rolled (chat-browser-entry.mjs, code-explorer-browser-
+// entry.mjs, ledger-browser-entry.mjs, adventure-browser-entry.mjs, spider-
+// fly-browser-entry.mjs, plan-browser-entry.mjs, research-browser-entry.mjs,
+// mud-browser-entry.mjs, sprites-browser-entry.mjs): a closure over
+// focus/last/planState/researchState, a `try { runTurn(...) } catch` that
+// turns a throw into a safe answer instead of ending the session (the page
+// has no other chance to show that turn's reply), the post-call state
+// capture, and a return shape covering every field one caller or another
+// reads back.
+//
+// The nine differ in what they hand `runTurn` beyond the common core
+// (`uiContext`, `synthesisBudget`, `gameConfig`, `researchConfig`,
+// `actingSubject`, a per-character `sessionId`...) and in what they do with a
+// turn's result besides the standard focus/last/planState/researchState fold
+// (sync an externally-held plan holder, grow a visited-rooms set, bump a
+// per-character turn tally). `buildExtraOptions`/`captureExtraState` below
+// are exactly those two seams — everything else is common enough to live
+// here once.
+//
+// The catch fallback text converges on the FULLEST of the nine: several
+// callers had already drifted to a shorter one (mud-browser-entry.mjs drops
+// "or /help"; research-browser-entry.mjs drops "or /help" AND "answering
+// that") — proof, not just a risk, that duplicating this string invites
+// exactly this drift.
+import { runTurn as defaultRunTurn } from "../../services/chat.mjs";
+
+function turnErrorFallback(message) {
+  return `Something went wrong answering that (${message}). Try rephrasing, or /help.`;
+}
+
+/**
+ * `createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint,
+ * buildExtraOptions, captureExtraState })` — a live turn-dispatch session
+ * over the real engine (`runTurn`), threading focus/last/planState/
+ * researchState across calls the way every browser chat dock does.
+ *
+ * `vocabHint` is the session-lifetime hint every caller computes once at
+ * creation (a fixed string, or `vocabExampleHint(vocabSeeded)`'s result) —
+ * never recomputed per turn.
+ *
+ * `buildExtraOptions(state, callArgs)` (optional) returns extra `runTurn`
+ * options to merge OVER the defaults below — anything a specific page needs
+ * (`uiContext: "browser"`, `synthesisBudget`, `gameConfig`, `researchConfig`,
+ * a per-character `actingSubject`/`sessionId`, or a `planState` read from an
+ * external holder instead of this closure's own). `state` is
+ * `{ focus, last, planState, researchState }` as this turn is about to run;
+ * `callArgs` is whatever extra argument `turn(line, callArgs)` was given
+ * (plan-browser-entry.mjs's own per-call `{ maxDepth }` override, for one).
+ *
+ * `captureExtraState(result, state, callArgs)` (optional, may be async) runs
+ * once after a SUCCESSFUL turn, with `state` already folded forward
+ * (focus/last/planState/researchState updated) — the caller's own chance to
+ * do further bookkeeping (sync an external plan holder, reload memory to
+ * grow a visited-rooms set, bump a turn tally). Never runs on a throw: none
+ * of the nine originals touch their own state when `runTurn` itself failed.
+ *
+ * Returns `{ memoryDir, sessionId, turn, focus, last, planState,
+ * setPlanState, researchState, setResearchState }`. `turn(line, callArgs)`
+ * resolves to `{ answer, end, record, plan, research }` — the union of every
+ * field any of the nine originals reads; a caller ignores what it doesn't
+ * need. `research` is passed through undefined/null/a queue snapshot exactly
+ * as `runTurn` returned it (a caller may distinguish "not a research turn"
+ * from "a research turn that just ended").
+ *
+ * `runTurn` (default: the real engine) is injectable, purely so a test can
+ * force the catch path deterministically without needing an input that
+ * happens to make the real, deliberately crash-resistant engine throw.
+ */
+export function createTurnSession({
+  memoryDir, graph, lexicon, sessionId, vocabHint = "",
+  buildExtraOptions = () => ({}),
+  captureExtraState = async () => {},
+  runTurn = defaultRunTurn,
+} = {}) {
+  let focus = null;
+  let last = null;
+  let planState = null;
+  let researchState = null;
+
+  async function turn(line, callArgs) {
+    const before = { focus, last, planState, researchState };
+    const extra = buildExtraOptions(before, callArgs) || {};
+    let result;
+    try {
+      result = await runTurn(line, {
+        config: null, source: null, graph, focus, last, memoryDir, sessionId,
+        env: {}, lexicon, vocabHint, planState, researchState,
+        ...extra,
+      });
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return { answer: turnErrorFallback(message), end: false, record: null, plan: null, research: null };
+    }
+    focus = result.focus;
+    last = result.last;
+    if ("planState" in result) planState = result.planState;
+    if ("researchState" in result) researchState = result.researchState;
+    await captureExtraState(result, { focus, last, planState, researchState }, callArgs);
+    return {
+      answer: result.answer,
+      end: Boolean(result.end),
+      record: result.record ?? null,
+      plan: result.plan ?? null,
+      research: result.research,
+    };
+  }
+
+  return {
+    memoryDir,
+    sessionId,
+    get focus() { return focus; },
+    get last() { return last; },
+    get planState() { return planState; },
+    setPlanState(next) { planState = next; },
+    get researchState() { return researchState; },
+    setResearchState(next) { researchState = next; },
+    turn,
+  };
+}

package/src/tools/definitions.mjs

@@ -20,12 +20,19 @@
 // restated here, so a verb the parser learns is a verb the documentation gains.
 
 import { RELATIONS, WHERE_MARKERS } from "../domain/ask-vocab.mjs";
+import { EXPRESSION_PALETTE } from "../domain/sprite-expressions.mjs";
 
 /** The relation kinds tmct_ask traverses, each with the opening verbs a question can
  *  use for it. Read from the parser's RELATIONS table — never a hand-kept copy. */
 export const askLexicon = () =>
   Object.entries(RELATIONS).map(([kind, { verbs }]) => ({ kind, verbs: verbs.slice(0, 4) }));
 
+/** The expression words tmct_sprite's schema offers. Read from the face-fragment
+ *  palette sprite-expressions.mjs already ships — the same derivation askLexicon
+ *  does for the ask verbs, so an expression the palette gains is an expression
+ *  the schema gains. */
+export const spriteExpressionEnum = () => Object.keys(EXPRESSION_PALETTE).sort();
+
 const symbolArg = (description) => ({
   type: "object",
   required: ["symbol"],
@@ -193,6 +200,29 @@ export const TOOL_DEFINITIONS = Object.freeze([
     },
     example: { term: "sofa" },
   },
+  {
+    name: "tmct_sprite",
+    tier: "cold",
+    summary:
+      "The sprite markup for a class, resolved up the taught rdfs:subClassOf chain — with the expression and size asked for, and the ancestor chain the resolver walked to find it.",
+    inputSchema: {
+      type: "object",
+      required: ["class"],
+      properties: {
+        class: { type: "string", description: "The class to draw, e.g. spider. Resolved through the memory graph's own rdfs:subClassOf taxonomy." },
+        expression: {
+          type: "string",
+          enum: spriteExpressionEnum(),
+          description: "The face the sprite wears, as an mgx:feels value. A class whose template takes no expression parameter misses rather than dropping it.",
+        },
+        size: {
+          type: "string",
+          description: "A taught size property word (mgx:hasProperty), resolved to a numeric render SCALE — the size of the thing drawn, not a choice of template tier.",
+        },
+      },
+    },
+    example: { class: "spider", expression: "happy", size: "large" },
+  },
   {
     name: "tmct_architecture",
     tier: "cold",

package/src/tools/handlers/index.mjs

@@ -1,9 +1,10 @@
 // The tool-name → handler registry dispatchTool maps over. One module per tool, so a
 // tool's behaviour has exactly one home and this file only wires names to it.
 //
-// A handler takes (args, ctx) and returns the caller-facing string. ctx carries the
-// already-loaded { graph, svc, config, repoRoot }. A handler marked `ownsGraphLoad`
-// gets { config, source, tel } instead and loads whatever it needs itself.
+// A handler takes (args, ctx) and returns the caller-facing string, or kit.mjs's
+// toolResult({ content, data }) when it already holds the structured form of what that
+// string says. ctx carries the already-loaded { graph, svc, config, repoRoot }. A handler
+// marked `ownsGraphLoad` gets { config, source, tel } instead and loads what it needs.
 
 import { tmct_context } from "./tmct-context.mjs";
 import { tmct_context_more } from "./tmct-context-more.mjs";
@@ -15,6 +16,7 @@ import { tmct_search } from "./tmct-search.mjs";
 import { tmct_members } from "./tmct-members.mjs";
 import { tmct_subclasses } from "./tmct-subclasses.mjs";
 import { tmct_related } from "./tmct-related.mjs";
+import { tmct_sprite } from "./tmct-sprite.mjs";
 import { tmct_architecture } from "./tmct-architecture.mjs";
 import { tmct_exports } from "./tmct-exports.mjs";
 import { tmct_untested } from "./tmct-untested.mjs";
@@ -42,6 +44,7 @@ export const HANDLERS = Object.freeze({
   tmct_members,
   tmct_subclasses,
   tmct_related,
+  tmct_sprite,
   tmct_architecture,
   tmct_exports,
   tmct_untested,

package/src/tools/handlers/kit.mjs

@@ -1,11 +1,28 @@
-// What every per-tool handler module shares: the argument contract, the resolve-or-miss
-// contract, and the one shape most cold tools have (take a symbol, resolve it, render it).
+// What every per-tool handler module shares: the argument contract, the result contract,
+// the resolve-or-miss contract, and the one shape most cold tools have (take a symbol,
+// resolve it, render it).
 
 import { ToolError } from "../../adapters/config.mjs";
 import { resolveSymbol } from "../../domain/codegraph.mjs";
 
 export const SNIPPET_MAX_LINES = 200;
 
+/** A handler's answer when it already holds the structured form of what its prose says.
+ *  `content` is the prose. `data` is that structure, handed to dispatchToolStructured
+ *  callers as-is so a page renders it instead of parsing the sentence back apart.
+ *  `text` is what the string-only callers (dispatchTool, the CLI `cli <tool>` route)
+ *  receive; it defaults to `content`, and a tool sets it only where its flat string
+ *  already carried the structure in-band. A handler with nothing structured to add
+ *  keeps returning a bare string, and `data` is absent for it. */
+export function toolResult({ content, data, text = null }) {
+  return { content, data, text: text ?? content };
+}
+
+/** A handler may return either shape, so both dispatch paths have to tell them apart. */
+export const isToolResult = (value) =>
+  !!value && typeof value === "object"
+  && typeof value.content === "string" && typeof value.text === "string";
+
 /** A required string argument, trimmed. Missing or blank raises "<key> is required". */
 export function requiredArg(args, key) {
   const value = String(args?.[key] || "").trim();

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 } = {}) {
   // 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.
@@ -67,3 +73,21 @@ export async function dispatchTool(name, args, { config, source = defaultSource,
   const svc = createGraphService(graph, { sourceAccess: true, 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 };
+}