@gobing-ai/spur 0.3.71 → 0.3.72

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.3.71",
+            "version": "0.3.72",
             "source": "./plugins/sp"
         }
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.71",
+    "version": "0.3.72",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.50",
-        "@gobing-ai/ts-ai-runner": "^0.4.50",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.50",
-        "@gobing-ai/ts-infra": "^0.4.50",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.50",
-        "@gobing-ai/ts-rule-engine": "^0.4.50",
-        "@gobing-ai/ts-runtime": "^0.4.50",
-        "@gobing-ai/ts-utils": "^0.4.50",
+        "@gobing-ai/ts-db": "^0.4.54",
+        "@gobing-ai/ts-ai-runner": "^0.4.54",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.54",
+        "@gobing-ai/ts-infra": "^0.4.54",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.54",
+        "@gobing-ai/ts-rule-engine": "^0.4.54",
+        "@gobing-ai/ts-runtime": "^0.4.54",
+        "@gobing-ai/ts-utils": "^0.4.54",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.71",
+    "version": "0.3.72",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/daily-summary/daily-summary.mjs

@@ -149,6 +149,78 @@ async function getCcusageData(date) {
     return null;
   }
 }
+async function getSpurHistoryHealth(date, dbPath = ".spur/spur.db") {
+  try {
+    const resolvedPath = resolve(process.cwd(), dbPath);
+    if (!existsSync(resolvedPath)) {
+      return null;
+    }
+    const { Database } = await import("bun:sqlite");
+    const db = new Database(resolvedPath, { readonly: true });
+    try {
+      const loopTable = db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get("history_board_loop_findings");
+      let loops = [];
+      if (loopTable) {
+        const rows = db.query(`SELECT tool_name, args_digest, repeats, session_id, first_seq, last_seq, started_at
+                         FROM history_board_loop_findings
+                         WHERE started_at IS NULL OR started_at LIKE ?
+                         ORDER BY repeats DESC
+                         LIMIT 20`).all(`${date}%`);
+        loops = rows.map((r) => ({
+          toolName: r.tool_name,
+          argsDigest: r.args_digest || "repeated execution",
+          repeats: r.repeats,
+          sessionId: r.session_id,
+          fromSeq: r.first_seq,
+          toSeq: r.last_seq,
+          wastedTokens: r.repeats * 250
+        }));
+      }
+      let toolCalls = 0;
+      let toolErrors = 0;
+      const toolTable = db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get("history_board_tool_5m");
+      if (toolTable) {
+        const stats = db.query(`SELECT SUM(calls) AS calls, SUM(errors) AS errors
+                         FROM history_board_tool_5m
+                         WHERE bucket_start LIKE ?`).get(`${date}%`);
+        toolCalls = stats?.calls ?? 0;
+        toolErrors = stats?.errors ?? 0;
+      }
+      const redundantCalls = loops.reduce((acc, l) => acc + Math.max(0, l.repeats - 1), 0);
+      const wastedTokens = loops.reduce((acc, l) => acc + l.wastedTokens, 0);
+      const errorRatePct = toolCalls > 0 ? toolErrors / toolCalls * 100 : 0;
+      const remediationProposals = [];
+      for (const lp of loops.slice(0, 5)) {
+        const cleanTool = lp.toolName.replace(/[^a-zA-Z0-9_-]/g, "_");
+        const key = `repetition:${cleanTool}:${lp.argsDigest.slice(0, 16)}`;
+        const title = `Break execution loop in ${lp.toolName} (${lp.repeats} repeats)`;
+        const body = `Finding: ${key}\\nObserved ${lp.repeats} redundant invocations in session ${lp.sessionId} (steps #${lp.fromSeq ?? 1}\u2192#${lp.toSeq ?? lp.repeats}). Wasted tokens: ~${lp.wastedTokens}.`;
+        const command = `spur task create --section "Fix ${cleanTool} repetition loop" --body "${body}"`;
+        remediationProposals.push({ key, title, command });
+      }
+      if (toolCalls > 0 && errorRatePct > 10) {
+        const key = "reliability:tooling:high-error-rate";
+        const title = `Investigate high tool error rate (${errorRatePct.toFixed(1)}%)`;
+        const body = `Finding: ${key}\\nObserved ${toolErrors} errors across ${toolCalls} tool calls (${errorRatePct.toFixed(1)}% error rate) on ${date}.`;
+        const command = `spur task create --section "Investigate tool error rate spikes" --body "${body}"`;
+        remediationProposals.push({ key, title, command });
+      }
+      return {
+        toolCalls,
+        toolErrors,
+        errorRatePct,
+        loops,
+        redundantCalls,
+        wastedTokens,
+        remediationProposals
+      };
+    } finally {
+      db.close();
+    }
+  } catch {
+    return null;
+  }
+}
 async function getGitCommits(date) {
   try {
     const { start, end } = getDateRange(date);
@@ -333,6 +405,49 @@ function generateMarkdown(summary) {
     lines.push(pending);
     lines.push("");
   }
+  if (summary.historyHealth) {
+    const hh = summary.historyHealth;
+    lines.push("## Execution Loops & Health Findings");
+    lines.push("");
+    if (hh.loops.length === 0 && hh.toolCalls === 0) {
+      lines.push("- **Status:** \u2705 Clean \u2014 No execution loops or tool calls recorded for this date.");
+      lines.push("");
+    } else {
+      lines.push("| Metric | Value |");
+      lines.push("|--------|-------|");
+      lines.push(`| Tool Invocations | ${hh.toolCalls.toLocaleString()} |`);
+      lines.push(`| Tool Errors | ${hh.toolErrors.toLocaleString()} (${hh.errorRatePct.toFixed(1)}%) |`);
+      lines.push(`| Detected Loops (Repeats \u2265 3) | ${hh.loops.length} |`);
+      lines.push(`| Redundant Invocations | ${hh.redundantCalls.toLocaleString()} |`);
+      lines.push(`| Estimated Wasted Tokens | ${hh.wastedTokens.toLocaleString()} |`);
+      lines.push("");
+      if (hh.loops.length > 0) {
+        lines.push("### Detected Execution Loops");
+        lines.push("");
+        for (const lp of hh.loops.slice(0, 10)) {
+          const seqInfo = lp.fromSeq && lp.toSeq ? ` (steps #${lp.fromSeq} \u2192 #${lp.toSeq})` : "";
+          const argsHint = lp.argsDigest === "74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b" ? "empty/unrecorded arguments" : lp.argsDigest.length > 28 ? `${lp.argsDigest.slice(0, 24)}...` : lp.argsDigest;
+          lines.push(`- \`${lp.toolName || "unknown"}\` \xD7 **${lp.repeats} repeats** in session \`${lp.sessionId}\`${seqInfo}`);
+          lines.push(`  - *Args hint:* \`${argsHint}\` (~${lp.wastedTokens.toLocaleString()} wasted tokens)`);
+        }
+        lines.push("");
+      }
+      if (hh.remediationProposals.length > 0) {
+        lines.push("### Auto-Healing Remediation Proposals");
+        lines.push("");
+        lines.push("To remediate root causes and prevent recurring token waste, execute:");
+        lines.push("");
+        lines.push("```bash");
+        for (const prop of hh.remediationProposals) {
+          lines.push(`# ${prop.title} [${prop.key}]`);
+          lines.push(prop.command);
+          lines.push("");
+        }
+        lines.push("```");
+        lines.push("");
+      }
+    }
+  }
   if (summary.historyReportPath) {
     lines.push("## History Report");
     lines.push("");
@@ -417,6 +532,11 @@ async function buildDailySummary(options) {
   if (gitActivity !== undefined) {
     result.gitActivity = gitActivity;
   }
+  const historyHealth = await getSpurHistoryHealth(options.date);
+  if (historyHealth && (historyHealth.loops.length > 0 || historyHealth.toolCalls > 0)) {
+    result.historyHealth = historyHealth;
+    platforms.push("Spur History");
+  }
   return result;
 }
 async function main() {
@@ -469,6 +589,7 @@ export {
   printUsage,
   parseArgs,
   main,
+  getSpurHistoryHealth,
   getGitCommits,
   getDateRange,
   getCcusageData,

package/plugins/sp/scripts/daily-summary/daily-summary.ts

@@ -59,6 +59,30 @@ export interface UserAnnotations {
     pending: string;
 }
 
+export interface HistoryLoopFinding {
+    toolName: string;
+    argsDigest: string;
+    repeats: number;
+    sessionId: string;
+    fromSeq?: number;
+    toSeq?: number;
+    wastedTokens: number;
+}
+
+export interface HistoryHealthSummary {
+    toolCalls: number;
+    toolErrors: number;
+    errorRatePct: number;
+    loops: HistoryLoopFinding[];
+    redundantCalls: number;
+    wastedTokens: number;
+    remediationProposals: Array<{
+        key: string;
+        title: string;
+        command: string;
+    }>;
+}
+
 export interface DailySummary {
     date: string;
     platforms: string[];
@@ -77,6 +101,8 @@ export interface DailySummary {
     };
     commits: GitCommit[];
     annotations: UserAnnotations;
+    /** Health metrics and loop findings from Spur history analytics. */
+    historyHealth?: HistoryHealthSummary;
     /** Path to the newest history report artifact (R7), resolved from the
      * `.spur/reports/history/latest.json` pointer. Omitted when no report exists. */
     historyReportPath?: string;
@@ -257,6 +283,122 @@ export async function getCcusageData(date: string): Promise<CcusageData | null>
     }
 }
 
+// ─── Spur History Health Integration ──────────────────────────────────────────
+
+export async function getSpurHistoryHealth(
+    date: string,
+    dbPath = '.spur/spur.db',
+): Promise<HistoryHealthSummary | null> {
+    try {
+        const resolvedPath = resolve(process.cwd(), dbPath);
+        if (!existsSync(resolvedPath)) {
+            return null;
+        }
+
+        const { Database } = await import('bun:sqlite');
+        const db = new Database(resolvedPath, { readonly: true });
+
+        try {
+            // 1. Query execution loop findings
+            const loopTable = db
+                .query<{ name: string }, [string]>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+                .get('history_board_loop_findings');
+
+            let loops: HistoryLoopFinding[] = [];
+            if (loopTable) {
+                const rows = db
+                    .query<
+                        {
+                            tool_name: string;
+                            args_digest: string;
+                            repeats: number;
+                            session_id: string;
+                            first_seq: number;
+                            last_seq: number;
+                            started_at: string | null;
+                        },
+                        [string]
+                    >(
+                        `SELECT tool_name, args_digest, repeats, session_id, first_seq, last_seq, started_at
+                         FROM history_board_loop_findings
+                         WHERE started_at IS NULL OR started_at LIKE ?
+                         ORDER BY repeats DESC
+                         LIMIT 20`,
+                    )
+                    .all(`${date}%`);
+
+                loops = rows.map((r) => ({
+                    toolName: r.tool_name,
+                    argsDigest: r.args_digest || 'repeated execution',
+                    repeats: r.repeats,
+                    sessionId: r.session_id,
+                    fromSeq: r.first_seq,
+                    toSeq: r.last_seq,
+                    wastedTokens: r.repeats * 250,
+                }));
+            }
+
+            // 2. Query tool calls and errors
+            let toolCalls = 0;
+            let toolErrors = 0;
+            const toolTable = db
+                .query<{ name: string }, [string]>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+                .get('history_board_tool_5m');
+
+            if (toolTable) {
+                const stats = db
+                    .query<{ calls: number | null; errors: number | null }, [string]>(
+                        `SELECT SUM(calls) AS calls, SUM(errors) AS errors
+                         FROM history_board_tool_5m
+                         WHERE bucket_start LIKE ?`,
+                    )
+                    .get(`${date}%`);
+
+                toolCalls = stats?.calls ?? 0;
+                toolErrors = stats?.errors ?? 0;
+            }
+
+            const redundantCalls = loops.reduce((acc, l) => acc + Math.max(0, l.repeats - 1), 0);
+            const wastedTokens = loops.reduce((acc, l) => acc + l.wastedTokens, 0);
+            const errorRatePct = toolCalls > 0 ? (toolErrors / toolCalls) * 100 : 0;
+
+            // 3. Generate auto-healing remediation proposals
+            const remediationProposals: Array<{ key: string; title: string; command: string }> = [];
+
+            for (const lp of loops.slice(0, 5)) {
+                const cleanTool = lp.toolName.replace(/[^a-zA-Z0-9_-]/g, '_');
+                const key = `repetition:${cleanTool}:${lp.argsDigest.slice(0, 16)}`;
+                const title = `Break execution loop in ${lp.toolName} (${lp.repeats} repeats)`;
+                const body = `Finding: ${key}\\nObserved ${lp.repeats} redundant invocations in session ${lp.sessionId} (steps #${lp.fromSeq ?? 1}→#${lp.toSeq ?? lp.repeats}). Wasted tokens: ~${lp.wastedTokens}.`;
+                const command = `spur task create --section "Fix ${cleanTool} repetition loop" --body "${body}"`;
+                remediationProposals.push({ key, title, command });
+            }
+
+            if (toolCalls > 0 && errorRatePct > 10) {
+                const key = 'reliability:tooling:high-error-rate';
+                const title = `Investigate high tool error rate (${errorRatePct.toFixed(1)}%)`;
+                const body = `Finding: ${key}\\nObserved ${toolErrors} errors across ${toolCalls} tool calls (${errorRatePct.toFixed(1)}% error rate) on ${date}.`;
+                const command = `spur task create --section "Investigate tool error rate spikes" --body "${body}"`;
+                remediationProposals.push({ key, title, command });
+            }
+
+            return {
+                toolCalls,
+                toolErrors,
+                errorRatePct,
+                loops,
+                redundantCalls,
+                wastedTokens,
+                remediationProposals,
+            };
+        } finally {
+            db.close();
+        }
+    } catch {
+        return null;
+    }
+}
+
 // ─── Git Integration ─────────────────────────────────────────────────────────
 
 export async function getGitCommits(date: string): Promise<GitCommit[]> {
@@ -477,6 +619,61 @@ export function generateMarkdown(summary: DailySummary): string {
         lines.push('');
     }
 
+    // Execution Loops & Health Findings
+    if (summary.historyHealth) {
+        const hh = summary.historyHealth;
+        lines.push('## Execution Loops & Health Findings');
+        lines.push('');
+
+        if (hh.loops.length === 0 && hh.toolCalls === 0) {
+            lines.push('- **Status:** ✅ Clean — No execution loops or tool calls recorded for this date.');
+            lines.push('');
+        } else {
+            lines.push('| Metric | Value |');
+            lines.push('|--------|-------|');
+            lines.push(`| Tool Invocations | ${hh.toolCalls.toLocaleString()} |`);
+            lines.push(`| Tool Errors | ${hh.toolErrors.toLocaleString()} (${hh.errorRatePct.toFixed(1)}%) |`);
+            lines.push(`| Detected Loops (Repeats ≥ 3) | ${hh.loops.length} |`);
+            lines.push(`| Redundant Invocations | ${hh.redundantCalls.toLocaleString()} |`);
+            lines.push(`| Estimated Wasted Tokens | ${hh.wastedTokens.toLocaleString()} |`);
+            lines.push('');
+
+            if (hh.loops.length > 0) {
+                lines.push('### Detected Execution Loops');
+                lines.push('');
+                for (const lp of hh.loops.slice(0, 10)) {
+                    const seqInfo = lp.fromSeq && lp.toSeq ? ` (steps #${lp.fromSeq} → #${lp.toSeq})` : '';
+                    const argsHint =
+                        lp.argsDigest === '74234e98afe7498fb5daf1f36ac2d78acc339464f950703b8c019892f982b90b'
+                            ? 'empty/unrecorded arguments'
+                            : lp.argsDigest.length > 28
+                              ? `${lp.argsDigest.slice(0, 24)}...`
+                              : lp.argsDigest;
+                    lines.push(
+                        `- \`${lp.toolName || 'unknown'}\` × **${lp.repeats} repeats** in session \`${lp.sessionId}\`${seqInfo}`,
+                    );
+                    lines.push(`  - *Args hint:* \`${argsHint}\` (~${lp.wastedTokens.toLocaleString()} wasted tokens)`);
+                }
+                lines.push('');
+            }
+
+            if (hh.remediationProposals.length > 0) {
+                lines.push('### Auto-Healing Remediation Proposals');
+                lines.push('');
+                lines.push('To remediate root causes and prevent recurring token waste, execute:');
+                lines.push('');
+                lines.push('```bash');
+                for (const prop of hh.remediationProposals) {
+                    lines.push(`# ${prop.title} [${prop.key}]`);
+                    lines.push(prop.command);
+                    lines.push('');
+                }
+                lines.push('```');
+                lines.push('');
+            }
+        }
+    }
+
     // History report path (R7 — surfaces the newest nightly-run artifact).
     if (summary.historyReportPath) {
         lines.push('## History Report');
@@ -598,6 +795,13 @@ export async function buildDailySummary(options: CliOptions): Promise<DailySumma
         result.gitActivity = gitActivity;
     }
 
+    // Query Spur history health (loops, tool errors, and auto-healing proposals)
+    const historyHealth = await getSpurHistoryHealth(options.date);
+    if (historyHealth && (historyHealth.loops.length > 0 || historyHealth.toolCalls > 0)) {
+        result.historyHealth = historyHealth;
+        platforms.push('Spur History');
+    }
+
     return result;
 }
 

package/schemas/spur-config.schema.json

@@ -92,6 +92,41 @@
                         "enabled": {
                             "type": "boolean",
                             "description": "Enable the scheduled-task runner. OFF by default for CLI (run-once)."
+                        },
+                        "jobs": {
+                            "type": "array",
+                            "description": "Declarative scheduled commands (task 0734). Each entry registers one scheduler tick that enqueues a `scheduler.custom` queue job running `command` through `/bin/sh -c`. Normalized and validated by @gobing-ai/ts-infra runNodeApplication before the server starts.",
+                            "items": {
+                                "type": "object",
+                                "required": ["name", "command"],
+                                "properties": {
+                                    "name": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Job name, unique across the list after trimming. Reported as the `scheduler.custom:<name>` display name on scheduler.job.executed."
+                                    },
+                                    "command": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Shell command run by `/bin/sh -c` with the project root as cwd. Trusted operator input \u2014 never logged."
+                                    },
+                                    "intervalMinutes": {
+                                        "type": "integer",
+                                        "minimum": 1,
+                                        "maximum": 35791,
+                                        "description": "Fixed interval in minutes. Mutually exclusive with `cron`. The upper bound is the Node timer ceiling (2147483647 ms)."
+                                    },
+                                    "cron": {
+                                        "type": "string",
+                                        "minLength": 1,
+                                        "description": "Five-field cron expression (minute hour day-of-month month day-of-week) evaluated in local time. Mutually exclusive with `intervalMinutes`."
+                                    }
+                                },
+                                "oneOf": [
+                                    { "required": ["intervalMinutes"], "not": { "required": ["cron"] } },
+                                    { "required": ["cron"], "not": { "required": ["intervalMinutes"] } }
+                                ]
+                            }
                         }
                     }
                 }