simt-dev 0.6.3 → 0.7.1

package/src/locate.mjs

@@ -35,23 +35,47 @@ export function renderLocator(command, { subject = CLI, remedy = `REMEDY run: np
   const D = '$';
   return `# ${D}${BIN_ENV} must name ONE program: an executable on PATH, or a .mjs entry
 # point to hand to node. It cannot be a command line, because there is no safe way
-# to split one in sh without eval, and a value with a space is refused rather than
-# half-executed - running from a source checkout is normal for anyone working on
-# this project itself, so this path has to work with no install step.
+# to split one in sh without eval, and a value with a space that names no file is
+# refused rather than half-executed - running from a source checkout is normal for
+# anyone working on this project itself, so this path has to work with no install step.
+#
+# Every .mjs entry point goes through run_node, which checks for node first: a GUI
+# client's PATH often carries none (nvm is sourced only in an interactive shell), and
+# exec node there fails with 127 and no explanation of what to install.
+run_node() {
+  if ! command -v node >/dev/null 2>&1; then
+    echo "${CLI}: cannot find node to run ${D}1." >&2
+    echo "  the hook runs a .mjs entry point through node; install Node >= 22.20.0," >&2
+    echo "  or set ${BIN_ENV} to an executable ${CLI}" >&2
+    exit 1
+  fi
+  entry="${D}1"
+  shift
+  exec node "${D}entry" "${D}@"
+}
+
 run_simt_dev() {
   case "${D}1" in
     *' '*)
+      # A space is ambiguous as text and unambiguous as a file: a value that names
+      # something on disk is a path in a directory with a space, and runs as one.
+      if [ -f "${D}1" ]; then
+        case "${D}1" in
+          *.mjs)
+            run_node "${D}@"
+            ;;
+          *)
+            exec "${D}@"
+            ;;
+        esac
+      fi
       echo "${CLI}: ${D}${BIN_ENV} names a command line, not a program." >&2
       echo "  set it to a single executable or a .mjs path, e.g." >&2
       echo "    ${BIN_ENV}=/path/to/checkout/${BIN_REL}" >&2
       exit 1
       ;;
     *.mjs)
-      # shift first: "${D}@" still holds ${D}1, which would pass the program path to
-      # itself as the first argument.
-      program="${D}1"
-      shift
-      exec node "${D}program" "${D}@"
+      run_node "${D}@"
       ;;
     *)
       exec "${D}1" "${D}@"
@@ -64,7 +88,7 @@ if [ -n "${D}{${BIN_ENV}:-}" ]; then
 fi
 
 if [ -f "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ]; then
-  exec node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
+  run_node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
 fi
 
 # The binary this repository downloaded for itself: the pinned bytes, no node.

package/src/manifest/schema.mjs

@@ -0,0 +1,213 @@
+// The manifest's own schema: one table of the keys this file may carry, and one
+// loader that says what is wrong with the file rather than throwing or guessing.
+//
+// The manifest was read in 29 places, each doing a bare `JSON.parse` and then
+// reaching for the key it wanted. That is three answers to "what is this repo" -
+// the parse, the key access, and whatever default the caller invented - and a
+// manifest with `"mode": "kernal"` reached the projection as a mode it had never
+// heard of. A typo in one key silently changed behaviour, because nothing in the
+// tool had ever said what the keys are (review 0003 Q69).
+//
+// Every shape below was read off the manifest this repository carries, not from
+// memory: the first draft of this table called `limits.fileLines` a positive integer
+// and `surfaces` an object, and both are wrong in the only file the tool has to hand.
+// `test/manifest-schema.test.mjs` holds the table to that file, which is the check
+// that would have caught it.
+//
+// `owner` is the reason a key is in this table at all. A `tool` key is written by
+// this binary and a repository editing it is fighting the writer; a `repo` key is
+// the repository's own declaration and this tool only reads it. The distinction is
+// already load-bearing (`GENERATED_KEYS`, `init` keeping `limits`), and stating it
+// here is what keeps the two from drifting apart.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+
+/** Absent means 1: the field arrived after the file did, and every file predates it. */
+const MANIFEST_VERSION = 1;
+
+/**
+ * The manifest a repository has, which is not necessarily the one this tool would write.
+ *
+ * The file was renamed from `simt-dev.json` to `simt.json`. Every read site used to say
+ * `join(root, MANIFEST_FILE)` and would have reported an adopted repository as unadopted the
+ * day the constant moved - and "no manifest" means "never adopted", which is the answer
+ * that offers to re-adopt a repo that is already done. Fourteen repositories carry the
+ * old name on disk.
+ *
+ * So the old name is read as a fallback and the new one is written. `writeManifest`
+ * renames rather than creating a second file, which is how the window closes: the first
+ * `simt init` or `simt sync` in an adopted repo retires the old name by moving it.
+ */
+export async function manifestPath(root) {
+  const next = join(root, MANIFEST_FILE);
+  if (existsSync(next)) return next;
+  const previous = join(root, MANIFEST_LEGACY);
+  return existsSync(previous) ? previous : next;
+}
+
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+const isPositiveInt = (value) => Number.isInteger(value) && value > 0;
+
+/**
+ * The keys a manifest may carry.
+ *
+ * `check` returns a sentence naming what is wrong, or null. It returns a sentence
+ * rather than a boolean because the reader of a problem is a person looking at a file
+ * they edited by hand, and "invalid" tells them nothing they did not know.
+ */
+export const KEYS = [
+  { key: '$comment', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (typeof v === 'string' || isStringList(v) ? null : '$comment must be a string or a list of strings') },
+  { key: 'id', owner: 'tool', since: '0.7.0', check: (v) => (typeof v === 'string' && v.length > 0 ? null : 'id must be a non-empty string') },
+  { key: 'version', owner: 'tool', since: '0.9.0', check: (v) => (Number.isInteger(v) && v >= 1 ? null : 'version must be an integer of at least 1') },
+  { key: 'stack', owner: 'tool', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'stack must be a list of profile ids') },
+  { key: 'limits', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'limits must be an object') },
+  // {warn, error, excludeTextFiles, exclude} - ADR-005's two tiers plus the paths a
+  // repository opts out of, all of which the repository owns and `init` keeps.
+  { key: 'limits.fileLines', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) && isPositiveInt(v.warn) && isPositiveInt(v.error) && v.error >= v.warn ? null : 'limits.fileLines must be {warn, error} with error >= warn') },
+  { key: 'limits.coverage', owner: 'repo', since: '0.7.0', check: (v) => (v === null || (typeof v === 'number' && v >= 0 && v <= 100) ? null : 'limits.coverage must be null or a percentage') },
+  { key: 'gates', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'gates must be an object of gate name to command') },
+  { key: 'localSkills', owner: 'repo', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'localSkills must be a list of skill ids') },
+  { key: 'profiles', owner: 'repo', since: '0.8.0', check: (v) => (isStringList(v) ? null : 'profiles must be a list of profile ids') },
+  { key: 'substitutions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'substitutions must be an object keyed by rule id') },
+  { key: 'packs', owner: 'repo', since: '0.8.0', check: (v) => (Array.isArray(v) ? null : 'packs must be a list') },
+  // A workspace declaration is a path relative to the repository; `workspace.mjs`
+  // refuses to walk one that resolves outside, so the type is the whole check.
+  { key: 'workspace', owner: 'repo', since: '0.7.0', check: (v) => (typeof v === 'string' ? null : 'workspace must be a path string') },
+  { key: 'decisions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'decisions must be an object') },
+  { key: 'budget', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'budget must be an object') },
+  { key: 'budget.bytes', owner: 'repo', since: '0.8.0', check: (v) => (isPositiveInt(v) ? null : 'budget.bytes must be a positive integer') },
+  { key: 'mode', owner: 'repo', since: '0.8.0', check: (v) => (v === 'full' || v === 'kernel' ? null : 'mode must be "full" or "kernel", not ' + JSON.stringify(v)) },
+  { key: 'shared', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'shared must be an object') },
+  // The overlay `plan/template.mjs` compiles over the default tracker body; an array
+  // would be accepted by an object-typed read and then produce an empty template.
+  { key: 'plans', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'plans must be an object overlay') },
+  // Null and absent both mean "the global standard applies" (manifestDrift's own
+  // rule), and a list is what `init` writes. An object here is a shape nothing has
+  // ever produced, so accepting it would be the validator blessing a typo.
+  { key: 'surfaces', owner: 'repo', since: '0.8.0', check: (v) => (v === null || isStringList(v) ? null : 'surfaces must be null or a list of surface ids') },
+  { key: 'projection', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (isObject(v) ? null : 'projection must be an object') },
+];
+
+const KNOWABLE = new Set(KEYS.map((entry) => entry.key));
+
+/** The keys this tool writes, derived from the table: the `generated` marks above. */
+export const GENERATED_KEYS_OF = new Set(KEYS.filter((entry) => entry.generated === true).map((entry) => entry.key));
+
+
+/**
+ * Namespaces a consumer registered against this table.
+ *
+ * A namespace is a sub-object of the manifest that another part of the tool owns -
+ * plan 0004's `work` is the first. It registers its keys here rather than editing the
+ * table, so adding one touches two files and no reader has to learn a second shape
+ * (review 0003 Q69).
+ */
+const NAMESPACES = new Map();
+
+/**
+ * Declare the keys of one namespace. Registered keys are checked exactly like top-level
+ * ones; a namespace nobody registered is left alone, because an unknown key has never
+ * been an error in this file.
+ *
+ * @param {string} name the manifest key that carries the namespace
+ * @param {{key: string, since?: string, check: (value: unknown) => string|null}[]} keys
+ * @returns {number} how many keys the namespace declares
+ */
+export function registerNamespace(name, keys) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error('namespace "' + name + '" must be lower-case words joined by hyphens');
+  }
+  if (KNOWABLE.has(name)) throw new Error('namespace "' + name + '" is already a manifest key');
+  if (NAMESPACES.has(name)) throw new Error('namespace "' + name + '" is already registered');
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw new Error('namespace "' + name + '" must register at least one key');
+  }
+  for (const entry of keys) {
+    if (typeof entry?.key !== 'string' || !/^[a-z][a-z0-9]*$/.test(entry.key)) {
+      throw new Error('namespace "' + name + '" keys must be lower-case single words');
+    }
+    if (typeof entry.check !== 'function') {
+      throw new Error('namespace "' + name + '" key "' + entry.key + '" has no check');
+    }
+  }
+  NAMESPACES.set(name, keys.map((entry) => ({ owner: 'repo', since: '0.9.0', ...entry })));
+  return keys.length;
+}
+
+/** The namespaces a consumer declared, for a reader that needs the whole set. */
+export function registeredNamespaces() {
+  return [...NAMESPACES.keys()].sort();
+}
+
+/**
+ * What is wrong with one parsed manifest.
+ *
+ * An unknown key is not a problem. A repository that keeps its own note in this file
+ * is doing the thing the file's own comment invites, and a validator that refused it
+ * would be the tool insisting its schema is the whole of a file it calls the
+ * repository's. Only a KNOWN key with an impossible value is reported.
+ */
+export function manifestProblems(manifest) {
+  const problems = [];
+  for (const { key, check } of KEYS) {
+    const [head, tail] = key.includes('.') ? key.split('.') : [key, null];
+    if (!(head in manifest)) continue;
+    if (tail !== null && (!isObject(manifest[head]) || !(tail in manifest[head]))) continue;
+    const value = tail === null ? manifest[head] : manifest[head][tail];
+    if (value === undefined) continue;
+    const problem = check(value);
+    if (problem !== null) problems.push(problem);
+  }
+  for (const [name, keys] of NAMESPACES) {
+    const value = manifest[name];
+    if (!isObject(value)) continue;
+    for (const entry of keys) {
+      if (!(entry.key in value) || value[entry.key] === undefined) continue;
+      const problem = entry.check(value[entry.key]);
+      if (problem !== null) problems.push(name + '.' + entry.key + ': ' + problem);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The manifest a repository has, with its problems named.
+ *
+ * `manifest` is null when there is no file and when the file does not parse, because
+ * a caller that receives a half-read object cannot tell which it has - and the one
+ * caller that did (`fingerprint`) returned `{error}` in place of a manifest, so a
+ * broken file looked like a declaration of a key called `error` (review 0003 Q69).
+ * `exists` and `problems` are what tell the two apart, and neither is optional.
+ *
+ * @returns {Promise<{manifest: object|null, exists: boolean, version: number, problems: string[], path: string}>}
+ */
+export async function loadManifest(root) {
+  const path = await manifestPath(root);
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    return { manifest: null, exists: false, version: MANIFEST_VERSION, problems: [], path };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: [`unparseable: ${error.message}`], path };
+  }
+  if (!isObject(parsed)) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: ['not a JSON object'], path };
+  }
+  return {
+    manifest: parsed,
+    exists: true,
+    version: Number.isInteger(parsed.version) ? parsed.version : MANIFEST_VERSION,
+    problems: manifestProblems(parsed),
+    path,
+  };
+}

package/src/mcp/resources.mjs

@@ -16,7 +16,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { DECISIONS_DIR, loadDecisions, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
+import { DECISIONS_DIR, loadDecisionsCached, redactEstate, redactInternalPaths } from '../decisions/index.mjs';
 import { planNext } from '../plan/index.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
 import { desiredRegion, loadRules } from '../projection/rules.mjs';
@@ -122,7 +122,9 @@ export async function listResources(root = process.cwd()) {
   const [rules, mdc, { decisions }, region, plan] = await Promise.all([
     loadRules(null),
     loadMdcRules(),
-    loadDecisions({ all: true }),
+    // Q55: the shipped records through the shared cache (root locates the cache
+    // file; the directory stays the package's own, which is what is served).
+    loadDecisionsCached({ root, dir: DECISIONS_DIR, all: true }),
     kernelRegion(root),
     planNext(root, null),
   ]);
@@ -197,26 +199,23 @@ export async function readResource(uri, root = process.cwd()) {
     const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
     const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
     if (rule === undefined) return null;
-    const text = `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim();
-    return {
-      uri,
-      mimeType: 'text/markdown',
-      text,
-      // The body a tool returns is redacted for the same reason: a reader outside this
-      // estate is told what the rule says and not which directory here it is filed in.
-      bytes: Buffer.byteLength(text),
-    };
+    // The body a tool returns is redacted for the same reason: a reader outside this
+    // estate is told what the rule says and not which directory here it is filed in.
+    return { uri, mimeType: 'text/markdown', text: `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim() };
   }
 
   // `loadDecisions` reads the index, not the records: it reports status, currency and
   // byte count, and keeps no body. Reading the file the index named is one read of a
   // record the reader has already asked for by id.
-  const { decisions } = await loadDecisions({ all: true });
+  const { decisions } = await loadDecisionsCached({ root, dir: DECISIONS_DIR, all: true });
   const decision = decisions.find((candidate) => candidate.id === parsed.id);
   if (decision === undefined) return null;
   const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');
   const text = redactInternalPaths(redactEstate(raw)).trim();
-  return { uri, mimeType: 'text/markdown', text, bytes: Buffer.byteLength(text) };
+  // `bytes` is not a `ResourceContents` field: a client validating the result against
+  // the specification sees an unexpected property, and the length is `text.length` away
+  // (Q56).
+  return { uri, mimeType: 'text/markdown', text };
 }
 
 function frontmatterOf(rule) {

package/src/mcp/server.mjs

@@ -24,6 +24,7 @@ import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 import { getPrompt, PROMPTS } from './prompts.mjs';
 import { RESOURCE_TEMPLATES, listResources, readResource } from './resources.mjs';
+import { check } from './schema.mjs';
 
 /**
  * Every protocol revision this server speaks, newest first.
@@ -49,6 +50,8 @@ export const RPC = {
   PARSE: -32700,
   REQUEST: -32600,
   METHOD: -32601,
+  /** Arguments that do not match the `inputSchema` the client was shown. */
+  INVALID_PARAMS: -32602,
   INTERNAL: -32603,
   /**
    * `UnsupportedProtocolVersionError`, renumbered to -32022 in 2026-07-28. The spec
@@ -86,6 +89,15 @@ const SERVER_INFO = { name: 'simt-dev', title: 'SIMT developer and agent tooling
  */
 const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
 
+/**
+ * The largest request line this server will answer, in bytes.
+ *
+ * One mebibyte, because the largest honest argument here is a task description or a path
+ * list and both are kilobytes: a line past this is a malformed request or a stream that
+ * lost its newline, and neither should be parsed in full.
+ */
+const MAX_LINE_BYTES = 1 << 20;
+
 /**
  * Handle one parsed request. Pure with respect to the process: returns the response
  * object or null (for a notification), and never writes anywhere. Testable without a
@@ -103,16 +115,31 @@ const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
  * caller names the root and the default is the process's cwd, which is what an editor's
  * stdio server sits in.
  *
+ * `signal` aborts the one in-flight `tools/call` (wired by `serve` to
+ * `notifications/cancelled`); `notify` emits `notifications/progress` while it
+ * runs. Both are null in tests that call this directly, and every tool must
+ * treat a missing context as "run to completion quietly".
+ *
  * @param {object|null} request a parsed JSON-RPC message
  * @param {object[]} tools
- * @param {{packageVersion?: string, state?: {version: string|null}, root?: string}} options
+ * @param {{packageVersion?: string, state?: {version: string|null}, root?: string, signal?: AbortSignal|null, notify?: ((message: object) => void)|null}} options
  * @returns {Promise<object|null>}
  */
-export async function handle(request, tools, { packageVersion, state, root } = {}) {
+export async function handle(request, tools, { packageVersion, state, root, signal = null, notify = null } = {}) {
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
+  // The envelope is checked before anything reads it. `jsonrpc:"2.0"` and an id that is
+  // a string, a number or absent are the three things every revision requires of a
+  // request. An object id used to be echoed back unchanged, which leaves the client
+  // holding an answer it cannot match to anything it sent (Q56).
+  if (request.jsonrpc !== '2.0') {
+    return error(null, RPC.REQUEST, 'request must carry jsonrpc:"2.0"');
+  }
   const { id, method, params } = request;
+  if (id !== undefined && id !== null && typeof id !== 'string' && typeof id !== 'number') {
+    return error(null, RPC.REQUEST, 'id must be a string, a number or absent');
+  }
   // A notification is a request with no id, and the spec's rule is unconditional: it
   // never gets a response, whatever its method. Answering one anyway desynchronises a
   // client that is waiting for the next real answer in the stream.
@@ -195,23 +222,46 @@ export async function handle(request, tools, { packageVersion, state, root } = {
         return error(id, RPC.METHOD, `no tool named "${name}"; call tools/list first`);
       }
       const args = params?.arguments ?? {};
+      // The schema in `tools/list` is the schema this server enforces. A tool that
+      // declares `required:['name']` and runs happily on `{}` answers a question nobody
+      // asked, and the answer looks like a real one - `skills_show` with no name used to
+      // be a lookup for the string "undefined" (Q56). Bad arguments are the client's
+      // mistake, so they are a protocol error and not a tool result.
+      const invalid = check(args, tool.inputSchema);
+      if (invalid !== null) {
+        return error(id, RPC.INVALID_PARAMS, `invalid arguments for ${name}: ${invalid}`);
+      }
+      // The one impurity in this file, and scoped to it: progress has to reach
+      // the client while the tool runs, not after it returns. Nothing else
+      // writes here - diagnostics still go to stderr, never this stream.
+      const progressToken = params?._meta?.progressToken;
+      const toolCtx = {
+        signal,
+        onProgress:
+          progressToken !== undefined && progressToken !== null && typeof notify === 'function'
+            ? (progress, total) =>
+                notify({
+                  jsonrpc: '2.0',
+                  method: 'notifications/progress',
+                  params: { progressToken, progress, total },
+                })
+            : null,
+      };
       try {
-        const payload = await tool.run(args);
+        const payload = await tool.run(args, toolCtx);
         // Both blocks, always. `structuredContent` is what a client validates against
         // `outputSchema` and what it can index; the text block is what a client that
         // predates structured output reads. Emitting one without the other leaves half
         // the clients guessing, which is the state this release was filed for.
-        return reply({
-          content: [contentOf(payload)],
-          structuredContent: payload,
-          isError: false,
-        });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: false });
       } catch (failure) {
         // An error is a result too, and it carries the same two shapes: the remedy is
         // the part a model needs to act on, and it has to survive in whichever block the
         // client reads.
         const payload = { error: failure.message, remedy: failure.remedy ?? null };
-        return reply({ content: [contentOf(payload)], structuredContent: payload, isError: true });
+        const shaped = bounded(payload);
+        return reply({ content: shaped.content, structuredContent: shaped.structuredContent, isError: true });
       }
     }
 
@@ -259,8 +309,12 @@ export async function handle(request, tools, { packageVersion, state, root } = {
   }
 }
 
+// One entry point, named the way a client names it. This used to spell the CLI command
+// (`simt skills brief`) while the tool description called itself THE entry point and the
+// prompt pointed at `brief` - three answers to "where do I start", and the one a model
+// read first was the only one it could not call (Q56).
 const INSTRUCTIONS =
-  `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`;
+  'Read-only. Every answer is JSON. Call `skills_brief` first: it returns the pre-assembled skill set for a task, plus what it deliberately left out and why, and it needs no index. Call `brief` for the repository packet once the index exists.';
 
 function serverInfo(packageVersion) {
   return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
@@ -348,17 +402,28 @@ function describe(tool, version) {
   return entry;
 }
 
-/** Content is one text block. Bounded, and truncation is announced in the text itself -
- *  the same rule the CLI follows, because a model that cannot tell a truncated answer
- *  from a complete one will guess. */
-function contentOf(payload) {
-  let text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+/** Both blocks, bounded together.
+ *
+ * `maxBytes` used to cut the text block alone, so a client reading `structuredContent`
+ * got the whole payload beside a text block that said it had been truncated: two answers
+ * to one question, and the unannounced one was the larger. A truncated payload is not the
+ * payload, so the structured block says so in its own shape - a model validating against
+ * `outputSchema` reads a complete-looking object as complete and the missing part as
+ * absent, which is the one reading truncation must never produce (Q56). */
+function bounded(payload) {
+  const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
   const limit = typeof payload === 'object' && payload !== null ? payload.maxBytes : 0;
-  if (Number.isInteger(limit) && limit > 0 && Buffer.byteLength(text) > limit) {
-    const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
-    text = `${slice}\nTRUNCATED ${Buffer.byteLength(text) - limit} bytes omitted; raise maxBytes`;
+  const size = Buffer.byteLength(text);
+  if (!Number.isInteger(limit) || limit <= 0 || size <= limit) {
+    return { content: [{ type: 'text', text }], structuredContent: payload };
   }
-  return { type: 'text', text };
+  const slice = Buffer.from(text).subarray(0, limit).toString('utf8');
+  const omitted = size - limit;
+  const cut = `${slice}\nTRUNCATED ${omitted} bytes omitted; raise maxBytes`;
+  return {
+    content: [{ type: 'text', text: cut }],
+    structuredContent: { truncated: true, omittedBytes: omitted, maxBytes: limit, text: cut },
+  };
 }
 
 function result(id, value) {
@@ -384,33 +449,81 @@ function error(id, code, message) {
 export async function serve(tools, { input = process.stdin, output = process.stdout, packageVersion, onError } = {}) {
   const rl = createInterface({ input, crlfDelay: Infinity });
   const state = { version: null };
-  for await (const line of rl) {
-    if (line.trim() === '') continue;
-
-    // Parse and handling fail differently and must answer differently. A line that is
-    // not JSON has no id to answer to, so it is a parse error with `id: null`; a
-    // throw inside `handle` belongs to the request it was answering, so it keeps
-    // that request's id — answering it as a parse error hangs the client that is
-    // still waiting for its answer (Q12).
-    let response;
+  // The in-flight call a `notifications/cancelled` can abort. Read this way
+  // because the loop below is blocked awaiting the tool while the client
+  // decides: the event loop still turns on subprocess waits, so the peek
+  // fires mid-run and the tool checks the signal between rows. The async
+  // iterator below yields the same line afterwards and `handle` answers it
+  // with null, as every notification is answered - the peek consumes nothing.
+  let inflight = null;
+  const peekCancel = (line) => {
+    if (!inflight || line.trim() === '') return;
     let message;
     try {
       message = JSON.parse(line);
-    } catch (parseFailure) {
-      response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
+    } catch {
+      return;
+    }
+    if (message?.method === 'notifications/cancelled' && message?.params?.requestId === inflight.id) {
+      inflight.controller.abort();
     }
-    if (response === undefined) {
+  };
+  rl.on('line', peekCancel);
+  try {
+    for await (const line of rl) {
+      if (line.trim() === '') continue;
+      // readline has already buffered this line, so the cap bounds what is parsed and
+      // answered rather than what is read. That is still the difference between a request
+      // the server refuses by name and one it takes apart for minutes: a 40 MB line used
+      // to reach `JSON.parse` and take the process with it (Q56).
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+        output.write(
+          `${JSON.stringify(error(null, RPC.REQUEST, `request is larger than ${MAX_LINE_BYTES} bytes`))}\n`,
+        );
+        continue;
+      }
+
+      // Parse and handling fail differently and must answer differently. A line that is
+      // not JSON has no id to answer to, so it is a parse error with `id: null`; a
+      // throw inside `handle` belongs to the request it was answering, so it keeps
+      // that request's id — answering it as a parse error hangs the client that is
+      // still waiting for its answer (Q12).
+      let response;
+      let message;
       try {
-        response = await handle(message, tools, { packageVersion, state });
-      } catch (handlerFailure) {
-        const id = message !== null && typeof message === 'object' && 'id' in message ? message.id : null;
-        response = error(id, RPC.INTERNAL, `internal error: ${handlerFailure?.message ?? handlerFailure}`);
+        message = JSON.parse(line);
+      } catch (parseFailure) {
+        response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
+      }
+      if (response === undefined) {
+        // A notification never runs: without an id there is nothing to cancel
+        // and nothing to answer, so `notifications/cancelled` for an idle server
+        // is a no-op rather than an error.
+        const isNotification =
+          message === null || typeof message !== 'object' || Array.isArray(message) || message.id === undefined || message.id === null;
+        const controller = isNotification ? null : new AbortController();
+        if (controller) inflight = { id: message.id, controller };
+        try {
+          response = await handle(message, tools, {
+            packageVersion,
+            state,
+            signal: controller?.signal ?? null,
+            notify: (notification) => output.write(`${JSON.stringify(notification)}\n`),
+          });
+        } catch (handlerFailure) {
+          const id = message !== null && typeof message === 'object' && 'id' in message ? message.id : null;
+          response = error(id, RPC.INTERNAL, `internal error: ${handlerFailure?.message ?? handlerFailure}`);
+        } finally {
+          if (controller) inflight = null;
+        }
       }
+      if (response === null) continue;
+      output.write(`${JSON.stringify(response)}\n`);
     }
-    if (response === null) continue;
-    output.write(`${JSON.stringify(response)}\n`);
+    return EXIT_OK;
+  } finally {
+    rl.off('line', peekCancel);
   }
-  return EXIT_OK;
 }
 
 const EXIT_OK = 0;