teapot-coding-agent 0.5.0 → 0.7.0

package/README.md

@@ -110,13 +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`. Paths are
+  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.
-- **Goal / knowledge**: `GOAL.md` (goal + status), `AGENTS.md` (project
-  knowledge), `MEMORY.md` (agent notes) live in each workspace as normal git-
-  editable Markdown. The goal file is the source of truth; the harness re-reads
-  it on restart.
+- **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 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
 
@@ -162,13 +173,14 @@ description: Steps to cut a release safely
 
 ### Session log format (JSONL)
 
-One file per agent (`dataDir/<agent>.jsonl`); every conversation *including
-forks* lives in the same interleaved stream:
+One file per session (`<dataDir>/sessions/<sid>/chat.jsonl`, sid =
+`<agentId>-<uuid8>`); every conversation *including forks* lives in the same
+interleaved stream:
 
 ```json
-{"v":1,"id":"e27","seq":27,"ts":"…","agent":"alpha","session":"sess-alpha-main",
+{"v":1,"id":"e27","seq":27,"ts":"…","agent":"alpha","session":"alpha-9f3c21ab",
  "branch":"br032sl","parent":"e26","type":"fork",
- "data":{"fromSession":"sess-alpha-main","fromBranch":"br0","fromEvent":"e26","newBranch":"br032sl"}}
+ "data":{"fromSession":"alpha-9f3c21ab","fromBranch":"br0","fromEvent":"e26","newBranch":"br032sl"}}
 ```
 
 - every event carries `session`, `branch`, `parent` (previous event on the same branch), monotonic `seq`

package/dist/agent/agent.js

@@ -14,19 +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.
 
-## Persistent context files (human-readable, git-tracked)
-- AGENTS.md    : project knowledge/conventions written for agents (read it first)
-- GOAL.md      : your current long-term goal and its status
-- MEMORY.md    : durable notes you write for yourself
+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.
 
-Keep these files updated with edit_file/write_file. They survive restarts.
+## 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;
@@ -66,7 +79,7 @@ export class Agent {
             provider: "",
             ...opts,
         };
-        this.log = new EventLog(opts.logFile, opts.id);
+        this.log = new EventLog(path.join(opts.sessionDir, "chat.jsonl"), opts.id);
         this.skillRoots = [
             { dir: path.join(opts.workspace, "skills"), source: "workspace" },
             ...(opts.globalSkillsDir ? [{ dir: opts.globalSkillsDir, source: "global" }] : []),
@@ -77,7 +90,8 @@ export class Agent {
             maxOutputBytes: 60_000,
             skillRoots: this.skillRoots,
         };
-        this.mainSession = `sess-${opts.id}-main`;
+        // the session id IS the directory name — one directory per incarnation
+        this.mainSession = path.basename(opts.sessionDir);
         this.currentSession = this.mainSession;
     }
     skillRoots;
@@ -91,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);
@@ -124,18 +127,49 @@ export class Agent {
     async init() {
         await this.log.load();
         await fs.mkdir(this.workspace, { recursive: true });
-        // seed persistent context files if missing
-        await this.seed("AGENTS.md", "# Project knowledge\n\n(Describe conventions, build commands, and gotchas here.)\n");
-        await this.seed("MEMORY.md", "# Memory\n");
-        const goalText = await this.readGoalFile();
-        if (goalText !== null)
-            this.goal = this.parseGoalFile(goalText);
-        else
-            await this.writeGoalFile();
+        // goal lives next to the session log (dataDir), NOT in the workspace —
+        // migrate a legacy workspace GOAL.md once, then never touch the workspace
+        await this.migrateGoalFromWorkspace();
+        const stored = await this.readGoalStore();
+        this.goal = stored ?? { text: "", status: "active", updatedAt: new Date().toISOString() };
         if (this.opts.restoreSession)
             await this.restoreFromLog();
         await this.refreshSkills();
     }
+    /** harness-managed files inside the session directory */
+    get goalFile() {
+        return path.join(this.opts.sessionDir, "goal.md");
+    }
+    get memoryFile() {
+        return path.join(this.opts.sessionDir, "memory.md");
+    }
+    async readGoalStoreRaw() {
+        return fs.readFile(this.goalFile, "utf8").catch(() => null);
+    }
+    async readGoalStore() {
+        const raw = await this.readGoalStoreRaw();
+        return raw === null ? null : this.parseGoalFile(raw);
+    }
+    /** One-time import of a pre-0.6.0 workspace GOAL.md; content is preserved. */
+    async migrateGoalFromWorkspace() {
+        const legacy = path.join(this.workspace, "GOAL.md");
+        let wsText;
+        try {
+            wsText = await fs.readFile(legacy, "utf8");
+        }
+        catch {
+            return; // nothing to migrate
+        }
+        const existing = await this.readGoalStoreRaw();
+        if (existing === null)
+            await fs.writeFile(this.goalFile, wsText, "utf8");
+        await fs.rm(legacy).catch(() => { });
+        await this.log.append("system_note", this.currentSession, this.currentBranch, {
+            event: "goal-migrated",
+            from: "GOAL.md",
+            to: this.goalFile,
+        });
+    }
     /**
      * Rebuild the in-memory conversation from the JSONL event log so a restart
      * continues where the agent left off instead of starting blank.
@@ -237,24 +271,20 @@ export class Agent {
             });
         }
     }
-    async seed(file, content) {
-        const p = path.join(this.workspace, file);
-        try {
-            await fs.access(p);
-        }
-        catch {
-            await fs.writeFile(p, content, "utf8");
-        }
-    }
-    readGoalFile() {
-        return fs.readFile(path.join(this.workspace, "GOAL.md"), "utf8").catch(() => null);
-    }
     parseGoalFile(text) {
         // humans and agents may append their own status lines — latest wins
         const all = [...text.matchAll(/status:\s*(\w+)/gi)];
         const last = all[all.length - 1]?.[1];
         const status = last === "done" ? "done" : last === "paused" ? "paused" : "active";
-        return { text: text.trim(), status, updatedAt: new Date().toISOString() };
+        // keep bookkeeping lines out of the injected goal text
+        let body = text.trim();
+        for (let i = 0; i < 4; i++) {
+            const stripped = body.replace(/\n+(?:status|updated):[^\n]*$/i, "").trimEnd();
+            if (stripped === body)
+                break;
+            body = stripped;
+        }
+        return { text: body, status, updatedAt: new Date().toISOString() };
     }
     async writeGoalFile() {
         // don't let previously-appended bookkeeping lines accumulate in the body
@@ -265,7 +295,7 @@ export class Agent {
                 break;
             body = stripped;
         }
-        await fs.writeFile(path.join(this.workspace, "GOAL.md"), `${body}\n\nstatus: ${this.goal.status}\nupdated: ${this.goal.updatedAt}\n`, "utf8");
+        await fs.writeFile(this.goalFile, `${body}\n\nstatus: ${this.goal.status}\nupdated: ${this.goal.updatedAt}\n`, "utf8");
     }
     async setGoal(text) {
         this.goal = { text, status: "active", updatedAt: new Date().toISOString() };
@@ -290,6 +320,7 @@ export class Agent {
             stats: { ...this.stats },
             model: this.opts.llm.model,
             provider: this.opts.provider,
+            sessionDir: this.opts.sessionDir,
         };
     }
     /** Queue a user prompt; wakes the loop if needed. Returns immediately. */
@@ -354,7 +385,7 @@ export class Agent {
                 await this.sleepInterruptible(this.opts.continueDelayMs);
                 if (this.stopRequested)
                     break;
-                const nudge = "Continue working toward the goal in GOAL.md. If you are blocked, explain why briefly.";
+                const nudge = "Continue working toward the current goal. If you are blocked, explain why briefly.";
                 await this.log.append("prompt", this.currentSession, this.currentBranch, {
                     source: "harness",
                     text: nudge,
@@ -491,6 +522,54 @@ export class Agent {
                     });
                     continue;
                 }
+                if (call.function.name === "set_goal") {
+                    const a = safeParse(call.function.arguments);
+                    const text = String(a.text ?? "").trim();
+                    if (text)
+                        await this.setGoal(text);
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: text ? "goal updated" : "empty goal rejected",
+                    });
+                    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);
+                    await fs.writeFile(this.memoryFile, content, "utf8");
+                    this.messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: "memory saved (injected into future prompts)",
+                    });
+                    continue;
+                }
                 await this.log.append("tool_call", this.currentSession, this.currentBranch, {
                     callId: call.id,
                     name: call.function.name,
@@ -518,13 +597,9 @@ export class Agent {
         throw new Error("runaway detection: too many turns in one round (>200)");
     }
     buildMessages() {
-        const sys = [SYSTEM_TEMPLATE];
-        if (this.goal.text) {
-            sys.push(`## Current goal (${this.goal.status})\n${this.goal.text}`);
-        }
-        sys.push(this.skillsListing());
+        // 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) {
@@ -627,7 +702,7 @@ export class Agent {
                 {
                     role: "user",
                     content: `[harness] Context was compacted: ${oldCount} earlier messages were summarized. ` +
-                        "Persistent files (GOAL.md / AGENTS.md / MEMORY.md) are still on disk — re-read them when needed.\n\n" +
+                        "Goal and notes are managed by the harness (AGENTS.md / memory.md are injected into your prompt when present).\n\n" +
                         `## Summary of earlier conversation\n${summary}`,
                 },
                 ...this.messages.slice(cut),
@@ -723,7 +798,7 @@ export class Agent {
         this.currentBranch = branch;
     }
 }
-/** workspace tools + agent-meta tools (finish / report_progress) */
+/** workspace tools + agent-meta tools (finish / report_progress / set_goal / set_memory) */
 function allToolSpecs() {
     return [
         ...toolSpecs(),
@@ -731,7 +806,7 @@ function allToolSpecs() {
             type: "function",
             function: {
                 name: "finish",
-                description: "End the current round. Call with goalComplete=true only when the goal in GOAL.md is fully achieved.",
+                description: "End the current round. Call with goalComplete=true only when the current goal (shown in your prompt) is fully achieved.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -759,6 +834,54 @@ function allToolSpecs() {
                 },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "set_goal",
+                description: "Replace the harness-managed goal text. Use when the objective itself changes — not for routine updates.",
+                parameters: {
+                    type: "object",
+                    properties: { text: { type: "string" } },
+                    required: ["text"],
+                },
+            },
+        },
+        {
+            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 notes (memory.md). Keep them terse: decisions, gotchas, where you left off.",
+                parameters: {
+                    type: "object",
+                    properties: { content: { type: "string" } },
+                    required: ["content"],
+                },
+            },
+        },
+        {
+            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 str(v) {

package/dist/master.js

@@ -3,7 +3,8 @@
  * Agents are in-process async loops (I/O bound only); all CPU-heavy work is
  * delegated to subprocesses managed by the bash tool with hard timeouts.
  */
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, renameSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import os from "node:os";
 import { Agent } from "./agent/agent.js";
@@ -192,8 +193,14 @@ export class Master {
         // single low-frequency tick for everything periodic (idle cost ≈ 0)
         setInterval(() => void this.tick(), 15_000).unref();
     }
-    /** Create an agent; optionally persist it to the config file. */
-    async addAgent(ac, persist = false) {
+    /**
+     * Create an agent; optionally persist it to the config file.
+     * Each incarnation gets its own session directory under
+     * <dataDir>/sessions/<agentId>-<uuid>/ (chat.jsonl, goal.md, memory.md).
+     * Restarts reuse the latest existing session; fresh creations never touch
+     * an older one's history.
+     */
+    async addAgent(ac, opts = {}) {
         if (this.agents.has(ac.id))
             throw new Error(`agent id already exists: ${ac.id}`);
         // provider resolution: inline overrides > named provider > legacy llm block
@@ -210,12 +217,13 @@ export class Master {
         };
         if (!llm.model)
             throw new Error(`agent ${ac.id}: no model configured (set model on the agent or on its provider)`);
-        const logFile = path.join(this.config.dataDir, `${ac.id}.jsonl`);
+        const sessionDir = this.resolveSessionDir(ac.id, opts.fresh === true);
+        await mkdirSync(sessionDir, { recursive: true });
         const agent = new Agent({
             id: ac.id,
             workspace: path.resolve(ac.workspace),
             llm,
-            logFile,
+            sessionDir,
             progressIntervalMs: this.config.progressIntervalMs,
             autoContinue: true,
             ...(this.config.contextTokenBudget ? { contextTokenBudget: this.config.contextTokenBudget } : {}),
@@ -225,12 +233,68 @@ export class Master {
         agent.log.onEvent = (e) => printAgentEvent(e);
         await agent.init();
         this.agents.set(ac.id, agent);
-        if (persist) {
+        if (opts.persist) {
             this.config.agents.push(ac);
             this.saveConfig();
         }
         return agent;
     }
+    /** sessions root + helpers */
+    sessionsRoot() {
+        return path.join(this.config.dataDir, "sessions");
+    }
+    findLatestSessionDir(agentId) {
+        let dirs = [];
+        try {
+            dirs = readdirSync(this.sessionsRoot())
+                .filter((d) => d === agentId || d.startsWith(`${agentId}-`))
+                .sort((a, b) => {
+                // newest chat.jsonl wins
+                const ma = this.sessionMtime(path.join(this.sessionsRoot(), a));
+                const mb = this.sessionMtime(path.join(this.sessionsRoot(), b));
+                return mb - ma;
+            });
+        }
+        catch {
+            return null;
+        }
+        return dirs[0] ? path.join(this.sessionsRoot(), dirs[0]) : null;
+    }
+    sessionMtime(dir) {
+        try {
+            return statSync(path.join(dir, "chat.jsonl")).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    resolveSessionDir(agentId, fresh) {
+        const root = this.sessionsRoot();
+        mkdirSync(root, { recursive: true });
+        // one-time migration from the ≤0.5.0 flat layout (<dataDir>/<id>.jsonl)
+        if (!fresh) {
+            const legacy = path.join(this.config.dataDir, `${agentId}.jsonl`);
+            if (existsSync(legacy)) {
+                const target = path.join(root, agentId);
+                if (!existsSync(target)) {
+                    mkdirSync(target, { recursive: true });
+                    renameSync(legacy, path.join(target, "chat.jsonl"));
+                    console.log(`[teapot] migrated session storage: ${agentId}.jsonl → sessions/${agentId}/chat.jsonl`);
+                }
+            }
+        }
+        if (!fresh) {
+            const existing = this.findLatestSessionDir(agentId);
+            if (existing)
+                return existing; // restart → continue where we left off
+        }
+        // fresh incarnation: guaranteed-unique directory
+        let sid = "";
+        do {
+            sid = `${agentId}-${randomUUID().slice(0, 8)}`;
+        } while (existsSync(path.join(root, sid)));
+        return path.join(root, sid);
+    }
     async removeAgent(id) {
         const agent = this.agents.get(id);
         if (!agent)

package/dist/server/api.js

@@ -143,7 +143,7 @@ export function buildApp(master) {
         }
         const id = (body.id?.trim() || path.basename(ws)).replace(/[^\w.-]/g, "-").slice(0, 40);
         try {
-            const agent = await master.addAgent({ id, workspace: ws, provider: body.provider, model: body.model }, true);
+            const agent = await master.addAgent({ id, workspace: ws, provider: body.provider, model: body.model }, { persist: true, fresh: true });
             if (body.start !== false)
                 agent.start("created via web");
             return c.json({ ok: true, agent: agent.snapshot() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teapot-coding-agent",
-  "version": "0.5.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",