@wrongstack/plugins 0.277.1 → 0.280.0

package/dist/session-recap.js

@@ -0,0 +1,421 @@
+// src/session-recap/index.ts
+var state = {
+  recapsPublished: 0,
+  recapsErrored: 0,
+  recapsSkipped: 0,
+  aiSummariesWritten: 0,
+  aiSummaryErrors: 0,
+  stopInvocations: 0,
+  totalInputTokens: 0,
+  totalOutputTokens: 0,
+  perModel: /* @__PURE__ */ new Map(),
+  toolCounts: /* @__PURE__ */ new Map(),
+  commitCount: 0,
+  startedAt: null,
+  lastActivityAt: null,
+  stopHookUnregister: null,
+  eventUnsubscribers: []
+};
+var DEFAULTS = {
+  enabled: true,
+  subjectPrefix: "session recap: ",
+  includeTranscriptTail: 3,
+  maxBodyChars: 8e3,
+  aiSummary: false
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] !== false,
+    subjectPrefix: typeof r["subjectPrefix"] === "string" ? r["subjectPrefix"] : DEFAULTS.subjectPrefix,
+    includeTranscriptTail: typeof r["includeTranscriptTail"] === "number" && r["includeTranscriptTail"] >= 0 ? r["includeTranscriptTail"] : DEFAULTS.includeTranscriptTail,
+    maxBodyChars: typeof r["maxBodyChars"] === "number" && r["maxBodyChars"] > 0 ? r["maxBodyChars"] : DEFAULTS.maxBodyChars,
+    aiSummary: r["aiSummary"] === true
+  };
+}
+function touchActivity() {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (state.startedAt === null) state.startedAt = now;
+  state.lastActivityAt = now;
+}
+function bumpModelUsage(model, inputTokens, outputTokens) {
+  let m = state.perModel.get(model);
+  if (!m) {
+    m = { inputTokens: 0, outputTokens: 0, invocations: 0 };
+    state.perModel.set(model, m);
+  }
+  m.inputTokens += inputTokens;
+  m.outputTokens += outputTokens;
+  m.invocations += 1;
+  state.totalInputTokens += inputTokens;
+  state.totalOutputTokens += outputTokens;
+}
+function bumpToolCount(name) {
+  state.toolCounts.set(name, (state.toolCounts.get(name) ?? 0) + 1);
+}
+function formatDuration(startedAt, lastActivityAt) {
+  if (!startedAt) return "0s";
+  const start = Date.parse(startedAt);
+  const end = lastActivityAt ? Date.parse(lastActivityAt) : Date.now();
+  const ms = Math.max(0, end - start);
+  const sec = Math.floor(ms / 1e3);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  const remSec = sec % 60;
+  if (min < 60) return `${min}m${remSec}s`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return `${hr}h${remMin}m`;
+}
+function topN(map, n) {
+  return [...map.entries()].sort((a, b) => {
+    const av = a[1];
+    const bv = b[1];
+    if (typeof av === "number" && typeof bv === "number") return bv - av;
+    return 0;
+  }).slice(0, n);
+}
+async function readTranscriptTail(transcriptPath, n) {
+  if (!transcriptPath || n <= 0) return [];
+  let raw;
+  try {
+    const { readFile } = await import('fs/promises');
+    raw = await readFile(transcriptPath, "utf-8");
+  } catch {
+    return [];
+  }
+  const lines = raw.split("\n").filter((l) => l.length > 0);
+  const tail = lines.slice(-n);
+  const out = [];
+  for (const l of tail) {
+    try {
+      out.push(JSON.parse(l));
+    } catch {
+    }
+  }
+  return out;
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max) + `
+
+[truncated ${s.length - max} chars]` : s;
+}
+var plugin = {
+  name: "session-recap",
+  version: "0.1.0",
+  description: "Stop hook that posts a one-page session summary (tokens, tools, commits, last activity) to the project mailbox",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      subjectPrefix: {
+        type: "string",
+        default: DEFAULTS.subjectPrefix,
+        description: "Prepended to the broadcast subject."
+      },
+      includeTranscriptTail: {
+        type: "number",
+        minimum: 0,
+        maximum: 50,
+        default: 3,
+        description: "Number of last transcript events to include in the recap body."
+      },
+      maxBodyChars: {
+        type: "number",
+        minimum: 500,
+        default: 8e3,
+        description: "Hard cap on the recap body size (chars)."
+      },
+      aiSummary: {
+        type: "boolean",
+        default: false,
+        description: 'Prepend an LLM-written natural-language summary (api.llm) to the recap. Provider/model follow extensions["session-recap"].llm, then the session default.'
+      },
+      llm: {
+        type: "object",
+        description: "Optional { provider, model } override for the AI summary."
+      }
+    }
+  },
+  setup(api) {
+    state.recapsPublished = 0;
+    state.recapsErrored = 0;
+    state.recapsSkipped = 0;
+    state.aiSummariesWritten = 0;
+    state.aiSummaryErrors = 0;
+    state.stopInvocations = 0;
+    state.totalInputTokens = 0;
+    state.totalOutputTokens = 0;
+    state.perModel.clear();
+    state.toolCounts.clear();
+    state.commitCount = 0;
+    state.startedAt = null;
+    state.lastActivityAt = null;
+    state.stopHookUnregister = null;
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const cfg = readConfig(api.config.extensions?.["session-recap"]);
+    const mailbox = api.mailbox;
+    if (api.onEvent) {
+      const offUsage = api.onEvent("provider.response", (payload) => {
+        touchActivity();
+        const p = payload;
+        const model = p?.model ?? "unknown";
+        const input = p?.usage?.input ?? 0;
+        const output = p?.usage?.output ?? 0;
+        bumpModelUsage(model, input, output);
+      });
+      state.eventUnsubscribers.push(offUsage);
+    }
+    if (api.onPattern) {
+      const offTool = api.onPattern("tool.*", (eventName, payload) => {
+        touchActivity();
+        const p = payload;
+        const toolName = p?.tool ?? p?.name ?? eventName;
+        if (typeof toolName === "string") bumpToolCount(toolName);
+        if (toolName === "git_autocommit" || toolName.startsWith("git ")) ;
+      });
+      state.eventUnsubscribers.push(offTool);
+      const offResult = api.onPattern("tool.result", (_event, payload) => {
+        const p = payload;
+        if (p?.tool === "git_autocommit" && p.isError === false) {
+          state.commitCount += 1;
+        }
+      });
+      state.eventUnsubscribers.push(offResult);
+    }
+    const stopHook = async (input) => {
+      if (!cfg.enabled) return;
+      touchActivity();
+      state.stopInvocations += 1;
+      if (!mailbox) {
+        state.recapsSkipped += 1;
+        api.log.warn(
+          "session-recap: no mailbox available on api \u2014 recap disabled. Add `mailbox` to the setupPlugins() call to enable cross-session summaries."
+        );
+        return;
+      }
+      const transcriptPath = api.session?.transcriptPath;
+      const tailEvents = await readTranscriptTail(transcriptPath, cfg.includeTranscriptTail);
+      const duration = formatDuration(state.startedAt, state.lastActivityAt);
+      const recap = {
+        session: {
+          id: input.sessionId ?? null,
+          cwd: input.cwd ?? null,
+          startedAt: state.startedAt,
+          endedAt: state.lastActivityAt,
+          duration
+        },
+        tokens: {
+          total: { input: state.totalInputTokens, output: state.totalOutputTokens },
+          perModel: topN(state.perModel, 10).map(([model, u]) => ({
+            model,
+            input: u.inputTokens,
+            output: u.outputTokens,
+            invocations: u.invocations
+          }))
+        },
+        tools: {
+          totalCalls: [...state.toolCounts.values()].reduce((a, b) => a + b, 0),
+          uniqueTools: state.toolCounts.size,
+          top: topN(state.toolCounts, 5)
+        },
+        commits: state.commitCount,
+        transcriptTail: tailEvents.flatMap((e) => {
+          const entry = {};
+          if (e.type !== void 0) entry.type = e.type;
+          if (e.ts !== void 0) entry.ts = e.ts;
+          if (e.role !== void 0) entry.role = e.role;
+          if (typeof e.content === "string") entry.preview = e.content.slice(0, 200);
+          return [entry];
+        })
+      };
+      const subject = `${cfg.subjectPrefix}${recap.session.id ?? "session"} \u2014 ${duration}, ${recap.tools.totalCalls} tool calls, ${recap.tokens.total.input + recap.tokens.total.output} tokens`.slice(
+        0,
+        200
+      );
+      let aiSummary = null;
+      if (cfg.aiSummary && api.llm) {
+        try {
+          const topTools = recap.tools.top.map(([n, c]) => `${n}\xD7${c}`).join(", ") || "none";
+          const result = await api.llm.complete(
+            `Summarize this coding-agent session in 2-3 sentences for a teammate catching up. Focus on what was worked on and the scale of activity. Be concrete and terse.
+
+Duration: ${duration}
+Tool calls: ${recap.tools.totalCalls} (top: ${topTools})
+Commits: ${recap.commits}
+Tokens: ${recap.tokens.total.input} in / ${recap.tokens.total.output} out
+` + (recap.transcriptTail.length > 0 ? `Recent activity: ${recap.transcriptTail.map((e) => e.preview ?? e.type ?? "").filter(Boolean).join(" | ").slice(0, 500)}` : ""),
+            { system: "You write concise engineering session recaps.", maxTokens: 200 }
+          );
+          const text = result.text.trim();
+          if (text) {
+            aiSummary = text;
+            state.aiSummariesWritten += 1;
+          }
+        } catch {
+          state.aiSummaryErrors += 1;
+        }
+      }
+      const recapWithSummary = aiSummary ? { summary: aiSummary, ...recap } : recap;
+      const bodyPrefix = aiSummary ? `${aiSummary}
+
+---
+` : "";
+      const body = truncate(
+        bodyPrefix + JSON.stringify(recapWithSummary, null, 2),
+        cfg.maxBodyChars
+      );
+      try {
+        const result = await mailbox.send({
+          from: "plugin:session-recap",
+          to: "*",
+          type: "status",
+          subject,
+          body,
+          priority: "low"
+        });
+        state.recapsPublished += 1;
+        api.log.info("session-recap: published session summary", {
+          messageId: result.id ?? null,
+          duration,
+          toolCalls: recap.tools.totalCalls,
+          tokensIn: recap.tokens.total.input,
+          tokensOut: recap.tokens.total.output
+        });
+      } catch (err) {
+        state.recapsErrored += 1;
+        api.log.warn("session-recap: mailbox.send failed", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    };
+    state.stopHookUnregister = api.registerHook("Stop", void 0, stopHook);
+    api.tools.register({
+      name: "session_recap_status",
+      description: "Reports session-recap state: config, accumulated metrics (tokens, tool calls, commits), and last recap status.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          subjectPrefix: cfg.subjectPrefix,
+          includeTranscriptTail: cfg.includeTranscriptTail,
+          maxBodyChars: cfg.maxBodyChars,
+          mailboxAvailable: Boolean(mailbox),
+          aiSummary: cfg.aiSummary,
+          llmAvailable: Boolean(api.llm),
+          counters: {
+            stopInvocations: state.stopInvocations,
+            recapsPublished: state.recapsPublished,
+            recapsErrored: state.recapsErrored,
+            recapsSkipped: state.recapsSkipped,
+            aiSummariesWritten: state.aiSummariesWritten,
+            aiSummaryErrors: state.aiSummaryErrors
+          },
+          metrics: {
+            totalInputTokens: state.totalInputTokens,
+            totalOutputTokens: state.totalOutputTokens,
+            perModel: topN(state.perModel, 10).map(([model, u]) => ({
+              model,
+              input: u.inputTokens,
+              output: u.outputTokens,
+              invocations: u.invocations
+            })),
+            toolCalls: {
+              total: [...state.toolCounts.values()].reduce((a, b) => a + b, 0),
+              uniqueTools: state.toolCounts.size,
+              top: topN(state.toolCounts, 5)
+            },
+            commits: state.commitCount
+          },
+          timing: {
+            startedAt: state.startedAt,
+            lastActivityAt: state.lastActivityAt,
+            duration: formatDuration(state.startedAt, state.lastActivityAt)
+          }
+        };
+      }
+    });
+    api.log.info("session-recap plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      mailboxAvailable: Boolean(mailbox)
+    });
+  },
+  teardown(api) {
+    if (state.stopHookUnregister) {
+      try {
+        state.stopHookUnregister();
+      } catch {
+      }
+      state.stopHookUnregister = null;
+    }
+    for (const off of state.eventUnsubscribers) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    state.eventUnsubscribers = [];
+    const final = {
+      recapsPublished: state.recapsPublished,
+      recapsErrored: state.recapsErrored,
+      recapsSkipped: state.recapsSkipped,
+      aiSummariesWritten: state.aiSummariesWritten,
+      totalInputTokens: state.totalInputTokens,
+      totalOutputTokens: state.totalOutputTokens,
+      toolCalls: [...state.toolCounts.values()].reduce((a, b) => a + b, 0),
+      commits: state.commitCount
+    };
+    state.recapsPublished = 0;
+    state.recapsErrored = 0;
+    state.recapsSkipped = 0;
+    state.aiSummariesWritten = 0;
+    state.aiSummaryErrors = 0;
+    state.stopInvocations = 0;
+    state.totalInputTokens = 0;
+    state.totalOutputTokens = 0;
+    state.perModel.clear();
+    state.toolCounts.clear();
+    state.commitCount = 0;
+    state.startedAt = null;
+    state.lastActivityAt = null;
+    api.log.info("session-recap: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `session-recap: ${state.stopInvocations} stop(s), ${state.recapsPublished} recap(s) published (${state.aiSummariesWritten} with AI summary), ${state.recapsErrored} error(s), ${state.totalInputTokens + state.totalOutputTokens} tokens observed`,
+      counters: {
+        stopInvocations: state.stopInvocations,
+        recapsPublished: state.recapsPublished,
+        recapsErrored: state.recapsErrored,
+        recapsSkipped: state.recapsSkipped,
+        aiSummariesWritten: state.aiSummariesWritten,
+        aiSummaryErrors: state.aiSummaryErrors
+      },
+      metrics: {
+        totalInputTokens: state.totalInputTokens,
+        totalOutputTokens: state.totalOutputTokens,
+        toolCalls: [...state.toolCounts.values()].reduce((a, b) => a + b, 0),
+        commits: state.commitCount
+      }
+    };
+  }
+};
+var session_recap_default = plugin;
+
+export { session_recap_default as default };

package/dist/shell-check.js

@@ -4,6 +4,14 @@ import { join } from 'path';
 
 // src/shell-check/index.ts
 var API_VERSION = "^0.1.10";
+var state = {
+  /** Per-session invocation count. */
+  invocationCount: 0,
+  /** Total issues found across all runs this session (success or fail). */
+  totalIssues: 0,
+  /** Most recent run summary, surfaced by health(). */
+  lastRun: null
+};
 function runShellCheck(files, severity, cwd) {
   if (!existsSync("shellcheck")) {
     try {
@@ -92,6 +100,9 @@ var plugin = {
     }
   },
   setup(api) {
+    state.invocationCount = 0;
+    state.totalIssues = 0;
+    state.lastRun = null;
     api.tools.register({
       name: "shellcheck",
       description: "Run shellcheck analysis on shell script files. Pass `files` for specific files, or `directory` (optionally with `pattern`) to recursively scan for .sh files. Returns issues with file, line, column, severity, code, and message.",
@@ -130,10 +141,12 @@ var plugin = {
       category: "Code Quality",
       mutating: true,
       async execute(input) {
-        const files = input["files"];
-        const directory = input["directory"] ?? ".";
-        const pattern = input["pattern"] ?? "";
-        const severity = input["severity"] ?? "warning";
+        const inp = input;
+        const files = inp.files;
+        const directory = inp.directory ?? ".";
+        const pattern = inp.pattern ?? "";
+        const severity = inp.severity ?? "warning";
+        state.invocationCount += 1;
         let checkFiles;
         let scannedDirectories = false;
         if (files && files.length > 0) {
@@ -143,6 +156,13 @@ var plugin = {
           scannedDirectories = true;
         }
         if (checkFiles.length === 0) {
+          state.lastRun = {
+            when: (/* @__PURE__ */ new Date()).toISOString(),
+            filesChecked: 0,
+            issues: 0,
+            severity,
+            mode: scannedDirectories ? "directory" : "files"
+          };
           return {
             ok: true,
             filesScanned: 0,
@@ -171,6 +191,14 @@ var plugin = {
         const styleCount = issues.filter((i) => i.level === "style").length;
         api.metrics.counter("issues_found", issues.length, { severity });
         api.metrics.histogram("issues_per_file", issues.length / Math.max(checkFiles.length, 1));
+        state.totalIssues += issues.length;
+        state.lastRun = {
+          when: (/* @__PURE__ */ new Date()).toISOString(),
+          filesChecked: checkFiles.length,
+          issues: issues.length,
+          severity,
+          mode: scannedDirectories ? "directory" : "files"
+        };
         return {
           ok: true,
           mode: scannedDirectories ? "directory" : "files",
@@ -190,6 +218,26 @@ var plugin = {
       }
     });
     api.log.info("shell-check plugin loaded", { version: "0.2.0" });
+  },
+  teardown(api) {
+    const finalInvocations = state.invocationCount;
+    const finalIssues = state.totalIssues;
+    state.invocationCount = 0;
+    state.totalIssues = 0;
+    state.lastRun = null;
+    api.log.info("shell-check: teardown complete", {
+      invocations: finalInvocations,
+      totalIssues: finalIssues
+    });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: state.lastRun === null ? `shell-check: ${state.invocationCount} run(s) this session` : `shell-check: last run checked ${state.lastRun.filesChecked} file(s), ${state.lastRun.issues} issue(s) at ${state.lastRun.when}`,
+      invocationCount: state.invocationCount,
+      totalIssues: state.totalIssues,
+      lastRun: state.lastRun
+    };
   }
 };
 var shell_check_default = plugin;

package/dist/spec-linker.d.ts

@@ -0,0 +1,51 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * spec-linker plugin — markdown link auditor for plugin references.
+ *
+ * Two hooks:
+ *  1. **PostToolUse** on `write|edit` — READ-ONLY. Scans the saved
+ *     file for unlinked plugin references and surfaces them to the
+ *     LLM via `additionalContext`. The LLM decides whether to fix
+ *     the file in a follow-up edit.
+ *
+ *  2. **PreToolUse** on `write` (NOT `edit`) — AUTO-FIX. When the
+ *     `autoFix` config is `true`, scans the would-be content and
+ *     returns a `modifiedInput.content` where each unlinked plugin
+ *     reference is wrapped in a markdown link. The tool executor
+ *     then writes the fixed content instead of the original.
+ *
+ * Why `write` only and not `edit`? The `edit` tool's input shape
+ * is `{ path, old_string, new_string }` — `new_string` is a small
+ * patch, not the whole file. To auto-fix `edit` cleanly we'd have
+ * to either:
+ *   - parse the file, find where `old_string` lives, substitute
+ *     `new_string` with the auto-fixed version, and re-derive
+ *     the new `old_string` (a hard string-diff problem), or
+ *   - reject `edit` and force `write` (bad UX).
+ * Both are too complex for the win. `write` is the common case
+ * for new files; `edit` stays read-only and the PostToolUse
+ * context tells the LLM what to fix.
+ *
+ * The plugin catalog is sourced from `../catalog.js` (single source
+ * of truth — adding a new plugin to the catalog table there is
+ * enough for this plugin to start detecting it).
+ *
+ * Config (`config.extensions['spec-linker']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "fileGlobs": ["**\/*.md", "**\/*.mdx"],
+ *   "maxReferences": 8,
+ *   "autoFix": false   // when true, PreToolUse on `write` wraps unlinked
+ *                      // references in markdown links via modifiedInput
+ * }
+ * ```
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };