teapot-coding-agent 0.6.0 → 0.7.0

package/README.md

@@ -110,18 +110,24 @@ master (Hono server, src/master.ts + src/server/api.ts)
   never hard-coded.
 - **Tools** (`src/agent/tools.ts`): provider-agnostic JSON-schema function
   specs — `read_file`, `write_file`, `edit_file`, `list_dir`, `bash` (git goes
-  through bash), plus meta tools `finish` / `report_progress` / `set_goal` /
-  `set_memory`. Paths are confined to the workspace; bash runs detached in its
-  own process group and the whole group is SIGKILLed on timeout.
+  through bash), plus meta tools `finish` / `report_progress` / `get_goal` /
+  `set_goal` / `read_memory` / `set_memory` / `list_skills`. Paths are
+  confined to the workspace; bash runs detached in its own process group and
+  the whole group is SIGKILLed on timeout.
+- **Cache-friendly prompt design** — the system prompt is byte-identical on
+  every turn; session state (goal, memory, skills) is fetched via tools, never
+  injected. Combined with the append-only message history this keeps provider
+  prefix caches hot, so long sessions pay incremental input prices instead of
+  re-sending full context every turn.
 - **Session storage** — everything teapot manages lives under
   `<dataDir>/sessions/<sid>/` (`chat.jsonl`, `goal.md`, `memory.md`), so agent
   workspaces stay clean. Each incarnation gets a fresh `<agentId>-<uuid>`
   directory (no history leaks across projects); restarts reuse the latest one.
   Legacy layouts are migrated automatically.
-- **Goal / knowledge** — goal + memory are harness-managed and injected into
-  the prompt every turn (agents update them via `set_goal` / `set_memory`);
-  `AGENTS.md` is optional project knowledge in the workspace root that is
-  injected when present. Nothing is seeded into your project anymore.
+- **Goal / knowledge** — goal + memory are harness-managed and read/written
+  through tools (`get_goal` / `set_goal` / `read_memory` / `set_memory`);
+  `AGENTS.md` is optional project knowledge in the workspace root that agents
+  are told to read at session start. Nothing is seeded into your project.
 
 ### Web UI
 

package/dist/agent/agent.js

@@ -14,24 +14,32 @@ import { executeTool, toolSpecs, currentSkills } from "./tools.js";
 import { bus } from "../bus.js";
 const SYSTEM_TEMPLATE = `You are a coding agent working autonomously inside a workspace.
 
-## Goal (managed by the harness)
-The current goal is injected into this prompt by the harness. Change it with
-set_goal(text) when the objective itself changes; call finish(goalComplete=true)
-only when the goal is fully achieved.
+This system prompt is intentionally STATIC — session state is never injected
+into it, so API prompt caches stay hot across turns. Fetch state with tools
+instead; they are cheap and always current.
 
-## Persistent context (all optional — create only if useful)
-- AGENTS.md (workspace root): project knowledge/conventions. When present, the
-  harness injects it into this prompt; keep it current with edit_file/write_file.
-- memory.md: your durable notes, harness-managed — update them with
-  set_memory(content); they are injected into future prompts.
-- skills/: reusable playbooks via load_skill / save_skill.
+## Goal (harness-managed)
+- get_goal() → current objective + status. Call it at session start, after a
+  compaction notice, or whenever you lose the thread.
+- set_goal(text) → change the objective itself (not routine updates).
+- finish(goalComplete=true, summary) → goal fully achieved.
+
+## Your notes (memory.md, harness-managed)
+- read_memory() / set_memory(content) → durable notes injected nowhere else.
+  Keep them terse: decisions, gotchas, where you left off.
+
+## Skills (reusable playbooks)
+- list_skills() → what exists. load_skill(name) → full playbook.
+- save_skill(name, description, content) → distill a reusable procedure.
+
+## Project knowledge
+- AGENTS.md in the workspace root (optional): conventions & commands. Read it
+  with read_file at session start when present, keep it current.
 
 ## Rules
 - Work step by step with tools. Verify results (run tests/builds) before claiming progress.
-- When a task matches an available skill's description, load_skill it first and follow the playbook.
-- When you develop a reusable procedure, save_skill it — skills persist and are offered to future sessions.
+- When a loaded skill matches your task, follow its playbook.
 - When you make meaningful progress, call report_progress.
-- When the goal is fully achieved, call finish(goalComplete=true) with a short summary.
 - Be frugal: prefer small precise edits, avoid runaway loops.`;
 export class Agent {
     log;
@@ -97,17 +105,6 @@ export class Agent {
             /* keep previous cache */
         }
     }
-    skillsListing() {
-        if (this.skillsCache.length === 0) {
-            return ("## Skills\n" +
-                "No skills exist yet. When you develop a reusable procedure worth keeping " +
-                "(build steps, checklists, project conventions), distill it into a durable playbook " +
-                "with save_skill so future sessions can load it via load_skill.");
-        }
-        return ("## Skills (reusable playbooks)\n" +
-            "When the current task matches a description below, call load_skill(name) first and follow it.\n" +
-            this.skillsCache.map((s) => `- ${s.name}: ${s.description || "(no description)"}`).join("\n"));
-    }
     callLlm(messages, tools, onDelta) {
         const fn = this.opts.chatFn ?? chatStream;
         return fn(this.opts.llm, messages, tools, this.abort?.signal, onDelta);
@@ -479,7 +476,7 @@ export class Agent {
                 turn: ++this.stats.turns,
             });
             // stream the assistant reply live to connected clients
-            const res = await this.llmCall(await this.buildMessages(), allToolSpecs(), (s) => {
+            const res = await this.llmCall(this.buildMessages(), allToolSpecs(), (s) => {
                 bus.emit("update", {
                     kind: "llm-delta",
                     agentId: this.opts.id,
@@ -537,6 +534,31 @@ export class Agent {
                     });
                     continue;
                 }
+                if (call.function.name === "get_goal") {
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: JSON.stringify({ goal: this.goal.text || "(none set)", status: this.goal.status }, null, 1),
+                    });
+                    continue;
+                }
+                if (call.function.name === "read_memory") {
+                    const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: mem.trim() || "(memory.md is empty — nothing noted yet)",
+                    });
+                    continue;
+                }
+                if (call.function.name === "list_skills") {
+                    await this.refreshSkills();
+                    const list = this.skillsCache.length
+                        ? this.skillsCache.map((s) => `- ${s.name}: ${s.description || "(no description)"}`).join("\n")
+                        : "(no skills yet — create one with save_skill)";
+                    this.messages.push({ role: "tool", tool_call_id: call.id, content: list });
+                    continue;
+                }
                 if (call.function.name === "set_memory") {
                     const a = safeParse(call.function.arguments);
                     const content = String(a.content ?? "").slice(0, 32_000);
@@ -574,37 +596,10 @@ export class Agent {
         }
         throw new Error("runaway detection: too many turns in one round (>200)");
     }
-    /** AGENTS.md is optional project knowledge — injected when present. */
-    agentsMdCache = null;
-    async readAgentsMd() {
-        try {
-            const p = path.join(this.workspace, "AGENTS.md");
-            const st = await fs.stat(p);
-            if (this.agentsMdCache?.mtimeMs === st.mtimeMs)
-                return this.agentsMdCache.text;
-            const text = await fs.readFile(p, "utf8");
-            this.agentsMdCache = { mtimeMs: st.mtimeMs, text };
-            return text;
-        }
-        catch {
-            this.agentsMdCache = null;
-            return "";
-        }
-    }
-    async buildMessages() {
-        const sys = [SYSTEM_TEMPLATE];
-        if (this.goal.text) {
-            sys.push(`## Current goal (${this.goal.status})\n${this.goal.text}`);
-        }
-        const agentsMd = await this.readAgentsMd();
-        if (agentsMd.trim())
-            sys.push(`## Project knowledge (AGENTS.md)\n${clipText(agentsMd, 8000)}`);
-        const memory = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
-        if (memory.trim())
-            sys.push(`## Your notes (memory.md)\n${clipText(memory, 4000)}`);
-        sys.push(this.skillsListing());
+    buildMessages() {
+        // deliberately static: [system] + append-only history keeps prefix caches hot
         const hasSystem = this.messages[0]?.role === "system";
-        const head = [{ role: "system", content: sys.join("\n\n") }];
+        const head = [{ role: "system", content: SYSTEM_TEMPLATE }];
         return hasSystem ? [...head, ...this.messages.slice(1)] : [...head, ...this.messages];
     }
     async handleFinish(argsJson) {
@@ -629,7 +624,7 @@ export class Agent {
             text: request,
         });
         this.messages.push({ role: "user", content: request });
-        const res = await this.llmCall(await this.buildMessages(), []); // no tools: pure report
+        const res = await this.llmCall(this.buildMessages(), []); // no tools: pure report
         await this.recordProgress(JSON.stringify({ freeform: res.message.content }));
         await this.log.append("message", this.currentSession, this.currentBranch, {
             role: "assistant",
@@ -843,7 +838,7 @@ function allToolSpecs() {
             type: "function",
             function: {
                 name: "set_goal",
-                description: "Replace the harness-managed goal text (it is injected into your prompt). Use when the objective itself changes — not for routine updates.",
+                description: "Replace the harness-managed goal text. Use when the objective itself changes — not for routine updates.",
                 parameters: {
                     type: "object",
                     properties: { text: { type: "string" } },
@@ -851,11 +846,27 @@ function allToolSpecs() {
                 },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "get_goal",
+                description: "Fetch the current goal and its status. Cheap — call at session start, after a compaction notice, or when unsure.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "read_memory",
+                description: "Read your durable notes (memory.md).",
+                parameters: { type: "object", properties: {} },
+            },
+        },
         {
             type: "function",
             function: {
                 name: "set_memory",
-                description: "Overwrite your durable session notes (memory.md, injected into future prompts). Keep them terse: decisions, gotchas, where you left off.",
+                description: "Overwrite your durable notes (memory.md). Keep them terse: decisions, gotchas, where you left off.",
                 parameters: {
                     type: "object",
                     properties: { content: { type: "string" } },
@@ -863,11 +874,16 @@ function allToolSpecs() {
                 },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "list_skills",
+                description: "List available skills (name + description). Call before load_skill or to avoid duplicating an existing skill.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
     ];
 }
-function clipText(s, max) {
-    return s.length <= max ? s : s.slice(0, max) + `\n… [truncated, ${s.length} chars total]`;
-}
 function str(v) {
     return typeof v === "string" ? v : "";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teapot-coding-agent",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A lightweight, always-on multi-agent harness for AI coding agents",
   "type": "module",
   "license": "AGPL-3.0-or-later",