simt-dev 0.7.1 → 0.8.0

package/src/agents/render.mjs

@@ -25,9 +25,12 @@ import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { PACKAGE_ROOT } from '../workspace.mjs';
-import { splitFrontmatter } from '../memory/decide.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 import { LOADERS } from '../projection/loaders.mjs';
 import { journaledWriteFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
+import { readBefore } from '../diff.mjs';
+import { readIfExists } from '../util/fs.mjs';
 
 /** The one agent this tool ships, and the filename stem every harness shares. */
 const AGENT_FILE = 'simt-agent.md';
@@ -149,7 +152,7 @@ function parseSimpleFront(front) {
  */
 export async function loadAgent() {
   const raw = await readFile(join(PACKAGE_ROOT, 'agents', AGENT_FILE), 'utf8');
-  const { front, body } = splitFrontmatter(raw);
+  const { front, body } = parseFrontmatter(raw);
   const meta = parseSimpleFront(front ?? '');
   if (!meta.name || !meta.description) {
     throw new Error(`${AGENT_FILE} must declare a name and a description in its frontmatter`);
@@ -213,15 +216,6 @@ export function rendered(adapterRow, agent, existing) {
   return { text, action: 'updated' };
 }
 
-/** Read a file as UTF-8, or null when it is not there. */
-async function readIfExists(path) {
-  try {
-    return await readFile(path, 'utf8');
-  } catch {
-    return null;
-  }
-}
-
 /**
  * The agent files a repository should carry, one per harness that documents an
  * agents directory, plus the companion skill file. Reads each existing file and
@@ -252,13 +246,16 @@ export async function planAgents(root, { harness } = {}) {
  * Skips files that are already unchanged. Returns the paths written.
  */
 export async function writeAgentPlan(root, journal, plan) {
-  const written = [];
-  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
-    await mkdir(join(root, dirname(p.path)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, p.path), p.text);
-    written.push(p.path);
-  }
-  return written;
+  const changes = await Promise.all(
+    plan
+      .filter((x) => x.action !== 'unchanged')
+      .map(async (p) => {
+        const path = join(root, p.path);
+        return change({ path, before: await readBefore(path), after: p.text, owner: 'agents', reason: p.action });
+      }),
+  );
+  await applyPlan(root, changes, { mode: { apply: true }, journal, commit: false });
+  return plan.filter((x) => x.action !== 'unchanged').map((p) => p.path);
 }
 
 /**

package/src/api.mjs

@@ -6,16 +6,18 @@
 // same question must not get three answers, and they cannot disagree if they are
 // reading one function's return value.
 //
-// This is the read half only. The commands that write (`init`, `sync`, `hooks
-// install`, `skills install`, `upgrade`) still print their plans from the command
-// module, because their output is a diff a person reviews before it is applied
-// (ADR-001). They migrate in the next slice, when `run(ctx, input)` exists to carry
-// a plan back to a caller that can show it.
+// The write half arrives through `run(command, input)`: a writer still renders its plan
+// from the command module, because a person reviews that diff before it is applied
+// (ADR-001), but a library caller now gets that plan back as text and documents instead
+// of having it printed at a terminal it does not own. `run` resolves the same registry
+// and calls the same handler `dispatch` does, so the two surfaces cannot answer
+// differently.
 //
 // The exports map in package.json points `import 'simt-dev'` here, and keeps
 // `./src/*` because the plugin runtime and the harness shims import deep paths.
 // Removing that subpath would break them to make the surface look tidier.
 
+export { run, renderText, renderJson } from './run.mjs';
 export { checkRepo, checkTargets, checkTarget, frozenFindings } from './commands/sync.mjs';
 export { diagnose, serialisedFindings } from './commands/doctor.mjs';
 export { rulesCatalogue, rulesWhyFacts } from './commands/rules.mjs';

package/src/argv.mjs

@@ -44,6 +44,14 @@ export const BOOL_FLAGS = new Set([
   'pretty',
   'accept-conflicts',
   'backup',
+  // init: opt out of the agent files and the agent-hooks in one flag. The parser's
+  // `no-` convention spells the flag as a negation of the positive `agents`, so the
+  // positive name is what belongs here and `init` reads `flags.agents === false` -
+  // the user-facing flag stays `--no-agents`. They are the two halves of the same
+  // decision - which harnesses the adoption speaks to - and the standalone agents /
+  // agent-hooks install commands remain for a repo that wants them later. Off by
+  // default because the adoption writes them by default.
+  'agents',
   'list',
   // tokens: measure every repository under the root, not just the one. Plan 0003 R06
   // names this flag `--workspace`, and that name has been a VALUE flag since plan
@@ -196,6 +204,10 @@ export const VALUE_FLAGS = new Set([
   // name only the author's branch knows, and the default (origin/main, then main)
   // is a guess the report states out loud rather than a question it asks.
   'base',
+  // slice start: the id for a prompt slice, overriding the slug derived from the
+  // prompt text. A value, because the derived slug is a guess a reader may want to
+  // pin, and a flag without a value would not say what to name the slice.
+  'id',
 ]);
 
 /**
@@ -241,6 +253,11 @@ export function parse(argv) {
   const flags = {};
   const positional = [];
   let passthrough = false;
+  // `--` is consumed as a separator, but its presence is a fact a command may need:
+  // `slice start -- "<text>"` reads the prompt as everything after the marker, and a
+  // positional that merely happens to sit there is a different command. Carried as a
+  // flag so it reaches the command the way every other parsed fact does.
+  let dashdash = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -251,6 +268,7 @@ export function parse(argv) {
     }
     if (arg === '--') {
       passthrough = true;
+      dashdash = true;
       continue;
     }
 
@@ -316,6 +334,7 @@ export function parse(argv) {
     return { ok: false, error: usage(`unknown flag --${raw}`) };
   }
 
+  if (dashdash) flags.dashdash = true;
   return { ok: true, value: { flags, positional } };
 }
 

package/src/bench/ablate.mjs

@@ -19,15 +19,14 @@ import { plan } from '../projection/project.mjs';
 import { isEligible, loadRules, readDeclared, ruleValues, select } from '../projection/rules.mjs';
 import { resolveSurfaces, rulePath, SURFACES } from '../projection/surfaces.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { evaluateRunRecord, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
 import {
   DEFAULT_BOOTSTRAP_SAMPLES,
   DEFAULT_BOOTSTRAP_SEED,
   compareArms,
-  evaluateRunRecord,
   holmAdjust,
-  loadPrices,
-  loadRunRecords,
-} from './report.mjs';
+} from '../measure/stats.mjs';
 
 export const DEFAULT_CANARY_SIZE = 10;
 export const DEL_R_TOLERANCE = 0.01;

package/src/bench/adapters.json

@@ -1,165 +1,207 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "adapters": {
     "claude": {
       "id": "claude",
       "label": "Claude Code",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "claude",
-      "template": "claude -p \"{prompt}\" --output-format json --max-turns {turns}",
-      "args": ["-p", "{prompt}", "--output-format", "json", "--max-turns", "{turns}"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "json",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["-p", "{prompt}", "--output-format", "json", "--max-turns", "{turns}"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["ANTHROPIC_API_KEY"] },
       "isolation": "env",
-      "env": ["ANTHROPIC_API_KEY"],
-      "usageSource": "usage.*, total_cost_usd, num_turns",
-      "fields": {
-        "input": ["usage.input_tokens", "usage.input"],
-        "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cacheWrite"],
-        "cacheRead": ["usage.cache_read_input_tokens", "usage.cacheRead"],
-        "output": ["usage.output_tokens", "usage.output"],
-        "turns": ["num_turns", "usage.turns"],
-        "toolCalls": ["num_tool_calls", "tool_calls", "usage.toolCalls"],
-        "costUsd": ["total_cost_usd", "cost_usd", "costUsd"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "json",
+        "fields": {
+          "input": ["usage.input_tokens", "usage.input"],
+          "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cacheWrite"],
+          "cacheRead": ["usage.cache_read_input_tokens", "usage.cacheRead"],
+          "output": ["usage.output_tokens", "usage.output"],
+          "turns": ["num_turns", "usage.turns"],
+          "toolCalls": ["num_tool_calls", "tool_calls", "usage.toolCalls"],
+          "costUsd": ["total_cost_usd", "cost_usd", "costUsd"]
+        }
+      },
+      "transcript": { "sources": ["stdout"] }
     },
     "codex": {
       "id": "codex",
       "label": "Codex",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "codex",
-      "template": "codex exec --json \"{prompt}\"",
-      "args": ["exec", "--json", "{prompt}"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "jsonl",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["exec", "--json", "{prompt}"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["OPENAI_API_KEY"] },
       "isolation": "env",
-      "env": ["OPENAI_API_KEY"],
-      "usageSource": "token events in JSONL",
-      "fields": {
-        "input": ["usage.input_tokens", "input_tokens", "usage.input"],
-        "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cache_write_input_tokens", "cache_write_input_tokens"],
-        "cacheRead": ["usage.cached_input_tokens", "usage.cache_read_input_tokens", "cached_input_tokens"],
-        "output": ["usage.output_tokens", "output_tokens", "usage.output"],
-        "turns": ["turns", "num_turns"],
-        "toolCalls": ["tool_calls", "num_tool_calls"],
-        "costUsd": ["total_cost_usd", "cost_usd", "cost"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "jsonl",
+        "fields": {
+          "input": ["usage.input_tokens", "input_tokens", "usage.input"],
+          "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cache_write_input_tokens", "cache_write_input_tokens"],
+          "cacheRead": ["usage.cached_input_tokens", "usage.cache_read_input_tokens", "cached_input_tokens"],
+          "output": ["usage.output_tokens", "output_tokens", "usage.output"],
+          "turns": ["turns", "num_turns"],
+          "toolCalls": ["tool_calls", "num_tool_calls"],
+          "costUsd": ["total_cost_usd", "cost_usd", "cost"]
+        },
+        "events": {
+          "turns": [{ "type": "turn.completed" }],
+          "toolCalls": [
+            { "type": "item.completed", "item.type": ["command_execution", "tool_call", "mcp_tool_call"] }
+          ]
+        }
+      },
+      "transcript": { "sources": ["stdout"] }
     },
     "gemini": {
       "id": "gemini",
       "label": "Gemini CLI",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "gemini",
-      "template": "gemini -p \"{prompt}\" --output-format json",
-      "args": ["-p", "{prompt}", "--output-format", "json"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "json",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["-p", "{prompt}", "--output-format", "json"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["GEMINI_API_KEY", "GOOGLE_API_KEY"] },
       "isolation": "env",
-      "env": ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
-      "usageSource": "stats block",
-      "fields": {
-        "input": ["stats.inputTokens", "stats.tokens.prompt", "stats.prompt_tokens", "usage.input_tokens"],
-        "cacheWrite": ["stats.cacheWriteTokens", "stats.tokens.cacheWrite", "usage.cache_creation_input_tokens"],
-        "cacheRead": ["stats.cachedTokens", "stats.tokens.cached", "usage.cache_read_input_tokens"],
-        "output": ["stats.outputTokens", "stats.tokens.candidates", "stats.completion_tokens", "usage.output_tokens"],
-        "turns": ["stats.turns", "stats.totalTurns", "num_turns"],
-        "toolCalls": ["stats.toolCalls", "stats.tools.totalCalls", "num_tool_calls"],
-        "costUsd": ["stats.totalCostUsd", "stats.costUsd", "total_cost_usd"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "json",
+        "fields": {
+          "input": ["stats.inputTokens", "stats.tokens.prompt", "stats.prompt_tokens", "usage.input_tokens"],
+          "cacheWrite": ["stats.cacheWriteTokens", "stats.tokens.cacheWrite", "usage.cache_creation_input_tokens"],
+          "cacheRead": ["stats.cachedTokens", "stats.tokens.cached", "usage.cache_read_input_tokens"],
+          "output": ["stats.outputTokens", "stats.tokens.candidates", "stats.completion_tokens", "usage.output_tokens"],
+          "turns": ["stats.turns", "stats.totalTurns", "num_turns"],
+          "toolCalls": ["stats.toolCalls", "stats.tools.totalCalls", "num_tool_calls"],
+          "costUsd": ["stats.totalCostUsd", "stats.costUsd", "total_cost_usd"]
+        },
+        "totals": [
+          {
+            "root": "stats.models",
+            "keys": { "input": "tokens.prompt", "cacheRead": "tokens.cached", "output": "tokens.candidates" }
+          }
+        ]
+      },
+      "transcript": { "sources": ["stdout"] }
     },
     "opencode": {
       "id": "opencode",
       "label": "opencode",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "opencode",
-      "template": "opencode run \"{prompt}\"",
-      "args": ["run", "--format", "json", "{prompt}"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "jsonl",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["run", "--format", "json", "{prompt}"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"] },
       "isolation": "env",
-      "env": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
-      "usageSource": "session export",
-      "fields": {
-        "input": ["tokens.input", "usage.input_tokens", "part.tokens.input"],
-        "cacheWrite": ["tokens.cache.write", "usage.cache_creation_input_tokens", "part.tokens.cache.write"],
-        "cacheRead": ["tokens.cache.read", "usage.cache_read_input_tokens", "part.tokens.cache.read"],
-        "output": ["tokens.output", "usage.output_tokens", "part.tokens.output"],
-        "turns": ["turns", "num_turns"],
-        "toolCalls": ["toolCalls", "num_tool_calls"],
-        "costUsd": ["cost", "part.cost", "total_cost_usd"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "jsonl",
+        "fields": {
+          "input": ["tokens.input", "usage.input_tokens", "part.tokens.input"],
+          "cacheWrite": ["tokens.cache.write", "usage.cache_creation_input_tokens", "part.tokens.cache.write"],
+          "cacheRead": ["tokens.cache.read", "usage.cache_read_input_tokens", "part.tokens.cache.read"],
+          "output": ["tokens.output", "usage.output_tokens", "part.tokens.output"],
+          "turns": ["turns", "num_turns"],
+          "toolCalls": ["toolCalls", "num_tool_calls"],
+          "costUsd": ["cost", "part.cost", "total_cost_usd"]
+        },
+        "events": {
+          "turns": [{ "type": "step_finish" }, { "event": "message_send" }],
+          "toolCalls": [{ "type": "tool_use" }]
+        }
+      },
+      "transcript": { "sources": ["stdout"] }
     },
     "cursor": {
       "id": "cursor",
       "label": "Cursor CLI",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "cursor-agent",
-      "template": "cursor-agent -p \"{prompt}\" --output-format json",
-      "args": ["-p", "{prompt}", "--output-format", "json"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "json",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["-p", "{prompt}", "--output-format", "json"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["CURSOR_API_KEY"] },
       "isolation": "env",
-      "env": ["CURSOR_API_KEY"],
-      "usageSource": "result JSON",
-      "fields": {
-        "input": ["usage.input_tokens", "usage.input", "stats.inputTokens"],
-        "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cacheWrite", "stats.cacheWriteTokens"],
-        "cacheRead": ["usage.cache_read_input_tokens", "usage.cacheRead", "stats.cachedTokens"],
-        "output": ["usage.output_tokens", "usage.output", "stats.outputTokens"],
-        "turns": ["num_turns", "turns", "usage.turns"],
-        "toolCalls": ["num_tool_calls", "tool_calls", "usage.toolCalls", "toolCalls"],
-        "costUsd": ["total_cost_usd", "costUsd", "cost_usd"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "json",
+        "fields": {
+          "input": ["usage.input_tokens", "usage.input", "stats.inputTokens"],
+          "cacheWrite": ["usage.cache_creation_input_tokens", "usage.cacheWrite", "stats.cacheWriteTokens"],
+          "cacheRead": ["usage.cache_read_input_tokens", "usage.cacheRead", "stats.cachedTokens"],
+          "output": ["usage.output_tokens", "usage.output", "stats.outputTokens"],
+          "turns": ["num_turns", "turns", "usage.turns"],
+          "toolCalls": ["num_tool_calls", "tool_calls", "usage.toolCalls", "toolCalls"],
+          "costUsd": ["total_cost_usd", "costUsd", "cost_usd"]
+        }
+      },
+      "transcript": { "sources": ["stdout"] }
     },
     "aider": {
       "id": "aider",
       "label": "Aider",
-      "kind": "cli",
+      "kind": "agent",
       "bin": "aider",
-      "template": "aider --message \"{prompt}\" --yes-always",
-      "args": ["--message", "{prompt}", "--yes-always", "--analytics-log", "{analyticsLog}"],
-      "modelArgs": ["--model", "{model}"],
-      "format": "analytics-log",
+      "prompt": {
+        "delivery": "argv",
+        "args": ["--message", "{prompt}", "--yes-always", "--analytics-log", "{analyticsLog}"],
+        "modelArgs": ["--model", "{model}"]
+      },
+      "env": { "allow": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"] },
       "isolation": "env",
-      "env": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
-      "usageSource": "--analytics-log file",
-      "fields": {
-        "input": ["prompt_tokens", "properties.prompt_tokens", "usage.input_tokens"],
-        "cacheWrite": ["cache_creation_input_tokens", "properties.cache_write_tokens"],
-        "cacheRead": ["cache_read_input_tokens", "properties.cache_read_tokens"],
-        "output": ["completion_tokens", "properties.completion_tokens", "usage.output_tokens"],
-        "turns": ["turns", "properties.turns"],
-        "toolCalls": ["tool_calls", "properties.tool_calls"],
-        "costUsd": ["cost", "total_cost", "properties.cost", "properties.total_cost"]
-      }
+      "timeoutMs": 120000,
+      "usage": {
+        "format": "analytics-log",
+        "fields": {
+          "input": ["prompt_tokens", "properties.prompt_tokens", "usage.input_tokens"],
+          "cacheWrite": ["cache_creation_input_tokens", "properties.cache_write_tokens"],
+          "cacheRead": ["cache_read_input_tokens", "properties.cache_read_tokens"],
+          "output": ["completion_tokens", "properties.completion_tokens", "usage.output_tokens"],
+          "turns": ["turns", "properties.turns"],
+          "toolCalls": ["tool_calls", "properties.tool_calls"],
+          "costUsd": ["cost", "total_cost", "properties.cost", "properties.total_cost"]
+        }
+      },
+      "transcript": { "sources": ["stdout", "analytics"] }
     },
     "gold": {
       "id": "gold",
       "label": "Gold Oracle",
-      "kind": "builtin",
+      "kind": "oracle",
+      "oracle": { "from": "vault" },
       "bin": null,
-      "template": null,
-      "args": [],
-      "modelArgs": [],
-      "format": "builtin",
+      "prompt": { "delivery": "argv", "args": [], "modelArgs": [] },
+      "env": { "allow": [] },
       "isolation": "none",
-      "env": [],
-      "usageSource": "vault gold.patch",
-      "fields": {}
+      "usage": { "format": "none", "fields": {}, "fixed": { "turns": 1, "toolCalls": 1 } },
+      "transcript": { "sources": [] }
     },
     "noop": {
       "id": "noop",
       "label": "No-op Baseline",
-      "kind": "builtin",
+      "kind": "oracle",
+      "oracle": { "from": "none" },
       "bin": null,
-      "template": null,
-      "args": [],
-      "modelArgs": [],
-      "format": "builtin",
+      "prompt": { "delivery": "argv", "args": [], "modelArgs": [] },
+      "env": { "allow": [] },
       "isolation": "none",
-      "env": [],
-      "usageSource": "none",
-      "fields": {}
+      "usage": { "format": "none", "fields": {} },
+      "transcript": { "sources": [] }
     }
   }
 }