teapot-coding-agent 0.14.10 → 0.15.0

package/dist/agent/agent.js

@@ -469,7 +469,17 @@ export class Agent {
                 break;
             body = stripped;
         }
-        return { text: body, status, updatedAt: new Date().toISOString() };
+        // verification contract (pi-goal-x style): a `verify:` block at the tail
+        let verify = "";
+        const vm = body.match(/\nverify:\s*\n([\s\S]+)$/i) ?? body.match(/^verify:\s*(.+)$/im);
+        if (vm) {
+            verify = vm[1].trim();
+            body = (body.slice(0, vm.index).trimEnd());
+        }
+        const out = { text: body, status, updatedAt: new Date().toISOString() };
+        if (verify)
+            out.verify = verify;
+        return out;
     }
     async writeGoalFile() {
         // don't let previously-appended bookkeeping lines accumulate in the body
@@ -480,7 +490,8 @@ export class Agent {
                 break;
             body = stripped;
         }
-        await fs.writeFile(this.goalFile, `${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` +
+            (this.goal.verify ? `verify:\n${this.goal.verify}\n` : ""), "utf8");
     }
     async setGoal(text) {
         this.goal = { text, status: "active", updatedAt: new Date().toISOString() };
@@ -546,6 +557,33 @@ export class Agent {
         await this.writeGoalFile();
         await this.log.append("goal", this.currentSession, this.currentBranch, { event: "status", status });
     }
+    /** Set the goal's verification contract (completion requirements). */
+    async setGoalVerify(verify) {
+        this.goal = { ...this.goal, verify: verify.slice(0, 4000), updatedAt: new Date().toISOString() };
+        await this.writeGoalFile();
+        await this.log.append("goal", this.currentSession, this.currentBranch, {
+            event: "verify-set",
+            verify: verify.slice(0, 2000),
+        });
+    }
+    /** Record a verification-contract audit outcome (pi-goal-x style review). */
+    async setGoalAudit(verdict, feedback) {
+        this.goal = {
+            ...this.goal,
+            updatedAt: new Date().toISOString(),
+            audit: { verdict, feedback: feedback.slice(0, 4000), at: new Date().toISOString() },
+        };
+        if (verdict === "approved")
+            this.goal.status = "done";
+        else if (this.goal.status === "done")
+            this.goal.status = "active"; // reopened
+        await this.writeGoalFile();
+        await this.log.append("goal", this.currentSession, this.currentBranch, {
+            event: "audit",
+            verdict,
+            feedback: feedback.slice(0, 2000),
+        });
+    }
     snapshot() {
         return {
             id: this.opts.id,
@@ -554,7 +592,12 @@ export class Agent {
             workspace: this.workspace,
             session: this.currentSession,
             branch: this.currentBranch,
-            goal: { status: this.goal.status, text: this.goal.text.slice(0, 400) },
+            goal: {
+                status: this.goal.status,
+                text: this.goal.text.slice(0, 400),
+                ...(this.goal.verify ? { verify: this.goal.verify.slice(0, 1000) } : {}),
+                ...(this.goal.audit ? { audit: this.goal.audit } : {}),
+            },
             latestProgress: this.latestProgress,
             stats: { ...this.stats },
             model: this.opts.llm.model,
@@ -595,20 +638,69 @@ export class Agent {
             this.activityChars = 0;
             this.turnsSinceProgress = 0;
         }
+        // stable id shared by the log event and the UI's pending echo — the UI
+        // flips its echo to "sent" when prompt-delivered carries this id back
+        const promptId = source === "user" ? `u${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}` : "";
         void this.ensureReady()
             .then(() => {
-            this.pendingPrompts.push({ source, text });
-            return this.log.append("prompt", this.currentSession, this.currentBranch, { source, text });
+            this.pendingPrompts.push({ source, text, ...(promptId ? { id: promptId } : {}) });
+            return this.log.append("prompt", this.currentSession, this.currentBranch, {
+                source,
+                text,
+                ...(promptId ? { promptId } : {}),
+            });
         })
             .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
             .catch(() => { });
+        return promptId;
     }
-    /** Hand queued user prompts to the model at a turn boundary. */
+    /**
+     * Withdraw a still-pending user prompt (before it reaches an LLM call).
+     * Returns the text so the UI can put it back into the composer draft.
+     */
+    cancelPrompt(promptId) {
+        const i = this.pendingPrompts.findIndex((p) => p.id === promptId);
+        if (i === -1)
+            return null; // already delivered or unknown
+        const [p] = this.pendingPrompts.splice(i, 1);
+        void this.log
+            .append("system_note", this.currentSession, this.currentBranch, {
+            event: "prompt-cancelled",
+            promptId,
+            preview: p.text.slice(0, 80),
+        })
+            .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
+            .catch(() => { });
+        return p.text;
+    }
+    /**
+     * Hand queued user prompts to the model at a turn boundary. Each consumed
+     * prompt is logged as a system_note (prompt-delivered) so the UI can flip
+     * its pending echo to "sent" at exactly the moment the text enters an LLM
+     * call payload — not merely when it was logged.
+     */
     drainPendingPrompts() {
         for (const p of this.pendingPrompts.splice(0)) {
             this.messages.push({ role: "user", content: p.text });
+            if (p.source === "user") {
+                const id = p.id ?? `u${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+                this.deliveredPrompts.push(id);
+                // cap: UI only needs recent confirmations
+                if (this.deliveredPrompts.length > 64)
+                    this.deliveredPrompts.shift();
+                void this.log
+                    .append("system_note", this.currentSession, this.currentBranch, {
+                    event: "prompt-delivered",
+                    promptId: id,
+                    preview: p.text.slice(0, 80),
+                })
+                    .then(() => bus.emit("update", { kind: "agent-update", agentId: this.opts.id }))
+                    .catch(() => { });
+            }
         }
     }
+    /** ids of user prompts that have entered an LLM call payload (recent first-capped) */
+    deliveredPrompts = [];
     /** Resolves when all queued work (including a running loop) has settled. */
     settled() {
         return this.runChain.catch(() => { });
@@ -873,11 +965,20 @@ export class Agent {
                     const text = String(a.text ?? "").trim();
                     if (text)
                         await this.setGoal(text);
+                    // pi-goal-x-style verification contract: plain-text completion
+                    // requirements audited before finish(goalComplete=true) is honored
+                    if (typeof a.verify === "string" && a.verify.trim())
+                        await this.setGoalVerify(a.verify.trim().slice(0, 4000));
                     await this.answerMeta(call, text ? "goal updated" : "empty goal rejected");
                     continue;
                 }
                 if (call.function.name === "get_goal") {
-                    await this.answerMeta(call, JSON.stringify({ goal: this.goal.text || "(none set)", status: this.goal.status }, null, 1));
+                    await this.answerMeta(call, JSON.stringify({
+                        goal: this.goal.text || "(none set)",
+                        status: this.goal.status,
+                        ...(this.goal.verify ? { verify: this.goal.verify } : {}),
+                        ...(this.goal.audit ? { lastAudit: this.goal.audit } : {}),
+                    }, null, 1));
                     continue;
                 }
                 if (call.function.name === "ask_user") {
@@ -1054,8 +1155,59 @@ export class Agent {
     }
     async handleFinish(argsJson) {
         const args = safeParse(argsJson);
-        if (args.goalComplete === true)
-            await this.setGoalStatus("done");
+        if (args.goalComplete === true && this.goal.status !== "done") {
+            if (this.goal.verify?.trim()) {
+                // pi-goal-x-style INDEPENDENT COMPLETION REVIEW: a separate LLM call
+                // checks the verification contract against the conversation + summary
+                // before "done" is honored. changes-required reopens the goal and
+                // queues the auditor's feedback as the next user prompt.
+                await this.log.append("goal", this.currentSession, this.currentBranch, {
+                    event: "audit-started",
+                    verify: this.goal.verify.slice(0, 2000),
+                });
+                try {
+                    const auditPrompt = `You are an independent completion AUDITOR (not the worker). Decide whether the goal is genuinely complete.\n\n` +
+                        `GOAL:\n${this.goal.text.slice(0, 4000)}\n\nVERIFICATION CONTRACT (must ALL hold):\n${this.goal.verify.slice(0, 2000)}\n\n` +
+                        `WORKER'S FINAL SUMMARY:\n${String(args.summary ?? "").slice(0, 3000)}\n\n` +
+                        `Conversation evidence follows. Reply with EXACTLY one line starting either\n` +
+                        `"APPROVED: <one-sentence justification>" or\n` +
+                        `"CHANGES-REQUIRED: <the specific gaps that must be addressed>".`;
+                    const res = await this.callLlm([
+                        ...this.buildMessages(),
+                        { role: "user", content: auditPrompt },
+                    ], []);
+                    const text = String(res.message.content ?? "");
+                    const approved = /^APPROVED\b/i.test(text.trim());
+                    const feedback = text.replace(/^(APPROVED|CHANGES-REQUIRED)\s*[:—-]?\s*/i, "").trim();
+                    await this.setGoalAudit(approved ? "approved" : "changes-required", feedback || "(no detail)");
+                    await this.log.append("message", this.currentSession, this.currentBranch, {
+                        role: "assistant",
+                        content: approved
+                            ? `✅ completion audit: APPROVED — ${feedback}`
+                            : `🔍 completion audit: CHANGES REQUIRED — ${feedback}`,
+                    });
+                    if (!approved) {
+                        // hand the gaps back to the worker as its next instruction
+                        this.pendingPrompts.push({
+                            source: "harness",
+                            text: `[harness] The completion audit REJECTED this finish. Address these gaps, then finish again with goalComplete=true:\n\n${feedback.slice(0, 2000)}`,
+                        });
+                    }
+                }
+                catch (err) {
+                    // auditor unavailable → fail open (record it, honor the finish) so a
+                    // flaky provider can't trap work in an unauditable loop
+                    await this.log.append("system_note", this.currentSession, this.currentBranch, {
+                        event: "audit-failed",
+                        detail: String(err.message).slice(0, 300),
+                    });
+                    await this.setGoalStatus("done");
+                }
+            }
+            else {
+                await this.setGoalStatus("done");
+            }
+        }
         await this.log.append("message", this.currentSession, this.currentBranch, {
             role: "assistant",
             final: true,
@@ -1420,10 +1572,19 @@ 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.",
+                description: "Replace the harness-managed goal text. Use when the objective itself changes — not for routine updates. " +
+                    "Optionally attach a verification contract (plain-text completion requirements); finish(goalComplete=true) " +
+                    "is then audited against it by an independent reviewer before the goal counts as done.",
                 parameters: {
                     type: "object",
-                    properties: { text: { type: "string" } },
+                    properties: {
+                        text: { type: "string" },
+                        verify: {
+                            type: "string",
+                            description: "completion requirements that must verifiably hold, e.g. 'npm test passes with zero failures; " +
+                                "the new endpoint appears in README'. Omit for no audit.",
+                        },
+                    },
                     required: ["text"],
                 },
             },
@@ -1617,6 +1778,13 @@ function rebuildMessagesFrom(list) {
         "get_feedback", "add_feedback", "record_decision", "get_decisions",
     ]);
     const openCalls = new Map(); // real tool_call id -> name
+    // callId -> the tool_call entry on its assistant message (fast arg enrichment)
+    const assistantCalls = new Map();
+    const rememberAssistantCalls = (m) => {
+        if (Array.isArray(m.tool_calls))
+            for (const t of m.tool_calls)
+                assistantCalls.set(t.id, t);
+    };
     // meta answers are now logged as regular tool_results; the legacy progress
     // synthesizer below must not duplicate them
     const loggedResults = new Set(list.filter((e) => e.type === "tool_result").map((e) => String(e.data.callId ?? "")));
@@ -1654,14 +1822,20 @@ function rebuildMessagesFrom(list) {
                     if (!META_TOOLS.has(t.function.name))
                         openCalls.set(t.id, t.function.name);
             }
+            rememberAssistantCalls(m);
             msgs.push(m);
         }
         else if (e.type === "tool_call") {
             // enrich the preceding assistant tool_calls with real arguments —
             // prefer the provider's raw string so restored requests stay
-            // byte-identical (prefix caches stay warm across restarts)
-            const prev = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.some((t) => t.id === d.callId));
-            const tc = prev?.tool_calls?.find((t) => t.id === d.callId);
+            // byte-identical (prefix caches stay warm across restarts).
+            // Indexed by call id: the old [...msgs].reverse().find() scanned the
+            // whole message list per call — O(n²) on multi-thousand-event logs.
+            let tc = assistantCalls.get(String(d.callId ?? ""));
+            if (!tc) {
+                const prev = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.some((t) => t.id === d.callId));
+                tc = prev?.tool_calls?.find((t) => t.id === d.callId);
+            }
             if (tc) {
                 if (typeof d.argsRaw === "string")
                     tc.function.arguments = d.argsRaw;

package/dist/agent/tools.js

@@ -16,7 +16,12 @@ function clip(s, max) {
 async function readText(p) {
     return fs.readFile(p, "utf8");
 }
-/** Resolve a path inside the workspace; reject escapes (incl. symlink targets). */
+/** Resolve a path inside the workspace; reject escapes (incl. symlink targets).
+ *  KNOWN LIMIT (review finding, accepted): the check-then-open pattern has a
+ *  TOCTOU window — a symlink swapped in between safeJoin() and fs.open() could
+ *  point outside the workspace. Closing it needs openat(2)/O_NOFOLLOW at every
+ *  call site; the operator-facing risk is low (requires workspace write access
+ *  already), so we document rather than rewrite all call sites. */
 export function safeJoin(cwd, p) {
     const abs = path.resolve(cwd, p);
     const rel = path.relative(cwd, abs);

package/dist/config-schema.js

@@ -37,7 +37,8 @@ export const ConfigPatchSchema = z.object({
     defaultProvider: z.string().optional(),
     progressIntervalMs: z.number().int().min(10_000, "progress interval must be ≥ 10s").optional(),
     progressMinChars: z.number().int().min(100).optional(),
-    contextTokenBudget: z.number().int().min(1_000).optional(),
+    // null clears a previously pinned compact budget → back to per-model derivation
+    contextTokenBudget: z.number().int().min(1_000).nullable().optional(),
     contextWindowTokens: z.number().int().min(1_000).optional(),
     maxSpawnDepth: z.number().int().min(0).max(8).optional(),
     tasks: z.array(TaskSchema).optional(),

package/dist/log/events.js

@@ -97,8 +97,12 @@ export class EventLog {
         }
         const p = new Promise((resolve, reject) => {
             this.chain = this.chain.then(() => {
-                if (!this.stream)
+                if (!this.stream) {
+                    // log closed (dispose) — resolve so callers don't await forever,
+                    // but say so: silent drops made post-shutdown writes look logged
+                    console.error(`[teapot] event dropped after log close (${this.agentId}): ${type}`);
                     return resolve(evt);
+                }
                 this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => err ? reject(err) : resolve(evt));
             }, () => resolve(evt));
         });

package/dist/master.js

@@ -218,8 +218,12 @@ export class Master {
                 a.opts.progressMinChars =
                     patch.progressMinChars;
         }
-        if (patch.contextTokenBudget !== undefined)
-            this.config.contextTokenBudget = patch.contextTokenBudget;
+        // explicit null clears a previously saved budget → back to per-model
+        // derivation (75% of each agent's known window); a positive number pins it
+        if (patch.contextTokenBudget !== undefined) {
+            this.config.contextTokenBudget =
+                (patch.contextTokenBudget ?? 0) > 0 ? patch.contextTokenBudget : undefined;
+        }
         if (patch.maxSpawnDepth !== undefined)
             this.config.maxSpawnDepth = patch.maxSpawnDepth;
         if (patch.tasks) {
@@ -246,11 +250,17 @@ export class Master {
             }
         }
         for (const t of this.config.tasks ?? []) {
-            this.tasks.push({
-                task: t,
-                schedule: parseSchedule(t.schedule),
-                lastRunMin: t.lastRunMin ?? -1,
-            });
+            try {
+                this.tasks.push({
+                    task: t,
+                    schedule: parseSchedule(t.schedule),
+                    lastRunMin: t.lastRunMin ?? -1,
+                });
+            }
+            catch (err) {
+                // a hand-edited schedule typo must not stop the server from listening
+                console.error(`[teapot] skipping task "${t.id}": ${err.message}`);
+            }
         }
         // single low-frequency tick for everything periodic (idle cost ≈ 0)
         setInterval(() => void this.tick(), 15_000).unref();
@@ -397,7 +407,11 @@ export class Master {
                 })),
                 stop: (ids) => this.stopChildrenFor(ac.id, ids),
                 message: (id, text) => this.messageChild(ac.id, id, text),
-                wait: (ids, ms) => this.waitChildren(ac.id, ids, ms),
+                wait: (ids, ms) => 
+                // wire the parent's tool-abort signal: a user stop / dispose must
+                // interrupt the park immediately instead of leaving the run chain
+                // blocked until the full timeout (up to 1h)
+                this.waitChildren(ac.id, ids, ms, self.toolCtx.signal),
             };
             agent.toolCtx.subAgents = hooks;
         }

package/dist/server/api.js

@@ -77,7 +77,17 @@ export function buildApp(master) {
                     }
                 };
                 send({ kind: "hello", agents: [...master.agents.values()].map((a) => a.snapshot()) });
-                onUpdate = (ev) => send(ev);
+                onUpdate = (raw) => {
+                    const ev = raw;
+                    // attach the fresh snapshot to agent-update events so clients can
+                    // update their state WITHOUT a follow-up GET /api/agents poll
+                    if (ev?.kind === "agent-update" && ev.agentId) {
+                        const a = master.agents.get(ev.agentId);
+                        send({ ...ev, snapshot: a?.snapshot() });
+                        return;
+                    }
+                    send(ev);
+                };
                 bus.on("update", onUpdate);
                 // app-level liveness ping every 30s
                 ka = setInterval(() => send({ kind: "ping" }), 30_000);
@@ -205,7 +215,9 @@ export function buildApp(master) {
         // collision, auto-suffix so creating ~/a/proj and ~/b/proj just works
         let id = base;
         let n = 2;
-        while (master.agents.has(id))
+        // ids must be unique among RUNNING agents AND persisted config entries —
+        // a config-only agent (not yet loaded) would otherwise collide on addAgent
+        while (master.agents.has(id) || master.config.agents.some((a) => a.id === id))
             id = `${base.slice(0, 38)}-${n++}`;
         try {
             const agent = await master.addAgent({ id, workspace: ws, provider: body.provider, model: body.model }, { persist: true, fresh: true });
@@ -451,11 +463,25 @@ export function buildApp(master) {
         if (!body.text?.trim())
             return c.json({ error: "text required" }, 400);
         // returns immediately: the prompt is logged + broadcast now, delivered to
-        // the model at the next turn boundary (never blocks on a running agent)
-        a.enqueuePrompt(body.text, "user");
+        // the model at the next turn boundary (never blocks on a running agent).
+        // promptId ties the UI's pending echo to the later prompt-delivered note.
+        const promptId = a.enqueuePrompt(body.text, "user");
         if (body.start !== false && a.status !== "running")
             a.start("prompt");
-        return c.json({ ok: true, queued: a.snapshot().pendingPrompts });
+        return c.json({ ok: true, promptId, queued: a.snapshot().pendingPrompts });
+    });
+    // Withdraw a still-pending prompt; returns its text for the composer draft.
+    app.post("/api/agents/:id/prompt/cancel", async (c) => {
+        const a = master.agents.get(c.req.param("id"));
+        if (!a)
+            return c.json({ error: "not found" }, 404);
+        const body = await c.req.json();
+        if (!body.promptId)
+            return c.json({ error: "promptId required" }, 400);
+        const text = a.cancelPrompt(body.promptId);
+        if (text === null)
+            return c.json({ error: "not pending (already delivered?)" }, 409);
+        return c.json({ ok: true, text });
     });
     app.post("/api/agents/:id/start", (c) => {
         const a = master.agents.get(c.req.param("id"));
@@ -534,6 +560,8 @@ export function buildApp(master) {
         const body = await c.req.json();
         if (body.text) {
             await a.setGoal(body.text);
+            if (typeof body.verify === "string" && body.verify.trim())
+                await a.setGoalVerify(body.verify.trim());
             // goals live behind get_goal(), so a silent save would go unnoticed —
             // queue a harness prompt unless the caller explicitly declines
             if (body.notify !== false)
@@ -701,12 +729,33 @@ export function buildApp(master) {
         return c.json({ ok: true, ...r });
     });
     // ---- event log access (human/inspect friendly) ----
+    // mtime-keyed parse cache: the web UI polls this endpoint every ~400ms and
+    // re-reading + re-parsing the WHOLE chat.jsonl each time dominated CPU on
+    // multi-MB sessions. The file only ever appends, so an unchanged mtime lets
+    // us serve the previous parse verbatim.
+    const eventsCache = new Map();
+    async function readEventsCached(filePath) {
+        try {
+            const st = await fs.stat(filePath);
+            const hit = eventsCache.get(filePath);
+            if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
+                return hit.events;
+            const events = await readEvents(filePath);
+            if (eventsCache.size > 64)
+                eventsCache.clear();
+            eventsCache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, events });
+            return events;
+        }
+        catch {
+            return readEvents(filePath);
+        }
+    }
     app.get("/api/agents/:id/events", async (c) => {
         const a = master.agents.get(c.req.param("id"));
         if (!a)
             return c.json({ error: "not found" }, 404);
         const limit = Math.min(Number(c.req.query("limit") ?? 200), 5000);
-        let events = await readEvents(a.log.filePath);
+        let events = await readEventsCached(a.log.filePath);
         const branch = c.req.query("branch");
         const session = c.req.query("session");
         if (branch)

package/package.json

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