@wrongstack/plugins 0.277.2 → 0.280.0

package/dist/auto-doc.d.ts

@@ -7,6 +7,14 @@ import { Plugin } from '@wrongstack/core';
  * - auto_doc: Generate and inject doc comments into JS/TS files.
  *   Pass `dry_run: true` to preview without writing (replaces the former
  *   `auto_doc (dry_run)` tool).
+ *
+ * LLM mode (opt-in): with `config.extensions['auto-doc'].useLlm = true`
+ * (or per-call `use_llm: true`) and a host that wires `api.llm`, each
+ * doc comment's prose is written by the LLM from the entity's signature
+ * and body instead of the `TODO: describe …` placeholder. Provider/model
+ * follow the plugin's `config.extensions['auto-doc'].llm` override, then
+ * the session default. Best-effort: any LLM failure (or a bad response)
+ * falls back to the template for that entity — a doc comment always lands.
  */
 
 declare const plugin: Plugin;

package/dist/auto-doc.js

@@ -1,5 +1,14 @@
 // src/auto-doc/index.ts
 var AUTO_DOC_API_VERSION = "^0.1.10";
+var state = {
+  invocationCount: 0,
+  /** Doc comments whose prose came from the LLM this session. */
+  llmDocs: 0,
+  /** LLM calls that failed and fell back to the template. */
+  llmFallbacks: 0,
+  /** Last invocation summary — surfaced by health() for /diag plugins. */
+  lastInvocation: null
+};
 function parseSource(content) {
   const entities = [];
   const lines = content.split("\n");
@@ -75,6 +84,54 @@ ${params}${returns}
    */`;
   }
 }
+function entitySnippet(content, entity, maxLines = 25) {
+  const lines = content.split("\n");
+  const start = entity.startLine - 1;
+  return lines.slice(start, start + maxLines).join("\n");
+}
+async function generateDocCommentLlm(entity, snippet, includeTypes, api) {
+  if (!api.llm) return null;
+  const paramList = entity.kind === "function" ? entity.params : [];
+  try {
+    const result = await api.llm.complete(
+      `Write documentation for this ${entity.kind} named "${entity.name}". Respond with ONLY a JSON object of the form {"summary": string, "params": {"<name>": string}, "returns": string}. summary is one concise sentence. params has one entry per parameter` + (paramList.length > 0 ? ` (${paramList.join(", ")})` : " (may be empty)") + ". returns describes the return value (empty string if none). No prose outside the JSON.\n\n```\n" + snippet + "\n```",
+      {
+        system: "You are a precise API documentation writer. Output only JSON.",
+        maxTokens: 400,
+        responseFormat: "json"
+      }
+    );
+    const parsed = JSON.parse(extractJsonObject(result.text));
+    const summary = typeof parsed.summary === "string" && parsed.summary.trim() ? parsed.summary.trim() : `Describe ${entity.name}`;
+    if (entity.kind !== "function") {
+      return `/**
+   * ${summary}
+   */`;
+    }
+    const paramLines = paramList.map((p) => {
+      const desc = parsed.params && typeof parsed.params[p] === "string" && parsed.params[p].trim() ? parsed.params[p].trim() : "parameter";
+      return `   * @param ${p} - ${desc}`;
+    });
+    const returnsDesc = typeof parsed.returns === "string" && parsed.returns.trim() ? parsed.returns.trim() : "";
+    const returnsLine = entity.returnType && returnsDesc ? `
+   * @returns ${includeTypes ? `{${entity.returnType}} ` : ""}${returnsDesc}` : entity.returnType ? `
+   * @returns ${includeTypes ? `{${entity.returnType}} ` : ""}return value` : "";
+    const paramBlock = paramLines.length > 0 ? `
+${paramLines.join("\n")}` : "";
+    return `/**
+   * ${summary}${paramBlock}${returnsLine}
+   */`;
+  } catch {
+    return null;
+  }
+}
+function extractJsonObject(text) {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  const body = fenced?.[1] ?? text;
+  const start = body.indexOf("{");
+  const end = body.lastIndexOf("}");
+  return start >= 0 && end > start ? body.slice(start, end + 1) : body.trim();
+}
 function needsDocComment(content, entity) {
   const lines = content.split("\n");
   const lineIdx = entity.startLine - 1;
@@ -92,13 +149,27 @@ function injectDocComment(content, entity, doc) {
 }
 async function runAutoDoc(input, api) {
   if (!input.files || typeof input.files !== "object" || !Array.isArray(input.files)) {
-    return { ok: false, error: "input.files must be an array of file paths", filesProcessed: 0, changes: [] };
+    return {
+      ok: false,
+      error: "input.files must be an array of file paths",
+      filesProcessed: 0,
+      changes: []
+    };
   }
   if (input.files.length === 0) {
-    return { ok: false, error: "input.files is empty \u2014 provide at least one file path", filesProcessed: 0, changes: [] };
+    return {
+      ok: false,
+      error: "input.files is empty \u2014 provide at least one file path",
+      filesProcessed: 0,
+      changes: []
+    };
   }
-  const includeTypes = api.config.extensions?.["auto-doc"]?.["includeTypes"] ?? false;
+  const extConfig = api.config.extensions?.["auto-doc"] ?? {};
+  const includeTypes = extConfig["includeTypes"] ?? false;
+  const useLlm = (input.use_llm ?? extConfig["useLlm"] ?? false) === true && Boolean(api.llm);
+  const maxLlmEntities = typeof extConfig["maxLlmEntities"] === "number" && extConfig["maxLlmEntities"] >= 0 ? extConfig["maxLlmEntities"] : 25;
   const results = [];
+  let llmBudget = maxLlmEntities;
   for (const file of input.files) {
     try {
       const { readFileSync, writeFileSync } = await import('fs');
@@ -113,9 +184,28 @@ async function runAutoDoc(input, api) {
       let modified = content;
       for (const entity of entities) {
         if (!input.force && !needsDocComment(modified, entity)) continue;
-        const doc = generateDocComment(entity, includeTypes);
+        let doc = null;
+        let source = "template";
+        if (useLlm && llmBudget > 0) {
+          llmBudget -= 1;
+          doc = await generateDocCommentLlm(
+            entity,
+            entitySnippet(modified, entity),
+            includeTypes,
+            api
+          );
+          if (doc) {
+            source = "llm";
+            state.llmDocs += 1;
+            api.metrics.counter("llm_docs");
+          } else {
+            state.llmFallbacks += 1;
+            api.metrics.counter("llm_fallbacks");
+          }
+        }
+        if (!doc) doc = generateDocComment(entity, includeTypes);
         modified = injectDocComment(modified, entity, doc);
-        results.push({ file, entity: entity.name });
+        results.push({ file, entity: entity.name, source });
       }
       if (!input.dry_run && results.length > 0) {
         writeFileSync(file, modified, "utf-8");
@@ -125,7 +215,12 @@ async function runAutoDoc(input, api) {
       api.log.error(`auto-doc: error processing ${file}: ${err}`);
     }
   }
-  return { ok: true, filesProcessed: input.files.length, changes: results };
+  return {
+    ok: true,
+    filesProcessed: input.files.length,
+    changes: results,
+    llm: useLlm ? { docs: state.llmDocs, fallbacks: state.llmFallbacks } : void 0
+  };
 }
 var plugin = {
   name: "auto-doc",
@@ -133,26 +228,68 @@ var plugin = {
   description: "Auto-generates JSDoc/TSDoc comments for functions, classes, types, and interfaces",
   apiVersion: AUTO_DOC_API_VERSION,
   capabilities: { tools: true, pipelines: ["toolCall"] },
-  defaultConfig: { style: "tsdoc", includeTypes: false, dryRun: false },
+  defaultConfig: {
+    style: "tsdoc",
+    includeTypes: false,
+    dryRun: false,
+    useLlm: false,
+    maxLlmEntities: 25
+  },
   configSchema: {
     type: "object",
     properties: {
       style: { type: "string", enum: ["jsdoc", "tsdoc"], default: "tsdoc" },
       includeTypes: { type: "boolean", default: false },
-      dryRun: { type: "boolean", default: false }
+      dryRun: { type: "boolean", default: false },
+      useLlm: {
+        type: "boolean",
+        default: false,
+        description: 'Write doc prose with the LLM (api.llm) instead of TODO placeholders. Provider/model follow extensions["auto-doc"].llm, then the session default.'
+      },
+      maxLlmEntities: {
+        type: "number",
+        minimum: 0,
+        default: 25,
+        description: "Cap on LLM-written doc comments per invocation; entities beyond it use the template."
+      },
+      llm: {
+        type: "object",
+        description: "Optional { provider, model } override for LLM doc prose."
+      }
     }
   },
   setup(api) {
+    state.invocationCount = 0;
+    state.llmDocs = 0;
+    state.llmFallbacks = 0;
+    state.lastInvocation = null;
     api.tools.register({
       name: "auto_doc",
       description: "Auto-generate JSDoc/TSDoc comments for functions, classes, types, and interfaces in source files. Set `dry_run: true` to preview without writing.",
       inputSchema: {
         type: "object",
         properties: {
-          files: { type: "array", items: { type: "string" }, description: "Source files to document" },
-          style: { type: "string", enum: ["jsdoc", "tsdoc"], default: "tsdoc", description: "Comment style" },
+          files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Source files to document"
+          },
+          style: {
+            type: "string",
+            enum: ["jsdoc", "tsdoc"],
+            default: "tsdoc",
+            description: "Comment style"
+          },
           force: { type: "boolean", default: false, description: "Overwrite existing docstrings" },
-          dry_run: { type: "boolean", default: false, description: "Preview generated comments without writing to files" }
+          dry_run: {
+            type: "boolean",
+            default: false,
+            description: "Preview generated comments without writing to files"
+          },
+          use_llm: {
+            type: "boolean",
+            description: "Write doc prose with the LLM (api.llm) instead of TODO placeholders. Overrides the useLlm config flag for this call."
+          }
         },
         required: ["files"]
       },
@@ -160,13 +297,38 @@ var plugin = {
       mutating: true,
       category: "Project",
       async execute(input) {
-        return runAutoDoc(input, api);
+        const inp = input;
+        state.invocationCount += 1;
+        const result = await runAutoDoc(inp, api);
+        state.lastInvocation = {
+          when: (/* @__PURE__ */ new Date()).toISOString(),
+          files: Array.isArray(inp.files) ? inp.files.length : 0,
+          style: inp.style === "jsdoc" ? "jsdoc" : "tsdoc",
+          dryRun: inp.dry_run === true
+        };
+        return result;
       }
     });
     api.log.info("auto-doc plugin loaded", { version: "0.2.0", capabilities: ["auto_doc"] });
   },
   teardown(api) {
-    api.log.info("auto-doc plugin unloaded");
+    const finalCount = state.invocationCount;
+    const finalLlmDocs = state.llmDocs;
+    state.invocationCount = 0;
+    state.llmDocs = 0;
+    state.llmFallbacks = 0;
+    state.lastInvocation = null;
+    api.log.info("auto-doc: teardown complete", { invocations: finalCount, llmDocs: finalLlmDocs });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: state.lastInvocation === null ? `auto-doc: ${state.invocationCount} invocation(s) this session` : `auto-doc: last run ${state.lastInvocation.files} file(s) at ${state.lastInvocation.when} (${state.lastInvocation.dryRun ? "dry-run" : "write"}); ${state.llmDocs} LLM doc(s), ${state.llmFallbacks} fallback(s)`,
+      invocationCount: state.invocationCount,
+      llmDocs: state.llmDocs,
+      llmFallbacks: state.llmFallbacks,
+      lastInvocation: state.lastInvocation
+    };
   }
 };
 var auto_doc_default = plugin;

package/dist/auto-escalate.d.ts

@@ -0,0 +1,45 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * auto-escalate plugin — turns transient provider errors into a graceful
+ * model-escalation ladder instead of a hard failure.
+ *
+ * Registers an `AgentExtension.onError` hook (wired at agent-loop.ts:636).
+ * When a provider call fails with a retryable error (overload, rate
+ * limit, timeout, 5xx), the plugin asks the agent loop to retry the turn
+ * with the NEXT model in a configured escalation ladder — e.g. a busy
+ * fast model escalates to a more capable one that may have spare
+ * capacity. On a non-retryable error, or once the ladder is exhausted,
+ * it steps aside (returns nothing) so the host's built-in error recovery
+ * runs unchanged.
+ *
+ * Loop constraint: the agent loop caps recovery retries at 2 per turn
+ * (agent-loop.ts), so at most the first ~2 rungs of the ladder are used
+ * before the loop fails. Order the ladder cheapest→most-capable.
+ *
+ * Safety posture: opt-in — loads inert until
+ * `config.extensions['auto-escalate'].enabled = true`. It never forces a
+ * `fail`; it only requests retries with a better model, and otherwise
+ * defers to the default handler.
+ *
+ * Config (`config.extensions['auto-escalate']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": false,
+ *   "escalation": ["claude-sonnet-5", "claude-opus-4-8"],
+ *   "retryablePatterns": ["overload", "rate.?limit", "429", "50[023]", "timeout", "ETIMEDOUT", "ECONNRESET"]
+ * }
+ * ```
+ *
+ * Tools:
+ *  - `auto_escalate_status` — ladder, patterns, and escalation counters
+ *
+ * @public
+ */
+
+declare function errorText(err: unknown): string;
+declare function isRetryable(text: string, patterns: RegExp[]): boolean;
+declare const plugin: Plugin;
+
+export { plugin as default, errorText, isRetryable };

package/dist/auto-escalate.js

@@ -0,0 +1,190 @@
+// src/auto-escalate/index.ts
+var DEFAULT_PATTERNS = [
+  "overload",
+  "rate.?limit",
+  "\\b429\\b",
+  "\\b50[023]\\b",
+  "timeout",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "temporarily unavailable"
+];
+function readConfig(raw) {
+  const base = {
+    enabled: false,
+    escalation: [],
+    retryablePatterns: DEFAULT_PATTERNS.map((p) => new RegExp(p, "i"))
+  };
+  if (!raw || typeof raw !== "object") return base;
+  const r = raw;
+  const escalation = Array.isArray(r["escalation"]) ? r["escalation"].filter((m) => typeof m === "string" && m.length > 0) : [];
+  const patterns = Array.isArray(r["retryablePatterns"]) ? r["retryablePatterns"].filter((p) => typeof p === "string" && p.length > 0).flatMap((p) => {
+    try {
+      return [new RegExp(p, "i")];
+    } catch {
+      return [];
+    }
+  }) : base.retryablePatterns;
+  return {
+    enabled: r["enabled"] === true,
+    escalation,
+    retryablePatterns: patterns.length > 0 ? patterns : base.retryablePatterns
+  };
+}
+var state = {
+  errorsSeen: 0,
+  escalationsRequested: 0,
+  laddersExhausted: 0,
+  runEscalations: 0,
+  lastEscalation: null,
+  extensionUnregister: null
+};
+function errorText(err) {
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+function isRetryable(text, patterns) {
+  return patterns.some((re) => re.test(text));
+}
+var plugin = {
+  name: "auto-escalate",
+  version: "0.1.0",
+  description: "On retryable provider errors, retries the turn with the next model in an escalation ladder (onError). Opt-in; defers to default recovery otherwise.",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true },
+  defaultConfig: { enabled: false, escalation: [], retryablePatterns: DEFAULT_PATTERNS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: {
+        type: "boolean",
+        default: false,
+        description: "Master switch. OFF by default because it changes error-recovery behavior."
+      },
+      escalation: {
+        type: "array",
+        items: { type: "string" },
+        default: [],
+        description: "Ordered model ids (cheapest\u2192most-capable) to retry with on successive retryable errors."
+      },
+      retryablePatterns: {
+        type: "array",
+        items: { type: "string" },
+        description: "Case-insensitive regexes; an error whose text matches any is treated as retryable."
+      }
+    }
+  },
+  setup(api) {
+    state.errorsSeen = 0;
+    state.escalationsRequested = 0;
+    state.laddersExhausted = 0;
+    state.runEscalations = 0;
+    state.lastEscalation = null;
+    if (state.extensionUnregister) {
+      try {
+        state.extensionUnregister();
+      } catch {
+      }
+      state.extensionUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["auto-escalate"]);
+    if (cfg.enabled && cfg.escalation.length > 0) {
+      state.extensionUnregister = api.extensions.register({
+        name: "auto-escalate",
+        owner: "auto-escalate",
+        // Fresh run → reset the ladder position.
+        beforeRun() {
+          state.runEscalations = 0;
+        },
+        onError(_ctx, err, phase) {
+          if (phase !== "provider") return;
+          state.errorsSeen += 1;
+          const text = errorText(err);
+          if (!isRetryable(text, cfg.retryablePatterns)) return;
+          if (state.runEscalations >= cfg.escalation.length) {
+            state.laddersExhausted += 1;
+            return;
+          }
+          const nextModel = cfg.escalation[state.runEscalations];
+          state.runEscalations += 1;
+          state.escalationsRequested += 1;
+          state.lastEscalation = {
+            to: nextModel,
+            reason: text.slice(0, 200),
+            when: (/* @__PURE__ */ new Date()).toISOString()
+          };
+          api.metrics.counter("escalations", 1, { to: nextModel });
+          api.log.warn("auto-escalate: retrying with escalated model", { to: nextModel });
+          return { action: "retry", model: nextModel };
+        }
+      });
+    }
+    api.tools.register({
+      name: "auto_escalate_status",
+      description: "Reports auto-escalate state: enabled, escalation ladder, and escalation counters.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          escalation: cfg.escalation,
+          retryablePatterns: cfg.retryablePatterns.map((r) => r.source),
+          counters: {
+            errorsSeen: state.errorsSeen,
+            escalationsRequested: state.escalationsRequested,
+            laddersExhausted: state.laddersExhausted
+          },
+          lastEscalation: state.lastEscalation
+        };
+      }
+    });
+    api.log.info("auto-escalate plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      ladder: cfg.escalation
+    });
+  },
+  teardown(api) {
+    if (state.extensionUnregister) {
+      try {
+        state.extensionUnregister();
+      } catch {
+      }
+      state.extensionUnregister = null;
+    }
+    const final = {
+      errorsSeen: state.errorsSeen,
+      escalationsRequested: state.escalationsRequested,
+      laddersExhausted: state.laddersExhausted
+    };
+    state.errorsSeen = 0;
+    state.escalationsRequested = 0;
+    state.laddersExhausted = 0;
+    state.runEscalations = 0;
+    state.lastEscalation = null;
+    api.log.info("auto-escalate: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `auto-escalate: ${state.escalationsRequested} escalation(s) of ${state.errorsSeen} error(s), ${state.laddersExhausted} ladder(s) exhausted`,
+      counters: {
+        errorsSeen: state.errorsSeen,
+        escalationsRequested: state.escalationsRequested,
+        laddersExhausted: state.laddersExhausted
+      }
+    };
+  }
+};
+var auto_escalate_default = plugin;
+
+export { auto_escalate_default as default, errorText, isRetryable };

package/dist/branch-guard.d.ts

@@ -0,0 +1,33 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * branch-guard plugin — PreToolUse hook that blocks commits, pushes,
+ * and merges to protected branches (default: main, master).
+ *
+ * Tools registered:
+ * - branch_guard_status : Show protected branches, mode, and counters.
+ *
+ * Hooks registered:
+ * - PreToolUse with matcher `bash|git_autocommit`. Inspects the tool
+ *   input for git commit / push / merge / rebase commands (bash) or
+ *   the tool call itself (git_autocommit). If the current branch is
+ *   protected, the call is blocked with a clear reason.
+ *
+ * Config (`config.extensions['branch-guard']`):
+ *
+ * ```jsonc
+ * {
+ *   "branches": ["main", "master"],  // protected branch names
+ *   "mode": "block",                 // "block" | "warn"
+ *   "blockMerge": true,              // also block merges into protected
+ *   "blockPush": true,               // also block pushes from protected
+ *   "blockCommit": true              // also block commits on protected
+ * }
+ * ```
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };