@secondlayer/sentinel 0.5.0 → 0.7.0

package/dist/cli.js

@@ -92,6 +92,7 @@ function runPhase(run) {
   const last = run.events.at(-1);
   return last ? [last.name ?? last.kind, last.state].filter(Boolean).join(" ") : "starting";
 }
+var WATCH_NOTE_MAX = 500;
 var rowsOf = (intents) => intents.flatMap((i) => i.rows);
 var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
 var CONTROL_NAME = "Control changes";
@@ -198,10 +199,32 @@ function mutedUntilOf(w, now = Date.now()) {
   const at = w.delivery.mutedUntil;
   return at && Date.parse(at) > now ? at : null;
 }
+function changeText(c) {
+  const name = c.subject.kind === "asset" ? subjectName(c.subject, c.units) : c.watch.title;
+  const rule = (r) => ruleSummary(r, c.units);
+  switch (c.action) {
+    case "on":
+      return `${c.watch.title} turned on`;
+    case "off":
+      return `${c.watch.title} turned off`;
+    case "muted":
+    case "cooldown":
+      return `${c.watch.title}: ${c.action === "muted" ? "mute" : "cooldown"} ${c.note ?? ""}`.trim();
+    case "note":
+      return `${c.watch.title}: note ${c.note ?? "set"}`;
+    case "applied":
+      if (c.prevRule && c.rule)
+        return `${name} rule changed: ${rule(c.prevRule)} → ${rule(c.rule)}`;
+      return c.rule ? `${name} rule set: ${rule(c.rule)}` : `${name} rule set`;
+  }
+}
 function createClient(opts) {
   const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   const doFetch = opts.fetch ?? globalThis.fetch;
-  const authHeader = () => ({ authorization: `Bearer ${opts.token}` });
+  const authHeader = () => ({
+    authorization: `Bearer ${opts.token}`,
+    ...opts.client ? { "x-sentinel-client": opts.client } : {}
+  });
   async function call(method, path, body) {
     const res = await doFetch(`${baseUrl}${path}`, {
       method,
@@ -245,6 +268,7 @@ function createClient(opts) {
       on
     }),
     mute: (planId, watchId, mutedUntil) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { mutedUntil }),
+    setWatchNote: (planId, watchId, note) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { note }),
     muteAlert: (alertId, hours) => call("POST", `/alerts/${encodeURIComponent(alertId)}/mute`, { hours }),
     parseRule: (planId, subject, text) => call("POST", `${appPlan(planId)}/rules/parse`, { subject, text }),
     monitorSettings: (planId, settings) => call("POST", `${appPlan(planId)}/monitor`, settings),
@@ -304,7 +328,8 @@ function createClient(opts) {
     setProjectDestinations: (projectId, dest) => call("POST", `${appProject(projectId)}/destinations`, dest),
     setProjectMonitoring: (projectId, on) => call("POST", `${appProject(projectId)}/monitoring`, { on }),
     projectWatches: (projectId) => call("GET", `${appProject(projectId)}/watches`),
-    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`)
+    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`),
+    projectChanges: (projectId, opts = {}) => call("GET", `${appProject(projectId)}/changes${query(opts)}`)
   };
 }
 function query(params) {
@@ -873,6 +898,7 @@ projects (the contracts of one protocol; a write only happens with --yes):
   projects remove <project> --confirm "<name>" [--yes]   every contract you added in it, and the project
   projects watches <project> [--json]                the project's watches as one list
   projects activity <project> <watch> [--contract <id>] [--window 7|90] [--json]
+  projects changes <project> [--watch <watch>] [--mutes] [--limit N] [--cursor C] [--json]   who turned watches on/off or changed rules
   projects destinations <project> [--email on|off] [--webhook URL] [--slack URL] [--yes]   a URL left out is cleared
   projects monitoring <project> on|off [--yes]
 
@@ -884,6 +910,7 @@ monitoring (a write only happens with --yes; without it you see what would chang
   watches <plan> [--json]                        subjects, rules, status, mutes
   rule <plan> <subject> "<sentence>" [--yes]     read the sentence; --yes adds or edits the rules it found
   watch on|off <plan> <subject> [--yes]          on and off apply now
+  watch-note <plan> <subject> "<text>"|--clear [--yes]   the note sent with this watch's alerts (500 characters)
   mute <plan> <subject> [1h|24h|7d] [--yes]      default 24h
   unmute <plan> <subject> [--yes]
   mute-alert <alert> [1h|24h|7d] [--yes]         mute the watch behind an alert
@@ -917,7 +944,10 @@ var VALUE_FLAGS = new Set([
   "--commit",
   "--into",
   "--window",
-  "--example"
+  "--example",
+  "--watch",
+  "--limit",
+  "--cursor"
 ]);
 var cell2 = (v, empty = "—") => v === null || v === undefined || v === "" ? empty : String(v);
 var table = (rows) => {
@@ -1216,6 +1246,7 @@ No run command: no PoC is stored for this finding.`);
         return await monitoringMore(cmd, args.slice(1), flags, values, io, usage);
       case "watches":
       case "rule":
+      case "watch-note":
       case "mute":
       case "unmute":
       case "mute-alert":
@@ -1409,6 +1440,9 @@ async function monitoring(cmd, pos, on, flags, values, io, usage) {
       io.out([i.title, i.tag, i.on ? "on" : "off", intentLine(i), muted ? `muted until ${muted}` : ""].filter(Boolean).join("  "));
       for (const w of i.rows)
         io.out(`  ${w.status.padEnd(14)}${ruleSummary(w.rule, w.units)}`);
+      const note = i.rows.map((w) => w.delivery.note).find(Boolean);
+      if (note)
+        io.out(`  note: ${note}`);
     }
     return 0;
   }
@@ -1482,6 +1516,21 @@ async function monitoring(cmd, pos, on, flags, values, io, usage) {
     io.out(`${willDo} ${effect}`);
     return 0;
   }
+  if (cmd === "watch-note") {
+    const clear = flags.includes("--clear");
+    if (clear === (third !== undefined))
+      return usage("watch-note takes a note in quotes, or --clear");
+    const note = clear ? null : (third ?? "").trim();
+    if (note !== null && note.length > WATCH_NOTE_MAX)
+      return usage(`Keep the note under ${WATCH_NOTE_MAX} characters`);
+    const willDo = note ? `Send this note with ${g.name}'s alerts: ${note}` : `Clear the note on ${g.name}.`;
+    if (previewOnly(io, flags, willDo, "Takes effect now."))
+      return 0;
+    for (const w of g.watches)
+      await io.client.setWatchNote(planId, w.id, note);
+    io.out(note ? `Note set on ${g.name}.` : `Note cleared on ${g.name}.`);
+    return 0;
+  }
   const mute = cmd === "mute";
   const dur = third ?? "24h";
   if (mute && !(dur in DURATIONS))
@@ -1844,6 +1893,7 @@ async function projects(pos, flags, values, io, usage) {
     "remove",
     "watches",
     "activity",
+    "changes",
     "destinations",
     "monitoring"
   ];
@@ -1998,6 +2048,30 @@ async function projects(pos, flags, values, io, usage) {
         printActivity(io, intent.title, a);
       return 0;
     }
+    case "changes": {
+      const limit = values["--limit"] === undefined ? undefined : Number(values["--limit"]);
+      if (limit !== undefined && !(Number.isInteger(limit) && limit > 0))
+        return usage("--limit takes a whole number above 0");
+      const watchName = values["--watch"];
+      const watch = watchName ? pickIntent((await io.client.projectWatches(id)).intents, watchName).id : undefined;
+      const r = await io.client.projectChanges(id, {
+        limit,
+        cursor: values["--cursor"],
+        watch,
+        ...flags.includes("--mutes") ? { filter: "mutes" } : {}
+      });
+      if (json) {
+        io.out(JSON.stringify(r, null, 2));
+        return 0;
+      }
+      if (!r.events.length)
+        io.out("No changes yet.");
+      for (const c of r.events)
+        io.out([c.at, changeText(c), c.source ?? ""].join("  ").trimEnd());
+      if (r.next)
+        io.out(`More: --cursor ${r.next}`);
+      return 0;
+    }
     case "destinations": {
       const email = values["--email"];
       if (email !== undefined && onOff(email) === null)
@@ -2075,7 +2149,7 @@ async function main() {
     return 2;
   }
   const baseUrl = process.env.SENTINEL_API_URL;
-  const clientFor = (token) => createClient({ token, baseUrl });
+  const clientFor = (token) => createClient({ token, baseUrl, client: "cli" });
   return run(argv, {
     client: clientFor(credential?.token ?? ""),
     out: console.log,

package/dist/index.js

@@ -86,6 +86,7 @@ function runPhase(run) {
   const last = run.events.at(-1);
   return last ? [last.name ?? last.kind, last.state].filter(Boolean).join(" ") : "starting";
 }
+var WATCH_NOTE_MAX = 500;
 var rowsOf = (intents) => intents.flatMap((i) => i.rows);
 var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
 var CONTROL_NAME = "Control changes";
@@ -213,10 +214,32 @@ function mutedUntilOf(w, now = Date.now()) {
   const at = w.delivery.mutedUntil;
   return at && Date.parse(at) > now ? at : null;
 }
+function changeText(c) {
+  const name = c.subject.kind === "asset" ? subjectName(c.subject, c.units) : c.watch.title;
+  const rule = (r) => ruleSummary(r, c.units);
+  switch (c.action) {
+    case "on":
+      return `${c.watch.title} turned on`;
+    case "off":
+      return `${c.watch.title} turned off`;
+    case "muted":
+    case "cooldown":
+      return `${c.watch.title}: ${c.action === "muted" ? "mute" : "cooldown"} ${c.note ?? ""}`.trim();
+    case "note":
+      return `${c.watch.title}: note ${c.note ?? "set"}`;
+    case "applied":
+      if (c.prevRule && c.rule)
+        return `${name} rule changed: ${rule(c.prevRule)} → ${rule(c.rule)}`;
+      return c.rule ? `${name} rule set: ${rule(c.rule)}` : `${name} rule set`;
+  }
+}
 function createClient(opts) {
   const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   const doFetch = opts.fetch ?? globalThis.fetch;
-  const authHeader = () => ({ authorization: `Bearer ${opts.token}` });
+  const authHeader = () => ({
+    authorization: `Bearer ${opts.token}`,
+    ...opts.client ? { "x-sentinel-client": opts.client } : {}
+  });
   async function call(method, path, body) {
     const res = await doFetch(`${baseUrl}${path}`, {
       method,
@@ -260,6 +283,7 @@ function createClient(opts) {
       on
     }),
     mute: (planId, watchId, mutedUntil) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { mutedUntil }),
+    setWatchNote: (planId, watchId, note) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { note }),
     muteAlert: (alertId, hours) => call("POST", `/alerts/${encodeURIComponent(alertId)}/mute`, { hours }),
     parseRule: (planId, subject, text) => call("POST", `${appPlan(planId)}/rules/parse`, { subject, text }),
     monitorSettings: (planId, settings) => call("POST", `${appPlan(planId)}/monitor`, settings),
@@ -319,7 +343,8 @@ function createClient(opts) {
     setProjectDestinations: (projectId, dest) => call("POST", `${appProject(projectId)}/destinations`, dest),
     setProjectMonitoring: (projectId, on) => call("POST", `${appProject(projectId)}/monitoring`, { on }),
     projectWatches: (projectId) => call("GET", `${appProject(projectId)}/watches`),
-    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`)
+    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`),
+    projectChanges: (projectId, opts = {}) => call("GET", `${appProject(projectId)}/changes${query(opts)}`)
   };
 }
 function query(params) {
@@ -364,7 +389,9 @@ export {
   NOT_LOGGED_IN,
   SentinelError,
   SubjectError,
+  WATCH_NOTE_MAX,
   assetClause,
+  changeText,
   clearSession,
   clearTokenFile,
   createClient,

package/dist/mcp.js

@@ -12666,6 +12666,7 @@ function runPhase(run) {
   const last = run.events.at(-1);
   return last ? [last.name ?? last.kind, last.state].filter(Boolean).join(" ") : "starting";
 }
+var WATCH_NOTE_MAX = 500;
 var rowsOf = (intents) => intents.flatMap((i) => i.rows);
 var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
 var CONTROL_NAME = "Control changes";
@@ -12781,7 +12782,10 @@ function mutedUntilOf(w, now = Date.now()) {
 function createClient(opts) {
   const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   const doFetch = opts.fetch ?? globalThis.fetch;
-  const authHeader = () => ({ authorization: `Bearer ${opts.token}` });
+  const authHeader = () => ({
+    authorization: `Bearer ${opts.token}`,
+    ...opts.client ? { "x-sentinel-client": opts.client } : {}
+  });
   async function call(method, path, body) {
     const res = await doFetch(`${baseUrl}${path}`, {
       method,
@@ -12825,6 +12829,7 @@ function createClient(opts) {
       on
     }),
     mute: (planId, watchId, mutedUntil) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { mutedUntil }),
+    setWatchNote: (planId, watchId, note) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { note }),
     muteAlert: (alertId, hours) => call("POST", `/alerts/${encodeURIComponent(alertId)}/mute`, { hours }),
     parseRule: (planId, subject, text) => call("POST", `${appPlan(planId)}/rules/parse`, { subject, text }),
     monitorSettings: (planId, settings) => call("POST", `${appPlan(planId)}/monitor`, settings),
@@ -12884,7 +12889,8 @@ function createClient(opts) {
     setProjectDestinations: (projectId, dest) => call("POST", `${appProject(projectId)}/destinations`, dest),
     setProjectMonitoring: (projectId, on) => call("POST", `${appProject(projectId)}/monitoring`, { on }),
     projectWatches: (projectId) => call("GET", `${appProject(projectId)}/watches`),
-    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`)
+    projectActivity: (projectId, intentId, opts = {}) => call("GET", `${appProject(projectId)}/watches/${encodeURIComponent(intentId)}/activity${query(opts)}`),
+    projectChanges: (projectId, opts = {}) => call("GET", `${appProject(projectId)}/changes${query(opts)}`)
   };
 }
 function query(params) {
@@ -20725,6 +20731,7 @@ function intentView(i) {
     ...i.alsoChecks ? { alsoChecks: i.alsoChecks } : {},
     status: subjectStatus(i.rows),
     mutedUntil: i.rows.map((w) => mutedUntilOf(w)).find(Boolean) ?? null,
+    note: i.rows.map((w) => w.delivery.note).find(Boolean) ?? null,
     rules: i.rows.map((w) => ({
       watchId: w.id,
       kind: w.rule.kind,
@@ -20748,6 +20755,19 @@ async function muteSubject(client, a, hours) {
     await client.mute(ctx.planId, w.id, mutedUntil);
   return done(willDo, "Takes effect now.", { mutedUntil });
 }
+async function noteSubject(client, a) {
+  const text = typeof a.note === "string" ? a.note.trim() : "";
+  if (text.length > WATCH_NOTE_MAX)
+    throw new SentinelError(400, `Keep the note under ${WATCH_NOTE_MAX} characters`);
+  const ctx = await watchContext(client, a.planId);
+  const g = resolveSubject(ctx.watches, a.subject);
+  const willDo = text ? `Send this note with ${g.name}'s alerts: ${text}` : `Clear the note on ${g.name}.`;
+  if (a.confirm !== true)
+    return preview(willDo, "Takes effect now.");
+  for (const w of g.watches)
+    await client.setWatchNote(ctx.planId, w.id, text || null);
+  return done(willDo, "Takes effect now.");
+}
 function buildTools(client) {
   const planId = string2().describe("Plan id, from list_contracts");
   const subject = string2().describe("A watched subject: a function name or a token symbol, from list_watches");
@@ -21080,6 +21100,16 @@ function buildTools(client) {
       input: { planId, subject, hours: MUTE_HOURS, confirm },
       run: async (a) => muteSubject(client, a, a.hours)
     },
+    set_watch_note: {
+      description: "Set the note sent with a subject's alerts: your team's own words (who holds the key, where to post first), plain text, 500 characters at most. An empty note clears it. Sentinel adds nothing to it. Takes effect at once. Without confirm it only describes.",
+      input: {
+        planId,
+        subject,
+        note: string2().max(WATCH_NOTE_MAX).describe("The note; empty clears it"),
+        confirm
+      },
+      run: async (a) => noteSubject(client, a)
+    },
     unmute_watch: {
       description: "Clear a subject's mute. Takes effect at once. Without confirm it only describes.",
       input: { planId, subject, confirm },
@@ -21577,6 +21607,22 @@ function buildTools(client) {
         window: a.window
       })
     },
+    list_project_changes: {
+      description: 'The account\'s changes to what Sentinel watches across a project, newest first: each watch turned on or off, rule edits (rule and prevRule, the one it replaced), mutes and cooldowns, with how each was made (source) and when. `watch` keeps one watch (an id from list_project_watches); filter "mutes" keeps mutes and cooldowns; pass `next` back as cursor for older ones.',
+      input: {
+        projectId,
+        watch: string2().optional(),
+        filter: literal("mutes").optional(),
+        limit: number2().int().min(1).max(200).optional(),
+        cursor: string2().optional()
+      },
+      run: async (a) => client.projectChanges(a.projectId, {
+        watch: a.watch,
+        filter: a.filter,
+        limit: a.limit,
+        cursor: a.cursor
+      })
+    },
     set_project_destinations: {
       description: "Where a project's alerts go, set on each contract you added in it: email on or off, a webhook URL, a Slack URL. A URL left out is cleared. Without confirm it only describes.",
       input: {
@@ -21622,7 +21668,7 @@ async function runTool(tool, args) {
   }
 }
 function buildServer(client) {
-  const server = new McpServer({ name: "sentinel", version: "0.5.0" });
+  const server = new McpServer({ name: "sentinel", version: "0.7.0" });
   for (const [name, tool] of Object.entries(buildTools(client))) {
     server.registerTool(name, { description: tool.description, inputSchema: tool.input }, (args) => runTool(tool, args));
   }
@@ -21637,6 +21683,7 @@ if (!credential) {
 }
 var client = createClient({
   token: credential.token,
-  baseUrl: process.env.SENTINEL_API_URL
+  baseUrl: process.env.SENTINEL_API_URL,
+  client: "mcp"
 });
 await buildServer(client).connect(new StdioServerTransport);

package/dist/sentinel-client.d.ts

@@ -157,7 +157,11 @@ export type WatchDelivery = {
     routes: string[];
     cooldownBlocks: number;
     mutedUntil: string | null;
+    /** The team's own words, sent with every alert this watch fires. Absent from a server before notes. */
+    note?: string | null;
 };
+/** The longest watch note the server takes (monitoring/watch.ts `WATCH_NOTE_MAX`). */
+export declare const WATCH_NOTE_MAX = 500;
 /** One of the caller's own watches on a plan's contract, as `GET /plan/:id/watches` returns it. */
 export type StoredWatch = {
     id: string;
@@ -251,7 +255,7 @@ export type WatchesView = {
     events: {
         id: string;
         watchId: string;
-        action: "proposed" | "applied" | "rejected" | "muted" | "cooldown";
+        action: "proposed" | "applied" | "rejected" | "muted" | "cooldown" | "note";
         rule: WatchRule | null;
         note: string | null;
         createdAt: string;
@@ -542,6 +546,35 @@ export type ProjectWatchesView = {
     locked: number;
     [field: string]: unknown;
 };
+/** One change to what Sentinel watches: turned on or off, a rule edit (`prevRule` is what it replaced), a mute, a
+ *  cooldown or a note set or cleared (never its text). `source` is how it was made (`web`, `key "<name>"`, …), null when not known. */
+export type WatchChange = {
+    id: string;
+    at: string;
+    action: "applied" | "on" | "off" | "muted" | "cooldown" | "note";
+    contractId: string;
+    watch: {
+        id: string;
+        title: string;
+    };
+    subject: WatchSubject;
+    units: Units | null;
+    rule: WatchRule | null;
+    prevRule: WatchRule | null;
+    note: string | null;
+    by: "you";
+    source: string | null;
+};
+export type ChangesOptions = {
+    limit?: number;
+    cursor?: string | null;
+    /** One intent watch's id (from projectWatches). */
+    watch?: string;
+    /** `mutes`: only mutes and cooldowns. */
+    filter?: "mutes";
+};
+/** One change as a line: `Money out turned on`, `sBTC rule changed: ≥ 5 → ≥ 2`. */
+export declare function changeText(c: WatchChange): string;
 /** One intent watch's activity, as the web app draws it: points, the history page, counts. */
 export type WatchActivity = {
     window: 7 | 90;
@@ -633,6 +666,8 @@ export type ClientOptions = {
     baseUrl?: string;
     token: string;
     fetch?: typeof globalThis.fetch;
+    /** Which tool is calling (sent as `x-sentinel-client`), so a change's history can say "sentinel CLI" or "MCP". */
+    client?: "cli" | "mcp";
 };
 export declare function createClient(opts: ClientOptions): {
     me: () => Promise<Record<string, unknown>>;
@@ -685,6 +720,10 @@ export declare function createClient(opts: ClientOptions): {
     mute: (planId: string, watchId: string, mutedUntil: string | null) => Promise<{
         watch: StoredWatch;
     }>;
+    /** Set the team's note on a watch (shown with every alert it sends), or clear it with null. Plain text, 500 characters at most. */
+    setWatchNote: (planId: string, watchId: string, note: string | null) => Promise<{
+        watch: StoredWatch;
+    }>;
     /** Mute the watch behind an alert for 1, 24 or 168 hours; 0 clears. */
     muteAlert: (alertId: string, hours: 0 | 1 | 24 | 168) => Promise<{
         mutedUntil: string | null;
@@ -890,6 +929,11 @@ export declare function createClient(opts: ClientOptions): {
         contract?: string;
         fn?: string;
     }) => Promise<WatchActivity>;
+    /** The account's changes to what Sentinel watches across the project, newest first; `next` pages back. */
+    projectChanges: (projectId: string, opts?: ChangesOptions) => Promise<{
+        events: WatchChange[];
+        next: string | null;
+    }>;
 };
 export type SentinelClient = ReturnType<typeof createClient>;
 /** A mute end `hours` out, a minute inside the 7-day limit so clock skew can't tip it over. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secondlayer/sentinel",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Sentinel from a terminal or an agent: the CLI, an MCP server and a client for your Stacks contract monitoring.",
   "license": "MIT",
   "repository": "https://runsentinel.app/docs",