@cmgmyr/hive 0.1.0

package/dist/tools/kv.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { db } from "../db.js";
+import { currentActor, effectiveProjectId } from "../context.js";
+import { run } from "../result.js";
+import { idParam, projectIdParam } from "./params.js";
+function purgeExpired(projectId) {
+    db.prepare("DELETE FROM kv WHERE project_id = ? AND expires_at IS NOT NULL AND expires_at < datetime('now')").run(projectId);
+}
+export function registerKv(server) {
+    server.registerTool("kv_set", {
+        description: "Set a small shared JSON value other sessions can discover. Optional TTL in seconds.",
+        inputSchema: {
+            key: z.string(),
+            value: z.any().describe("Any JSON value."),
+            ttl_seconds: z.number().int().positive().optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: { project_id: idParam, key: z.string() },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        purgeExpired(projectId);
+        const actor = currentActor();
+        db.prepare(`INSERT INTO kv (project_id, key, value, updated_by, expires_at)
+           VALUES (?, ?, ?, ?, CASE WHEN ? IS NULL THEN NULL ELSE datetime('now', printf('+%d seconds', ?)) END)
+           ON CONFLICT(project_id, key) DO UPDATE SET
+             value = excluded.value,
+             updated_by = excluded.updated_by,
+             updated_at = datetime('now'),
+             expires_at = excluded.expires_at`).run(projectId, args.key, JSON.stringify(args.value ?? null), actor, args.ttl_seconds ?? null, args.ttl_seconds ?? null);
+        return { project_id: projectId, key: args.key };
+    }));
+    server.registerTool("kv_get", {
+        description: "Get a shared JSON value by key.",
+        inputSchema: { key: z.string(), project_id: projectIdParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        purgeExpired(projectId);
+        const row = db
+            .prepare("SELECT * FROM kv WHERE project_id = ? AND key = ?")
+            .get(projectId, args.key);
+        if (!row)
+            return { project_id: projectId, key: args.key, found: false };
+        return {
+            project_id: projectId,
+            key: row.key,
+            found: true,
+            value: JSON.parse(row.value),
+            updated_by: row.updated_by,
+            updated_at: row.updated_at,
+            expires_at: row.expires_at,
+        };
+    }));
+    server.registerTool("kv_list", {
+        description: "List shared values, optionally filtered by key prefix.",
+        inputSchema: { prefix: z.string().optional(), project_id: projectIdParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        purgeExpired(projectId);
+        let sql = "SELECT * FROM kv WHERE project_id = ?";
+        const params = [projectId];
+        if (args.prefix) {
+            sql += " AND key LIKE ?";
+            params.push(`${args.prefix}%`);
+        }
+        sql += " ORDER BY key";
+        const rows = db.prepare(sql).all(...params);
+        return {
+            project_id: projectId,
+            entries: rows.map((r) => ({
+                key: r.key,
+                value: JSON.parse(r.value),
+                updated_by: r.updated_by,
+                updated_at: r.updated_at,
+                expires_at: r.expires_at,
+            })),
+        };
+    }));
+    server.registerTool("kv_delete", {
+        description: "Delete a shared value by key.",
+        inputSchema: { key: z.string(), project_id: projectIdParam },
+        outputSchema: { project_id: idParam, key: z.string(), deleted: z.boolean() },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const info = db
+            .prepare("DELETE FROM kv WHERE project_id = ? AND key = ?")
+            .run(projectId, args.key);
+        return { project_id: projectId, key: args.key, deleted: info.changes > 0 };
+    }));
+}

package/dist/tools/leases.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { db } from "../db.js";
+import { currentActor, effectiveProjectId } from "../context.js";
+import { run } from "../result.js";
+import { idParam, projectIdParam } from "./params.js";
+function purgeExpired(projectId) {
+    db.prepare("DELETE FROM leases WHERE project_id = ? AND expires_at < datetime('now')").run(projectId);
+}
+export function readLease(projectId, key) {
+    return db.prepare("SELECT * FROM leases WHERE project_id = ? AND lock_key = ?").get(projectId, key);
+}
+export function extendOwnedLease(projectId, key, actor, ttlSeconds) {
+    const info = db
+        .prepare(`UPDATE leases SET expires_at = datetime('now', printf('+%d seconds', ?))
+       WHERE project_id = ? AND lock_key = ? AND owner = ?`)
+        .run(ttlSeconds, projectId, key, actor);
+    return info.changes > 0;
+}
+export function registerLeases(server) {
+    server.registerTool("lease_acquire", {
+        description: "Try to take a named lease on a shared work area (non-blocking). Re-taking your own lease extends it. Leases expire on their own.",
+        inputSchema: {
+            key: z.string().describe('Stable and specific, like "file:src/api/routes.ts".'),
+            ttl_seconds: z.number().int().positive(),
+            project_id: projectIdParam,
+        },
+        outputSchema: {
+            project_id: idParam,
+            key: z.string(),
+            acquired: z.boolean(),
+            expires_at: z.string().optional(),
+            extended: z.boolean().optional(),
+            held_by: z.string().optional(),
+        },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        purgeExpired(projectId);
+        const actor = currentActor();
+        const inserted = db
+            .prepare(`INSERT INTO leases (project_id, lock_key, owner, expires_at)
+             VALUES (?, ?, ?, datetime('now', printf('+%d seconds', ?)))
+             ON CONFLICT(project_id, lock_key) DO NOTHING
+             RETURNING expires_at`)
+            .get(projectId, args.key, actor, args.ttl_seconds);
+        if (inserted) {
+            return { project_id: projectId, key: args.key, acquired: true, expires_at: inserted.expires_at };
+        }
+        const row = readLease(projectId, args.key);
+        if (!row) {
+            return { project_id: projectId, key: args.key, acquired: false };
+        }
+        if (row.owner === actor) {
+            if (extendOwnedLease(projectId, args.key, actor, args.ttl_seconds)) {
+                return { project_id: projectId, key: args.key, acquired: true, extended: true };
+            }
+            const current = readLease(projectId, args.key);
+            if (!current) {
+                return { project_id: projectId, key: args.key, acquired: false };
+            }
+            return {
+                project_id: projectId,
+                key: args.key,
+                acquired: false,
+                held_by: current.owner,
+                expires_at: current.expires_at,
+            };
+        }
+        return {
+            project_id: projectId,
+            key: args.key,
+            acquired: false,
+            held_by: row.owner,
+            expires_at: row.expires_at,
+        };
+    }));
+    server.registerTool("lease_release", {
+        description: "Release a lease you own.",
+        inputSchema: { key: z.string(), project_id: projectIdParam },
+        outputSchema: { project_id: idParam, key: z.string(), released: z.boolean() },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const info = db
+            .prepare("DELETE FROM leases WHERE project_id = ? AND lock_key = ? AND owner = ?")
+            .run(projectId, args.key, currentActor());
+        return { project_id: projectId, key: args.key, released: info.changes > 0 };
+    }));
+}

package/dist/tools/meta.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { db } from "../db.js";
+import { addProject, currentActor, listProjects, resolveProject, selectProjectById, TOUCH_INTERVAL_MS, trySelectedProject, } from "../context.js";
+import { errorMessage, run } from "../result.js";
+import { HELP_TOPICS, helpOverview } from "../help.js";
+import { idParam } from "./params.js";
+function refuseIfLocked(tool) {
+    if (process.env.HIVE_PROJECT_LOCK === "1") {
+        throw new Error(`${tool} sweeps the whole store, across every project and every actor. This session is locked to one project (HIVE_PROJECT_LOCK=1) and cannot run it. Run it from an unlocked session (a lead).`);
+    }
+}
+export const PROJECT_OWNER_TABLES = [
+    "pads",
+    "todos",
+    "kv",
+    "leases",
+    "agents",
+    "wakes",
+    "command_trust",
+];
+function existsWhere(table, column, value) {
+    return db.prepare(`SELECT 1 FROM ${table} WHERE ${column} = ? LIMIT 1`).get(value) !== undefined;
+}
+function projectOwnsRows(projectId) {
+    return PROJECT_OWNER_TABLES.some((table) => existsWhere(table, "project_id", projectId));
+}
+const pruneProjectIfEmpty = db.transaction((projectId) => {
+    if (projectOwnsRows(projectId))
+        return false;
+    return db.prepare("DELETE FROM projects WHERE id = ?").run(projectId).changes > 0;
+});
+export const ACTOR_OWNER_COLUMNS = [
+    ["agents", "actor_id"],
+    ["agents", "parent_actor_id"],
+    ["todos", "locked_by"],
+    ["todo_comments", "author"],
+    ["kv", "updated_by"],
+    ["leases", "owner"],
+    ["pads", "updated_by"],
+    ["wakes", "owner"],
+    ["wakes", "deliver_actor"],
+    ["agent_state_log", "actor_id"],
+];
+function actorOwnsRows(actorId) {
+    return ACTOR_OWNER_COLUMNS.some(([table, column]) => existsWhere(table, column, actorId));
+}
+const ACTOR_LIVENESS_WINDOW_MS = TOUCH_INTERVAL_MS * 2;
+function actorRecentlySeen(actorId) {
+    return (db
+        .prepare("SELECT 1 FROM actors WHERE id = ? AND last_seen_at >= datetime('now', ?) LIMIT 1")
+        .get(actorId, `-${Math.ceil(ACTOR_LIVENESS_WINDOW_MS / 1000)} seconds`) !== undefined);
+}
+const pruneActorIfInert = db.transaction((actorId) => {
+    if (actorRecentlySeen(actorId))
+        return "live";
+    if (actorOwnsRows(actorId))
+        return "kept";
+    return db.prepare("DELETE FROM actors WHERE id = ?").run(actorId).changes > 0 ? "deleted" : "kept";
+});
+export function registerMeta(server) {
+    server.registerTool("whoami", {
+        description: "Show this session's actor identity and effective project scope. Call this first in a new session.",
+        inputSchema: {},
+    }, () => run(() => {
+        const actorId = currentActor();
+        const actor = db.prepare("SELECT * FROM actors WHERE id = ?").get(actorId);
+        let project = null;
+        let projectError;
+        try {
+            project = resolveProject();
+        }
+        catch (e) {
+            projectError = e instanceof Error ? e.message : String(e);
+        }
+        return {
+            actor_id: actor.id,
+            actor_name: actor.name,
+            kind: actor.kind,
+            project: project ? { id: project.id, name: project.name, path: project.path } : null,
+            ...(projectError ? { project_error: projectError } : {}),
+            cwd: process.cwd(),
+        };
+    }));
+    server.registerTool("help", {
+        description: `Hive usage guidance. Omit topic for an overview, or pass one of: ${Object.keys(HELP_TOPICS).join(", ")}.`,
+        inputSchema: { topic: z.string().optional() },
+    }, ({ topic }) => run(() => {
+        if (!topic)
+            return helpOverview();
+        const text = HELP_TOPICS[topic.toLowerCase()];
+        if (!text) {
+            throw new Error(`Unknown topic "${topic}". Topics: ${Object.keys(HELP_TOPICS).join(", ")}`);
+        }
+        return text;
+    }));
+    server.registerTool("project_list", {
+        description: "List registered projects and the currently selected one.",
+        inputSchema: {},
+    }, () => run(() => ({
+        projects: listProjects(),
+        selected_project_id: trySelectedProject()?.id ?? null,
+    })));
+    server.registerTool("project_add", {
+        description: "Register a directory as a project. Defaults to the current working directory. Returns the existing project if the path is already registered.",
+        inputSchema: {
+            path: z.string().optional(),
+            name: z.string().optional(),
+        },
+        outputSchema: { id: idParam, name: z.string(), path: z.string(), created_at: z.string() },
+    }, ({ path, name }) => run(() => addProject(path, name)));
+    server.registerTool("project_select", {
+        description: "Set which project later tools act on in this session.",
+        inputSchema: { project_id: idParam },
+    }, ({ project_id }) => run(() => selectProjectById(project_id)));
+    server.registerTool("project_prune", {
+        description: "Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust), verified individually before each delete. Never prunes the caller's own project. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.",
+        inputSchema: {},
+        outputSchema: {
+            deleted: z.array(z.object({ id: idParam, name: z.string() })),
+            held_back: z.object({ project_id: idParam, reason: z.string() }),
+            errors: z.array(z.object({ id: idParam, name: z.string(), error: z.string() })).optional(),
+        },
+    }, () => run(() => {
+        refuseIfLocked("project_prune");
+        const homeId = resolveProject().id;
+        const deleted = [];
+        const errors = [];
+        for (const project of listProjects()) {
+            if (project.id === homeId)
+                continue;
+            try {
+                if (pruneProjectIfEmpty.immediate(project.id)) {
+                    deleted.push({ id: project.id, name: project.name });
+                }
+            }
+            catch (e) {
+                errors.push({ id: project.id, name: project.name, error: errorMessage(e) });
+            }
+        }
+        return {
+            deleted,
+            held_back: { project_id: homeId, reason: "caller's own project" },
+            ...(errors.length > 0 ? { errors } : {}),
+        };
+    }));
+    server.registerTool("actor_prune", {
+        description: "Delete every actor that owns no rows anywhere in the store and has not been active in the last minute: agents.actor_id, agents.parent_actor_id, todos.locked_by, todo_comments.author, kv.updated_by, leases.owner, pads.updated_by, wakes.owner, wakes.deliver_actor, agent_state_log.actor_id. The scan is global across every project, never scoped to the caller's: actors carry no project_id, so an actor can own rows in a project the caller cannot see, and a project-scoped scan would misread that actor as inert and delete it. Never prunes the caller's own actor. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep. Run this after project_prune when sweeping the store: an empty project owns no agents rows either, so today the order cannot orphan an actor, but that stops being true the day project deletion ever covers a non-empty project, and this ordering is the one that stays safe if it does. Immediate, permanent: no dry-run mode.",
+        inputSchema: {},
+        outputSchema: {
+            deleted: z.array(z.object({ id: z.string(), name: z.string() })),
+            held_back: z.object({ actor_id: z.string(), reason: z.string() }),
+            held_back_live: z.array(z.object({ id: z.string(), name: z.string() })),
+            errors: z.array(z.object({ id: z.string(), name: z.string(), error: z.string() })).optional(),
+        },
+    }, () => run(() => {
+        refuseIfLocked("actor_prune");
+        const homeActor = currentActor();
+        const actors = db.prepare("SELECT id, name, kind FROM actors").all();
+        const deleted = [];
+        const heldBackLive = [];
+        const errors = [];
+        for (const actor of actors) {
+            if (actor.id === homeActor)
+                continue;
+            try {
+                const outcome = pruneActorIfInert.immediate(actor.id);
+                if (outcome === "deleted")
+                    deleted.push({ id: actor.id, name: actor.name });
+                else if (outcome === "live")
+                    heldBackLive.push({ id: actor.id, name: actor.name });
+            }
+            catch (e) {
+                errors.push({ id: actor.id, name: actor.name, error: errorMessage(e) });
+            }
+        }
+        return {
+            deleted,
+            held_back: { actor_id: homeActor, reason: "caller's own actor" },
+            held_back_live: heldBackLive,
+            ...(errors.length > 0 ? { errors } : {}),
+        };
+    }));
+}

package/dist/tools/pads.js

@@ -0,0 +1,279 @@
+import { z } from "zod";
+import { db } from "../db.js";
+import { currentActor, effectiveProjectId, resolveProject } from "../context.js";
+import { matchesAnyTag, parseTags, run } from "../result.js";
+import { idParam, limitParam, offsetParam, projectIdParam } from "./params.js";
+function selectPad(projectId, padId, columns) {
+    const row = db
+        .prepare(`SELECT ${columns} FROM pads WHERE project_id = ? AND id = ?`)
+        .get(projectId, padId);
+    if (!row)
+        throw new Error(`No pad with id ${padId} in project ${projectId}. Call pad_list.`);
+    return row;
+}
+function getPad(projectId, padId) {
+    return selectPad(projectId, padId, "*");
+}
+export function getPadMeta(projectId, padId) {
+    return selectPad(projectId, padId, "id, name, revision, archived");
+}
+function revisionMismatchError(padId, expected, current) {
+    if (current == null) {
+        return new Error(`Pad ${padId} no longer exists; it may have just been deleted by another write. Call pad_list to confirm.`);
+    }
+    return new Error(`Revision mismatch for pad ${padId}: expected ${expected}, current ${current}. Re-read with pad_read and retry.`);
+}
+function currentRevisionOrDeleted(padId) {
+    const row = db.prepare("SELECT revision FROM pads WHERE id = ?").get(padId);
+    return row?.revision ?? null;
+}
+function assertRowChanged(padId, predicateRevision, changed) {
+    if (!changed) {
+        throw revisionMismatchError(padId, predicateRevision, currentRevisionOrDeleted(padId));
+    }
+}
+function checkRevision(pad, expected, required) {
+    if (expected == null) {
+        if (required) {
+            throw new Error(`expected_revision is required to overwrite pad ${pad.id}. Current revision: ${pad.revision}. Read it first with pad_read.`);
+        }
+        return;
+    }
+    if (expected !== pad.revision) {
+        throw revisionMismatchError(pad.id, expected, pad.revision);
+    }
+}
+export function bumpPad(padId, predicateRevision, set, ...params) {
+    const where = predicateRevision != null ? "id = ? AND revision = ?" : "id = ?";
+    const whereParams = predicateRevision != null ? [padId, predicateRevision] : [padId];
+    const row = db
+        .prepare(`UPDATE pads SET ${set}, revision = revision + 1,
+       updated_by = ?, updated_at = datetime('now') WHERE ${where} RETURNING revision`)
+        .get(...params, currentActor(), ...whereParams);
+    assertRowChanged(padId, predicateRevision, row != null);
+    return row.revision;
+}
+export const APPEND_WITH_SEPARATOR_SET = "content = content || (CASE WHEN content = '' OR substr(content, -1) = char(10) THEN '' ELSE char(10) END) || ?";
+export function getActivePadByName(projectId, name) {
+    return db
+        .prepare("SELECT * FROM pads WHERE project_id = ? AND name = ? AND archived = 0")
+        .get(projectId, name);
+}
+export function listActivePads(projectId) {
+    return db
+        .prepare(`SELECT name, revision, length(content) AS content_length, updated_by, updated_at
+       FROM pads WHERE project_id = ? AND archived = 0 ORDER BY name`)
+        .all(projectId);
+}
+export function overwritePadContent(projectId, padId, content, expectedRevision) {
+    const pad = getPadMeta(projectId, padId);
+    checkRevision(pad, expectedRevision, true);
+    return bumpPad(padId, pad.revision, "content = ?", content);
+}
+export function createPad(projectId, name, content, tags) {
+    const row = db
+        .prepare(`INSERT OR IGNORE INTO pads (project_id, name, content, tags, updated_by)
+       VALUES (?, ?, ?, ?, ?) RETURNING id`)
+        .get(projectId, name, content, JSON.stringify(tags), currentActor());
+    return row?.id ?? null;
+}
+export function registerPads(server) {
+    server.registerTool("pad_write", {
+        description: "Create a pad, or fully overwrite one by passing pad_id plus expected_revision. Pad names are unique per project. Prefer pad_append/pad_edit for targeted changes.",
+        inputSchema: {
+            name: z.string(),
+            content: z.string(),
+            tags: z.array(z.string()).optional(),
+            pad_id: idParam.optional().describe("Pass with expected_revision to overwrite."),
+            expected_revision: idParam.optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: { pad_id: idParam, revision: idParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        if (args.pad_id != null) {
+            const pad = getPadMeta(projectId, args.pad_id);
+            checkRevision(pad, args.expected_revision, true);
+            const revision = bumpPad(pad.id, pad.revision, "name = ?, content = ?, tags = COALESCE(?, tags)", args.name, args.content, args.tags ? JSON.stringify(args.tags) : null);
+            return { pad_id: pad.id, revision };
+        }
+        const padId = createPad(projectId, args.name, args.content, args.tags ?? []);
+        if (padId == null) {
+            throw new Error(`A pad named "${args.name}" already exists in this project. Read it with pad_read(name="${args.name}"), then overwrite with pad_id + expected_revision, or pick another name.`);
+        }
+        return { pad_id: padId, revision: 1 };
+    }));
+    server.registerTool("pad_read", {
+        description: "Read a pad's content, revision, and metadata by pad_id or name.",
+        inputSchema: {
+            pad_id: idParam.optional(),
+            name: z.string().optional(),
+            project_id: projectIdParam,
+        },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        let pad;
+        if (args.pad_id != null) {
+            pad = getPad(projectId, args.pad_id);
+        }
+        else if (args.name) {
+            const row = db
+                .prepare("SELECT * FROM pads WHERE project_id = ? AND name = ? AND archived = 0")
+                .get(projectId, args.name);
+            if (!row)
+                throw new Error(`No active pad named "${args.name}". Call pad_list.`);
+            pad = row;
+        }
+        else {
+            throw new Error("Pass pad_id or name.");
+        }
+        return {
+            pad_id: pad.id,
+            name: pad.name,
+            revision: pad.revision,
+            tags: parseTags(pad.tags),
+            updated_by: pad.updated_by,
+            updated_at: pad.updated_at,
+            content: pad.content,
+        };
+    }));
+    server.registerTool("pad_append", {
+        description: "Append content to the end of a pad. Optional expected_revision guards against concurrent writes.",
+        inputSchema: {
+            pad_id: idParam,
+            content: z.string(),
+            expected_revision: idParam.optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: { pad_id: idParam, revision: idParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const pad = getPadMeta(projectId, args.pad_id);
+        checkRevision(pad, args.expected_revision, false);
+        const revision = bumpPad(pad.id, args.expected_revision, APPEND_WITH_SEPARATOR_SET, args.content);
+        return { pad_id: pad.id, revision };
+    }));
+    server.registerTool("pad_edit", {
+        description: "Replace one literal occurrence of old_text with new_text in a pad. old_text must match exactly once; include surrounding context to disambiguate.",
+        inputSchema: {
+            pad_id: idParam,
+            old_text: z.string(),
+            new_text: z.string(),
+            expected_revision: idParam.optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: { pad_id: idParam, revision: idParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const pad = getPad(projectId, args.pad_id);
+        checkRevision(pad, args.expected_revision, false);
+        const parts = pad.content.split(args.old_text);
+        const occurrences = parts.length - 1;
+        if (occurrences === 0) {
+            throw new Error(`old_text not found in pad ${pad.id}. Re-read with pad_read.`);
+        }
+        if (occurrences > 1) {
+            throw new Error(`old_text matches ${occurrences} places in pad ${pad.id}. Include more surrounding context so it matches exactly once.`);
+        }
+        const revision = bumpPad(pad.id, pad.revision, "content = ?", parts.join(args.new_text));
+        return { pad_id: pad.id, revision };
+    }));
+    server.registerTool("pad_archive", {
+        description: "Archive a pad (or unarchive with archived=false). Archiving frees the name for a new active pad; the old content stays readable by pad_id.",
+        inputSchema: {
+            pad_id: idParam,
+            archived: z.boolean().optional().describe("Default true. Pass false to unarchive."),
+            project_id: projectIdParam,
+        },
+        outputSchema: { pad_id: idParam, archived: z.boolean(), revision: idParam },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const pad = getPadMeta(projectId, args.pad_id);
+        const archived = args.archived ?? true;
+        if ((pad.archived === 1) === archived) {
+            return { pad_id: pad.id, archived, revision: pad.revision };
+        }
+        let revision;
+        try {
+            revision = bumpPad(pad.id, undefined, "archived = ?", archived ? 1 : 0);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.includes("UNIQUE")) {
+                throw new Error(`Cannot unarchive pad ${pad.id}: an active pad named "${pad.name}" already exists. Rename or archive that pad first.`);
+            }
+            throw e;
+        }
+        return { pad_id: pad.id, archived, revision };
+    }));
+    server.registerTool("pad_delete", {
+        description: "Permanently delete a pad. Irreversible; prefer pad_archive. Optional expected_revision guards against deleting a pad someone just updated.",
+        inputSchema: {
+            pad_id: idParam,
+            expected_revision: idParam.optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: { pad_id: idParam, deleted: z.boolean() },
+    }, (args) => run(() => {
+        const projectId = effectiveProjectId(args.project_id);
+        const pad = getPadMeta(projectId, args.pad_id);
+        checkRevision(pad, args.expected_revision, false);
+        const info = db.prepare("DELETE FROM pads WHERE id = ? AND revision = ?").run(pad.id, pad.revision);
+        assertRowChanged(pad.id, pad.revision, info.changes > 0);
+        return { pad_id: pad.id, deleted: true };
+    }));
+    server.registerTool("pad_list", {
+        description: "List pads without full content. query matches names and content (returns a snippet); tags matches any listed tag.",
+        inputSchema: {
+            query: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            include_archived: z.boolean().optional(),
+            limit: limitParam,
+            offset: offsetParam,
+            project_id: projectIdParam,
+        },
+    }, (args) => run(() => {
+        const project = resolveProject(args.project_id);
+        const limit = Math.min(args.limit ?? 50, 200);
+        const offset = args.offset ?? 0;
+        const columns = `id, name, revision, tags, archived, updated_by, updated_at,
+          length(content) AS content_length${args.query ? ", content" : ""}`;
+        let sql = `SELECT ${columns} FROM pads WHERE project_id = ?`;
+        const params = [project.id];
+        if (!args.include_archived)
+            sql += " AND archived = 0";
+        if (args.query) {
+            sql += " AND (name LIKE ? OR content LIKE ?)";
+            params.push(`%${args.query}%`, `%${args.query}%`);
+        }
+        sql += " ORDER BY updated_at DESC";
+        const rows = db.prepare(sql).all(...params).filter((r) => matchesAnyTag(r.tags, args.tags));
+        const page = rows.slice(offset, offset + limit);
+        return {
+            project_id: project.id,
+            project_name: project.name,
+            total_count: rows.length,
+            offset,
+            limit,
+            pads: page.map((r) => {
+                let snippet;
+                if (args.query && r.content != null) {
+                    const idx = r.content.toLowerCase().indexOf(args.query.toLowerCase());
+                    if (idx >= 0) {
+                        snippet = r.content.slice(Math.max(0, idx - 40), idx + args.query.length + 80);
+                    }
+                }
+                return {
+                    pad_id: r.id,
+                    name: r.name,
+                    revision: r.revision,
+                    tags: parseTags(r.tags),
+                    archived: r.archived === 1,
+                    content_length: r.content_length,
+                    updated_by: r.updated_by,
+                    updated_at: r.updated_at,
+                    ...(snippet ? { snippet } : {}),
+                };
+            }),
+        };
+    }));
+}

package/dist/tools/params.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const idParam = z.number().int().positive();
+export const projectIdParam = idParam
+    .optional()
+    .describe("Different project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty.");
+export const agentNameParam = z
+    .string()
+    .optional()
+    .describe("The worker's name, e.g. \"impl\" or \"DEVX-123\". Prefer passing this rather than agent_id, but pass only one: if both arrive, agent_id wins and this is ignored. A partial name works when it matches exactly one running worker, so \"123\" finds DEVX-123.");
+export const agentIdParam = idParam
+    .optional()
+    .describe("Numeric agent id. Use name instead unless you have the id to hand.");
+export const limitParam = z.number().int().positive().optional();
+export const offsetParam = z.number().int().nonnegative().optional();