teapot-coding-agent 0.1.0

package/dist/agent/llm.js

@@ -0,0 +1,63 @@
+/**
+ * LLM access via the official `openai` npm client (OpenAI-compatible APIs:
+ * OpenAI, OpenRouter, local vLLM/Ollama, ...).
+ *
+ * We deliberately delegate retries/timeouts/response-shape handling to the
+ * SDK instead of hand-rolling them.
+ */
+import OpenAI from "openai";
+const clients = new WeakMap();
+function client(cfg) {
+    let c = clients.get(cfg);
+    if (!c) {
+        c = new OpenAI({
+            baseURL: cfg.baseUrl,
+            apiKey: cfg.apiKey,
+            timeout: cfg.timeoutMs ?? 120_000,
+            maxRetries: 4, // SDK handles backoff for 429/5xx/network errors
+        });
+        clients.set(cfg, c);
+    }
+    return c;
+}
+/**
+ * Providers are picky in different ways; the common denominator is that
+ * empty text content in user/assistant messages makes many of them 400.
+ * Fill blanks with a harmless placeholder before sending.
+ */
+function sanitize(messages) {
+    return messages.map((m) => {
+        if ((m.role === "user" || m.role === "assistant") && !m.content) {
+            return { ...m, content: m.tool_calls?.length ? "(tool call)" : "(no content)" };
+        }
+        if (m.role === "tool" && typeof m.content !== "string") {
+            return { ...m, content: String(m.content ?? "(no output)") };
+        }
+        return m;
+    });
+}
+export async function chat(cfg, messages, tools, signal) {
+    try {
+        const res = await client(cfg).chat.completions.create({
+            model: cfg.model,
+            messages: sanitize(messages),
+            ...(tools.length ? { tools } : {}),
+        }, { signal });
+        const message = res.choices?.[0]?.message;
+        if (!message)
+            throw new Error("LLM API returned no choices");
+        return {
+            message,
+            usage: res.usage
+                ? { inputTokens: res.usage.prompt_tokens, outputTokens: res.usage.completion_tokens }
+                : undefined,
+        };
+    }
+    catch (err) {
+        const e = err;
+        if (e.status === undefined)
+            throw err; // not an API error (abort, bug, ...)
+        const detail = e.error?.message ?? e.message ?? "unknown provider error";
+        throw new Error(`LLM API error ${e.status}: ${String(detail).slice(0, 500)}`);
+    }
+}

package/dist/agent/skills.js

@@ -0,0 +1,87 @@
+/**
+ * Agent Skills: reusable playbooks the agent can load on demand — and create
+ * itself, so knowledge accumulates across sessions instead of living only in
+ * chat history.
+ *
+ * A skill is a directory with a SKILL.md:
+ *
+ *   ---
+ *   name: release-checklist
+ *   description: Steps to cut a release safely
+ *   ---
+ *   (free-form instructions shown to the agent when it loads the skill)
+ *
+ * Roots are scanned in priority order; the first skill with a given name wins.
+ * Workspace skills (<workspace>/skills) beat global ones (~config/skills), so
+ * a project can override shared defaults. Everything stays human-readable and
+ * git-friendly Markdown — no database, no lock-in.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export const SKILL_FILE = "SKILL.md";
+export function isValidSkillName(name) {
+    return /^[a-z0-9][a-z0-9._-]{0,63}$/.test(name);
+}
+/**
+ * Minimal frontmatter parser for the subset we need: a leading `---` block of
+ * `key: value` lines. No YAML dependency by design.
+ */
+export function parseSkillMd(text) {
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!m)
+        return { meta: {}, body: text.trim() };
+    const meta = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (kv)
+            meta[kv[1].toLowerCase()] = kv[2].trim();
+    }
+    return { meta, body: m[2].trim() };
+}
+/** Root dirs in priority order: [0] overrides later ones on name clash. */
+export async function discoverSkills(roots) {
+    const byName = new Map();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await fs.readdir(root.dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // root missing → simply no skills there
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith("."))
+                continue;
+            const filePath = path.join(root.dir, e.name, SKILL_FILE);
+            let text;
+            try {
+                text = await fs.readFile(filePath, "utf8");
+            }
+            catch {
+                continue; // directory without SKILL.md is not a skill
+            }
+            const parsed = parseSkillMd(text);
+            const name = parsed.meta.name || e.name;
+            if (byName.has(name))
+                continue; // higher-priority root already defined it
+            byName.set(name, {
+                name,
+                description: parsed.meta.description || "",
+                source: root.source,
+                filePath,
+            });
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function readSkillFile(def) {
+    return fs.readFile(def.filePath, "utf8");
+}
+/** Write (or overwrite) a workspace skill; returns the file path written. */
+export async function saveSkill(workspaceRoot, name, description, content) {
+    const dir = path.join(workspaceRoot, name);
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, SKILL_FILE);
+    await fs.writeFile(filePath, `---\nname: ${name}\ndescription: ${description}\n---\n\n${content.trim()}\n`, "utf8");
+    return filePath;
+}

package/dist/agent/tools.js

@@ -0,0 +1,269 @@
+/**
+ * Tool execution: file ops, shell (with process-group kill + timeout), git.
+ * Tool specs are plain JSON-schema function definitions — provider-agnostic.
+ */
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { discoverSkills, isValidSkillName, readSkillFile, saveSkill, } from "./skills.js";
+const str = (v, fallback = "") => (typeof v === "string" ? v : fallback);
+const num = (v, fallback) => (typeof v === "number" ? v : fallback);
+function clip(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + `\n... [truncated, ${s.length} bytes total]`;
+}
+async function readText(p) {
+    return fs.readFile(p, "utf8");
+}
+/** Resolve a path inside the workspace; reject escapes. */
+function safeJoin(cwd, p) {
+    const abs = path.resolve(cwd, p);
+    const rel = path.relative(cwd, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new Error(`path escapes workspace: ${p}`);
+    }
+    return abs;
+}
+/** Run a command in its own process group; kill the whole group on timeout. */
+function runShell(cmd, ctx, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn("/bin/bash", ["-lc", cmd], {
+            cwd: ctx.cwd,
+            detached: true, // own process group
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, TERM: "dumb", GIT_PAGER: "cat", PAGER: "cat" },
+        });
+        let out = "";
+        let done = false;
+        let timedOut = false;
+        const collect = (chunk) => {
+            if (out.length < ctx.maxOutputBytes)
+                out += chunk.toString("utf8");
+        };
+        child.stdout.on("data", collect);
+        child.stderr.on("data", collect);
+        const killGroup = () => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, "SIGKILL"); // whole group
+            }
+            catch {
+                /* already gone */
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, timeoutMs);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            if (!done) {
+                done = true;
+                resolve({ ok: false, result: `spawn error: ${err.message}` });
+            }
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            if (done)
+                return;
+            done = true;
+            if (timedOut) {
+                resolve({
+                    ok: false,
+                    result: `TIMEOUT after ${timeoutMs}ms. Partial output:\n${clip(out.trim() || "(no output)", ctx.maxOutputBytes)}`,
+                });
+                return;
+            }
+            resolve({
+                ok: code === 0,
+                result: (code === 0 ? "" : `exit=${code}${signal ? ` signal=${signal}` : ""}\n`) +
+                    clip(out.trim() || "(no output)", ctx.maxOutputBytes),
+            });
+        });
+    });
+}
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const TOOLS = [
+    {
+        name: "read_file",
+        description: "Read a text file from the workspace. Supports offset/limit for large files. Returns numbered lines.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path relative to workspace root" },
+                offset: { type: "number", description: "1-indexed start line" },
+                limit: { type: "number", description: "Max lines to return" },
+            },
+            required: ["path"],
+        },
+        async run(args, ctx) {
+            const p = safeJoin(ctx.cwd, str(args.path));
+            const text = await readText(p);
+            const lines = text.split("\n");
+            const off = Math.max(0, num(args.offset, 1) - 1);
+            const lim = num(args.limit, 2000);
+            const slice = lines.slice(off, off + lim).map((l, i) => `${off + i + 1}| ${l}`);
+            const more = off + lim < lines.length ? `\n... (${lines.length - off - lim} more lines)` : "";
+            return { ok: true, result: slice.join("\n") + more };
+        },
+    },
+    {
+        name: "write_file",
+        description: "Create or overwrite a file with the given content (parent dirs auto-created).",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                content: { type: "string" },
+            },
+            required: ["path", "content"],
+        },
+        async run(args, ctx) {
+            const p = safeJoin(ctx.cwd, str(args.path));
+            await fs.mkdir(path.dirname(p), { recursive: true });
+            await fs.writeFile(p, str(args.content), "utf8");
+            return { ok: true, result: `wrote ${p} (${String(args.content).length} bytes)` };
+        },
+    },
+    {
+        name: "edit_file",
+        description: "Replace an exact unique substring in a file. old_text must match exactly and be unique.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                old_text: { type: "string" },
+                new_text: { type: "string" },
+            },
+            required: ["path", "old_text", "new_text"],
+        },
+        async run(args, ctx) {
+            const p = safeJoin(ctx.cwd, str(args.path));
+            const text = await readText(p);
+            const oldText = str(args.old_text);
+            const count = text.split(oldText).length - 1;
+            if (count === 0)
+                return { ok: false, result: "old_text not found in file" };
+            if (count > 1)
+                return { ok: false, result: `old_text matched ${count} times; must be unique` };
+            await fs.writeFile(p, text.replace(oldText, str(args.new_text)), "utf8");
+            return { ok: true, result: "edited" };
+        },
+    },
+    {
+        name: "list_dir",
+        description: "List files under a directory of the workspace.",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string", description: "default '.'" } },
+        },
+        async run(args, ctx) {
+            const p = safeJoin(ctx.cwd, str(args.path, "."));
+            const entries = await fs.readdir(p, { withFileTypes: true });
+            return {
+                ok: true,
+                result: entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name)).join("\n"),
+            };
+        },
+    },
+    {
+        name: "bash",
+        description: "Run a bash command inside the workspace (use it for git, builds, tests, etc.). " +
+            "Killed (whole process group) on timeout. stdout+stderr are returned.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string" },
+                timeout_ms: { type: "number", description: `default ${DEFAULT_TIMEOUT_MS}` },
+            },
+            required: ["command"],
+        },
+        async run(args, ctx) {
+            return runShell(str(args.command), ctx, Math.min(num(args.timeout_ms, ctx.defaultTimeoutMs), 600_000));
+        },
+    },
+    {
+        name: "load_skill",
+        description: "Load a skill's full instructions by name. Use when the system prompt's skill list " +
+            "matches your current task; follow the loaded playbook.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "skill name from the list in your system prompt" },
+            },
+            required: ["name"],
+        },
+        async run(args, ctx) {
+            const roots = ctx.skillRoots ?? [];
+            const skills = await discoverSkills(roots);
+            const def = skills.find((s) => s.name === str(args.name));
+            if (!def) {
+                return {
+                    ok: false,
+                    result: `unknown skill: ${str(args.name)}. Available: ${skills.map((s) => s.name).join(", ") || "(none)"}`,
+                };
+            }
+            return { ok: true, result: await readSkillFile(def) };
+        },
+    },
+    {
+        name: "save_skill",
+        description: "Create or update a reusable skill (a playbook you want to survive this session and be " +
+            "loadable later via load_skill). Write distilled, step-by-step instructions — not a chat log. " +
+            "The skill becomes available in your system prompt from the next turn.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "kebab-case id, e.g. release-checklist" },
+                description: { type: "string", description: "one line: what it is for / when to use it" },
+                content: { type: "string", description: "markdown instructions" },
+            },
+            required: ["name", "description", "content"],
+        },
+        async run(args, ctx) {
+            const roots = ctx.skillRoots ?? [];
+            if (roots.length === 0)
+                return { ok: false, result: "no skill roots configured" };
+            const name = str(args.name);
+            if (!isValidSkillName(name))
+                return { ok: false, result: "invalid skill name (use kebab-case: [a-z0-9.-], max 64 chars)" };
+            const description = str(args.description).slice(0, 200);
+            if (!description)
+                return { ok: false, result: "description required" };
+            const content = str(args.content);
+            if (!content.trim())
+                return { ok: false, result: "content required" };
+            const filePath = await saveSkill(roots[0].dir, name, description, content.slice(0, 64_000));
+            return { ok: true, result: `saved skill "${name}" to ${filePath} (listed from next turn)` };
+        },
+    },
+];
+/** Current skills across the configured roots (for the system prompt listing). */
+export async function currentSkills(ctx) {
+    return discoverSkills(ctx.skillRoots ?? []);
+}
+export function toolSpecs() {
+    return TOOLS.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+}
+export async function executeTool(name, rawArgs, ctx) {
+    const def = TOOLS.find((t) => t.name === name);
+    if (!def)
+        return { ok: false, result: `unknown tool: ${name}` };
+    let args;
+    try {
+        args = rawArgs ? JSON.parse(rawArgs) : {};
+    }
+    catch {
+        return { ok: false, result: `invalid JSON arguments: ${rawArgs.slice(0, 200)}` };
+    }
+    try {
+        return await def.run(args, ctx);
+    }
+    catch (err) {
+        return { ok: false, result: `tool error: ${err.message}` };
+    }
+}

package/dist/bus.js

@@ -0,0 +1,4 @@
+import { EventEmitter } from "node:events";
+/** Tiny process-wide pub/sub used to push updates to SSE clients (no polling). */
+export const bus = new EventEmitter();
+bus.setMaxListeners(100);

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * teapot master entry point.
+ * Usage: teapot [config.json]
+ * Config may also come from TEAPOT_* env vars (see src/master.ts).
+ */
+import { loadConfig, resolveConfigPath, Master } from "./master.js";
+import { buildApp, serveApp } from "./server/api.js";
+async function main() {
+    const configPath = resolveConfigPath(process.argv[2]);
+    const config = loadConfig(configPath);
+    console.log(`[teapot] config: ${configPath}`);
+    const hasProviders = Object.keys(config.providers ?? {}).length > 0;
+    if (!config.llm.apiKey && !hasProviders)
+        console.warn("[teapot] warning: no API key configured");
+    if (!config.llm.model && !hasProviders)
+        console.warn("[teapot] warning: no model configured");
+    const master = new Master(config, configPath);
+    await master.start();
+    const app = buildApp(master);
+    serveApp(app, config.port);
+    // agent crash isolation: an agent error never escapes its own loop; here we
+    // also make sure the process survives unexpected rejections.
+    process.on("uncaughtException", (err) => {
+        console.error("[teapot] uncaught exception (master survived):", err);
+    });
+    process.on("unhandledRejection", (err) => {
+        console.error("[teapot] unhandled rejection (master survived):", err);
+    });
+    const shutdown = async () => {
+        console.log("\n[teapot] shutting down...");
+        await Promise.allSettled([...master.agents.values()].map((a) => a.dispose()));
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+}
+void main();

package/dist/log/events.js

@@ -0,0 +1,132 @@
+/**
+ * Append-only JSONL event log.
+ *
+ * Design goals:
+ *  - One file per agent (sessions.log.jsonl). Every conversation, including
+ *    forks, lives in the SAME file as an interleaved event stream.
+ *  - Each line is one self-contained JSON object; humans can `cat`/`jq` it.
+ *  - Lineage is explicit: every event carries `session`, `branch`, and
+ *    `parent` (the previous event on the same branch). A `fork` event records
+ *    where the new branch started (fromSession/fromBranch/fromEvent), so any
+ *    session can be reconstructed by filtering `branch === X` or by walking
+ *    parent links from the fork point backwards into ancestor branches.
+ *  - Append-only + monotonic `seq` makes corruption detectable (a torn final
+ *    line is simply ignored on read).
+ */
+import { createWriteStream } from "node:fs";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+export class EventLog {
+    filePath;
+    agentId;
+    stream = null;
+    seq = 0;
+    chain = Promise.resolve();
+    /** branch -> last event id (in-memory reconstruction of parent chains) */
+    lastByBranch = new Map();
+    constructor(filePath, agentId) {
+        this.filePath = filePath;
+        this.agentId = agentId;
+    }
+    async load() {
+        mkdirSync(path.dirname(this.filePath), { recursive: true });
+        try {
+            const { readFile } = await import("node:fs/promises");
+            const text = await readFile(this.filePath, "utf8");
+            for (const line of text.split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const e = JSON.parse(line);
+                    if (typeof e.seq === "number" && e.seq > this.seq)
+                        this.seq = e.seq;
+                    this.lastByBranch.set(e.branch, e.id);
+                }
+                catch {
+                    /* torn trailing line: ignore */
+                }
+            }
+        }
+        catch {
+            /* new log */
+        }
+        // repair a torn tail: without this, the next append would fuse into the
+        // corrupt partial line and destroy two events instead of one
+        try {
+            const { stat, appendFile } = await import("node:fs/promises");
+            const st = await stat(this.filePath);
+            if (st.size > 0) {
+                const buf = Buffer.alloc(1);
+                const fh = await import("node:fs/promises").then((m) => m.open(this.filePath, "r"));
+                await fh.read(buf, 0, 1, st.size - 1);
+                await fh.close();
+                if (buf[0] !== 0x0a)
+                    await appendFile(this.filePath, "\n");
+            }
+        }
+        catch {
+            /* file may not exist yet */
+        }
+        this.stream = createWriteStream(this.filePath, { flags: "a" });
+        this.stream.on("error", (err) => {
+            console.error(`[teapot] log write error (${this.filePath}):`, err.message);
+        });
+    }
+    /** Append an event; resolves when it is handed to the OS (write flushed). */
+    append(type, session, branch, data) {
+        const evt = {
+            v: 1,
+            id: `e${++this.seq}`,
+            seq: this.seq,
+            ts: new Date().toISOString(),
+            agent: this.agentId,
+            session,
+            branch,
+            parent: this.lastByBranch.get(branch) ?? null,
+            type,
+            data,
+        };
+        this.lastByBranch.set(branch, evt.id);
+        const p = new Promise((resolve, reject) => {
+            this.chain = this.chain.then(() => {
+                if (!this.stream)
+                    return resolve(evt);
+                this.stream.write(JSON.stringify(evt) + "\n", "utf8", (err) => err ? reject(err) : resolve(evt));
+            }, () => resolve(evt));
+        });
+        this.chain = this.chain.then(() => { }, () => { });
+        return p;
+    }
+    lastEventId(branch) {
+        return this.lastByBranch.get(branch) ?? null;
+    }
+    async close() {
+        await this.chain.catch(() => { });
+        if (!this.stream)
+            return;
+        const s = this.stream;
+        this.stream = null;
+        await new Promise((res) => s.end(res));
+    }
+}
+/** Read all events from a JSONL file (tolerates a torn final line). */
+export async function readEvents(filePath) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        const out = [];
+        for (const line of (await readFile(filePath, "utf8")).split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* skip bad line */
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}