@polycode-projects/the-mechanical-code-talker 0.7.0 → 0.8.0

package/src/server-http.mjs

@@ -0,0 +1,296 @@
+// server-http.mjs — `tmct serve`: an Anthropic Messages API-compatible HTTP
+// endpoint (POST /v1/messages) over tmct's existing zero-model engine.
+//
+// This is Phase A of the capability-router plan (PLAN_CAPABILITY_ROUTER.md): the
+// COMMON INTERFACE a tool-loop client (Claude Code) already speaks. It is a
+// deterministic serialization/HTTP shim — NO model, ever. A request carries
+// { model, messages[], tools[], max_tokens, system? }; a response is a message
+// with `content` blocks (text and/or tool_use) and a `stop_reason`:
+//
+//   - TEXT ANSWER (stop_reason "end_turn"): the latest user text is run through
+//     runTurn (src/chat.mjs) over the configured graph — the same cited,
+//     read-only answer the chat surface gives. Emitted when no tools are
+//     declared, or when nothing maps to a declared graph-query tool.
+//   - TOOL_USE (stop_reason "tool_use"): when tools[] are declared and the
+//     request maps to a declared graph-query tool, a { type:"tool_use", id,
+//     name, input } block is emitted — `name`+`input` are backed by dispatchTool
+//     (src/server.mjs). The caller executes it and returns a tool_result block;
+//     the next request closes the loop with an end_turn text answer.
+//
+// bedrock-meter-pluggable: every response's `usage` is { input_tokens: 0,
+// output_tokens: 0 } — tmct is the $0 floor, priced as free by the meter.
+//
+// NOTE: src/server.mjs is the TOOL-DISPATCH layer (dispatchTool), NOT an HTTP
+// server; this module is the HTTP surface and imports that layer's exports.
+
+import { createServer } from "node:http";
+import { runTurn, COMMANDS, asBareCommand, isConversational } from "./chat.mjs";
+import { TOOLS } from "./server.mjs";
+import { parseEntities } from "./codegraph.mjs";
+import { uuidv7 } from "./uuid.mjs";
+import * as defaultSource from "./source.mjs";
+
+/** The zero usage every response carries — the meter prices tmct as the $0 floor. */
+const ZERO_USAGE = { input_tokens: 0, output_tokens: 0 };
+
+/** The tmct tools dispatchTool can back (the set the shim will emit a tool_use for).
+ *  A declared tool outside this set is ignored for emission (the request falls
+ *  through to a text answer) — the shim never emits a call it cannot ground. The
+ *  COMMANDS map (chat.mjs) names the richer graph tools; TOOLS names the hot
+ *  catalog. Their union is what dispatchTool serves. */
+const BACKED_TOOLS = new Set([
+  ...TOOLS.map((t) => t.name),
+  ...Object.values(COMMANDS).map((s) => s.tool),
+]);
+
+/** Flatten a message's `content` (a string OR a content-block array) into plain
+ *  text — concatenating the `text` blocks. Non-text blocks are ignored here. */
+function textOfContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b) => b && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n")
+    .trim();
+}
+
+/** The last message with the given role, or null. */
+function lastMessageOfRole(messages, role) {
+  if (!Array.isArray(messages)) return null;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i] && messages[i].role === role) return messages[i];
+  }
+  return null;
+}
+
+/** The first tool_result block in a message's content array, or null. The caller
+ *  returns one of these after executing a tool_use — its presence means the loop
+ *  is closing and we answer with end_turn. */
+function firstToolResult(message) {
+  const content = message && message.content;
+  if (!Array.isArray(content)) return null;
+  return content.find((b) => b && b.type === "tool_result") || null;
+}
+
+/** Render a tool_result block's `content` (string OR block array OR arbitrary
+ *  value) back to text — what the caller reported when it executed the tool. */
+function toolResultText(block) {
+  const c = block && block.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) return textOfContent(c);
+  if (c == null) return "";
+  try { return JSON.stringify(c); } catch { return String(c); }
+}
+
+/**
+ * Decide whether a user turn maps to a DECLARED, dispatch-backed graph-query
+ * tool, and bind its arguments. Deterministic, in-ethos (no NL guessing beyond
+ * the chat surface's own command routing):
+ *
+ *   1. A slash/bare command that names a tmct tool ("describe X", "/callers X",
+ *      "untested") → that tool with its argument bound from the exact arg key the
+ *      dispatchTool switch reads (COMMANDS in chat.mjs). Only when the tool is
+ *      declared by the caller.
+ *   2. Otherwise, a non-conversational structural question → tmct_ask{query:…},
+ *      when tmct_ask is declared. Small-talk (isConversational) never emits a
+ *      call — it falls through to a text answer.
+ *
+ * Returns { name, input } or null (→ answer as text).
+ */
+export function selectTool(text, declaredNames) {
+  const t = String(text || "").trim();
+  if (!t) return null;
+
+  // 1. explicit command form → a specific tool, argument bound
+  const cmdLine = t.startsWith("/") ? t : asBareCommand(t);
+  if (cmdLine) {
+    const [first, ...restTok] = cmdLine.replace(/^\//, "").split(/\s+/);
+    const spec = COMMANDS[String(first).toLowerCase()];
+    if (spec && declaredNames.has(spec.tool) && BACKED_TOOLS.has(spec.tool)) {
+      const input = {};
+      if (spec.arg) {
+        const val = restTok.join(" ").trim();
+        if (val) input[spec.arg] = val;
+        // an entity command with no argument can't bind a call — fall through
+        else if (!spec.optional) return askFallback(t, declaredNames);
+      }
+      return { name: spec.tool, input };
+    }
+  }
+
+  // 2. structural question → tmct_ask, unless it's small-talk
+  return askFallback(t, declaredNames);
+}
+
+/** The tmct_ask fallback: emit tmct_ask{query} for a non-conversational line when
+ *  the caller declared tmct_ask; otherwise null (→ text answer). */
+function askFallback(text, declaredNames) {
+  if (declaredNames.has("tmct_ask") && BACKED_TOOLS.has("tmct_ask") && !isConversational(text)) {
+    return { name: "tmct_ask", input: { query: text } };
+  }
+  return null;
+}
+
+/** Build the assistant message envelope shared by every branch. */
+function assistantMessage(model, content, stopReason) {
+  return {
+    id: `msg_${uuidv7().replace(/-/g, "")}`,
+    type: "message",
+    role: "assistant",
+    model: model || "tmct",
+    content,
+    stop_reason: stopReason,
+    stop_sequence: null,
+    usage: { ...ZERO_USAGE },
+  };
+}
+
+/**
+ * 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 returned tool_result → end_turn text (relay the tool's output)
+ *   - a mapped, declared graph tool → tool_use
+ *   - otherwise → end_turn text via runTurn
+ */
+export async function respondToMessages(body, { config, graph, source = defaultSource } = {}) {
+  const { model, messages, tools } = body || {};
+  const declaredNames = new Set(
+    (Array.isArray(tools) ? tools : []).map((t) => t && t.name).filter(Boolean),
+  );
+
+  // 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");
+  const tr = firstToolResult(lastUser);
+  if (tr) {
+    const text = toolResultText(tr) || "(the tool returned no output)";
+    return assistantMessage(model, [{ type: "text", text }], "end_turn");
+  }
+
+  const userText = textOfContent(lastUser && lastUser.content);
+
+  // tool_use emission: a declared, dispatch-backed graph tool the request maps to.
+  if (declaredNames.size) {
+    const sel = selectTool(userText, declaredNames);
+    if (sel) {
+      const block = {
+        type: "tool_use",
+        id: `toolu_${uuidv7().replace(/-/g, "")}`,
+        name: sel.name,
+        input: sel.input,
+      };
+      return assistantMessage(model, [block], "tool_use");
+    }
+  }
+
+  // text answer: the cited, read-only answer the chat surface gives. memoryDir is
+  // null so the endpoint is PURE — no session artifacts, no writes, deterministic.
+  const { answer } = await runTurn(userText, { config, graph, source, memoryDir: null });
+  return assistantMessage(model, [{ type: "text", text: answer }], "end_turn");
+}
+
+/** 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) {
+  return {
+    service: "tmct",
+    description: "Anthropic Messages API-compatible, deterministic, no-LLM graph router (the $0 floor).",
+    endpoint: { method: "POST", path: "/v1/messages" },
+    graph: config && config.graphFile,
+    tools: TOOLS.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema })),
+    usage_pricing: ZERO_USAGE,
+  };
+}
+
+async function readBody(req, limit = 5 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) { reject(new Error("request body too large")); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, status, obj) {
+  const payload = JSON.stringify(obj);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(payload);
+}
+
+/** An Anthropic-style error envelope. */
+function sendError(res, status, type, message) {
+  sendJson(res, status, { type: "error", error: { type, message } });
+}
+
+/**
+ * Start the HTTP server. Loads the graph once (tolerant: a missing artifact is
+ * the empty bootstrap graph, never an error). Returns { server, url, host, port,
+ * config, close } — `close()` shuts the socket cleanly (no hanging handles).
+ *
+ *   config — { graphFile } (build via configFor(repoPath) in bin/tmct.mjs)
+ *   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 } = {}) {
+  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).
+  const graph = parseEntities(await source.fetchEntities(config));
+
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, "http://localhost");
+      if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/v1/models")) {
+        sendJson(res, 200, describe(config));
+        return;
+      }
+      if (url.pathname !== "/v1/messages") {
+        sendError(res, 404, "not_found_error", `no route ${req.method} ${url.pathname}`);
+        return;
+      }
+      if (req.method !== "POST") {
+        sendError(res, 405, "invalid_request_error", "POST /v1/messages");
+        return;
+      }
+      let body;
+      try {
+        body = JSON.parse((await readBody(req)) || "{}");
+      } catch {
+        sendError(res, 400, "invalid_request_error", "request body is not valid JSON");
+        return;
+      }
+      if (!body || !Array.isArray(body.messages)) {
+        sendError(res, 400, "invalid_request_error", "`messages` array is required");
+        return;
+      }
+      const out = await respondToMessages(body, { config, graph, source });
+      sendJson(res, 200, out);
+    } catch (e) {
+      sendError(res, 500, "api_error", e && e.message ? e.message : String(e));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => { server.removeListener("error", reject); resolve(); });
+  });
+
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : port;
+  const url = `http://${host}:${boundPort}`;
+
+  return {
+    server,
+    host,
+    port: boundPort,
+    url,
+    config,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}

package/src/tui/app.mjs

@@ -69,6 +69,40 @@ export function wrapLines(lines, width) {
   return out;
 }
 
+// ---- line editor (pure, cursor-aware — readline-style in-line editing) ----
+// The input line is a (value, cursor) pair: `cursor` is an index in [0, value.length]
+// naming the gap BEFORE which the next character lands. Left/right move it; typing and
+// backspace act AT it, so a message can be edited mid-line and resubmitted. Pure so
+// node:test exercises the editing without a terminal.
+
+/** Insert `str` at the cursor; the cursor advances past it. */
+export function insertAt(value, cursor, str) {
+  const c = clampCursor(value, cursor);
+  return { value: value.slice(0, c) + str + value.slice(c), cursor: c + str.length };
+}
+
+/** Delete the character BEFORE the cursor (Backspace); the cursor steps left. A no-op
+ *  at column 0. (This shell treats Backspace and Delete alike — delete-before-cursor.) */
+export function backspaceAt(value, cursor) {
+  const c = clampCursor(value, cursor);
+  if (c <= 0) return { value, cursor: 0 };
+  return { value: value.slice(0, c - 1) + value.slice(c), cursor: c - 1 };
+}
+
+/** Clamp a cursor index into [0, value.length]. */
+export function clampCursor(value, cursor) {
+  return Math.max(0, Math.min(String(value).length, Number(cursor) || 0));
+}
+
+/** Split the value around the cursor for rendering: the text before it, the single
+ *  character UNDER it (a space when the cursor sits past the end), and the text after
+ *  that character — so the caret block can highlight `at` in place. */
+export function inputCells(value, cursor) {
+  const c = clampCursor(value, cursor);
+  const s = String(value);
+  return { before: s.slice(0, c), at: s.slice(c, c + 1) || " ", after: s.slice(c + 1) };
+}
+
 /** Terminal size, live across resizes (falls back to 80×24 off-TTY). */
 function useTerminalSize() {
   const { stdout } = useStdout();
@@ -90,6 +124,7 @@ export function App({ session }) {
   const { columns, rows } = useTerminalSize();
   const [items, setItems] = useState([]);
   const [input, setInput] = useState("");
+  const [cursor, setCursor] = useState(0); // caret position within `input` (readline-style)
   const [prompt, setPrompt] = useState(session.promptFor());
   const [busy, setBusy] = useState(false);
   // Command history (up/down arrow recall, readline-style). `history` is oldest→newest;
@@ -111,10 +146,14 @@ export function App({ session }) {
     }
   };
 
+  // Set the editable line to a whole string with the caret at its end (history recall,
+  // submit-reset) — one place so `input` and `cursor` never drift apart.
+  const setLine = (value) => { setInput(value); setCursor(value.length); };
+
   const trySubmit = (raw) => {
     if (busy) return; // one turn at a time — the engine is deterministic and fast
     const line = String(raw).trim();
-    setInput("");
+    setLine("");
     setHistCursor(-1); // any submit resets history navigation to the live input
     if (line) {
       // record for up-arrow recall; collapse an immediate duplicate of the last line
@@ -125,30 +164,36 @@ export function App({ session }) {
 
   useInput((ch, key) => {
     if (key.return) { trySubmit(input); return; }
-    if (key.backspace || key.delete) { setInput((s) => s.slice(0, -1)); return; }
-    if (key.ctrl && ch === "u") { setInput(""); return; }
+    // Left/right arrow + Ctrl-A/E: move the caret so a typed line can be edited mid-string
+    // and resubmitted (not just appended to / backspaced from the end).
+    if (key.leftArrow) { setCursor((c) => clampCursor(input, c - 1)); return; }
+    if (key.rightArrow) { setCursor((c) => clampCursor(input, c + 1)); return; }
+    if (key.ctrl && ch === "a") { setCursor(0); return; }                // home
+    if (key.ctrl && ch === "e") { setCursor(input.length); return; }     // end
+    if (key.backspace || key.delete) { const r = backspaceAt(input, cursor); setInput(r.value); setCursor(r.cursor); return; }
+    if (key.ctrl && ch === "u") { setLine(""); return; }
     // Up/down arrow: recall previous prompts (readline-style), oldest→newest history.
     if (key.upArrow) {
       if (!history.length) return;
       const nc = Math.min(histCursor + 1, history.length - 1);
       setHistCursor(nc);
-      setInput(history[history.length - 1 - nc]);
+      setLine(history[history.length - 1 - nc]);
       return;
     }
     if (key.downArrow) {
-      if (histCursor <= 0) { setHistCursor(-1); setInput(""); return; } // back to a fresh line
+      if (histCursor <= 0) { setHistCursor(-1); setLine(""); return; } // back to a fresh line
       const nc = histCursor - 1;
       setHistCursor(nc);
-      setInput(history[history.length - 1 - nc]);
+      setLine(history[history.length - 1 - nc]);
       return;
     }
-    if (key.ctrl || key.meta || key.escape || key.tab || key.leftArrow || key.rightArrow) return;
+    if (key.ctrl || key.meta || key.escape || key.tab) return;
     if (!ch) return;
     // A PASTED chunk arrives as one multi-char event; a newline inside it means
     // "submit this line" (one line per turn — the readline shell's per-line read).
     const nl = ch.search(/[\r\n]/);
-    if (nl === -1) { setInput((s) => s + ch); return; }
-    trySubmit(input + ch.slice(0, nl));
+    if (nl === -1) { const r = insertAt(input, cursor, ch); setInput(r.value); setCursor(r.cursor); return; }
+    trySubmit(input.slice(0, cursor) + ch.slice(0, nl) + input.slice(cursor));
   });
 
   // The pane's line budget: full height minus the input line and the status bar.
@@ -163,11 +208,15 @@ export function App({ session }) {
         h(Text, { key: `l${i}`, wrap: "truncate-end" }, line === "" ? " " : line)),
     ),
     h(Box, { height: 1 },
-      h(Text, { wrap: "truncate-end" },
-        h(Text, { bold: true }, prompt),
-        input,
-        busy ? h(Text, { dimColor: true }, "…") : h(Text, { inverse: true }, " "),
-      ),
+      (() => {
+        const { before, at, after } = inputCells(input, cursor);
+        return h(Text, { wrap: "truncate-end" },
+          h(Text, { bold: true }, prompt),
+          before,
+          busy ? h(Text, { dimColor: true }, "…") : h(Text, { inverse: true }, at), // caret block over the char at the cursor
+          busy ? null : after,
+        );
+      })(),
     ),
     h(Box, { height: 1 },
       h(Text, { dimColor: true, wrap: "truncate-end" },