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

package/src/surfaces/web/spider-fly-browser-entry.mjs

@@ -43,14 +43,19 @@
 // spider-fly.mjs's own header comment confirms grid movement never reads
 // them back (hand-written pathfinding over has-exit-* facts, not the taught
 // action-rule DSL), so nothing here depends on them being loaded.
-import { runTurn } from "../../services/chat.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
+import { registerWinkModel } from "../../adapters/wink-model.mjs";
 import {
   createInMemoryStore, normFactTerm, appendFacts, loadMemory, readFactRows,
 } from "../../adapters/memory/core.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { worldRelationGraphPayload } from "../../domain/ask.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import {
   worldFactRows, WORLD_NAME, WORLD_OPENING, cellId, parseCellId, DIRECTION_DELTA, visibleCells,
+  isLiveRenderableAgent, agentKindOf,
 } from "../../domain/spider-fly-world.mjs";
 import { foldSpiderFlyState, runSpiderFlyTick, startSpiderFlyGame, liveWebs, DEFAULT_VISION_RADIUS } from "../../services/spider-fly.mjs";
 import { pillsForSpiderFly, oneStepDirectionBetween } from "../../services/spider-fly-turn.mjs";
@@ -84,13 +89,27 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
     else if (f.predicate === "mgx:mass") initialAgents[f.subject] = { ...initialAgents[f.subject], mass: Number(f.object) };
   }
 
-  const graph = parseEntities({ individuals: [], objectProperties: [] });
+  // The graph the chat dock's own ask() traverses. There is no code graph
+  // here, so it holds the LIVE BOARD instead: one individual per agent, classed
+  // by its id, carrying its current cell, mass and mood. That is what makes
+  // "list the locations of flies and spiders" a real ask() capability call
+  // rather than another hand-written filter over the same rows. Rebuilt before
+  // every chat turn, since every tick moves the pieces.
+  let graph = parseEntities({ individuals: [], objectProperties: [] });
+  const readBoard = async () => {
+    const rows = readFactRows(await loadMemory(memoryDir));
+    return { rows, state: foldSpiderFlyState(rows) };
+  };
+  async function refreshWorldGraph() {
+    const { rows, state } = await readBoard();
+    graph = parseEntities(worldRelationGraphPayload(rows, {
+      classOf: (id) => (isLiveRenderableAgent(id, state) ? agentKindOf(id) : null),
+    }));
+  }
+  await refreshWorldGraph();
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
-  let planState = { spiderFly: { turn: 0 } };
   // The live, in-page-slider-adjustable knobs (mass-loss-rate/spawn-rate/
   // vision-radius per class, and every other spiderFly tunable) — starts at
   // the shipped defaults, mutated only through setConfig() below, and
@@ -100,6 +119,19 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
   // change only changes what happens FROM HERE ON, same as tmct.toml would.
   let config = { ...DEFAULT_GAME_CONFIG.spiderFly };
 
+  // The chat dock's turn dispatch — createTurnSession owns the focus/last/
+  // planState fold and the throw-safe catch fallback every browser entry
+  // needs; tick() below reaches into the SAME planState (via setPlanState)
+  // so a raw tick and a chat-driven tick can never disagree about the turn
+  // count either lane sees next.
+  const turnSession = createTurnSession({
+    memoryDir, graph, lexicon, sessionId, vocabHint: "",
+    // `graph` is re-read here, not captured above: createTurnSession binds its
+    // own once at creation, and this board is rebuilt every turn.
+    buildExtraOptions: () => ({ graph, gameConfig: { ...DEFAULT_GAME_CONFIG, spiderFly: config } }),
+  });
+  turnSession.setPlanState({ spiderFly: { turn: 0 } });
+
   return {
     memoryDir,
     sessionId,
@@ -107,34 +139,32 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
     initial: { turn: 0, agents: initialAgents, activeWebs: [] },
     taxonomyRows,
 
+    /** The board as a graph, as of the last refresh. Every tick moves the
+     *  pieces, so a caller putting a question to it calls `refreshGraph()`
+     *  first — which is exactly what `turn()` below already does. */
+    get graph() { return graph; },
+
+    /** Rebuild the board graph from the store's current rows. Exposed so a
+     *  question asked outside the chat dock (tmct.ask) reads this turn's
+     *  positions and not last turn's, the same way a typed one does. */
+    refreshGraph: refreshWorldGraph,
+
     /** Run one real engine turn directly. Returns spider-fly.mjs's own
      *  { turn, agents, ecology } shape unmodified. */
     async tick() {
       const result = await runSpiderFlyTick(memoryDir, { config });
-      planState = { spiderFly: { turn: result.turn } };
+      turnSession.setPlanState({ spiderFly: { turn: result.turn } });
       return result;
     },
 
     /** One dispatched chat turn — the SAME runTurn the CLI and the home
-     *  page's own chat run, over this session's own memoryDir. A throwing
-     *  runTurn must never kill the session — the page has no other chance
-     *  to show this turn's answer. */
+     *  page's own chat run, over this session's own memoryDir, via the
+     *  shared turn-dispatch wrapper (createTurnSession above) every browser
+     *  entry now uses. The board graph is rebuilt first, so a question about
+     *  where the pieces are reads this turn's positions and not last turn's. */
     async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "", planState,
-          gameConfig: { ...DEFAULT_GAME_CONFIG, spiderFly: config },
-        });
-      } catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null, plan: null };
-      }
-      focus = result.focus;
-      last = result.last;
-      if ("planState" in result) planState = result.planState;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null, plan: result.plan ?? null };
+      await refreshWorldGraph();
+      return turnSession.turn(line);
     },
 
     /** A read-only fold of the CURRENT board — no engine advance, no goal
@@ -143,11 +173,10 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
      *  chat-driven tick. Web individuals are never listed as agents (that's
      *  spider-1/fly-1/... only) — they surface only through activeWebs. */
     async snapshot() {
-      const rows = readFactRows(await loadMemory(memoryDir));
-      const state = foldSpiderFlyState(rows);
+      const { state } = await readBoard();
       const agents = {};
       for (const [id, place] of state.placements) {
-        if (state.removed.has(id) || /^web-\d+$/.test(id)) continue;
+        if (!isLiveRenderableAgent(id, state)) continue;
         agents[id] = { cell: place.cell, mass: state.mass.get(id)?.value ?? null };
       }
       return { turn: state.turnCount, agents, activeWebs: liveWebs(state.webs, state.turnCount) };
@@ -172,16 +201,23 @@ export async function createSpiderFlySession({ flyCount = 1 } = {}) {
   };
 }
 
-// cellId/parseCellId/DIRECTION_DELTA/visibleCells/DEFAULT_VISION_RADIUS are
-// re-exported so the page's own rendering script (spider-fly-viz.mjs) never
-// has to duplicate grid geometry or the vision-radius default: reconstructing
-// a spider's remaining silk-thread path from its returned direction list, and
-// computing the POV overlay's visible-cell mask, both need them.
-// pillsForSpiderFly/oneStepDirectionBetween are re-exported so the same page
-// can build its own dynamic deception-pill container without duplicating
-// spider-fly-turn.mjs's own pill logic.
-globalThis.tmctSpiderFly = {
-  createSpiderFlySession, normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
-  cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
-  pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG,
-};
+// `tmct.page` is grid geometry and sprite resolution — the two things on this
+// page the engine has no plain-English form for. Reconstructing a spider's
+// remaining silk-thread path from its returned direction list and masking the
+// POV overlay's visible cells both need the raw cell math; the deception pills
+// need spider-fly-turn.mjs's own pill logic.
+publishTmctSurface({
+  open: createSpiderFlySession,
+  // The board moves every tick, so a question rebuilds the graph first —
+  // the same refresh a typed turn does before it dispatches.
+  ask: async (request, options, session) => {
+    await session.refreshGraph();
+    return graphAsk(request, options, session);
+  },
+  plan: enginePlan,
+  page: {
+    normFactTerm, resolveSpriteForClass, SPRITE_REGISTRY, resolveSpriteAsset,
+    cellId, parseCellId, DIRECTION_DELTA, visibleCells, DEFAULT_VISION_RADIUS,
+    pillsForSpiderFly, oneStepDirectionBetween, DEFAULT_GAME_CONFIG, registerWinkModel,
+  },
+});

package/src/surfaces/web/sprites-browser-entry.mjs

@@ -9,19 +9,27 @@
 // (src/domain/sprite-facts.mjs's rows). A question the engine can't ground in
 // those rows gets the same refusal the CLI gives — never a guess.
 //
-// The page's own inline script answers the closed set of catalog-specific
-// question shapes (sprite-catalog-viz.mjs's answerSpriteQuestion) BEFORE
-// handing a line to this session, so this bundle carries no sprite-specific
-// grammar of its own.
-import { runTurn } from "../../services/chat.mjs";
+// Every line the dock takes goes to that session — the page intercepts
+// nothing, so a catalog question is answered by the same membership, count and
+// property lanes chat.mjs runs for any other caller, reading the sprite-facts
+// predicates straight.
+//
+// The scene composer's parser rides along here too: extractSceneItems resolves
+// a typed class name through ask.mjs's resolveObject, so it needs the real
+// resolver in the page rather than a self-contained function the page could
+// splice in as text.
 import { createInMemoryStore, appendFacts, normFactTerm } from "../../adapters/memory/core.mjs";
+import { extractSceneItems } from "../../domain/scene-compose.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
 import { loadLexicon } from "../../domain/grammar/lexicon.mjs";
 import { SPRITE_FACTS_PROVENANCE } from "../../domain/sprite-facts.mjs";
 import { registerWinkModel } from "../../adapters/wink-model.mjs";
+import { createTurnSession } from "./turn-session.mjs";
+import { publishTmctSurface } from "./tmct-surface.mjs";
+import { graphAsk, enginePlan } from "./engine-surface.mjs";
 
 /** A live in-memory chat session seeded with the embedded sprite-facts rows.
- *  Returns { memoryDir, sessionId, factCount, turn }. */
+ *  Returns { memoryDir, sessionId, graph, factCount, turn }. */
 export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   const memoryDir = createInMemoryStore();
   await appendFacts(memoryDir, factRows.map((f) => ({
@@ -32,37 +40,25 @@ export async function createSpriteCatalogSession({ factRows = [] } = {}) {
   const lexicon = loadLexicon();
   const sessionId = globalThis.crypto?.randomUUID?.() ?? String(Date.now());
 
-  let focus = null;
-  let last = null;
+  const session = createTurnSession({ memoryDir, graph, lexicon, sessionId, vocabHint: "" });
 
   return {
     memoryDir,
     sessionId,
+    graph,
     factCount: factRows.length,
-
-    /** One dispatched chat turn — the SAME runTurn the CLI runs, over this
-     *  session's own memoryDir. A throwing runTurn must never kill the
-     *  session — the page has no other chance to show this turn's answer. */
-    async turn(line) {
-      let result;
-      try {
-        result = await runTurn(line, {
-          config: null, source: null, graph, focus, last, memoryDir, sessionId,
-          env: {}, lexicon, vocabHint: "",
-        });
-      } catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        return { answer: `Something went wrong answering that (${message}). Try rephrasing, or /help.`, end: false, record: null };
-      }
-      focus = result.focus;
-      last = result.last;
-      return { answer: result.answer, end: Boolean(result.end), record: result.record ?? null };
-    },
+    turn: session.turn,
   };
 }
 
-// registerWinkModel is re-exported so the page's own inline script can hand in
-// the self-hosted wink pair (./vendor/wink.js) exactly the way chat.html/
-// ledger.html/plan.html register theirs — the bundle itself never imports
-// wink-nlp (wink-model.mjs's own header explains why).
-globalThis.tmctSprites = { createSpriteCatalogSession, registerWinkModel, normFactTerm };
+// `tmct.page` keeps the wink seam (the page hands in the self-hosted pair from
+// ./vendor/wink.js, exactly the way chat.html/ledger.html/plan.html register
+// theirs — the bundle itself never imports wink-nlp), the term normalizer, and
+// the scene composer's parser, which reads a typed line into drawable items
+// rather than answering anything.
+publishTmctSurface({
+  open: createSpriteCatalogSession,
+  ask: graphAsk,
+  plan: enginePlan,
+  page: { registerWinkModel, normFactTerm, extractSceneItems },
+});

package/src/surfaces/web/tmct-surface.mjs

@@ -0,0 +1,147 @@
+// tmct-surface.mjs — the one contract every demo page has with the engine.
+//
+// Each browser entry used to publish its own bag of primitives under its own
+// name (tmctChat, tmctMud, tmctLedger, tmctSpiderFly, ...), so a visitor
+// reading one page's source met a different wall of raw functions on every
+// page, wired together by hand. mud-browser-entry.mjs's own header stated the
+// reason for its 25: "so mud-viz.mjs's own inlined script never duplicates
+// sprite resolution or the digest/affordance/knowledge readers". Right
+// instinct, wrong unit — the page still had to know 25 names to say one
+// sentence.
+//
+// This publishes ONE `globalThis.tmct` instead, and every page reaches the
+// engine the same way:
+//
+//   await tmct.open(...)     open this page's session
+//   tmct.session             the live session, once opened
+//   await tmct.turn(line)    one conversational turn, the dock's entry point
+//   await tmct.ask(request)  one grounded question, prose plus its evidence
+//   await tmct.plan(request) one compound request, planned over what's loaded
+//
+// Whatever a page still needs that has NO plain-English form lives on
+// `tmct.page` — canvas geometry, sprite templates, a wink model to register, a
+// digest structure table. The split is the point: `tmct.ask(...)` is tmct
+// answering, `tmct.page.cellId(...)` is this page drawing. A reader can tell
+// them apart at a glance, which is exactly what eleven flat bags made
+// impossible.
+//
+// `ask` and `plan` are supplied per page rather than fixed here, because what
+// a page can ground a question against genuinely differs: code-explorer holds
+// a code graph, spider-fly holds a live board projected into one, the ledger
+// dock holds a memory store and no graph at all. A page that supplies neither
+// gets an honest refusal naming why, never a guess — the same promise the
+// engine itself makes.
+
+const NO_SESSION = "no session is open on this page yet — await tmct.open() first";
+
+// The demo ledger page carries TWO bundles at once: the committed
+// question-only one inlined into the HTML (memory-ask-browser-entry.mjs) and
+// the demo site's own full turn engine as a separate script tag
+// (ledger-browser-entry.mjs). Both publish this surface, and which one the
+// browser runs first is not something either can promise. So the
+// question-only one publishes as a `fallback` and the full engine always
+// wins, whichever order they load in. Registered globally rather than
+// module-locally because the two bundles carry their own copy of this module.
+const FALLBACK = Symbol.for("tmct.surface.fallback");
+
+/**
+ * `publishTmctSurface({ open, ask, plan, turn, page, target })` installs
+ * `target.tmct` (default `globalThis`) and returns it.
+ *
+ * `open(...args)` is the page's own session factory and is the only required
+ * argument — `createChatSession`, `createMudSession`, `createPlanSession` and
+ * the rest, called with whatever arguments they already take. Its result
+ * becomes `tmct.session`.
+ *
+ * `turn(line, options, session)` (optional) overrides how a line reaches the
+ * session. The default calls `session.turn(line, options)`, which is every
+ * page but mud — mud runs several characters over one world, so it routes on
+ * `{ as: character }` to that character's own window.
+ *
+ * `ask(request, options, session)` and `plan(request, options, session)`
+ * (optional) are the page's grounded-question and capability-planner routes.
+ * Left out, the matching verb refuses and says which route the page does have.
+ * Every verb takes the same `(what, options)` shape, so the research page's
+ * source-scoped `tmct.ask(q, { sources })` reads like the plan page's
+ * `tmct.turn("solve it", { maxDepth })`.
+ *
+ * `page` is the residual bag: this page's own rendering helpers, reachable as
+ * `tmct.page.*`.
+ *
+ * `fallback: true` publishes only where no fuller surface is standing, and
+ * yields to one that arrives later — the ledger page's two bundles.
+ */
+export function publishTmctSurface({
+  open, ask = null, plan = null, turn = null, page = {}, fallback = false, target = globalThis,
+} = {}) {
+  if (typeof open !== "function") {
+    throw new Error("publishTmctSurface: `open` must be this page's session factory");
+  }
+  const standing = target.tmct;
+  if (fallback && standing && !standing[FALLBACK]) return standing;
+  let session = null;
+
+  const liveSession = () => {
+    if (!session) throw new Error(NO_SESSION);
+    return session;
+  };
+
+  const surface = {
+    // Variadic, so each page's factory keeps the signature it already has —
+    // adventure and mud both take the world payload first, then their options.
+    async open(...args) {
+      session = await open(...args);
+      return session;
+    },
+
+    get session() { return session; },
+
+    async turn(line, options) {
+      const live = liveSession();
+      if (turn) return turn(line, options, live);
+      // Not every page holds a conversation. The ingest page grounds pasted
+      // prose into facts and answers nothing, so it says so rather than
+      // failing on a method it never had.
+      if (typeof live.turn !== "function") {
+        return {
+          answer: "this page runs no conversational turn — see tmct.session for what it does run",
+          end: false, record: null, plan: null, research: null,
+        };
+      }
+      return live.turn(line, options);
+    },
+
+    async ask(request, options) {
+      if (!ask) {
+        return {
+          answer: "this page has no separate ask route — it answers questions through tmct.turn()",
+          data: undefined,
+          miss: true,
+        };
+      }
+      return ask(request, options, liveSession());
+    },
+
+    async plan(request, options) {
+      if (!plan) {
+        return {
+          refused: true,
+          why: "this page's bundle carries no capability planner",
+          driver: null, calls: [], composed: null, observed: null,
+        };
+      }
+      return plan(request, options, liveSession());
+    },
+
+    page,
+
+    /** True where this is the question-only stand-in rather than a page's full
+     *  engine. The ledger page reads it to tell its two docks apart: the live
+     *  one teaches, the stand-in only answers. */
+    fallback,
+  };
+
+  surface[FALLBACK] = fallback;
+  target.tmct = surface;
+  return surface;
+}

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

@@ -0,0 +1,124 @@
+// 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, graph, turn, focus, last, planState,
+ * setPlanState, researchState, setResearchState }`. `graph` is the one this
+ * session was built over, exposed so a caller can put a question to the same
+ * graph its turns run against (engine-surface.mjs's `graphAsk`) without
+ * holding a second reference to it. `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,
+    graph,
+    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();