simt-dev 0.3.1 → 0.5.0

package/src/local/config.mjs

@@ -0,0 +1,269 @@
+// Local model configuration in `simt.json` / `simt-dev.json` (plan 0003 R37, ADR-075, ADR-090).
+//
+// Local models are optional and off by default. When `local` is absent from the manifest,
+// no socket is ever opened. When configured:
+//
+//   "local": {
+//     "chat":  { "url": "http://127.0.0.1:11434/v1", "model": "qwen2.5-coder:7b" },
+//     "embed": { "url": "http://127.0.0.1:11434/v1", "model": "nomic-embed-code" }
+//   }
+//
+// Non-loopback URLs are refused unless `--allow-remote` is explicitly passed (ADR-075).
+
+import { EXIT, fail } from '../output/index.mjs';
+import { MANIFEST_FILE } from '../name.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+
+/** Default per-request timeout for local model probes and requests, in milliseconds. */
+export const DEFAULT_LOCAL_TIMEOUT_MS = 5000;
+
+const ROLES = ['chat', 'embed'];
+
+const IPV4_LOOPBACK = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+
+/**
+ * Whether a parsed URL hostname resolves strictly to the local loopback interface.
+ *
+ * Accepts `localhost` (and `*.localhost`), IPv4 `127.0.0.0/8`, and IPv6 `::1`.
+ * Wildcard bind addresses (`0.0.0.0`, `::`) and LAN/remote hosts return false.
+ */
+export function isLoopbackHost(hostname) {
+  if (typeof hostname !== 'string') return false;
+  const clean = hostname.trim().toLowerCase().replace(/^\[|\]$/g, '');
+  if (!clean) return false;
+  if (clean === 'localhost' || clean.endsWith('.localhost')) return true;
+  if (IPV4_LOOPBACK.test(clean)) return true;
+  if (clean === '::1' || clean === '0:0:0:0:0:0:0:1') return true;
+  return false;
+}
+
+/**
+ * Whether a URL string is a valid HTTP(S) loopback URL with no embedded credentials.
+ */
+export function isLoopbackUrl(urlString) {
+  if (typeof urlString !== 'string' || urlString.trim().length === 0) return false;
+  let parsed;
+  try {
+    parsed = new URL(urlString.trim());
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
+  if (parsed.username !== '' || parsed.password !== '') return false;
+  return isLoopbackHost(parsed.hostname);
+}
+
+/**
+ * Normalise an OpenAI-compatible base URL and append an endpoint path under `/v1`.
+ *
+ * Accepts base URLs written either with or without a trailing `/v1` (for example
+ * `http://127.0.0.1:11434` or `http://127.0.0.1:11434/v1`) so Ollama, llama.cpp
+ * `llama-server`, LM Studio and MLX configs work identically.
+ */
+export function resolveEndpointUrl(baseUrl, endpointPath = '') {
+  const trimmedBase = String(baseUrl ?? '').trim().replace(/\/+$/, '');
+  const baseWithV1 = trimmedBase.endsWith('/v1') ? trimmedBase : `${trimmedBase}/v1`;
+  const cleanPath = String(endpointPath ?? '')
+    .trim()
+    .replace(/^\/+/, '')
+    .replace(/^v1(?:\/+|$)/, '');
+  return cleanPath ? `${baseWithV1}/${cleanPath}` : baseWithV1;
+}
+
+function parseEndpoint(role, entry, { allowRemote = false } = {}) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { endpoint: null, finding: `\`local.${role}\` must be an object with \`url\` and \`model\`` };
+  }
+
+  const rawUrl = typeof entry.url === 'string' ? entry.url.trim() : '';
+  if (!rawUrl) {
+    return { endpoint: null, finding: `\`local.${role}.url\` is required` };
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch {
+    return { endpoint: null, finding: `\`local.${role}.url\` (${rawUrl}) is not a valid URL` };
+  }
+
+  if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.url\` (${rawUrl}) must use http:// or https://`,
+    };
+  }
+
+  if (parsedUrl.username !== '' || parsedUrl.password !== '') {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.url\` must not embed credentials in the URL`,
+    };
+  }
+
+  const model = typeof entry.model === 'string' ? entry.model.trim() : '';
+  if (!model) {
+    return { endpoint: null, finding: `\`local.${role}.model\` is required` };
+  }
+
+  const timeoutMs = entry.timeoutMs === undefined ? DEFAULT_LOCAL_TIMEOUT_MS : entry.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    return {
+      endpoint: null,
+      finding: `\`local.${role}.timeoutMs\` must be a positive whole number`,
+    };
+  }
+
+  const loopback = isLoopbackHost(parsedUrl.hostname);
+  const baseUrl = resolveEndpointUrl(rawUrl, '');
+  const blocked = !loopback && !allowRemote;
+
+  if (blocked) {
+    return {
+      endpoint: {
+        role,
+        url: rawUrl,
+        baseUrl,
+        model,
+        timeoutMs,
+        loopback: false,
+        blocked: true,
+      },
+      remoteBlocked: true,
+      finding: `\`local.${role}.url\` (${rawUrl}) is not a loopback address; non-loopback URLs are refused without --allow-remote (ADR-075)`,
+    };
+  }
+
+  return {
+    endpoint: {
+      role,
+      url: rawUrl,
+      baseUrl,
+      model,
+      timeoutMs,
+      loopback,
+      blocked: false,
+    },
+    remoteBlocked: false,
+    finding: null,
+  };
+}
+
+/**
+ * Parse and validate the `local` block of a manifest. Pure: never opens a file or socket.
+ */
+export function parseLocalConfig(manifest, { allowRemote = false } = {}) {
+  const block = manifest?.local;
+  if (block === undefined || block === null) {
+    return { configured: false, chat: null, embed: null, findings: [], remoteBlocked: false };
+  }
+  if (typeof block !== 'object' || Array.isArray(block)) {
+    return {
+      configured: true,
+      chat: null,
+      embed: null,
+      findings: ['`local` must be an object'],
+      remoteBlocked: false,
+    };
+  }
+
+  const findings = [];
+  let remoteBlocked = false;
+
+  for (const key of Object.keys(block)) {
+    if (!ROLES.includes(key)) {
+      findings.push(`\`local.${key}\` is not a recognised local model role (expected \`chat\` or \`embed\`)`);
+    }
+  }
+
+  const parsedRoles = { chat: null, embed: null };
+  for (const role of ROLES) {
+    const raw = block[role];
+    if (raw === undefined || raw === null) continue;
+    const parsed = parseEndpoint(role, raw, { allowRemote });
+    parsedRoles[role] = parsed.endpoint;
+    if (parsed.remoteBlocked) remoteBlocked = true;
+    if (parsed.finding) findings.push(parsed.finding);
+  }
+
+  const configured =
+    parsedRoles.chat !== null ||
+    parsedRoles.embed !== null ||
+    findings.length > 0;
+
+  return {
+    configured,
+    chat: parsedRoles.chat,
+    embed: parsedRoles.embed,
+    findings,
+    remoteBlocked,
+  };
+}
+
+/**
+ * Read and validate the `local` block from a repository's manifest on disk.
+ */
+export async function readLocalConfig(root, { allowRemote = false } = {}) {
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists) {
+    return {
+      configured: false,
+      chat: null,
+      embed: null,
+      findings: [],
+      remoteBlocked: false,
+      manifestExists: false,
+      manifestError: null,
+    };
+  }
+  if (error !== null || manifest === null) {
+    return {
+      configured: false,
+      chat: null,
+      embed: null,
+      findings: [`${MANIFEST_FILE} is ${error ?? 'unreadable'}`],
+      remoteBlocked: false,
+      manifestExists: true,
+      manifestError: error ?? 'unreadable',
+    };
+  }
+  return {
+    ...parseLocalConfig(manifest, { allowRemote }),
+    manifestExists: true,
+    manifestError: null,
+  };
+}
+
+/**
+ * The guard every model consumer shares (R37's distill, R39's critic and bench).
+ *
+ * A `--local`-shaped call without a usable chat endpoint is a configuration
+ * error, never a silent fallback to the deterministic path: a caller who asked
+ * for the model and got the deterministic answer would read that answer as the
+ * model's — and the reverse, reading model output as deterministic, is worse.
+ * Second real user arrived with the critic, so the guard moved here from the
+ * distiller's `runEngine` (ADR-002).
+ *
+ * Returns `{ chat }` on success or `{ exit }` with the failure already shaped
+ * (the same pass-through shape the command layer returns).
+ */
+export function chatEndpoint(config) {
+  if (config.manifestError !== null) {
+    return { exit: fail(`${MANIFEST_FILE}: ${config.manifestError}`, EXIT.CONFIG) };
+  }
+  if (!config.configured || !config.chat || config.findings.length > 0) {
+    const detail = !config.configured
+      ? 'no local model is configured'
+      : config.remoteBlocked
+        ? 'the configured chat endpoint is non-loopback and was refused'
+        : 'the local configuration has errors';
+    return {
+      exit: fail(
+        `--local needs a usable local chat endpoint: ${detail}`,
+        EXIT.CONFIG,
+        `configure local.chat in ${MANIFEST_FILE} (plan 0003 R37), or run without --local for the deterministic path`,
+      ),
+    };
+  }
+  return { chat: config.chat };
+}

package/src/mcp/tools.mjs

@@ -27,6 +27,10 @@ import { discover } from '../compare/discover.mjs';
 import { buildRow, summarise } from '../compare/row.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { dirtyPaths, parsePathList, readBody } from '../commands/skills.mjs';
+import { assembleBrief } from '../brief/assemble.mjs';
+import { DEFAULT_BRIEF_BYTES } from '../brief/packet.mjs';
+import { readFederation } from '../federation/config.mjs';
+import { consult } from '../federation/query.mjs';
 import { planNext, planDone } from '../plan/index.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 import { measureSkill } from '../graph/load.mjs';
@@ -333,6 +337,47 @@ const output = {
     },
     required: ['root', 'id', 'wouldChange', 'dryRun'],
   },
+  brief: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      kind: { type: 'string' },
+      basis: { type: 'string' },
+      task: { type: 'string' },
+      scope: { type: 'array', items: { type: 'string' } },
+      budget: { type: 'number' },
+      bytes: { type: 'number' },
+      before: { type: 'number' },
+      floorHeld: { type: 'boolean' },
+      cut: { type: 'array', items: { type: 'string' } },
+      sections: { type: 'object', additionalProperties: { type: 'array', items: { type: 'string' } } },
+      text: { type: 'string' },
+    },
+    required: ['root', 'kind', 'basis', 'task', 'scope', 'budget', 'bytes', 'before', 'floorHeld', 'cut', 'sections', 'text'],
+  },
+  federation_query: {
+    type: 'object',
+    properties: {
+      root: { type: 'string' },
+      query: { type: 'string' },
+      servers: { type: 'array', items: { type: 'string' } },
+      answers: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            server: { type: 'string' },
+            tool: { type: 'string' },
+            query: { type: 'string' },
+            text: { type: 'string' },
+          },
+          required: ['server', 'tool', 'query', 'text'],
+        },
+      },
+      findings: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['root', 'query', 'servers', 'answers', 'findings'],
+  },
   /** The shape of every tool failure, which is a result and not a protocol error. */
   error: ERROR_SHAPE,
 };
@@ -624,7 +669,7 @@ export const TOOLS = [
       const { decisions } = await loadDecisions();
       const index = byId(decisions);
 
-      if (/^ADR-\d{3}$/i.test(what)) {
+      if (/^ADR-\d{3,}$/i.test(what)) {
         const id = what.toUpperCase();
         const d = decisions.find((x) => x.id === id);
         if (!d) throw new Error(`no decision record ${id}`);
@@ -772,6 +817,98 @@ export const TOOLS = [
       };
     },
   },
+  {
+    outputSchema: output.brief,
+    name: 'brief',
+    description:
+      'The packet for one task, in the bytes a prompt can carry: the kind of task it is, the commands that kind needs, the files the index ranks highest, the tests that cover them, the decisions that govern them, the skills that apply and the lessons that name those paths. Every argument is optional - with no task it describes the repository itself.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        task: { type: 'string', description: "what the agent is about to do, in the user's own words" },
+        paths: { type: 'string', description: 'comma-separated paths to scope the packet to, instead of the files git reports as modified' },
+        budget: { type: 'number', description: 'byte ceiling; 0 means the whole packet (default 2048)' },
+      },
+      required: [],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const budget = Number.isFinite(args?.budget) && args.budget >= 0 ? args.budget : DEFAULT_BRIEF_BYTES;
+      // Read, never build: every tool here declares itself read-only, and a call that
+      // indexed the tree would make that declaration false. A brief with no index to read
+      // says which command makes one - the same rule the delivered packet follows, so a
+      // pull and a push pay the same price and neither one writes.
+      const result = await assembleBrief({
+        root,
+        task: typeof args?.task === 'string' ? args.task : '',
+        paths: typeof args?.paths === 'string' ? args.paths : null,
+        budget,
+        build: false,
+      });
+      if (result.error) throw Object.assign(new Error('the index could not be read'), { remedy: `run: ${CLI} index` });
+      if (result.cold) throw Object.assign(new Error('this repository has no index to answer from'), { remedy: `run: ${CLI} index` });
+      return {
+        root: result.root,
+        kind: result.kind,
+        basis: result.basis,
+        task: result.task,
+        scope: result.scope,
+        budget: result.budget,
+        bytes: result.packed.after,
+        before: result.packed.before,
+        floorHeld: result.packed.floorHeld,
+        cut: result.packed.cut,
+        sections: result.sections,
+        text: result.packed.text,
+      };
+    },
+  },
+  {
+    outputSchema: output.federation_query,
+    name: 'federation_query',
+    description:
+      'Ask a code-graph server this repository declared one structural question, and return its answer with the name of the server that gave it. Read-only: it reads the "federation" block from simt.json and starts only the servers the manifest itself names, and a repository that declared none is told so rather than queried.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root: { type: 'string', description: 'repository root; defaults to the editor cwd' },
+        query: { type: 'string', description: "the structural question to ask, in the user's own words" },
+        server: { type: 'string', description: 'ask only this declared server, by name; omit to ask every one of them' },
+      },
+      required: ['query'],
+    },
+    async run(args) {
+      const root = rootOf(args);
+      const query = typeof args?.query === 'string' ? args.query.trim() : '';
+      if (query.length === 0) {
+        throw Object.assign(new Error('the query is empty'), {
+          remedy: 'pass a query, for example the symbol or file to look up',
+        });
+      }
+      const { servers, findings } = await readFederation(root);
+      if (servers.length === 0) {
+        throw Object.assign(new Error('this repository declares no federation server'), {
+          remedy: 'add a "federation" block naming a server to simt.json, or use the brief tool',
+        });
+      }
+      const only = typeof args?.server === 'string' && args.server.length > 0 ? args.server : null;
+      const chosen = only === null ? servers : servers.filter((server) => server.name === only);
+      if (only !== null && chosen.length === 0) {
+        throw Object.assign(new Error(`no declared federation server is named ${only}`), {
+          remedy: `declared servers: ${servers.map((server) => server.name).join(', ')}`,
+        });
+      }
+      const { answers, findings: failures } = await consult({ root, query, servers: chosen });
+      return {
+        root,
+        query,
+        servers: chosen.map((server) => server.name),
+        answers,
+        findings: [...findings, ...failures],
+      };
+    },
+  },
 ];
 
 export function toolNames() {