teapot-coding-agent 0.37.59 → 0.37.61

package/dist/agent/plugins.js

@@ -1,40 +1,5 @@
-/**
- * Agent Plugins (#162): read a `plugin.json` package and turn it into things teapot
- * already understands.
- *
- * The format (https://agent-plugins.org, spec 1.1.0) is deliberately tiny, and the
- * whole point of adopting it is that it needs almost no new machinery here:
- *
- *   my-plugin/
- *   ├── plugin.json     manifest: `$schema` + `name` are the only required fields
- *   ├── skills/<name>/SKILL.md   → a skill ROOT (teapot already scans for SKILL.md)
- *   ├── mcp.json        → `mcpServers`, the same shape as teapot's own MCP config
- *   └── com.example.client/…     → client extensions, which we do not implement
- *
- * So a plugin is loaded by VALIDATING it and then extracting those two components. No
- * plugin runtime, no per-plugin process for skills.
- *
- * What is validated, and why each rule exists:
- *   - `plugin.json` must exist, be an object, and carry `$schema` and `name`. The spec
- *     requires both; a manifest without them is not a plugin, and guessing is worse
- *     than saying so.
- *   - `name` must match the spec's pattern (lowercase, no `--`, no `..`). The pattern is
- *     not cosmetic: the name is used in paths and in tool namespaces, so `..` in a name
- *     is a traversal primitive.
- *   - **containment**: `plugin.json`, `skills/`, and every discovered `SKILL.md` must
- *     resolve INSIDE the plugin root after following symlinks. The spec makes this a
- *     MUST, and it is the one rule with a real security consequence: a plugin shipped
- *     as an archive can contain a symlink pointing at `~/.ssh`.
- *   - a `cwd`/`command` in `mcp.json` that escapes the root invalidates that SERVER,
- *     not the whole plugin — the spec draws exactly that boundary (§4.1).
- *
- * `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are expanded in `args`, `env` and `cwd` of a
- * stdio server, as the spec requires. `PLUGIN_DATA` is a client-managed per-plugin
- * directory, so each plugin gets a stable writable location that survives an upgrade.
- */
 import { readFile, readdir, realpath, mkdir, stat } from "node:fs/promises";
 import path from "node:path";
-/** the spec's name pattern, verbatim from plugin.schema.json */
 const NAME_RE = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
 export class PluginError extends Error {
     constructor(message) {
@@ -42,19 +7,10 @@ export class PluginError extends Error {
         this.name = "PluginError";
     }
 }
-/** true when `child` is `parent` or inside it (both already resolved) */
 function within(parent, child) {
     const rel = path.relative(parent, child);
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
-/**
- * Resolve a path and prove it stays inside `root`.
- *
- * `realpath` FIRST, because a symlink is exactly how an archive escapes its own root —
- * checking the literal path would let `skills/evil -> /etc` through. A path that does
- * not exist cannot escape, so ENOENT returns the lexical join and lets the caller's own
- * existence checks report it.
- */
 async function resolveInside(root, p) {
     const abs = path.resolve(root, p);
     try {
@@ -65,16 +21,9 @@ async function resolveInside(root, p) {
         return within(root, abs) ? abs : null;
     }
 }
-/** expand `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` (the only two the spec defines) */
 function expand(s, root, data) {
     return s.split("${PLUGIN_ROOT}").join(root).split("${PLUGIN_DATA}").join(data);
 }
-/**
- * Load and validate one plugin directory.
- *
- * @param dir    the plugin root
- * @param dataDir the client-managed `PLUGIN_DATA` directory for this plugin
- */
 export async function loadPlugin(dir, dataDir) {
     let root;
     try {
@@ -86,7 +35,6 @@ export async function loadPlugin(dir, dataDir) {
     const st = await stat(root).catch(() => null);
     if (!st?.isDirectory())
         throw new PluginError(`not a directory: ${dir}`);
-    // ---- manifest ----
     const manifestPath = await resolveInside(root, "plugin.json");
     if (!manifestPath)
         throw new PluginError("plugin.json resolves outside the plugin root");
@@ -106,8 +54,6 @@ export async function loadPlugin(dir, dataDir) {
     }
     if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest))
         throw new PluginError("plugin.json must be a JSON object");
-    // the spec makes BOTH required; without $schema we cannot know which version's rules
-    // to apply, and silently assuming 1.1.0 is how a v2 plugin gets half-loaded
     if (typeof manifest.$schema !== "string")
         throw new PluginError("plugin.json is missing $schema (an Agent Plugins manifest requires it)");
     if (typeof manifest.name !== "string" || !manifest.name)
@@ -126,11 +72,6 @@ export async function loadPlugin(dir, dataDir) {
         out.version = manifest.version;
     if (typeof manifest.description === "string")
         out.description = manifest.description;
-    // ---- skills/ ----
-    //
-    // An immediate child directory containing a regular `SKILL.md` is one skill. The
-    // spec says MUST NOT recurse deeper, and that is also what keeps a plugin from
-    // silently pulling in a skill buried in `scripts/vendor/…`.
     const skillsDir = await resolveInside(root, "skills");
     if (!skillsDir) {
         out.warnings.push("skills/ resolves outside the plugin root — ignored");
@@ -149,7 +90,6 @@ export async function loadPlugin(dir, dataDir) {
             const sst = await stat(sm).catch(() => null);
             if (!sst?.isFile())
                 continue;
-            // the SKILL.md itself must also be contained (a symlinked one could point anywhere)
             const real = await realpath(sm).catch(() => null);
             if (!real || !within(root, real)) {
                 out.warnings.push(`skill "${entry.name}": SKILL.md escapes the plugin root — skipped`);
@@ -158,7 +98,6 @@ export async function loadPlugin(dir, dataDir) {
             out.skills.push(entry.name);
         }
     }
-    // ---- mcp.json ----
     const mcpPath = await resolveInside(root, "mcp.json");
     if (mcpPath && (await stat(mcpPath).catch(() => null))?.isFile()) {
         let cfg;
@@ -185,14 +124,6 @@ export async function loadPlugin(dir, dataDir) {
     }
     return out;
 }
-/**
- * Turn one `mcp.json` server entry into teapot's `McpServerConfig`.
- *
- * Returns a STRING when the entry is invalid, because the spec's failure boundary is
- * per-server: one bad entry must not reject the plugin. The name is prefixed with the
- * plugin name so two plugins can each ship a server called `db` without colliding in
- * the shared registry.
- */
 async function pluginServer(name, raw, root, dataDir) {
     if (typeof raw !== "object" || raw === null)
         return `mcp server "${name}": not an object`;
@@ -202,7 +133,6 @@ async function pluginServer(name, raw, root, dataDir) {
         if (typeof s.command !== "string" || !s.command)
             return `mcp server "${name}": stdio requires a command`;
         const command = expand(s.command, root, dataDir);
-        // a plugin-relative command must START with ./ (spec §4.1.4) and stay inside
         let resolvedCmd = command;
         if (command.startsWith("./")) {
             const abs = await resolveInside(root, command);
@@ -216,7 +146,6 @@ async function pluginServer(name, raw, root, dataDir) {
                 return `mcp server "${name}": command escapes the plugin root`;
             resolvedCmd = abs;
         }
-        // cwd: "./x", "${PLUGIN_ROOT}/x" or "${PLUGIN_DATA}/x" — anything else is invalid
         let cwd;
         if (s.cwd !== undefined) {
             if (typeof s.cwd !== "string")
@@ -229,7 +158,6 @@ async function pluginServer(name, raw, root, dataDir) {
             const abs = path.resolve(expanded);
             if (!within(base, abs))
                 return `mcp server "${name}": cwd escapes its root`;
-            // PLUGIN_DATA may not exist yet; the spec says the client manages it
             if (rootedInData)
                 await mkdir(base, { recursive: true }).catch(() => { });
             cwd = abs;
@@ -237,7 +165,6 @@ async function pluginServer(name, raw, root, dataDir) {
         const env = {};
         if (s.env && typeof s.env === "object" && !Array.isArray(s.env)) {
             for (const [k, v] of Object.entries(s.env)) {
-                // the spec forbids these two in env: the client owns them
                 if (k === "PLUGIN_ROOT" || k === "PLUGIN_DATA")
                     return `mcp server "${name}": env may not set ${k}`;
                 if (typeof v === "string")
@@ -278,13 +205,6 @@ async function pluginServer(name, raw, root, dataDir) {
     }
     return `mcp server "${name}": unknown type ${JSON.stringify(type)} (expected stdio, streamable-http or sse)`;
 }
-/**
- * Load every plugin under a directory of plugins.
- *
- * A broken plugin is reported and skipped rather than failing the whole collection —
- * the operator installed it to get something else working, and a plugin is
- * third-party code.
- */
 export async function loadPlugins(dir, dataRoot) {
     const plugins = [];
     const errors = [];
@@ -296,7 +216,7 @@ export async function loadPlugins(dir, dataRoot) {
             .sort();
     }
     catch {
-        return { plugins, errors }; // no plugin dir is the normal case
+        return { plugins, errors };
     }
     for (const name of entries) {
         const p = path.join(dir, name);

package/dist/agent/provider-headers.js

@@ -1,28 +1,3 @@
-/**
- * Request headers a provider needs to route and cache a turn.
- *
- * Lives in its own module because it is a pure string computation and `llm.ts` imports the `openai`
- * SDK — which MEASURED +32MB RSS / +6.7MB heap just to be loaded. `model-meta.ts` needs exactly this
- * function and nothing else, so importing it from `llm.ts` pulled the whole SDK into the boot path of
- * every process (the server, every test file, every script).
- */
-/**
- * Per-endpoint request headers. Empty (harmless no-op) for every provider that
- * does not ask for any.
- *
- * OpenRouter app attribution (https://openrouter.ai/docs/app-attribution):
- * `HTTP-Referer` is the required identifier that puts teapot's usage on the
- * public rankings/analytics; the title names it; `programming-app` files it
- * under coding tools.
- *
- * OpenCode Go (https://opencode.ai/docs/go/#where-can-i-use-it) identifies a
- * conversation by `x-opencode-session` and returns HTTP 400 without it —
- * "Request is missing x-opencode-session and cannot be routed efficiently" —
- * so a turn on that endpoint must name the session it belongs to. The value is
- * the session directory name, which is stable for the whole conversation:
- * a compaction is a new request but not a new conversation, so it keeps the id,
- * while a fork/incarnation switch (`currentSession`) gets its own.
- */
 export function providerHeaders(baseUrl, sessionId) {
     try {
         const host = new URL(baseUrl).host;
@@ -33,13 +8,11 @@ export function providerHeaders(baseUrl, sessionId) {
                 "X-OpenRouter-Categories": "programming-app",
             };
         }
-        // scoped to this host so the id cannot follow the operator to another
-        // provider, and skipped entirely when there is no session to name
         if (sessionId && /(^|\.)opencode\.ai$/i.test(host))
             return { "x-opencode-session": sessionId };
         return {};
     }
     catch {
-        return {}; // unparseable baseUrl — never block a request over metadata
+        return {};
     }
 }

package/dist/agent/skills.js

@@ -1,35 +1,7 @@
-/**
- * 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.
- */
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { homeDir } from "../home.js";
 export const SKILL_FILE = "SKILL.md";
-/**
- * Cheap change-detector for a set of skill roots. Returns a stable string
- * that changes whenever a root is added, removed, or modified — so callers
- * can skip a full rescan (a readdir per root plus a read of every SKILL.md)
- * on the overwhelmingly common "nothing changed" path.
- *
- * It must walk every SKILL.md the discovery walk could adopt, not just the
- * roots: writing SKILL.md does not bump the parent directory's mtime. Helper
- * scripts edited in place ride along with the next skill write (saveSkill
- * rewrites SKILL.md), rather than triggering their own rescan.
- */
 export async function skillRootsFingerprint(roots) {
     const parts = [];
     for (const root of roots) {
@@ -39,17 +11,14 @@ export async function skillRootsFingerprint(roots) {
             st = await fs.stat(root.dir);
         }
         catch {
-            parts.push("-"); // root missing → no skills here (same as discoverSkills)
+            parts.push("-");
             continue;
         }
         parts.push(`${st.mtimeMs}:${st.size}`);
-        // same depth bound as the discovery walk, or a NESTED skill's add/edit leaves
-        // this stamp unchanged and the skill stays stale in list_skills
         await stampSkillFiles(root.dir, 0, parts);
     }
     return parts.join("|");
 }
-/** recursive fingerprint walk — mirrors walkSkills' depth bound */
 async function stampSkillFiles(dir, depth, parts) {
     if (depth > MAX_SKILL_DEPTH)
         return;
@@ -71,7 +40,6 @@ async function stampSkillFiles(dir, depth, parts) {
             parts.push(`${full}=${s.mtimeMs}:${s.size}`);
         }
         catch {
-            // not a skill dir itself — still a container to descend into
         }
         await stampSkillFiles(full, depth + 1, parts);
     }
@@ -79,21 +47,6 @@ async function stampSkillFiles(dir, depth, parts) {
 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.
- *
- * It does understand the two YAML shapes common in REAL third-party skills
- * (#28), because without them those files are unreadable:
- *  - FOLDED/LITERAL BLOCK SCALARS (`description: >-` … or `|` …), which is how
- *    most skill authors write a long description. Reading them naively yields
- *    the literal ">-" as the description, which silently destroys the one field
- *    the model matches its task against.
- *  - QUOTED values, whose surrounding quotes are stripped so a description
- *    containing a colon survives.
- * A key with an empty value (e.g. a nested `metadata:` block) is left out rather
- * than recorded as "".
- */
 export function parseSkillMd(text) {
     const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
     if (!m)
@@ -106,8 +59,6 @@ export function parseSkillMd(text) {
             continue;
         const key = kv[1].toLowerCase();
         const raw = kv[2].trim();
-        // folded (>-, >, |-, |) or literal (|, |-) block scalar: the value is the
-        // following, more-indented lines
         if (/^[>|][-+]?$/.test(raw)) {
             const parts = [];
             let j = i + 1;
@@ -118,7 +69,7 @@ export function parseSkillMd(text) {
                     continue;
                 }
                 if (!/^\s/.test(l))
-                    break; // dedented → block ended
+                    break;
                 parts.push(l.trim());
             }
             i = j - 1;
@@ -128,12 +79,11 @@ export function parseSkillMd(text) {
             continue;
         }
         if (raw === "")
-            continue; // `metadata:` with a nested block below
+            continue;
         meta[key] = unquote(raw);
     }
     return { meta, body: m[2].trim() };
 }
-/** Strip one layer of matching quotes; a quoted value may itself contain `:`. */
 function unquote(v) {
     const s = v.trim();
     if (s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))) {
@@ -144,21 +94,7 @@ function unquote(v) {
     }
     return s;
 }
-/**
- * Skill directories owned by OTHER coding harnesses (#28).
- *
- * SKILL.md is a shared convention, so these are readable as-is — the only
- * thing that ever blocked them was our frontmatter parser (folded scalars and
- * quoted values), now handled. Paths are the documented native locations,
- * plus the cross-tool directories several tools also read.
- *
- * Priority is deliberately the LOWEST of the user-supplied roots: a project
- * should never be shadowed by another tool's copy of the same skill. Missing
- * directories are skipped silently, and nothing is read unless it exists.
- */
 export function foreignSkillRoots(workspace) {
-    // #110: the shared helper also covers HOMEDRIVE/HOMEPATH, which is how
-    // Windows reports a home when USERPROFILE is absent.
     const home = homeDir();
     const out = [];
     const add = (dir) => {
@@ -166,27 +102,26 @@ export function foreignSkillRoots(workspace) {
             out.push({ dir, source: "foreign" });
     };
     if (workspace) {
-        // project-local locations other tools read
         for (const rel of [
-            path.join(".agents", "skills"), // cross-tool convention
+            path.join(".agents", "skills"),
             path.join(".claude", "skills"),
             path.join(".codex", "skills"),
             path.join(".cursor", "skills"),
             path.join(".gemini", "skills"),
-            path.join(".github", "skills"), // Copilot CLI + VS Code
+            path.join(".github", "skills"),
             path.join(".opencode", "skills"),
         ]) {
             add(path.join(workspace, rel));
         }
     }
     if (home) {
-        add(path.join(home, ".agents", "skills")); // cross-tool, personal
+        add(path.join(home, ".agents", "skills"));
         for (const rel of [
             [".claude", "skills"],
             [".codex", "skills"],
             [".cursor", "skills"],
             [".gemini", "skills"],
-            [".copilot", "skills"], // GitHub Copilot CLI + VS Code share this
+            [".copilot", "skills"],
             [".config", "opencode", "skills"],
         ]) {
             add(path.join(home, ...rel));
@@ -194,31 +129,15 @@ export function foreignSkillRoots(workspace) {
     }
     return out;
 }
-/**
- * How deep to look for nested skills (#27).
- *
- * Bounded because a skill directory also holds BUNDLED FILES (helper scripts)
- * and arbitrary payload, so an unbounded walk is not safe. Depth is not the
- * thing that makes a directory a skill — holding a SKILL.md is — so the bound
- * only limits how far we look, never what counts.
- */
 const MAX_SKILL_DEPTH = 4;
-/** Root dirs in priority order: [0] overrides later ones on name clash. */
 export async function discoverSkills(roots) {
     const byName = new Map();
-    // name -> depth, so a SHALLOWER skill beats a nested namesake (#27)
     const depthByName = new Map();
     for (const root of roots) {
         await walkSkills(root.dir, root.source, 0, byName, depthByName);
     }
     return [...byName.values()];
 }
-/**
- * Depth-first walk collecting every directory that holds a SKILL.md (#27).
- *
- * A directory without its own SKILL.md is only a container to descend into, which
- * is what keeps bundled helper directories from being reported as skills.
- */
 async function walkSkills(dir, source, depth, byName, depthByName) {
     if (depth > MAX_SKILL_DEPTH)
         return;
@@ -227,9 +146,8 @@ async function walkSkills(dir, source, depth, byName, depthByName) {
         entries = await fs.readdir(dir, { withFileTypes: true });
     }
     catch {
-        return; // root missing → simply no skills there
+        return;
     }
-    // a SKILL.md sitting directly in `dir` makes `dir` a skill AND a container
     const here = path.join(dir, SKILL_FILE);
     let hereText = null;
     try {
@@ -253,7 +171,6 @@ async function walkSkills(dir, source, depth, byName, depthByName) {
                     .sort();
             }
             catch {
-                /* unreadable dir → no bundled files */
             }
             byName.set(name, {
                 name,
@@ -268,15 +185,12 @@ async function walkSkills(dir, source, depth, byName, depthByName) {
     for (const e of entries) {
         if (!e.isDirectory() || e.name.startsWith("."))
             continue;
-        // a skill can sit at ANY depth (skills/stage1/template/SKILL.md), and
-        // "stage1" itself has no SKILL.md (#27)
         await walkSkills(path.join(dir, e.name), source, depth + 1, byName, depthByName);
     }
 }
 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 });