@polycode-projects/the-mechanical-code-talker 2.11.6 → 2.11.9

package/src/surfaces/http/server-http.mjs

@@ -15,9 +15,13 @@
 // HTTP surface.
 
 import { createServer } from "node:http";
-import { runTurn, selectTool } from "../../services/chat.mjs";
-import { TOOLS } from "../../tools/server.mjs";
+import { runTurn, selectTool, capabilityPlanDeps } from "../../services/chat.mjs";
+import { TOOLS, dispatchTool } from "../../tools/server.mjs";
+import { runCapabilityPlan, buildCapabilityPlanCtx, declaredCapabilityNames } from "../../domain/router/drive.mjs";
+import { isCapability } from "../../domain/router/registry.mjs";
+import { hallucinationsIn } from "../../domain/router/call-validator.mjs";
 import { parseEntities } from "../../domain/codegraph.mjs";
+import { ToolError } from "../../adapters/config.mjs";
 import { uuidv7 } from "../../adapters/uuid.mjs";
 import * as defaultSource from "../../adapters/source.mjs";
 
@@ -83,9 +87,58 @@ function assistantMessage(model, content, stopReason) {
   };
 }
 
+/** The first tool_use block of a transcript that ENDS on an assistant message —
+ *  a caller PROPOSING a call for tmct to validate and (if clean) run. Returns
+ *  { name, input, id, rest } (rest = any further tool_use blocks in the same
+ *  message, noted in the reply but not executed) or null. A transcript that ends
+ *  user-role with a tool_result is the loop-closing shape, not a proposal, so
+ *  this returns null for it — its final message is not an assistant message. */
+function proposedToolUse(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return null;
+  const last = messages[messages.length - 1];
+  if (!last || last.role !== "assistant" || !Array.isArray(last.content)) return null;
+  const uses = last.content.filter((b) => b && b.type === "tool_use" && typeof b.name === "string");
+  if (!uses.length) return null;
+  const [first, ...rest] = uses;
+  return {
+    name: first.name,
+    input: first.input && typeof first.input === "object" ? first.input : {},
+    id: first.id,
+    rest,
+  };
+}
+
+/** One human line for a hallucination-taxonomy problem, its reason in parentheses
+ *  so a caller can grep the machine reason off the prose. */
+function describeProblem(p, name) {
+  switch (p.reason) {
+    case "unknown-tool": return `"${p.detail}" is not a capability I know (unknown-tool)`;
+    case "undeclared": return `"${p.detail}" is a real capability but was not declared in this request (undeclared)`;
+    case "unknown-arg": return `${p.detail} is not an argument ${name} accepts (unknown-arg)`;
+    case "missing-arg": return `${p.detail} (missing-arg)`;
+    default: return `${p.detail} (${p.reason})`;
+  }
+}
+
+/** The tmct capabilities a request declared — what tmct will actually validate
+ *  and execute, as named in a hand-back / refusal so the caller can see the set. */
+function declaredCapabilityList(declaredNames) {
+  const caps = [...declaredNames].filter(isCapability);
+  return caps.length ? caps.join(", ") : "(none)";
+}
+
+/** Append the "N further calls not processed" note (when a proposal carried more
+ *  than one tool_use block) to a reply text. */
+function withRestNote(text, rest) {
+  if (!rest.length) return text;
+  return `${text}\n(${rest.length} further proposed call(s) in the same message were not processed: ${rest.map((b) => b.name).join(", ")}.)`;
+}
+
 /**
  * Produce the Messages-API response for one request body. Pure over its inputs
  * (the loaded graph + config), so it is unit-testable without a socket.
+ *   - a caller-PROPOSED tool_use (transcript ends on an assistant tool_use) →
+ *     validate with hallucinationsIn, then execute (end_turn) or refuse
  *   - a returned tool_result → end_turn text (relay the tool's output)
  *   - a mapped, declared graph tool → tool_use
  *   - otherwise → end_turn text via runTurn
@@ -96,6 +149,57 @@ export async function respondToMessages(body, { config, graph, source = defaultS
     (Array.isArray(tools) ? tools : []).map((t) => t && t.name).filter(Boolean),
   );
 
+  // A caller-proposed call: validate it against the registry + the declared set
+  // before anything runs, then execute a clean call or refuse a hallucinated one
+  // with the taxonomy's reason. Checked FIRST — a proposal ends on an assistant
+  // tool_use, so the loop-closing tool_result branch below (final user turn)
+  // never fires for it, and this never fires for a loop close.
+  const proposal = proposedToolUse(messages);
+  if (proposal) {
+    const { name, input, rest } = proposal;
+
+    // A tool the caller declared that is NOT a tmct capability is the caller's
+    // OWN tool — hand it back honestly rather than burning the taxonomy's
+    // unknown-tool (which stays reserved for a genuinely invented name).
+    if (declaredNames.has(name) && !isCapability(name)) {
+      const text = `"${name}" is your own tool, not a tmct capability — tmct validates and executes only tmct capabilities (${declaredCapabilityList(declaredNames)}). Nothing was executed.`;
+      return assistantMessage(model, [{ type: "text", text: withRestNote(text, rest) }], "end_turn");
+    }
+
+    const problems = hallucinationsIn({ name, input }, [...declaredNames]);
+    if (problems.length) {
+      const lines = problems.map((p) => `refusing the proposed call — ${describeProblem(p, name)}.`);
+      lines.push(`Nothing was executed; declared capabilities: ${declaredCapabilityList(declaredNames)}.`);
+      const msg = assistantMessage(model, [{ type: "text", text: withRestNote(lines.join("\n"), rest) }], "refusal");
+      msg.tmct_checked_call = { name, input, problems };
+      return msg;
+    }
+
+    // Clean. A taught: record is simulated over the taught rules only — never a
+    // dispatchable tool — so decline honestly rather than dispatch an "unknown
+    // tool" error under a call that actually validated.
+    if (name.startsWith("taught:")) {
+      const text = `"${name}" is a taught action — simulated over the taught rules, not a dispatchable tool — so nothing was executed. Run it in chat with "next".`;
+      const msg = assistantMessage(model, [{ type: "text", text: withRestNote(text, rest) }], "end_turn");
+      msg.tmct_checked_call = { name, input, problems: [] };
+      return msg;
+    }
+    try {
+      const out = await dispatchTool(name, input, { config, source });
+      const msg = assistantMessage(model, [{ type: "text", text: withRestNote(out, rest) }], "end_turn");
+      msg.tmct_checked_call = { name, input, problems: [] };
+      return msg;
+    } catch (e) {
+      if (!(e instanceof ToolError)) throw e;
+      // A well-formed call that grounded nothing is an honest MISS, not a
+      // refusal — the taxonomy is clean; the graph simply had no answer.
+      const text = `the proposed call was well-formed but grounded nothing: ${e.message}`;
+      const msg = assistantMessage(model, [{ type: "text", text: withRestNote(text, rest) }], "end_turn");
+      msg.tmct_checked_call = { name, input, problems: [] };
+      return msg;
+    }
+  }
+
   // Closing the loop: the caller executed our tool_use and returned a
   // tool_result. Relay it as the final, cited answer with end_turn.
   const lastUser = lastMessageOfRole(messages, "user");
@@ -127,6 +231,44 @@ export async function respondToMessages(body, { config, graph, source = defaultS
   return assistantMessage(model, [{ type: "text", text: answer }], "end_turn");
 }
 
+/** The capability names a /v1/plan request restricts its plan to (its `tools`
+ *  array of names or `{name}` objects), and any that are not registered
+ *  capabilities — the route rejects an `unknown` list with a 400 before the loop
+ *  ever runs. A request with no `tools` plans over every registered capability. */
+function planToolNames(body) {
+  const declared = declaredCapabilityNames();
+  if (!Array.isArray(body?.tools)) return { tools: declared, declared, unknown: [] };
+  const tools = body.tools.map((t) => (typeof t === "string" ? t : t && t.name)).filter(Boolean);
+  const unknown = tools.filter((t) => !declared.includes(t));
+  return { tools, declared, unknown };
+}
+
+/**
+ * Produce the /v1/plan response for one request body — the capability router
+ * (runCapabilityPlan) over HTTP, the same loop result the library export and the
+ * `tmct plan --json` CLI already return. Assumes a validated body (the route
+ * rejects a missing `request` or an unknown tool name with a 400 first).
+ *   - refused  → { request, ...loopResult } — an in-band honest "no plan found",
+ *                not a protocol error (still HTTP 200)
+ *   - grounded → { request, ...loopResult, usage } with $0 usage
+ *
+ * Per-request taught-action registrations ride ctx.disposers and are unregistered
+ * in the finally, so a second request re-reads the store instead of colliding on
+ * an already-registered taught capability name.
+ */
+export async function respondToPlan(body, { config, graph, memoryDir = null, source = defaultSource } = {}) {
+  const request = typeof body?.request === "string" ? body.request.trim() : "";
+  const { tools } = planToolNames(body);
+  const ctx = await buildCapabilityPlanCtx({ ...capabilityPlanDeps(), config, source, graph, memoryDir });
+  try {
+    const result = await runCapabilityPlan(request, tools, ctx);
+    if (result.refused) return { request, ...result };
+    return { request, ...result, usage: { ...ZERO_USAGE } };
+  } finally {
+    for (const dispose of ctx.disposers || []) dispose();
+  }
+}
+
 /** Self-description payload (GET /) — lets a routing target discover the endpoint
  *  and the tools tmct can back with just an HTTP GET. */
 function describe(config) {
@@ -134,6 +276,7 @@ function describe(config) {
     service: "tmct",
     description: "Anthropic Messages API-compatible, deterministic, no-LLM graph router (the $0 floor).",
     endpoint: { method: "POST", path: "/v1/messages" },
+    plan_endpoint: { method: "POST", path: "/v1/plan" },
     graph: config && config.graphFile,
     tools: TOOLS.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema })),
     usage_pricing: ZERO_USAGE,
@@ -174,7 +317,7 @@ function sendError(res, status, type, message) {
  *   host   — bind address (default 127.0.0.1)
  *   port   — TCP port; 0 picks an ephemeral port (tests)
  */
-export async function startServer({ config, host = "127.0.0.1", port = 0, source = defaultSource } = {}) {
+export async function startServer({ config, host = "127.0.0.1", port = 0, source = defaultSource, memoryDir = null } = {}) {
   if (!config || !config.graphFile) throw new Error("startServer requires config.graphFile");
   // Load the graph once, up front. A missing artifact loads as the empty
   // bootstrap graph — runTurn tolerates it (an honest empty/orienting answer).
@@ -187,6 +330,32 @@ export async function startServer({ config, host = "127.0.0.1", port = 0, source
         sendJson(res, 200, describe(config));
         return;
       }
+      if (url.pathname === "/v1/plan") {
+        if (req.method !== "POST") {
+          sendError(res, 405, "invalid_request_error", "POST /v1/plan");
+          return;
+        }
+        let body;
+        try {
+          body = JSON.parse((await readBody(req)) || "{}");
+        } catch {
+          sendError(res, 400, "invalid_request_error", "request body is not valid JSON");
+          return;
+        }
+        const request = typeof body?.request === "string" ? body.request.trim() : "";
+        if (!request) {
+          sendError(res, 400, "invalid_request_error", "`request` is required and must be a non-empty string");
+          return;
+        }
+        const { unknown, declared } = planToolNames(body);
+        if (unknown.length) {
+          sendError(res, 400, "invalid_request_error", `unknown tools name(s): ${unknown.join(", ")}; registered capabilities: ${declared.join(", ")}`);
+          return;
+        }
+        const out = await respondToPlan(body, { config, graph, memoryDir, source });
+        sendJson(res, 200, out);
+        return;
+      }
       if (url.pathname !== "/v1/messages") {
         sendError(res, 404, "not_found_error", `no route ${req.method} ${url.pathname}`);
         return;

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

@@ -179,4 +179,24 @@ export async function exportFactsJsonl(memoryDir) {
   return serializeFactsJsonl(await loadMemory(memoryDir));
 }
 
-globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, splitSentences: splitSentencesPreservingPaths };
+/**
+ * Every fact a "research <topic>" run has stored so far, in storage order —
+ * the exposure the "researched this session" panel needs and runTurn's
+ * result doesn't otherwise carry (a research turn's own record reports a
+ * per-topic FACT COUNT, research.mjs's own researchSnapshot, never the
+ * triples themselves). Reads the same provenance tags memoryStats already
+ * folds (readFactRows' `provenance`, the ' | '-joined compat string),
+ * filtered to the `research:<topicKey>@<depth>` prefix research.mjs's own
+ * `researchProvenanceTag` stamps every research-sourced fact with, rather
+ * than a second ingest-path computation — so this can never list a fact
+ * research didn't actually store.
+ */
+export async function researchedFactRows(memoryDir) {
+  const memory = await loadMemory(memoryDir);
+  const rows = readFactRows(memory);
+  return rows
+    .filter((row) => String(row.provenance || "").split(" | ").some((tag) => tag.startsWith("research:")))
+    .map((row) => ({ subject: row.subject, predicate: row.predicate, object: row.object }));
+}
+
+globalThis.tmctChat = { createChatSession, registerWinkModel, registerReferencePackProvider, registerLiveReferenceProvider, registerResearchProvider, normFactTerm, vocabExampleHint, memoryStats, openPersistedStore, exportFactsJsonl, researchedFactRows, splitSentences: splitSentencesPreservingPaths };