@agentistics/mcp 2.125.0 → 2.126.0

package/README.md

@@ -38,6 +38,7 @@ The `AGENTISTICS_API` env var must point to a running agentistics server.
 |------|---------|
 | `agentistics_summary` | All-time totals: tokens, cost, sessions, streak — unified or per-harness |
 | `agentistics_harnesses` | Side-by-side comparison of every tracked harness |
+| `agentistics_plan_limits` | Subscription windows, pacing, and the recommended harness/model before opening sessions |
 | `agentistics_projects` | Per-project token and cost breakdown (optionally per-harness) |
 | `agentistics_sessions` | Recent sessions with harness, duration, model, cost |
 | `agentistics_costs` | Model pricing breakdown and cache savings (optionally per-harness) |

package/dist/agentistics-mcp.js

@@ -1009,6 +1009,7 @@ var AGENT_TOOL_POLICY = {
   },
   agentistics_summary: { ...DATA, capability: "localTranscripts", host: true, risk: "R", routes: ["GET /api/data", "GET /api/runtime/metrics"], reason: "reads computed metrics" },
   agentistics_harnesses: { ...DATA, capability: "localTranscripts", host: true, risk: "R", routes: ["GET /api/data", "GET /api/runtime/metrics"], reason: "reads computed metrics per harness" },
+  agentistics_plan_limits: { ...DATA, capability: "localTranscripts", host: true, risk: "R", routes: ["GET /api/plan-limits"], reason: "reads subscription windows and routing guidance; does not start work" },
   agentistics_projects: { ...DATA, capability: "localTranscripts", host: true, risk: "R", routes: ["GET /api/data", "GET /api/runtime/metrics"], reason: "reads computed metrics per project" },
   agentistics_sessions: { ...DATA, capability: "localShell", host: true, risk: "R", routes: ["GET /api/data", "GET /api/fleet"], reason: "reads session metadata (first_prompt is untrusted text, §4.8)" },
   agentistics_costs: { ...DATA, capability: "localTranscripts", host: true, risk: "R", routes: ["GET /api/data", "GET /api/runtime/metrics"], reason: "reads computed costs" },
@@ -1038,6 +1039,46 @@ var PLAN_WINDOW_MS = {
   week: 7 * 24 * 60 * 60000
 };
 var PLAN_LIMITS_STALE_MS = 10 * 60000;
+var ROUTE_PREFERENCES = {
+  lead: [["claude", "opus"], ["codex"]],
+  "hard-bug": [["claude", "opus"], ["codex"]],
+  design: [["claude", "opus"], ["codex"]],
+  "spec-impl": [["codex"], ["claude", "sonnet"], ["gemini"], ["copilot"]],
+  mechanical: [["codex"], ["claude", "sonnet"], ["gemini"], ["copilot"]],
+  qa: [["gemini"], ["copilot"], ["codex"], ["claude", "sonnet"]],
+  probe: [["claude", "haiku"], ["gemini"]]
+};
+function routeRecommendation(budgets, kind, authorHarness) {
+  const allowTight = kind === "lead";
+  const eligible = budgets.filter((b) => b.plan !== "unregistered" && b.status !== "hold" && (allowTight || b.status !== "tight") && b.harness !== (kind === "qa" ? authorHarness : undefined));
+  const ordered = [...eligible].sort((a, b) => {
+    const ap = a.paceStatus === "under" ? 0 : 1;
+    const bp = b.paceStatus === "under" ? 0 : 1;
+    if (ap !== bp)
+      return ap - bp;
+    const ai = ROUTE_PREFERENCES[kind].findIndex(([h]) => h === a.harness);
+    const bi = ROUTE_PREFERENCES[kind].findIndex(([h]) => h === b.harness);
+    return (ai < 0 ? 999 : ai) - (bi < 0 ? 999 : bi);
+  });
+  const preference = ROUTE_PREFERENCES[kind];
+  const chosen = ordered.find((b) => preference.some(([h]) => h === b.harness));
+  const pick = chosen ?? ordered[0];
+  if (!pick) {
+    const earliest = budgets.filter((b) => b.status === "hold").sort((a, b) => a.weekResetsAt - b.weekResetsAt)[0];
+    const reset = earliest ? new Date(earliest.weekResetsAt).toISOString() : "the next reset";
+    return { harness: null, reason: `all plans on hold until ${reset}`, alternatives: [], cadence: { parallel: 0, note: "Wait for a plan to renew." } };
+  }
+  const selected = preference.find(([h]) => h === pick.harness);
+  const alternatives = ordered.filter((b) => b.harness !== pick.harness).map((b) => b.harness);
+  const paceText = pick.note ? ` ${pick.note}` : "";
+  return {
+    harness: pick.harness,
+    ...selected?.[1] ? { model: selected[1] } : {},
+    reason: `${pick.harness} is the preferred eligible plan for ${kind}.${paceText}`,
+    alternatives,
+    cadence: { parallel: pick.suggestedParallel ?? 1, note: pick.note ?? "Keep one worker running." }
+  };
+}
 var NEW_PERIOD_MS = 5 * 60000;
 // session-tokens.ts
 function sessionHarness(s) {
@@ -1424,6 +1465,13 @@ function sessionProof(env, readKey = (p) => readFileSync(p, "utf8"), readProc =
   }
 }
 
+// plan-limits-tool.ts
+function planLimitsTool(args, body) {
+  const budgets = body.budgets ?? [];
+  const recommendation = args?.kind ? routeRecommendation(budgets, args.kind, args.authorHarness) : undefined;
+  return { budgets, ...recommendation ? { recommendation } : {}, readAt: body.now ?? Date.now() };
+}
+
 // legacy-analytics.ts
 function legacySummary(data, harness) {
   const unified = !harness || harness === "all";
@@ -2230,6 +2278,18 @@ var TOOLS = [
     description: "Compare the tracked AI coding harnesses side by side. Lists every harness present in the data with its sessions, messages, token usage, estimated cost, and last-active date. Use this to answer 'which harness do I use most / costs most' questions. Rows tagged source \"projections\" (read from the journal) carry personTurns (the person's turns); there `messages` is a deprecated alias of personTurns, and subagent spend is reported apart (subagentTokens, subagentCostUSD).",
     inputSchema: { type: "object", properties: {}, required: [] }
   },
+  {
+    name: "agentistics_plan_limits",
+    description: "Read this BEFORE opening sessions; follow the recommendation; a plan on hold gets no new worker. Returns subscription budgets, pacing, and a routing recommendation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["lead", "hard-bug", "design", "spec-impl", "mechanical", "qa", "probe"] },
+        authorHarness: { type: "string" }
+      },
+      required: []
+    }
+  },
   {
     name: "agentistics_projects",
     description: 'List projects with session counts, message counts, token usage, estimated cost, and last active date. Optionally scope to a single harness. Rows tagged source "projections" (read from the journal) carry personTurns (the person\'s turns); there `messages` is a deprecated alias of personTurns, and subagent spend is reported apart (subagentTokens, subagentCostUSD).',
@@ -2662,6 +2722,9 @@ async function callTool(req) {
           metrics: (q) => fetch(`${API}/api/runtime/metrics?${q}`)
         }));
       }
+      case "agentistics_plan_limits": {
+        return text(planLimitsTool(args ?? {}, await apiGet("/api/plan-limits")));
+      }
       case "agentistics_projects": {
         const harness = args?.harness;
         return text(await analytics("agentistics_projects", harness, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentistics/mcp",
-  "version": "2.125.0",
+  "version": "2.126.0",
   "description": "Agentistics MCP server — Claude Code analytics for Claude Desktop and Claude Code",
   "type": "module",
   "main": "./dist/agentistics-mcp.js",