teapot-coding-agent 0.29.38 → 0.29.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,6 +15,7 @@ import { effortChoosable } from "./llm.js";
15
15
  import { sessionTitleFrom } from "../session-title.js";
16
16
  import { mcp } from "./mcp-registry.js";
17
17
  import { flattenToolName } from "./mcp-registry.js";
18
+ import { metaToolSpecs } from "./meta-tools.js";
18
19
  import { skillRootsFingerprint, foreignSkillRoots } from "./skills.js";
19
20
  import { bus } from "../bus.js";
20
21
  /**
@@ -2224,6 +2225,365 @@ export class Agent {
2224
2225
  * produces a final answer without tool calls. Returns true if the agent
2225
2226
  * called finish().
2226
2227
  */
2228
+ /**
2229
+ * The meta-tool handlers, keyed by the table's own name union.
2230
+ *
2231
+ * `Record<MetaToolName, …>` is the whole point: because `MetaToolName` is derived from
2232
+ * `META_TOOLS`, advertising a tool without handling it here is a TYPE ERROR rather than a
2233
+ * runtime "unknown tool". That failure used to be silent — the call fell through to
2234
+ * `executeTool`, which answered "unknown tool" for a tool the request had just described.
2235
+ *
2236
+ * Each handler mutates session state and answers its own `tool_call`. The return value is
2237
+ * the only control flow the old if-chain had:
2238
+ * - `"next"` — the `continue` it replaced: this call is done, move to the next one in
2239
+ * the assistant batch;
2240
+ * - `"end"` — the `return true` it replaced (`finish` only): end the whole batch, so a
2241
+ * model that emits finish() plus another call cannot keep mutating the workspace
2242
+ * after reporting completion (#105).
2243
+ */
2244
+ metaHandlers = {
2245
+ finish: async (call, m) => {
2246
+ this.pendingSubReport = ""; // the real summary supersedes it
2247
+ // #128: answer the tool_call BEFORE the audit runs.
2248
+ //
2249
+ // handleFinish() calls the auditor with `buildMessages()`, and at that
2250
+ // moment the history ended at an assistant message carrying
2251
+ // `tool_calls: [finish]` with NO matching `tool` message. Measured, the
2252
+ // auditor received exactly that:
2253
+ //
2254
+ // assistant(tool_calls=[finish])
2255
+ // user(audit prompt) <-- no tool(tool_call_id=…)
2256
+ //
2257
+ // OpenAI-compatible providers require every tool_call to be answered,
2258
+ // and a strict one rejects the request outright — so a CHANGES-REQUIRED
2259
+ // audit would fail with a protocol error rather than a verdict, and
2260
+ // #128's fail-open would then mark the goal done.
2261
+ //
2262
+ // Answering first also makes the log honest: the call really was
2263
+ // completed, it simply did not end the round.
2264
+ await this.answerMeta(call, "(completion submitted for audit)");
2265
+ await this.handleFinish(call.function.arguments);
2266
+ // surface still-running children so the operator knows work may
2267
+ // continue after this agent goes idle
2268
+ try {
2269
+ const running = (this.toolCtx.subAgents?.list?.() ?? []).filter((k) => k.status === "running");
2270
+ if (running.length)
2271
+ await this.log.append("system_note", this.currentSession, this.currentBranch, {
2272
+ event: "subs-still-running",
2273
+ detail: running.map((k) => `${k.id} (${k.status})`).join(", "),
2274
+ });
2275
+ }
2276
+ catch { /* best-effort notice */ }
2277
+ // answer the tool_call so a follow-up round stays API-valid
2278
+ await this.answerMeta(call, this.goal.status === "done" ? "(goal complete)" : "(round ended)");
2279
+ // the caller marks the round finished when this returns "end"
2280
+ // #105: `continue` advanced the TOOL-CALL loop, so every later call in
2281
+ // this same assistant message still executed — a model emitting
2282
+ // finish() plus one more call got real filesystem writes AFTER it had
2283
+ // reported `final: true` and the goal was already done. The parent was
2284
+ // told the work finished while the workspace was still being mutated.
2285
+ //
2286
+ // So finish ends the BATCH: answer anything still outstanding (so no
2287
+ // tool_call is left unpaired — the provider rejects the next request
2288
+ // otherwise, #76) and leave the tool loop. The outer loop then returns
2289
+ // on `finished`.
2290
+ await this.answerUnansweredToolCalls(m);
2291
+ return "end";
2292
+ },
2293
+ report_progress: async (call, m) => {
2294
+ await this.recordProgress(call.function.arguments);
2295
+ await this.answerMeta(call, "progress recorded");
2296
+ return "next";
2297
+ },
2298
+ set_goal: async (call, m) => {
2299
+ const a = safeParse(call.function.arguments);
2300
+ const text = String(a.text ?? "").trim();
2301
+ if (text)
2302
+ await this.setGoal(text);
2303
+ // pi-goal-x-style verification contract: plain-text completion
2304
+ // requirements audited before finish(goalComplete=true) is honored
2305
+ if (typeof a.verify === "string" && a.verify.trim())
2306
+ await this.setGoalVerify(a.verify.trim().slice(0, 4000));
2307
+ await this.answerMeta(call, text ? "goal updated" : "empty goal rejected");
2308
+ return "next";
2309
+ },
2310
+ get_goal: async (call, m) => {
2311
+ await this.answerMeta(call, JSON.stringify({
2312
+ goal: this.goal.text || "(none set)",
2313
+ status: this.goal.status,
2314
+ ...(this.goal.verify ? { verify: this.goal.verify } : {}),
2315
+ ...(this.goal.audit ? { lastAudit: this.goal.audit } : {}),
2316
+ }, null, 1));
2317
+ return "next";
2318
+ },
2319
+ ask_user: async (call, m) => {
2320
+ const a = safeParse(call.function.arguments);
2321
+ const question = String(a.question ?? "").slice(0, 2000);
2322
+ // models sometimes pass objects ({label}, {option}, {value}) —
2323
+ // extract the label instead of rendering "[object Object]" buttons
2324
+ const options = Array.isArray(a.options)
2325
+ ? a.options
2326
+ .slice(0, 6)
2327
+ .map((o) => {
2328
+ if (typeof o === "string")
2329
+ return o;
2330
+ if (o && typeof o === "object") {
2331
+ const obj = o;
2332
+ for (const k of ["label", "option", "choice", "value", "text"])
2333
+ if (typeof obj[k] === "string" && obj[k])
2334
+ return obj[k];
2335
+ }
2336
+ return "";
2337
+ })
2338
+ .filter((o) => o.trim())
2339
+ : [];
2340
+ // the callId lets the UI tell "still open" from "already answered"
2341
+ // (a settled tool_result for this id exists) and disable re-answering
2342
+ await this.log.append("question", this.currentSession, this.currentBranch, {
2343
+ question,
2344
+ options,
2345
+ callId: call.id,
2346
+ });
2347
+ await this.answerMeta(call, "question shown to the operator — the loop is parked until they reply. " +
2348
+ "Their reply (possibly free text, not one of the options) arrives as your next user message.");
2349
+ this.awaitingUser = true;
2350
+ this.setStatus("waiting", question.slice(0, 80));
2351
+ // control flow: park the loop; the operator's next prompt resumes it
2352
+ //
2353
+ // #54: answer the rest of this assistant batch BEFORE parking. The
2354
+ // throw leaves the whole tool loop, so any EARLIER call in the same
2355
+ // message that was logged but not yet run kept no tool_result — the
2356
+ // comment on the backstop below says as much, and it is exactly the
2357
+ // path that bites in practice because ask_user is common.
2358
+ await this.answerUnansweredToolCalls(m);
2359
+ throw Object.assign(new Error("waiting for user"), { name: "WaitForUser" });
2360
+ },
2361
+ get_todo: async (call, m) => {
2362
+ await this.answerMeta(call, this.todo.trim() || "(todo.md is empty — no task list yet)");
2363
+ return "next";
2364
+ },
2365
+ set_todo: async (call, m) => {
2366
+ const a = safeParse(call.function.arguments);
2367
+ // Surgical item changes — no full rewrite, so the operator's own headings and
2368
+ // notes in todo.md survive. `action` decides what to do; `done` is kept as
2369
+ // shorthand so a model that only sends {item, done} still works.
2370
+ const ACTIONS = new Set(["done", "reopen", "add", "remove"]);
2371
+ const updates = Array.isArray(a.updates)
2372
+ ? a.updates
2373
+ .map((u) => {
2374
+ const o = (u ?? {});
2375
+ const raw = String(o.action ?? "");
2376
+ const action = ACTIONS.has(raw)
2377
+ ? raw
2378
+ : undefined;
2379
+ return {
2380
+ item: String(o.item ?? ""),
2381
+ done: o.done !== false,
2382
+ ...(action ? { action } : {}),
2383
+ };
2384
+ })
2385
+ .filter((u) => u.item.trim())
2386
+ : [];
2387
+ if (updates.length > 0) {
2388
+ const note = await this.updateTodoItems(updates, "agent");
2389
+ await this.answerMeta(call, `${note} (visible to the operator)`);
2390
+ return "next";
2391
+ }
2392
+ const content = String(a.content ?? "").slice(0, 32_000);
2393
+ if (!content.trim()) {
2394
+ await this.answerMeta(call, "nothing to do: pass updates:[{item, action}] to change items " +
2395
+ "(action: done | reopen | add | remove), or content to replace the whole list");
2396
+ return "next";
2397
+ }
2398
+ await this.setTodo(content, "agent");
2399
+ await this.answerMeta(call, "task list replaced (visible to the operator)");
2400
+ return "next";
2401
+ },
2402
+ get_feedback: async (call, m) => {
2403
+ const fb = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
2404
+ this.messages.push({
2405
+ role: "tool",
2406
+ tool_call_id: call.id,
2407
+ content: fb.trim() || "(no feedback rules recorded yet)",
2408
+ });
2409
+ return "next";
2410
+ },
2411
+ add_feedback: async (call, m) => {
2412
+ const a = safeParse(call.function.arguments);
2413
+ const rule = String(a.rule ?? "").trim().slice(0, 500);
2414
+ if (!rule) {
2415
+ this.messages.push({ role: "tool", tool_call_id: call.id, content: "rule required" });
2416
+ return "next";
2417
+ }
2418
+ // repeated corrections gain weight: [xN] tag counts occurrences
2419
+ const existing = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
2420
+ const lines = existing.split("\n");
2421
+ const idx = lines.findIndex((l) => l.includes(rule.slice(0, 60)));
2422
+ if (idx !== -1 && /^\s*- /.test(lines[idx])) {
2423
+ const m = lines[idx].match(/\[x(\d+)\]/);
2424
+ const count = m ? Number(m[1]) + 1 : 2;
2425
+ lines[idx] = lines[idx].replace(/\[x\d+\]\s*/, "").replace(/- /, `- [x${count}] `);
2426
+ await fs.writeFile(this.feedbackFile, lines.join("\n"), "utf8");
2427
+ this.messages.push({
2428
+ role: "tool",
2429
+ tool_call_id: call.id,
2430
+ content: `rule already existed — count raised to ${count}. Repeated violations will be enforced more strictly.`,
2431
+ });
2432
+ }
2433
+ else {
2434
+ const entry = `\n- [x1] ${rule}`;
2435
+ await fs.writeFile(this.feedbackFile, existing + (existing ? "\n" : "") + "# Feedback rules\n" + entry, "utf8");
2436
+ this.messages.push({ role: "tool", tool_call_id: call.id, content: "feedback rule recorded — follow it from now on" });
2437
+ }
2438
+ return "next";
2439
+ },
2440
+ record_decision: async (call, m) => {
2441
+ const a = safeParse(call.function.arguments);
2442
+ const decision = String(a.decision ?? "").trim().slice(0, 500);
2443
+ const rationale = String(a.rationale ?? "").trim().slice(0, 2000);
2444
+ const alternatives = Array.isArray(a.alternatives) ? a.alternatives.map(String).slice(0, 5) : [];
2445
+ if (!decision || !rationale) {
2446
+ this.messages.push({
2447
+ role: "tool",
2448
+ tool_call_id: call.id,
2449
+ content: "decision and rationale are both required — record why, not just what",
2450
+ });
2451
+ return "next";
2452
+ }
2453
+ await fs.appendFile(this.decisionsFile, `\n## ${new Date().toISOString()} — ${decision}\n` +
2454
+ `- Why: ${rationale}\n` +
2455
+ (alternatives.length ? `- Alternatives considered:\n${alternatives.map((x) => ` - ${x}`).join("\n")}\n` : ""), "utf8");
2456
+ await this.log.append("decision", this.currentSession, this.currentBranch, {
2457
+ decision,
2458
+ rationale,
2459
+ alternatives,
2460
+ });
2461
+ await this.answerMeta(call, "decision recorded to decisions.md");
2462
+ return "next";
2463
+ },
2464
+ get_decisions: async (call, m) => {
2465
+ const dec = await fs.readFile(this.decisionsFile, "utf8").catch(() => "");
2466
+ this.messages.push({
2467
+ role: "tool",
2468
+ tool_call_id: call.id,
2469
+ content: dec.trim() || "(decisions.md is empty — no decisions recorded yet)",
2470
+ });
2471
+ return "next";
2472
+ },
2473
+ read_memory: async (call, m) => {
2474
+ const a = safeParse(call.function.arguments);
2475
+ const query = String(a.query ?? "").trim();
2476
+ const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2477
+ if (!mem.trim()) {
2478
+ await this.answerMeta(call, "(memory.md is empty — nothing noted yet)");
2479
+ return "next";
2480
+ }
2481
+ // #48: `query` searches instead of dumping the whole file.
2482
+ //
2483
+ // This is the one idea worth taking from the ecosystem. MCP's reference memory
2484
+ // server (the de-facto standard, used by Claude and offered by DSH as a
2485
+ // reference) exposes `search` alongside `read`, and its search is deliberately
2486
+ // a case-insensitive substring match — no embeddings, no model, no provider
2487
+ // dependency. DSH's guidance to the model is the same shape: "when historical
2488
+ // information may be relevant, search memory and use relevant results".
2489
+ //
2490
+ // MEASURED why it matters here: `set_memory` was called 181 times but
2491
+ // `read_memory` only 97 times across every session, and only 13 of those reads
2492
+ // came after a write. Dumping a growing file gives the model no way to ask a
2493
+ // QUESTION, so a big file is all-or-nothing — either burn the whole thing into
2494
+ // the context or do not look at all.
2495
+ if (!query) {
2496
+ await this.answerMeta(call, mem.trim());
2497
+ return "next";
2498
+ }
2499
+ const needle = query.toLowerCase();
2500
+ const hits = mem
2501
+ .split(/\r?\n/)
2502
+ .filter((line) => line.toLowerCase().includes(needle));
2503
+ await this.answerMeta(call, hits.length
2504
+ ? `${hits.length} line(s) matching ${JSON.stringify(query)}:\n${hits.join("\n")}`
2505
+ : `(no line in memory.md matches ${JSON.stringify(query)} — ${mem.split(/\r?\n/).length} lines searched; call read_memory with no query to see all of it)`);
2506
+ return "next";
2507
+ },
2508
+ list_skills: async (call, m) => {
2509
+ await this.refreshSkills();
2510
+ const list = this.skillsCache.length
2511
+ ? this.skillsCache.map((s) => `- ${s.name}: ${s.description || "(no description)"}`).join("\n")
2512
+ : "(no skills yet — create one with save_skill)";
2513
+ await this.answerMeta(call, list);
2514
+ return "next";
2515
+ },
2516
+ set_memory: async (call, m) => {
2517
+ const a = safeParse(call.function.arguments);
2518
+ const content = String(a.content ?? "").slice(0, 32_000);
2519
+ await fs.writeFile(this.memoryFile, content, "utf8");
2520
+ // #48: this used to say "injected into future prompts", which was false —
2521
+ // memory.md is never injected. The model then behaved as if it already held
2522
+ // its notes. Say what actually happened, and what the model must do instead.
2523
+ await this.answerMeta(call, `memory.md REPLACED (${content.length} bytes). It is not in your prompt — call read_memory when you need it.`);
2524
+ return "next";
2525
+ },
2526
+ forget_memory: async (call, m) => {
2527
+ const a = safeParse(call.function.arguments);
2528
+ const query = String(a.query ?? "").trim();
2529
+ if (!query) {
2530
+ await this.answerMeta(call, "forget_memory needs a `query` — nothing removed");
2531
+ return "next";
2532
+ }
2533
+ // #48: notes must be REMOVABLE, not only appendable.
2534
+ //
2535
+ // MCP's reference memory makes observations "added or removed
2536
+ // independently" for exactly this reason: an append-only store accumulates
2537
+ // stale facts ("the build takes 4 minutes" stays long after it takes 40
2538
+ // seconds), and a memory that is confidently wrong is worse than one that is
2539
+ // silent. Without a delete, the only way to correct a file was `set_memory`
2540
+ // with the whole content re-typed — which is how 1028 bytes became 83.
2541
+ const prev = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2542
+ if (!prev.trim()) {
2543
+ await this.answerMeta(call, "(memory.md is empty — nothing to forget)");
2544
+ return "next";
2545
+ }
2546
+ const needle = query.toLowerCase();
2547
+ const kept = [];
2548
+ const removed = [];
2549
+ for (const line of prev.split(/\r?\n/)) {
2550
+ if (line.toLowerCase().includes(needle))
2551
+ removed.push(line);
2552
+ else
2553
+ kept.push(line);
2554
+ }
2555
+ if (removed.length === 0) {
2556
+ await this.answerMeta(call, `(no line in memory.md matches ${JSON.stringify(query)} — nothing removed)`);
2557
+ return "next";
2558
+ }
2559
+ // collapse the blank runs a deletion leaves behind, so the file does not
2560
+ // grow holes
2561
+ const next = kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
2562
+ await fs.writeFile(this.memoryFile, next, "utf8");
2563
+ await this.answerMeta(call, `removed ${removed.length} line(s) from memory.md:\n${removed.join("\n").slice(0, 1_500)}\n` +
2564
+ `(memory.md is now ${next.length} bytes — re-add with add_memory if that was wrong)`);
2565
+ return "next";
2566
+ },
2567
+ add_memory: async (call, m) => {
2568
+ const a = safeParse(call.function.arguments);
2569
+ const text = String(a.text ?? "").trim().slice(0, 8_000);
2570
+ if (!text) {
2571
+ await this.answerMeta(call, "add_memory needs non-empty `text` — nothing appended");
2572
+ return "next";
2573
+ }
2574
+ // APPEND rather than replace (#48). `set_memory` overwrites the whole file,
2575
+ // so a model that had not just read it silently ERASED everything it did not
2576
+ // re-send — MEASURED on a real session: 21 writes, with the content dropping
2577
+ // from 1028 to 83 bytes. Appending is the operation "remember this" actually
2578
+ // wants, and it cannot lose what is already there.
2579
+ const prev = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2580
+ const sep = prev && !prev.endsWith("\n") ? "\n" : "";
2581
+ const next = `${prev}${sep}${text}\n`;
2582
+ await fs.writeFile(this.memoryFile, next.slice(0, 32_000), "utf8");
2583
+ await this.answerMeta(call, `appended to memory.md (now ${next.length} bytes). Not in your prompt — call read_memory to see it.`);
2584
+ return "next";
2585
+ },
2586
+ };
2227
2587
  async runTurnsUntilIdle() {
2228
2588
  let finished = false;
2229
2589
  // maxTurnsPerRound is a SOFT cap (0 disables): reaching it nudges the
@@ -2418,345 +2778,18 @@ export class Agent {
2418
2778
  await this.answerUnansweredToolCalls(m);
2419
2779
  return finished;
2420
2780
  }
2421
- if (call.function.name === "finish") {
2422
- this.pendingSubReport = ""; // the real summary supersedes it
2423
- // #128: answer the tool_call BEFORE the audit runs.
2424
- //
2425
- // handleFinish() calls the auditor with `buildMessages()`, and at that
2426
- // moment the history ended at an assistant message carrying
2427
- // `tool_calls: [finish]` with NO matching `tool` message. Measured, the
2428
- // auditor received exactly that:
2429
- //
2430
- // assistant(tool_calls=[finish])
2431
- // user(audit prompt) <-- no tool(tool_call_id=…)
2432
- //
2433
- // OpenAI-compatible providers require every tool_call to be answered,
2434
- // and a strict one rejects the request outright — so a CHANGES-REQUIRED
2435
- // audit would fail with a protocol error rather than a verdict, and
2436
- // #128's fail-open would then mark the goal done.
2437
- //
2438
- // Answering first also makes the log honest: the call really was
2439
- // completed, it simply did not end the round.
2440
- await this.answerMeta(call, "(completion submitted for audit)");
2441
- await this.handleFinish(call.function.arguments);
2442
- // surface still-running children so the operator knows work may
2443
- // continue after this agent goes idle
2444
- try {
2445
- const running = (this.toolCtx.subAgents?.list?.() ?? []).filter((k) => k.status === "running");
2446
- if (running.length)
2447
- await this.log.append("system_note", this.currentSession, this.currentBranch, {
2448
- event: "subs-still-running",
2449
- detail: running.map((k) => `${k.id} (${k.status})`).join(", "),
2450
- });
2781
+ // Meta tools dispatch through ONE table (src/agent/meta-tools.ts + metaHandlers
2782
+ // above), so a tool the prompt advertises but the loop does not handle is a
2783
+ // COMPILE error rather than a runtime "unknown tool". The two return kinds are the
2784
+ // two the old if-chain had: "next" is the `continue` it replaced, "end" is
2785
+ // finish() ending the whole batch (#105). Anything not in the table is a real tool
2786
+ // and falls through to executeTool below.
2787
+ const meta = this.metaHandlers[call.function.name];
2788
+ if (meta) {
2789
+ if ((await meta(call, m)) === "end") {
2790
+ finished = true;
2791
+ return true;
2451
2792
  }
2452
- catch { /* best-effort notice */ }
2453
- // answer the tool_call so a follow-up round stays API-valid
2454
- await this.answerMeta(call, this.goal.status === "done" ? "(goal complete)" : "(round ended)");
2455
- finished = true;
2456
- // #105: `continue` advanced the TOOL-CALL loop, so every later call in
2457
- // this same assistant message still executed — a model emitting
2458
- // finish() plus one more call got real filesystem writes AFTER it had
2459
- // reported `final: true` and the goal was already done. The parent was
2460
- // told the work finished while the workspace was still being mutated.
2461
- //
2462
- // So finish ends the BATCH: answer anything still outstanding (so no
2463
- // tool_call is left unpaired — the provider rejects the next request
2464
- // otherwise, #76) and leave the tool loop. The outer loop then returns
2465
- // on `finished`.
2466
- await this.answerUnansweredToolCalls(m);
2467
- return true;
2468
- }
2469
- if (call.function.name === "report_progress") {
2470
- await this.recordProgress(call.function.arguments);
2471
- await this.answerMeta(call, "progress recorded");
2472
- continue;
2473
- }
2474
- if (call.function.name === "set_goal") {
2475
- const a = safeParse(call.function.arguments);
2476
- const text = String(a.text ?? "").trim();
2477
- if (text)
2478
- await this.setGoal(text);
2479
- // pi-goal-x-style verification contract: plain-text completion
2480
- // requirements audited before finish(goalComplete=true) is honored
2481
- if (typeof a.verify === "string" && a.verify.trim())
2482
- await this.setGoalVerify(a.verify.trim().slice(0, 4000));
2483
- await this.answerMeta(call, text ? "goal updated" : "empty goal rejected");
2484
- continue;
2485
- }
2486
- if (call.function.name === "get_goal") {
2487
- await this.answerMeta(call, JSON.stringify({
2488
- goal: this.goal.text || "(none set)",
2489
- status: this.goal.status,
2490
- ...(this.goal.verify ? { verify: this.goal.verify } : {}),
2491
- ...(this.goal.audit ? { lastAudit: this.goal.audit } : {}),
2492
- }, null, 1));
2493
- continue;
2494
- }
2495
- if (call.function.name === "ask_user") {
2496
- const a = safeParse(call.function.arguments);
2497
- const question = String(a.question ?? "").slice(0, 2000);
2498
- // models sometimes pass objects ({label}, {option}, {value}) —
2499
- // extract the label instead of rendering "[object Object]" buttons
2500
- const options = Array.isArray(a.options)
2501
- ? a.options
2502
- .slice(0, 6)
2503
- .map((o) => {
2504
- if (typeof o === "string")
2505
- return o;
2506
- if (o && typeof o === "object") {
2507
- const obj = o;
2508
- for (const k of ["label", "option", "choice", "value", "text"])
2509
- if (typeof obj[k] === "string" && obj[k])
2510
- return obj[k];
2511
- }
2512
- return "";
2513
- })
2514
- .filter((o) => o.trim())
2515
- : [];
2516
- // the callId lets the UI tell "still open" from "already answered"
2517
- // (a settled tool_result for this id exists) and disable re-answering
2518
- await this.log.append("question", this.currentSession, this.currentBranch, {
2519
- question,
2520
- options,
2521
- callId: call.id,
2522
- });
2523
- await this.answerMeta(call, "question shown to the operator — the loop is parked until they reply. " +
2524
- "Their reply (possibly free text, not one of the options) arrives as your next user message.");
2525
- this.awaitingUser = true;
2526
- this.setStatus("waiting", question.slice(0, 80));
2527
- // control flow: park the loop; the operator's next prompt resumes it
2528
- //
2529
- // #54: answer the rest of this assistant batch BEFORE parking. The
2530
- // throw leaves the whole tool loop, so any EARLIER call in the same
2531
- // message that was logged but not yet run kept no tool_result — the
2532
- // comment on the backstop below says as much, and it is exactly the
2533
- // path that bites in practice because ask_user is common.
2534
- await this.answerUnansweredToolCalls(m);
2535
- throw Object.assign(new Error("waiting for user"), { name: "WaitForUser" });
2536
- }
2537
- if (call.function.name === "get_todo") {
2538
- await this.answerMeta(call, this.todo.trim() || "(todo.md is empty — no task list yet)");
2539
- continue;
2540
- }
2541
- if (call.function.name === "set_todo") {
2542
- const a = safeParse(call.function.arguments);
2543
- // Surgical item changes — no full rewrite, so the operator's own headings and
2544
- // notes in todo.md survive. `action` decides what to do; `done` is kept as
2545
- // shorthand so a model that only sends {item, done} still works.
2546
- const ACTIONS = new Set(["done", "reopen", "add", "remove"]);
2547
- const updates = Array.isArray(a.updates)
2548
- ? a.updates
2549
- .map((u) => {
2550
- const o = (u ?? {});
2551
- const raw = String(o.action ?? "");
2552
- const action = ACTIONS.has(raw)
2553
- ? raw
2554
- : undefined;
2555
- return {
2556
- item: String(o.item ?? ""),
2557
- done: o.done !== false,
2558
- ...(action ? { action } : {}),
2559
- };
2560
- })
2561
- .filter((u) => u.item.trim())
2562
- : [];
2563
- if (updates.length > 0) {
2564
- const note = await this.updateTodoItems(updates, "agent");
2565
- await this.answerMeta(call, `${note} (visible to the operator)`);
2566
- continue;
2567
- }
2568
- const content = String(a.content ?? "").slice(0, 32_000);
2569
- if (!content.trim()) {
2570
- await this.answerMeta(call, "nothing to do: pass updates:[{item, action}] to change items " +
2571
- "(action: done | reopen | add | remove), or content to replace the whole list");
2572
- continue;
2573
- }
2574
- await this.setTodo(content, "agent");
2575
- await this.answerMeta(call, "task list replaced (visible to the operator)");
2576
- continue;
2577
- }
2578
- if (call.function.name === "get_feedback") {
2579
- const fb = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
2580
- this.messages.push({
2581
- role: "tool",
2582
- tool_call_id: call.id,
2583
- content: fb.trim() || "(no feedback rules recorded yet)",
2584
- });
2585
- continue;
2586
- }
2587
- if (call.function.name === "add_feedback") {
2588
- const a = safeParse(call.function.arguments);
2589
- const rule = String(a.rule ?? "").trim().slice(0, 500);
2590
- if (!rule) {
2591
- this.messages.push({ role: "tool", tool_call_id: call.id, content: "rule required" });
2592
- continue;
2593
- }
2594
- // repeated corrections gain weight: [xN] tag counts occurrences
2595
- const existing = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
2596
- const lines = existing.split("\n");
2597
- const idx = lines.findIndex((l) => l.includes(rule.slice(0, 60)));
2598
- if (idx !== -1 && /^\s*- /.test(lines[idx])) {
2599
- const m = lines[idx].match(/\[x(\d+)\]/);
2600
- const count = m ? Number(m[1]) + 1 : 2;
2601
- lines[idx] = lines[idx].replace(/\[x\d+\]\s*/, "").replace(/- /, `- [x${count}] `);
2602
- await fs.writeFile(this.feedbackFile, lines.join("\n"), "utf8");
2603
- this.messages.push({
2604
- role: "tool",
2605
- tool_call_id: call.id,
2606
- content: `rule already existed — count raised to ${count}. Repeated violations will be enforced more strictly.`,
2607
- });
2608
- }
2609
- else {
2610
- const entry = `\n- [x1] ${rule}`;
2611
- await fs.writeFile(this.feedbackFile, existing + (existing ? "\n" : "") + "# Feedback rules\n" + entry, "utf8");
2612
- this.messages.push({ role: "tool", tool_call_id: call.id, content: "feedback rule recorded — follow it from now on" });
2613
- }
2614
- continue;
2615
- }
2616
- if (call.function.name === "record_decision") {
2617
- const a = safeParse(call.function.arguments);
2618
- const decision = String(a.decision ?? "").trim().slice(0, 500);
2619
- const rationale = String(a.rationale ?? "").trim().slice(0, 2000);
2620
- const alternatives = Array.isArray(a.alternatives) ? a.alternatives.map(String).slice(0, 5) : [];
2621
- if (!decision || !rationale) {
2622
- this.messages.push({
2623
- role: "tool",
2624
- tool_call_id: call.id,
2625
- content: "decision and rationale are both required — record why, not just what",
2626
- });
2627
- continue;
2628
- }
2629
- await fs.appendFile(this.decisionsFile, `\n## ${new Date().toISOString()} — ${decision}\n` +
2630
- `- Why: ${rationale}\n` +
2631
- (alternatives.length ? `- Alternatives considered:\n${alternatives.map((x) => ` - ${x}`).join("\n")}\n` : ""), "utf8");
2632
- await this.log.append("decision", this.currentSession, this.currentBranch, {
2633
- decision,
2634
- rationale,
2635
- alternatives,
2636
- });
2637
- await this.answerMeta(call, "decision recorded to decisions.md");
2638
- continue;
2639
- }
2640
- if (call.function.name === "get_decisions") {
2641
- const dec = await fs.readFile(this.decisionsFile, "utf8").catch(() => "");
2642
- this.messages.push({
2643
- role: "tool",
2644
- tool_call_id: call.id,
2645
- content: dec.trim() || "(decisions.md is empty — no decisions recorded yet)",
2646
- });
2647
- continue;
2648
- }
2649
- if (call.function.name === "read_memory") {
2650
- const a = safeParse(call.function.arguments);
2651
- const query = String(a.query ?? "").trim();
2652
- const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2653
- if (!mem.trim()) {
2654
- await this.answerMeta(call, "(memory.md is empty — nothing noted yet)");
2655
- continue;
2656
- }
2657
- // #48: `query` searches instead of dumping the whole file.
2658
- //
2659
- // This is the one idea worth taking from the ecosystem. MCP's reference memory
2660
- // server (the de-facto standard, used by Claude and offered by DSH as a
2661
- // reference) exposes `search` alongside `read`, and its search is deliberately
2662
- // a case-insensitive substring match — no embeddings, no model, no provider
2663
- // dependency. DSH's guidance to the model is the same shape: "when historical
2664
- // information may be relevant, search memory and use relevant results".
2665
- //
2666
- // MEASURED why it matters here: `set_memory` was called 181 times but
2667
- // `read_memory` only 97 times across every session, and only 13 of those reads
2668
- // came after a write. Dumping a growing file gives the model no way to ask a
2669
- // QUESTION, so a big file is all-or-nothing — either burn the whole thing into
2670
- // the context or do not look at all.
2671
- if (!query) {
2672
- await this.answerMeta(call, mem.trim());
2673
- continue;
2674
- }
2675
- const needle = query.toLowerCase();
2676
- const hits = mem
2677
- .split(/\r?\n/)
2678
- .filter((line) => line.toLowerCase().includes(needle));
2679
- await this.answerMeta(call, hits.length
2680
- ? `${hits.length} line(s) matching ${JSON.stringify(query)}:\n${hits.join("\n")}`
2681
- : `(no line in memory.md matches ${JSON.stringify(query)} — ${mem.split(/\r?\n/).length} lines searched; call read_memory with no query to see all of it)`);
2682
- continue;
2683
- }
2684
- if (call.function.name === "list_skills") {
2685
- await this.refreshSkills();
2686
- const list = this.skillsCache.length
2687
- ? this.skillsCache.map((s) => `- ${s.name}: ${s.description || "(no description)"}`).join("\n")
2688
- : "(no skills yet — create one with save_skill)";
2689
- await this.answerMeta(call, list);
2690
- continue;
2691
- }
2692
- if (call.function.name === "set_memory") {
2693
- const a = safeParse(call.function.arguments);
2694
- const content = String(a.content ?? "").slice(0, 32_000);
2695
- await fs.writeFile(this.memoryFile, content, "utf8");
2696
- // #48: this used to say "injected into future prompts", which was false —
2697
- // memory.md is never injected. The model then behaved as if it already held
2698
- // its notes. Say what actually happened, and what the model must do instead.
2699
- await this.answerMeta(call, `memory.md REPLACED (${content.length} bytes). It is not in your prompt — call read_memory when you need it.`);
2700
- continue;
2701
- }
2702
- if (call.function.name === "forget_memory") {
2703
- const a = safeParse(call.function.arguments);
2704
- const query = String(a.query ?? "").trim();
2705
- if (!query) {
2706
- await this.answerMeta(call, "forget_memory needs a `query` — nothing removed");
2707
- continue;
2708
- }
2709
- // #48: notes must be REMOVABLE, not only appendable.
2710
- //
2711
- // MCP's reference memory makes observations "added or removed
2712
- // independently" for exactly this reason: an append-only store accumulates
2713
- // stale facts ("the build takes 4 minutes" stays long after it takes 40
2714
- // seconds), and a memory that is confidently wrong is worse than one that is
2715
- // silent. Without a delete, the only way to correct a file was `set_memory`
2716
- // with the whole content re-typed — which is how 1028 bytes became 83.
2717
- const prev = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2718
- if (!prev.trim()) {
2719
- await this.answerMeta(call, "(memory.md is empty — nothing to forget)");
2720
- continue;
2721
- }
2722
- const needle = query.toLowerCase();
2723
- const kept = [];
2724
- const removed = [];
2725
- for (const line of prev.split(/\r?\n/)) {
2726
- if (line.toLowerCase().includes(needle))
2727
- removed.push(line);
2728
- else
2729
- kept.push(line);
2730
- }
2731
- if (removed.length === 0) {
2732
- await this.answerMeta(call, `(no line in memory.md matches ${JSON.stringify(query)} — nothing removed)`);
2733
- continue;
2734
- }
2735
- // collapse the blank runs a deletion leaves behind, so the file does not
2736
- // grow holes
2737
- const next = kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
2738
- await fs.writeFile(this.memoryFile, next, "utf8");
2739
- await this.answerMeta(call, `removed ${removed.length} line(s) from memory.md:\n${removed.join("\n").slice(0, 1_500)}\n` +
2740
- `(memory.md is now ${next.length} bytes — re-add with add_memory if that was wrong)`);
2741
- continue;
2742
- }
2743
- if (call.function.name === "add_memory") {
2744
- const a = safeParse(call.function.arguments);
2745
- const text = String(a.text ?? "").trim().slice(0, 8_000);
2746
- if (!text) {
2747
- await this.answerMeta(call, "add_memory needs non-empty `text` — nothing appended");
2748
- continue;
2749
- }
2750
- // APPEND rather than replace (#48). `set_memory` overwrites the whole file,
2751
- // so a model that had not just read it silently ERASED everything it did not
2752
- // re-send — MEASURED on a real session: 21 writes, with the content dropping
2753
- // from 1028 to 83 bytes. Appending is the operation "remember this" actually
2754
- // wants, and it cannot lose what is already there.
2755
- const prev = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
2756
- const sep = prev && !prev.endsWith("\n") ? "\n" : "";
2757
- const next = `${prev}${sep}${text}\n`;
2758
- await fs.writeFile(this.memoryFile, next.slice(0, 32_000), "utf8");
2759
- await this.answerMeta(call, `appended to memory.md (now ${next.length} bytes). Not in your prompt — call read_memory to see it.`);
2760
2793
  continue;
2761
2794
  }
2762
2795
  await this.log.append("tool_call", this.currentSession, this.currentBranch, {
@@ -4197,248 +4230,9 @@ export class Agent {
4197
4230
  * the common case, so the cost of the feature is one empty spread.
4198
4231
  */
4199
4232
  function allToolSpecs() {
4200
- return [
4201
- ...toolSpecs(),
4202
- {
4203
- type: "function",
4204
- function: {
4205
- name: "finish",
4206
- description: "End the current round. Call with goalComplete=true only when the current goal (shown in your prompt) is fully achieved.",
4207
- parameters: {
4208
- type: "object",
4209
- properties: {
4210
- goalComplete: { type: "boolean" },
4211
- summary: { type: "string" },
4212
- },
4213
- },
4214
- },
4215
- },
4216
- {
4217
- type: "function",
4218
- function: {
4219
- name: "report_progress",
4220
- description: "Report current progress to humans: doing, goalStatus, recent attempts, problems, next step.",
4221
- parameters: {
4222
- type: "object",
4223
- properties: {
4224
- doing: { type: "string" },
4225
- goalStatus: { type: "string" },
4226
- recent: { type: "string" },
4227
- problems: { type: "string" },
4228
- next: { type: "string" },
4229
- },
4230
- required: ["doing", "goalStatus", "recent"],
4231
- },
4232
- },
4233
- },
4234
- {
4235
- type: "function",
4236
- function: {
4237
- name: "set_goal",
4238
- description: "Replace the harness-managed goal text. Use when the objective itself changes — not for routine updates. " +
4239
- "Optionally attach a verification contract (plain-text completion requirements); finish(goalComplete=true) " +
4240
- "is then audited against it by an independent reviewer before the goal counts as done.",
4241
- parameters: {
4242
- type: "object",
4243
- properties: {
4244
- text: { type: "string" },
4245
- verify: {
4246
- type: "string",
4247
- description: "completion requirements that must verifiably hold, e.g. 'npm test passes with zero failures; " +
4248
- "the new endpoint appears in README'. Omit for no audit.",
4249
- },
4250
- },
4251
- required: ["text"],
4252
- },
4253
- },
4254
- },
4255
- {
4256
- type: "function",
4257
- function: {
4258
- name: "ask_user",
4259
- description: "Pause and ask the operator a question — plan confirmation, ambiguous requirements, " +
4260
- "a decision only they can make. The loop parks until they reply; their message arrives " +
4261
- "as your next user turn. Use sparingly: do your homework first, then ask once, concretely.",
4262
- parameters: {
4263
- type: "object",
4264
- properties: {
4265
- question: { type: "string", description: "what you need decided — include the context and trade-offs" },
4266
- options: {
4267
- type: "array",
4268
- items: { type: "string" },
4269
- description: "optional short answer choices the operator can tap",
4270
- },
4271
- },
4272
- required: ["question"],
4273
- },
4274
- },
4275
- },
4276
- {
4277
- type: "function",
4278
- function: {
4279
- name: "get_goal",
4280
- description: "Fetch the current goal and its status. Cheap — call at session start, after a compaction notice, or when unsure.",
4281
- parameters: { type: "object", properties: {} },
4282
- },
4283
- },
4284
- {
4285
- type: "function",
4286
- function: {
4287
- name: "record_decision",
4288
- description: "Log a significant choice you made AND why — alternatives considered, trade-offs. Compaction forgets reasoning; this file doesn't.",
4289
- parameters: {
4290
- type: "object",
4291
- properties: {
4292
- decision: { type: "string", description: "what was decided, in one sentence" },
4293
- rationale: { type: "string", description: "why — the reasoning and trade-offs" },
4294
- alternatives: {
4295
- type: "array",
4296
- items: { type: "string" },
4297
- description: "options considered but rejected",
4298
- },
4299
- },
4300
- required: ["decision", "rationale"],
4301
- },
4302
- },
4303
- },
4304
- {
4305
- type: "function",
4306
- function: {
4307
- name: "get_decisions",
4308
- description: "Read previously logged decisions and their rationale (decisions.md).",
4309
- parameters: { type: "object", properties: {} },
4310
- },
4311
- },
4312
- {
4313
- type: "function",
4314
- function: {
4315
- name: "get_feedback",
4316
- description: "Read the operator's feedback rules (corrections they've given you, with repetition counts). Check after being corrected.",
4317
- parameters: { type: "object", properties: {} },
4318
- },
4319
- },
4320
- {
4321
- type: "function",
4322
- function: {
4323
- name: "add_feedback",
4324
- description: "Record a correction as a durable rule (or raise an existing rule's count). Call whenever the operator corrects your behavior so the same mistake isn't repeated.",
4325
- parameters: {
4326
- type: "object",
4327
- properties: { rule: { type: "string", description: "the rule in one imperative sentence" } },
4328
- required: ["rule"],
4329
- },
4330
- },
4331
- },
4332
- {
4333
- type: "function",
4334
- function: {
4335
- name: "get_todo",
4336
- description: "Fetch the operator-maintained task list (todo.md). Check it when picking up work or when unsure what to do next.",
4337
- parameters: { type: "object", properties: {} },
4338
- },
4339
- },
4340
- {
4341
- type: "function",
4342
- function: {
4343
- name: "set_todo",
4344
- description: "Update the operator-visible task list (todo.md). PREFERRED: pass updates to change specific " +
4345
- "items — cheap, surgical, no risk of mangling other sections or the operator's own notes. " +
4346
- "Each entry names an item by its exact text and says what to do: done (default), reopen, " +
4347
- "add, or remove. Only pass content to rewrite the whole list when restructuring it. " +
4348
- "Call this promptly on every item you complete.",
4349
- parameters: {
4350
- type: "object",
4351
- properties: {
4352
- updates: {
4353
- type: "array",
4354
- description: "surgical item changes — match existing items by their exact text in todo.md",
4355
- items: {
4356
- type: "object",
4357
- properties: {
4358
- item: { type: "string", description: "item text (without the \"- [ ]\" marker)" },
4359
- action: {
4360
- type: "string",
4361
- enum: ["done", "reopen", "add", "remove"],
4362
- description: "done = check off (default), reopen = uncheck, add = append a new item " +
4363
- "(works even when nothing matches), remove = delete the line",
4364
- },
4365
- done: { type: "boolean", description: "shorthand for action done/reopen (default true)" },
4366
- },
4367
- required: ["item"],
4368
- },
4369
- },
4370
- content: {
4371
- type: "string",
4372
- description: "full replacement markdown — only for restructures; prefer updates",
4373
- },
4374
- },
4375
- },
4376
- },
4377
- },
4378
- {
4379
- type: "function",
4380
- function: {
4381
- name: "read_memory",
4382
- description: "Read your durable notes (memory.md). Pass `query` to search for the lines that mention something — cheaper than reading the whole file, and the right call when you only need to check one fact.",
4383
- parameters: {
4384
- type: "object",
4385
- properties: {
4386
- query: {
4387
- type: "string",
4388
- description: "case-insensitive substring; omit it to get the whole file",
4389
- },
4390
- },
4391
- },
4392
- },
4393
- },
4394
- {
4395
- type: "function",
4396
- function: {
4397
- name: "forget_memory",
4398
- description: "Delete the lines of memory.md that match a substring. Use it to remove a note that became wrong, or to consolidate duplicates. Returns what was removed, so a mistake is visible and re-addable.",
4399
- parameters: {
4400
- type: "object",
4401
- properties: {
4402
- query: { type: "string", description: "case-insensitive substring of the line(s) to delete" },
4403
- },
4404
- required: ["query"],
4405
- },
4406
- },
4407
- },
4408
- {
4409
- type: "function",
4410
- function: {
4411
- name: "set_memory",
4412
- description: "REPLACE your durable notes (memory.md) entirely — anything you do not include is lost. Prefer add_memory unless you are rewriting the whole file. Keep notes terse: decisions, gotchas, where you left off.",
4413
- parameters: {
4414
- type: "object",
4415
- properties: { content: { type: "string" } },
4416
- required: ["content"],
4417
- },
4418
- },
4419
- },
4420
- {
4421
- type: "function",
4422
- function: {
4423
- name: "add_memory",
4424
- description: "Append one note to memory.md without touching what is already there. Use this to remember a decision, a gotcha, or where you left off — it cannot lose earlier notes (#48).",
4425
- parameters: {
4426
- type: "object",
4427
- properties: { text: { type: "string", description: "the note to append, one or two lines" } },
4428
- required: ["text"],
4429
- },
4430
- },
4431
- },
4432
- {
4433
- type: "function",
4434
- function: {
4435
- name: "list_skills",
4436
- description: "List available skills (name + description). Call before load_skill or to avoid duplicating an existing skill.",
4437
- parameters: { type: "object", properties: {} },
4438
- },
4439
- },
4440
- ...mcpSpecs(),
4441
- ];
4233
+ // meta tools come from ONE table (src/agent/meta-tools.ts) so a declared tool always has
4234
+ // a handler; see the note there for the two silent failure modes this removes.
4235
+ return [...toolSpecs(), ...metaToolSpecs(), ...mcpSpecs()];
4442
4236
  }
4443
4237
  /**
4444
4238
  * MCP tools as function specs, flattened and namespaced.