seisin 0.4.0 → 0.5.0

package/src/mcp.js

@@ -29,11 +29,12 @@
 import { toRepoRelative } from "./paths.js";
 import { loadConfig, findConfig } from "./config.js";
 import { inspect } from "./inspect.js";
-import { explain, ownersOf } from "./owners.js";
+import { explain, explainFileRead, ownersOf, readTarget } from "./owners.js";
+import { CREDENTIAL_HOMES, expand } from "./grants.js";
 import { settingsFor } from "./srt.js";
-import { pending, requestsPath, grantFor, refuseIfBarred, markStale } from "./requests.js";
+import { pending, requestsPath, refuseIfBarred, shellId } from "./requests.js";
 import { read, logPath } from "./log.js";
-import { causesOf } from "./serve.js";
+import { causesOf, parseSince, queue as requestQueue, verdicts, wallsByRole } from "./views.js";
 import { walls, wasted } from "./walls.js";
 
 /**
@@ -53,7 +54,7 @@ const TOOLS = [
   {
     name: "seisin_state",
     description:
-      "The permission map: every role, the folders it may write, the keys it may read, " +
+      "The map: every role, its territory (the folders it may write), the keys it may read, " +
       "and every way the policy silently does not hold. Read-only.",
     inputSchema: {
       type: "object",
@@ -78,15 +79,15 @@ const TOOLS = [
   {
     name: "seisin_requests",
     description:
-      "Permissions agents asked for and cannot have yet, waiting on a human, with how many " +
-      "times each was asked. A refusal files one of these automatically, so this is where " +
-      "to look after being denied rather than retrying. Read-only — approving is not " +
+      "Requests: access agents asked for and cannot have yet, waiting on a person, with how many " +
+      "times each was asked. A denial files one of these automatically, so this is where " +
+      "to look after being denied rather than retrying. Read-only — granting is not " +
       "available here, by design.",
     inputSchema: { type: "object", properties: {} },
   },
   {
     name: "seisin_activity",
-    description: "Recent allow/deny decisions, newest last. Read-only.",
+    description: "Recent log entries — allowed, denied or observed — newest last. Read-only.",
     inputSchema: {
       type: "object",
       properties: {
@@ -100,13 +101,27 @@ const TOOLS = [
     name: "seisin_causes",
     description:
       "Denials grouped by what was denied — by path, and one level coarser by the name at " +
-      "the end of it — with how many are on paths no role owns. This is the question " +
-      "`seisin_activity` cannot answer: the raw log has the events, this has them counted " +
-      "against the policy as it stands, so a cause that has been granted since stops " +
-      "counting. Reach for it before proposing a change: a day that is three quarters one " +
-      "filename is a tooling problem, and the same volume spread across unrelated paths is " +
-      "a question about who owns what. Read-only.",
-    inputSchema: { type: "object", properties: { limit: { type: "number" } } },
+      "the end of it — over the whole log, or since an ISO date. The counts are history: " +
+      "what was denied. What is measured against the policy as it stands is where each " +
+      "path is now — `standing`: unowned (a decision nobody has made), owned, protected " +
+      "(closed to every role on purpose, nothing to grant) or outside (a port, a key, or " +
+      "outside the repository) — and, per cause, `stillRefused`, how many of the roles " +
+      "that hit it would hit it today. An unowned cause also carries `kind` and `hint`: " +
+      "git (lock or metadata), credential, temporary, build or territory, and the move " +
+      "that fits it (`standing.unowned.kinds` counts them). Only `territory` is a question " +
+      "of who owns what; do not propose an owner for the others — a lock, a test's scratch " +
+      "or a credential given to whoever asked widens a role. " +
+      "`seisin_activity` has the raw events; this has " +
+      "them read against the policy. Reach for it before proposing a change: a day that " +
+      "is three quarters one filename is a tooling problem, and the same volume spread " +
+      "across unrelated unowned paths is a question about who owns what. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number" },
+        since: { type: "string", description: "ISO date; only denials at or after it" },
+      },
+    },
   },
   {
     name: "seisin_walls",
@@ -121,14 +136,16 @@ const TOOLS = [
     name: "seisin_draft_grant",
     description:
       "Draft the change a pending request would make, as text, plus the command a person " +
-      "runs to apply it. Reach for this after a refusal: the denial is already in " +
-      "seisin_requests, and this turns it into a concrete proposal someone can approve. " +
+      "runs to apply it. Reach for this after a denial: it is already in " +
+      "seisin_requests, and this turns it into a concrete proposal a person can grant. " +
       "Read-only, and it is the tool where that matters most: the name says grant and it " +
-      "does not grant. The approval is a human action in another channel.",
+      "does not grant. Granting is a person's action, in another channel.",
     inputSchema: {
       type: "object",
-      properties: { number: { type: "number", description: "position in seisin_requests" } },
-      required: ["number"],
+      properties: {
+        id: { type: "string", description: "the request's id from seisin_requests — preferred: it does not move when the queue does" },
+        number: { type: "number", description: "position in seisin_requests (legacy; the draft still names the id)" },
+      },
     },
   },
 ];
@@ -166,12 +183,22 @@ const HANDLERS = {
     // not enforced is documentation.
     if (action !== "read" && action !== "write" && action !== "mcp")
       throw new Error(`action must be "read", "write" or "mcp", got ${JSON.stringify(action)}`);
+    if (typeof role !== "string" || !role)
+      throw new Error("role must be a non-empty string");
     if (typeof target !== "string" || !target)
       throw new Error("target must be a non-empty path");
     const cfg = config();
     if (!cfg.roles[role])
       return { error: `unknown role "${role}"`, known: Object.keys(cfg.roles) };
     if (action === "mcp") return explain(cfg, role, "mcp", target);
+    // A read of a file outside every key dir is open, as it is for the CLI.
+    // The server has no working directory of its own, so the root stands in.
+    if (action === "read") {
+      const asked = readTarget(cfg, target, cfg.root);
+      return asked.key
+        ? explain(cfg, role, "read", asked.target)
+        : explainFileRead(cfg, role, asked.target, CREDENTIAL_HOMES.map(expand));
+    }
     const rel = toRepoRelative(cfg, target);
     const verdict = explain(cfg, role, action, rel);
     return { ...verdict, alsoOwnedBy: action === "write" ? ownersOf(cfg, rel) : undefined };
@@ -179,17 +206,17 @@ const HANDLERS = {
 
   seisin_requests() {
     const cfg = config();
-    const queue = markStale(pending(requestsPath(cfg.root)), read(logPath(cfg.root)));
+    const queue = requestQueue(cfg.root, read(logPath(cfg.root)), cfg.keyDirs);
     return {
       pending: queue.map((r, i) => ({
-        number: i + 1, role: r.role, action: r.action,
+        number: i + 1, id: r.key, role: r.role, action: r.action,
         wants: r.grant, ownedBy: r.owners, asked: r.times, lastAsked: r.last,
         ...(r.stale ? { stale: `not asked again in ${r.stale.runs} runs of ${r.role} since` } : {}),
       })),
       // Said in the payload and not only in the tool description, because a
       // model reading this is deciding what to do next.
       note: queue.length
-        ? "Approving is not available through MCP. Tell the operator to run: seisin grant <number>"
+        ? "Granting is not available through MCP. Ask a person to run: seisin grant '<id>'"
         : "nothing waiting",
     };
   },
@@ -203,13 +230,20 @@ const HANDLERS = {
    * and asks it to re-derive the grouping — without the policy, which is the
    * half that makes the grouping mean anything.
    */
-  seisin_causes({ limit }) {
+  seisin_causes({ limit, since }) {
     const cfg = config();
-    const c = causesOf(cfg, read(logPath(cfg.root), { limit: 4000 }));
+    // The whole log, as the console reads it. This read the last 4000 lines
+    // after the console had stopped doing so, and the two then disagreed about
+    // the same log — 3,999 refusals here against 6,630 there, measured — with
+    // nothing telling the agent its window was half of the person's.
+    const from = parseSince(since);
+    const c = causesOf(cfg, read(logPath(cfg.root), from ? { since: from } : {}), { ask: verdicts(cfg) });
     return {
       total: c.total,
       distinct: c.distinct,
+      ...(from && { since: from }),
       unowned: c.unowned,
+      standing: c.standing,
       families: c.families,
       causes: typeof limit === "number" ? c.causes.slice(0, limit) : c.causes,
     };
@@ -217,14 +251,15 @@ const HANDLERS = {
 
   seisin_walls({ role }) {
     const cfg = config();
-    const file = logPath(cfg.root);
-    const names = role ? [role] : Object.keys(cfg.roles);
     if (role && !cfg.roles[role]) throw new Error(`unknown role "${role}"`);
+    // One read of the log for every role, not one per role (32 on a real policy).
+    const denied = read(logPath(cfg.root), { verdict: "denied" });
+    const ask = verdicts(cfg);
+    const byRole = role
+      ? Object.fromEntries([[role, walls(cfg, role, { entries: denied, ask })]].filter(([, w]) => w.length))
+      : wallsByRole(cfg, denied, { ask });
     const out = {};
-    for (const r of names) {
-      const w = walls(cfg, r, { file });
-      if (w.length) out[r] = { walls: w, spentRetrying: wasted(w) };
-    }
+    for (const [r, w] of Object.entries(byRole)) out[r] = { walls: w, spentRetrying: wasted(w) };
     return { roles: out, spentRetrying: Object.values(out).reduce((n, x) => n + x.spentRetrying, 0) };
   },
 
@@ -237,12 +272,23 @@ const HANDLERS = {
     return { entries: read(logPath(cfg.root), { role, verdict, limit: n }) };
   },
 
-  seisin_draft_grant({ number }) {
-    if (!Number.isInteger(Number(number)) || Number(number) < 1)
-      throw new Error("number must be a positive integer from seisin_requests");
+  seisin_draft_grant({ id, number } = {}) {
     const cfg = config();
-    const req = pending(requestsPath(cfg.root))[Number(number) - 1];
-    if (!req) throw new Error(`no pending request #${number}`);
+    const queue = pending(requestsPath(cfg.root), { keyDirs: cfg.keyDirs });
+    let req;
+    if (typeof id === "string" && id) {
+      req = queue.find((r) => r.key === id);
+      if (!req) throw new Error(`request ${id} is not pending`);
+    } else {
+      if (!Number.isInteger(Number(number)) || Number(number) < 1)
+        throw new Error("id (preferred) or number from seisin_requests is required");
+      req = queue[Number(number) - 1];
+      if (!req) throw new Error(`no pending request #${number}`);
+    }
+    // The command is written against the id, whatever was asked with: a
+    // number is a position in a queue agents keep writing to, and the person
+    // runs this later, against the queue as it is then.
+    const ref = shellId(req.key);
 
     // The same refusal `seisin grant` and the console apply, asked here first.
     // Without it this drafted, as approvable, a request that `never_writes`
@@ -255,7 +301,7 @@ const HANDLERS = {
         ownedBy: req.owners,
         applyWith: null,
         note: "Not approvable as it stands: never_writes wins over writes. Decline it with " +
-          `\`seisin decline ${number}\`, or remove the never_writes entry if the subtraction is wrong.`,
+          `\`seisin decline ${ref}\`, or remove the never_writes entry if the subtraction is wrong.`,
       };
     }
     const field = req.action === "read" ? "keys" : "writes";
@@ -263,7 +309,8 @@ const HANDLERS = {
       wouldAdd: { role: req.role, field, value: req.grant },
       preview: `[roles.${req.role}]\n${field} = [ …, "${req.grant}" ]   # asked ${req.times}×`,
       ownedBy: req.owners,
-      applyWith: `seisin grant ${number} --reason "<why>"`,
+      id: req.key,
+      applyWith: `seisin grant ${ref} --reason "<why>"`,
       note: "Not applied. seisin's MCP server writes nothing — a person runs the command above.",
     };
   },
@@ -284,7 +331,10 @@ function handle(message, { write, version }) {
   const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
   const fail = (id, code, msg) => send({ jsonrpc: "2.0", id, error: { code, message: msg } });
 
-  const { id, method, params = {} } = message;
+  const { id, method } = message;
+  // `?? {}` so an explicit null params (not just missing) does not crash the
+  // dispatcher and leave the request unanswered.
+  const params = message.params ?? {};
 
   // A notification has no id and takes no answer. Replying to one is a protocol
   // error that some clients tolerate and others hang on.
@@ -298,9 +348,9 @@ function handle(message, { write, version }) {
         capabilities: { tools: {} },
         serverInfo: { name: "seisin", title: "seisin — folders and keys per agent", version },
         instructions:
-          "Read-only view of this repo's agent permissions. Ask seisin_explain before " +
+          "Read-only view of this repo's roles, territories and keys. Ask seisin_explain before " +
           "suggesting an agent edit a file it may not own. Granting is not available " +
-          "here: surface seisin_requests and let the operator run `seisin grant`.",
+          "here: surface seisin_requests and let a person run `seisin grant`.",
       });
     }
     case "ping":
@@ -310,8 +360,11 @@ function handle(message, { write, version }) {
     case "tools/list":
       return reply(id, { tools: TOOLS });
     case "tools/call": {
-      const fn = HANDLERS[params.name];
-      if (!fn) return fail(id, -32602, `unknown tool "${params.name}"`);
+      // hasOwn, not a bare lookup: `params.name` of "constructor" or
+      // "hasOwnProperty" would otherwise resolve to a function on Object's
+      // prototype and be invoked as a tool.
+      const fn = Object.hasOwn(HANDLERS, params.name) ? HANDLERS[params.name] : null;
+      if (typeof fn !== "function") return fail(id, -32602, `unknown tool ${JSON.stringify(params.name)}`);
       try {
         const result = fn(params.arguments ?? {});
         // Content, not a bare object: every client renders `content`, and only

package/src/notify.js

@@ -17,20 +17,20 @@
  *     never holds the URL, and `SEISIN_NOTIFY_URL` is dropped from its
  *     environment even if the role names it;
  *   - the URL is not readable from any territory. A ntfy topic or a webhook is
- *     a credential — whoever can read it can send the person a fake "approve
+ *     a credential — whoever can read it can send the person a fake "grant
  *     #3". So it lives in a key directory no role declares (`url_file`), or in
  *     the parent's environment, and never as a plain value in seisin.toml,
  *     which every role can read.
  */
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { keyOf, pending, requestsPath, grantFor } from "./requests.js";
+import { keyOf, pending, requestsPath, grantFor, shellId } from "./requests.js";
 
-export const FORMATS = ["text", "json", "slack"];
-export const ENV_URL = "SEISIN_NOTIFY_URL";
+const FORMATS = ["text", "json", "slack"];
+const ENV_URL = "SEISIN_NOTIFY_URL";
 
 /** The URL to notify, or null. Read in the parent only. */
-export function notifyUrl(config, env = process.env) {
+function notifyUrl(config, env = process.env) {
   if (env[ENV_URL]) return env[ENV_URL].trim();
   if (!config.notify?.urlFile) return null;
   try {
@@ -45,14 +45,19 @@ export function notifyUrl(config, env = process.env) {
 export function message(config, req, number, format = "text") {
   const owner = req.owners?.length ? `It belongs to ${req.owners.join(", ")}.` : "Nobody owns it.";
   const text =
-    `seisin (${basename(config.root)}): ${req.role} was refused ${req.action} on ${req.target}. ${owner} ` +
-    `Approve: seisin grant ${number} · decline: seisin decline ${number}`;
-  if (format === "slack") return { type: "application/json", body: JSON.stringify({ text }) };
+    `seisin (${basename(config.root)}): ${req.role} was denied ${req.action} on ${req.target}. ${owner} ` +
+    `Grant: seisin grant ${shellId(keyOf(req))} · decline: seisin decline ${shellId(keyOf(req))}`;
+  // Slack reads `<url|label>` as a link and `<!channel>` as a mention, and the
+  // path is chosen by the agent: `<https://evil|approve here>` in a target
+  // would arrive as a clickable link in the channel a person approves from.
+  // Its own escaping, and only these three characters, is what it asks for.
+  if (format === "slack")
+    return { type: "application/json", body: JSON.stringify({ text: text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;") }) };
   if (format === "json")
     return {
       type: "application/json",
       body: JSON.stringify({
-        text, repo: basename(config.root), number, role: req.role, action: req.action,
+        text, repo: basename(config.root), number, id: keyOf(req), role: req.role, action: req.action,
         target: req.target, owners: req.owners ?? [], grant: grantFor(req),
       }),
     };
@@ -141,6 +146,6 @@ export function readNotify(table, { path, root, keyDirs, roles, own }) {
   if (holders.length)
     throw new Error(
       `${path}: [notify] url_file "${urlFile}" is declared as a key by ${holders.join(", ")} — ` +
-      `that role could read it and send the person a fake "approve". No role may hold it.`);
+      `that role could read it and send the person a fake "grant this". No role may hold it.`);
   return { urlFile, format };
 }