teapot-coding-agent 0.29.28 → 0.29.30

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.
@@ -13,6 +13,8 @@ import { chat, chatStream } from "./llm.js";
13
13
  import { executeTool, toolSpecs, currentSkills, safeJoin, isContextOverflow, hasRunningBgShells, killBgShells } from "./tools.js";
14
14
  import { effortChoosable } from "./llm.js";
15
15
  import { sessionTitleFrom } from "../session-title.js";
16
+ import { mcp } from "./mcp-registry.js";
17
+ import { flattenToolName } from "./mcp-registry.js";
16
18
  import { skillRootsFingerprint, foreignSkillRoots } from "./skills.js";
17
19
  import { bus } from "../bus.js";
18
20
  /**
@@ -98,6 +100,22 @@ const KEEP_RECENT_TOKENS = 15_000;
98
100
  * configured for.
99
101
  */
100
102
  const PRUNE_AT_SHARE = 0.95;
103
+ /**
104
+ * Short-context mode (#161): the same knobs, retuned for a window where the default
105
+ * tail is a large share of everything.
106
+ *
107
+ * Measured reasoning, not a guess: `KEEP_RECENT_TOKENS` is 15k, which is 5.7% of a
108
+ * 262k window (fine) but 47% of a 32k one — so on a small model the verbatim tail
109
+ * alone nearly fills the budget and the first prune does almost nothing useful.
110
+ * The mode therefore (a) prunes at 0.6 of the budget instead of 0.95, (b) keeps a
111
+ * QUARTER of the budget verbatim instead of a fixed 15k, and (c) clips tool results
112
+ * down to 200 chars instead of 400, because on a small window the head of an output
113
+ * is most of what fits.
114
+ *
115
+ * Opt-in by design: on a large window this throws away real information early.
116
+ */
117
+ const SHORT_PRUNE_AT_SHARE = 0.6;
118
+ const SHORT_PRUNE_KEEP_CHARS = 200;
101
119
  /**
102
120
  * The summarize call is skipped when the summarizable prefix is a small share of
103
121
  * the budget, because the call cannot reuse any prefix cache (its system prompt is
@@ -234,6 +252,17 @@ Most session state is not injected into prompts — fetch it with tools instead:
234
252
  save_skill(name, description, content, files=[{name, content}]) so future
235
253
  sessions can load_skill them — helper scripts go through files and are made
236
254
  executable automatically.
255
+ - LEAD with the answer or the action: no preamble ("Great question", "Let me…",
256
+ "I'll now…") and no closing pleasantries ("Hope this helps", "let me know if…").
257
+ The operator reads the first line and the last line — make those two carry what
258
+ happened and what is next.
259
+ - For multi-step work, number the steps and keep ONE in progress at a time. When you
260
+ are partway through, say which step finished and which is next; do not re-narrate
261
+ the whole plan, and do not assume the operator remembers the previous turn.
262
+ - Report what now WORKS, concretely, rather than what you changed: "login works with
263
+ magic links — try /login" beats "I made some changes to the auth flow".
264
+ - State errors as cause and fix ("test fails at a.spec.ts:42: expected 200, got 401 —
265
+ missing auth header"), never as alarm ("uh oh", "there seems to be a problem").
237
266
  - When you make meaningful progress, call report_progress. Its output is
238
267
  shown to the operator directly (rendered as markdown in the progress
239
268
  panel) — do NOT also repeat the same content as a chat message; end the
@@ -433,6 +462,8 @@ export class Agent {
433
462
  contextWindowTokens: 0,
434
463
  restoreSession: true,
435
464
  globalSkillsDir: "",
465
+ pluginSkillRoots: [],
466
+ shortContext: false,
436
467
  bundledSkillsDir: "",
437
468
  spawnDepth: 0,
438
469
  readOnlyTools: false,
@@ -453,6 +484,7 @@ export class Agent {
453
484
  this.skillRoots = [
454
485
  { dir: path.join(opts.workspace, "skills"), source: "workspace" },
455
486
  ...(opts.globalSkillsDir ? [{ dir: opts.globalSkillsDir, source: "global" }] : []),
487
+ ...(opts.pluginSkillRoots ?? []),
456
488
  // OTHER HARNESSES' skill directories (#28). The SKILL.md format is shared,
457
489
  // so these are readable as-is — verified against real third-party skills
458
490
  // (terminalskills/skills, trailofbits/skills, …). They sit below the
@@ -1102,7 +1134,7 @@ export class Agent {
1102
1134
  // FORCED: this reproduces what the live session had already done, so it must
1103
1135
  // not consult the "is there room" bar — a restored context that happens to sit
1104
1136
  // below it still has to match the prompt the provider last accepted.
1105
- this.maybePrune(true);
1137
+ await this.maybePrune(true);
1106
1138
  // #54: answer tool_calls the log says are still open.
1107
1139
  //
1108
1140
  // The restore path rebuilds `msgs` straight from the log, so a call whose
@@ -3347,17 +3379,20 @@ export class Agent {
3347
3379
  * re-pruned so a reload does not hand the provider a strictly larger prompt than
3348
3380
  * the one that had just succeeded.
3349
3381
  */
3350
- maybePrune(force = false) {
3382
+ async maybePrune(force = false) {
3351
3383
  const est = this.contextSizeForBudgeting(); // floored — see #73
3352
3384
  const budget = this.opts.contextTokenBudget;
3353
3385
  if (!budget)
3354
3386
  return 0;
3355
3387
  // Below the bar there is enough room for the next request, so clipping now would
3356
3388
  // spend information to buy space that is already free.
3357
- if (!force && est < budget * PRUNE_AT_SHARE)
3389
+ const pruneShare = this.opts.shortContext ? SHORT_PRUNE_AT_SHARE : PRUNE_AT_SHARE;
3390
+ if (!force && est < budget * pruneShare)
3358
3391
  return 0;
3359
- // protect the recent tail (~half the budget in chars) from any pruning
3360
- const protectChars = budget * 2;
3392
+ // protect the recent tail (~half the budget in chars) from any pruning. Short mode
3393
+ // protects a THIRD of it: a 2x-budget tail on a small window is most of the window,
3394
+ // so pruning would find nothing to do exactly when it is needed (#161).
3395
+ const protectChars = this.opts.shortContext ? Math.floor(budget * 1.2) : budget * 2;
3361
3396
  let seen = 0;
3362
3397
  let boundary = this.messages.length;
3363
3398
  for (let i = this.messages.length - 1; i >= 0; i--) {
@@ -3392,13 +3427,19 @@ export class Agent {
3392
3427
  PRUNABLE_TOOLS.has(toolName) &&
3393
3428
  (m.content?.length ?? 0) > PRUNE_MIN) {
3394
3429
  const len = m.content.length;
3395
- saved += len - 400;
3396
- m.content = m.content.slice(0, 400) + `\n…[pruned ${len} bytes of ${toolName || "tool"} output]`;
3430
+ const keep = this.opts.shortContext ? SHORT_PRUNE_KEEP_CHARS : 400;
3431
+ saved += len - keep;
3432
+ m.content =
3433
+ m.content.slice(0, keep) + `\n…[pruned ${len} bytes of ${toolName || "tool"} output]`;
3397
3434
  count++;
3398
3435
  }
3399
3436
  }
3400
3437
  if (count > 0)
3401
- void this.log.append("system_note", this.currentSession, this.currentBranch, {
3438
+ // AWAITED, not fire-and-forget: the caller decides what to do next based on the
3439
+ // count, and a compaction pass that reports its outcome must have its reasons on
3440
+ // disk first — a `void` append could land after the pass returned, so the log
3441
+ // read the order "compacted" → "pruned".
3442
+ await this.log.append("system_note", this.currentSession, this.currentBranch, {
3402
3443
  event: "context-pruned",
3403
3444
  outputs: count,
3404
3445
  savedBytes: saved,
@@ -3416,6 +3457,12 @@ export class Agent {
3416
3457
  // what would overflow the window; the char heuristic is only a fallback
3417
3458
  // for providers that omit usage
3418
3459
  const before = this.contextSizeForBudgeting(); // floored — see #73
3460
+ // SHORT-CONTEXT MODE (#161) prunes INSIDE the budget, so it must run before the
3461
+ // "are we over budget" return below — otherwise its lower threshold is unreachable
3462
+ // and the mode does nothing at all. This is the one path where pruning deliberately
3463
+ // spends information early, and it only exists because the operator asked for it.
3464
+ if (this.opts.shortContext)
3465
+ await this.maybePrune();
3419
3466
  if (!force && before < this.opts.contextTokenBudget)
3420
3467
  return;
3421
3468
  if (!force && this.opts.autoCompact === false)
@@ -3423,7 +3470,7 @@ export class Agent {
3423
3470
  // stage 1: clip oversized old tool outputs before considering a summarize.
3424
3471
  // ONLY reached once this pass is actually over budget — pruning is destructive,
3425
3472
  // so it must not run on a context that still has room (see maybePrune()).
3426
- const pruned = this.maybePrune(true);
3473
+ const pruned = await this.maybePrune(true);
3427
3474
  // If clipping alone brought the request back under budget, STOP: that is the
3428
3475
  // cheapest possible compaction (no LLM call, no history rewritten, the tool
3429
3476
  // results are re-issuable) and everything below would discard context the model
@@ -3469,6 +3516,9 @@ export class Agent {
3469
3516
  // of the budget — a fixed floor GREATER than the budget would keep everything
3470
3517
  // and compaction would never fire at all (measured: a 500-token budget kept
3471
3518
  // a 7.5k-token history intact)
3519
+ // already scaled: on a small budget a quarter is below the 15k default, so a
3520
+ // 32k-window session keeps ~6k rather than 15k. Short mode does NOT need to
3521
+ // change this — checked while implementing #161 rather than assumed.
3472
3522
  : Math.min(KEEP_RECENT_TOKENS, Math.max(1, Math.floor(this.opts.contextTokenBudget / 4)));
3473
3523
  let cut = -1;
3474
3524
  for (let i = this.messages.length - 1; i >= 1; i--) {
@@ -4029,7 +4079,14 @@ export class Agent {
4029
4079
  this.currentBranch = branch;
4030
4080
  }
4031
4081
  }
4032
- /** workspace tools + agent-meta tools (finish / report_progress / set_goal / set_memory) */
4082
+ /**
4083
+ * workspace tools + agent-meta tools + every tool from every CONNECTED MCP server.
4084
+ *
4085
+ * The MCP tools are appended LAST and their names are namespaced (`mcp__server__tool`),
4086
+ * so adding one can never shadow a built-in — a server exposing `bash` must not be able
4087
+ * to take over the shell. `mcpSpecs()` is empty when nothing is configured, which is
4088
+ * the common case, so the cost of the feature is one empty spread.
4089
+ */
4033
4090
  function allToolSpecs() {
4034
4091
  return [
4035
4092
  ...toolSpecs(),
@@ -4263,8 +4320,27 @@ function allToolSpecs() {
4263
4320
  parameters: { type: "object", properties: {} },
4264
4321
  },
4265
4322
  },
4323
+ ...mcpSpecs(),
4266
4324
  ];
4267
4325
  }
4326
+ /**
4327
+ * MCP tools as function specs, flattened and namespaced.
4328
+ *
4329
+ * Descriptions are prefixed with their origin so the model can reason about which
4330
+ * server a result came from — with three servers exposing `search`, a bare description
4331
+ * gives it nothing to choose with. The server's own JSON Schema is forwarded as-is:
4332
+ * rewriting it would drop constraints the server enforces.
4333
+ */
4334
+ function mcpSpecs() {
4335
+ return mcp.allTools().map((t) => ({
4336
+ type: "function",
4337
+ function: {
4338
+ name: flattenToolName(t.server, t.name),
4339
+ description: `[MCP: ${t.server}] ${t.description || `${t.name} (no description provided)`}`,
4340
+ parameters: t.inputSchema,
4341
+ },
4342
+ }));
4343
+ }
4268
4344
  function str(v) {
4269
4345
  return typeof v === "string" ? v : "";
4270
4346
  }
@@ -0,0 +1,163 @@
1
+ /**
2
+ * The MCP server registry (#67): keeps connections, discovers tools, and dispatches
3
+ * calls.
4
+ *
5
+ * Why a registry instead of connecting per agent: several agents usually want the same
6
+ * server, and a stdio server is a PROCESS. One connection per agent would spawn one
7
+ * server per agent, each with its own state and its own startup cost. The pool keys by
8
+ * server name, so N agents share one connection — and a `tools/call` is still
9
+ * per-agent, because the arguments are.
10
+ *
11
+ * Naming. Two servers may both expose `search`, and a server may expose a name that
12
+ * collides with a built-in tool (`bash`, `read_file`). Every MCP tool is therefore
13
+ * exposed to the model as `mcp__<server>__<tool>`, which cannot collide with a
14
+ * built-in (those have no `__`) and tells the model where the result came from. The
15
+ * original name is what gets sent to the server.
16
+ */
17
+ import { connectMcp, McpError } from "./mcp.js";
18
+ /** the prefix a model-visible MCP tool name carries */
19
+ export const MCP_PREFIX = "mcp__";
20
+ /** `mcp__server__tool` — the flat name handed to the LLM */
21
+ export function flattenToolName(server, tool) {
22
+ // `__` is the separator, so a server or tool name containing it would be ambiguous.
23
+ // Collapse runs rather than rejecting: a server called "my__server" is unusual but
24
+ // not worth failing over, and the mapping stays stable.
25
+ const s = server.replace(/__/g, "_");
26
+ return `${MCP_PREFIX}${s}__${tool}`;
27
+ }
28
+ /** pull the parts back out of a flat name, or null when it is not an MCP tool */
29
+ export function splitToolName(flat) {
30
+ if (!flat.startsWith(MCP_PREFIX))
31
+ return null;
32
+ const rest = flat.slice(MCP_PREFIX.length);
33
+ const at = rest.indexOf("__");
34
+ if (at <= 0 || at === rest.length - 2)
35
+ return null;
36
+ return { server: rest.slice(0, at), tool: rest.slice(at + 2) };
37
+ }
38
+ export class McpRegistry {
39
+ servers = new Map();
40
+ /** replace the configured server list (on boot and after a settings save) */
41
+ apply(configs) {
42
+ const wanted = new Set(configs.map((c) => c.name));
43
+ // drop connections for servers that were removed or renamed
44
+ for (const [name, st] of this.servers) {
45
+ if (!wanted.has(name)) {
46
+ void st.connection?.close();
47
+ this.servers.delete(name);
48
+ }
49
+ }
50
+ for (const cfg of configs) {
51
+ const prev = this.servers.get(cfg.name);
52
+ // a config EDIT means the old connection is pointing at the wrong thing
53
+ const changed = Boolean(prev) && JSON.stringify(prev.config) !== JSON.stringify(cfg);
54
+ if (changed)
55
+ void prev.connection?.close();
56
+ const reuse = prev && !changed;
57
+ const status = cfg.enabled === false ? "disabled" : reuse ? prev.status : "disconnected";
58
+ const next = {
59
+ config: cfg,
60
+ tools: reuse ? prev.tools : [],
61
+ status,
62
+ };
63
+ if (reuse && prev.connection)
64
+ next.connection = prev.connection;
65
+ if (reuse && prev.lastError)
66
+ next.lastError = prev.lastError;
67
+ if (reuse && prev.lastChecked)
68
+ next.lastChecked = prev.lastChecked;
69
+ this.servers.set(cfg.name, next);
70
+ }
71
+ }
72
+ names() {
73
+ return [...this.servers.keys()];
74
+ }
75
+ states() {
76
+ return [...this.servers.values()];
77
+ }
78
+ /** connect one server (idempotent) and discover its tools */
79
+ async connect(name) {
80
+ const st = this.servers.get(name);
81
+ if (!st)
82
+ throw new McpError(`no such MCP server: ${name}`);
83
+ if (st.config.enabled === false) {
84
+ st.status = "disabled";
85
+ return st;
86
+ }
87
+ if (st.status === "connected" && st.connection)
88
+ return st;
89
+ st.status = "connecting";
90
+ st.lastError = undefined;
91
+ try {
92
+ const conn = await connectMcp(st.config);
93
+ const tools = await conn.tools();
94
+ st.connection = conn;
95
+ st.tools = tools;
96
+ st.status = "connected";
97
+ st.lastChecked = Date.now();
98
+ return st;
99
+ }
100
+ catch (err) {
101
+ st.status = "error";
102
+ st.lastError = err.message;
103
+ st.lastChecked = Date.now();
104
+ st.connection = undefined;
105
+ st.tools = [];
106
+ throw err;
107
+ }
108
+ }
109
+ /** connect every enabled server; failures are recorded, never thrown */
110
+ async connectAll() {
111
+ await Promise.all([...this.servers.keys()].map(async (n) => {
112
+ try {
113
+ await this.connect(n);
114
+ }
115
+ catch {
116
+ /* recorded in the state; one dead server must not stop the others */
117
+ }
118
+ }));
119
+ }
120
+ /** every tool from every CONNECTED server, flattened */
121
+ allTools() {
122
+ return [...this.servers.values()]
123
+ .filter((s) => s.status === "connected")
124
+ .flatMap((s) => s.tools);
125
+ }
126
+ /** dispatch a flattened name; returns null when it is not an MCP tool */
127
+ async call(flatName, args) {
128
+ const parts = splitToolName(flatName);
129
+ if (!parts)
130
+ return null;
131
+ const st = this.servers.get(parts.server);
132
+ if (!st)
133
+ return { ok: false, text: `no such MCP server: ${parts.server}` };
134
+ // a call for a server that is configured but not yet connected should connect on
135
+ // demand rather than fail: the operator adding a tool mid-session must not need a
136
+ // restart, and auto-connect is cheap for the HTTP transports
137
+ if (st.status !== "connected" || !st.connection) {
138
+ try {
139
+ await this.connect(parts.server);
140
+ }
141
+ catch (err) {
142
+ return { ok: false, text: `MCP server "${parts.server}" is not connected: ${err.message}` };
143
+ }
144
+ }
145
+ try {
146
+ const r = await this.servers.get(parts.server).connection.call(parts.tool, args);
147
+ return { ok: r.ok, text: r.text };
148
+ }
149
+ catch (err) {
150
+ return { ok: false, text: `MCP call failed: ${err.message}` };
151
+ }
152
+ }
153
+ async closeAll() {
154
+ for (const st of this.servers.values())
155
+ await st.connection?.close();
156
+ for (const st of this.servers.values()) {
157
+ st.connection = undefined;
158
+ st.status = st.config.enabled === false ? "disabled" : "disconnected";
159
+ }
160
+ }
161
+ }
162
+ /** process-wide registry: one connection per server, shared by every agent */
163
+ export const mcp = new McpRegistry();