getprismo 0.1.53 → 0.1.55

package/lib/prismo-dev/cli.js

@@ -3,7 +3,7 @@ const { printHelp, printCommandHelp } = require("./help");
 
 const VALID_COMMANDS = new Set([
   "dev", "init", "doctor", "firewall", "benchmark", "shield", "mcp",
-  "connect", "sync", "status", "disconnect", "agent", "connector", "setup", "scan", "digest",
+  "connect", "sync", "status", "disconnect", "agent", "connector", "setup", "scan", "digest", "sessions", "report",
   "optimize", "context", "cc", "cursor", "receipt", "instructions",
   "timeline", "replay", "boundaries", "usage", "guard", "watch", "demo", "repair",
   "enforce", "bridge", "hook", "protect",
@@ -69,6 +69,10 @@ function createCli(deps) {
     runDisconnect,
     runStatus,
     runSync,
+    buildSessionsView,
+    renderSessionsTerminal,
+    buildLocalReport,
+    renderLocalReportTerminal,
     renderGuardTerminal,
     runGuard,
     REPAIR_CAUSES,
@@ -474,6 +478,34 @@ function createCli(deps) {
       return;
     }
 
+    if (command === "sessions") {
+      const json = rest.includes("--json");
+      const limitIndex = rest.indexOf("--limit");
+      const toolIndex = rest.indexOf("--tool");
+      const target = getPositionals(rest, new Set(["--limit", "--tool"]))[0] || process.cwd();
+      const view = buildSessionsView(target, {
+        limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 10),
+        tool: toolIndex >= 0 ? rest[toolIndex + 1] : "all",
+        allRepos: rest.includes("--all-repos"),
+      });
+      if (json) console.log(JSON.stringify(view, null, 2));
+      else console.log(renderSessionsTerminal(view));
+      return;
+    }
+
+    if (command === "report") {
+      const json = rest.includes("--json");
+      const limitIndex = rest.indexOf("--limit");
+      const target = getPositionals(rest, new Set(["--limit"]))[0] || process.cwd();
+      const report = buildLocalReport(target, {
+        limit: parsePositiveInt(limitIndex >= 0 ? rest[limitIndex + 1] : null, 10),
+        allRepos: rest.includes("--all-repos"),
+      });
+      if (json) console.log(JSON.stringify(report, null, 2));
+      else console.log(renderLocalReportTerminal(report));
+      return;
+    }
+
     if (command === "digest") {
       const json = rest.includes("--json");
       const daysIndex = rest.indexOf("--days");

package/lib/prismo-dev/help.js

@@ -17,6 +17,8 @@ Usage:
   prismo bridge [--json] [path]
   prismo sync [--json] [--dry-run] [--watch] [--all-repos] [--interval N] [--limit N] [--tool all|codex|claude|cursor] [path]
   prismo status [--json]
+  prismo sessions [--json] [--all-repos] [--limit N] [--tool all|codex|claude|cursor] [path]
+  prismo report [--json] [--all-repos] [--limit N] [path]
   prismo digest [--json] [--days N]
   prismo disconnect [--json]
   prismo agent [--json] [--once] [--watch] [--interval N] [--sync-interval N] [--limit N] [--mode MODE] [path]
@@ -54,6 +56,8 @@ Commands:
   bridge     Explain optional agent bridge mode and live interception levels.
   sync        Send safe aggregate local agent telemetry to Prismo; use --watch for background-style sync.
   status      Show local PrismoDev connection and last sync state.
+  sessions    List recent local agent sessions with tokens, waste, risk, and top cause (add --all-repos for every repo).
+  report      Local waste snapshot: observed/wasted tokens, top causes, repeated reads/commands, and the next action. No connection needed.
   digest      Print the launch report: verified saved tokens/dollars first, with live prevention labeled estimated.
   disconnect  Remove the local PrismoDev cloud connection.
   agent       Claim and execute safe workspace actions queued from Prismo Cloud.
@@ -475,9 +479,13 @@ Tools exposed:
   prismo_firewall
   prismo_cc_timeline
   prismo_cursor_sessions
+  prismo_should_shield   (agent-native: should I shield this command?)
+  prismo_loop_check      (agent-native: am I looping?)
+  prismo_context_guard   (agent-native: what repo am I in / what to avoid rereading?)
 
 Output:
   Starts a local JSON-RPC MCP server over stdio. Use it from MCP-compatible clients so agents can scan context waste, search shielded command output, and request scoped context without loading huge logs into chat.
+  The agent-native tools answer single mid-session questions directly so Claude Code, Codex, and Cursor can call Prismo while they work, not just after.
 
   prismo mcp doctor validates the local MCP tool surface and prints a ready-to-use client config snippet.`,
   connect: `PrismoDev Connect

package/lib/prismo-dev/mcp.js

@@ -1,3 +1,40 @@
+const path = require("path");
+
+// Commands whose output reliably floods agent context and should run through
+// shield (full output to disk, compact summary to the model).
+const NOISY_COMMAND_PATTERNS = [
+  { re: /(^|\s)(jest|vitest|mocha|pytest|rspec|phpunit|ava|tap)(\s|$)|(\b(npm|yarn|pnpm|bun)\s+(run\s+)?test\b)|\b(go|cargo)\s+test\b/, why: "test runs emit large pass/fail output" },
+  { re: /(^|\s)(webpack|rollup|esbuild|vite|tsc)(\s|$)|\b(next|nuxt|astro)\s+build\b|\b(npm|yarn|pnpm|bun)\s+(run\s+)?build\b|\b(go|cargo)\s+build\b|(^|\s)make(\s|$)/, why: "builds emit long compiler/bundler output" },
+  { re: /\b(npm|pnpm|bun)\s+(install|ci|i)\b|\byarn(\s+install)?\b|\bpip\s+install\b|\bbundle\s+install\b/, why: "installs print large dependency trees" },
+  { re: /(^|\s)(eslint|ruff|flake8|mypy|pylint)(\s|$)|\b(npm|yarn|pnpm)\s+(run\s+)?lint\b|tsc\s+--noEmit/, why: "linters/type-checkers emit many diagnostics" },
+  { re: /\b(playwright|cypress|e2e)\b/, why: "e2e runs dump verbose logs" },
+  { re: /\bdocker\s+build\b|\bterraform\b|\bkubectl\s+logs\b|\bcoverage\b|--verbose\b/, why: "infra/coverage/verbose commands flood output" },
+];
+const QUICK_COMMAND_PATTERNS = [
+  /(^|\s)(git\s+(status|log|diff|branch|show)|ls|pwd|whoami|which|echo|cat|head|tail|wc|env|date|node\s+-v|--version)(\s|$)/,
+];
+
+function classifyCommandForShield(command, repeatedCommands = []) {
+  const cmd = String(command || "").trim();
+  if (!cmd) return { shouldShield: false, confidence: "low", reason: "No command provided." };
+  const normalized = cmd.replace(/\s+/g, " ");
+  const repeated = (repeatedCommands || []).some((item) => {
+    const value = String(item.value || "").replace(/\s+/g, " ");
+    return value && (normalized.includes(value) || value.includes(normalized)) && Number(item.count || 0) >= 3;
+  });
+  if (repeated) {
+    return { shouldShield: true, confidence: "high", reason: "This command has already repeated several times in recent sessions; shield it so each retry costs a summary, not full output." };
+  }
+  const noisy = NOISY_COMMAND_PATTERNS.find((entry) => entry.re.test(normalized));
+  if (noisy) {
+    return { shouldShield: true, confidence: "high", reason: `Shield recommended: ${noisy.why}.` };
+  }
+  if (QUICK_COMMAND_PATTERNS.some((re) => re.test(normalized))) {
+    return { shouldShield: false, confidence: "high", reason: "Quick, low-output command; shielding is unnecessary." };
+  }
+  return { shouldShield: false, confidence: "low", reason: "No known flooding pattern; shield only if you expect large output." };
+}
+
 function createTextResult(payload) {
   const text = typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
   return {
@@ -147,6 +184,20 @@ function createMcpTools(deps) {
       tool: { type: "string", enum: ["all", "codex", "claude", "cursor"], description: "Which local session logs to inspect." },
       limit: limitProperty,
     }),
+    // Agent-native, mid-loop decision tools: tight yes/no answers an agent can
+    // act on during a session, not analysis dumps.
+    makeTool("prismo_should_shield", "Decide whether a shell command should be run through Prismo shield (full output to disk, compact summary to context) before you run it. Call this before any command that might print a lot.", {
+      command: { type: "string", description: "The exact shell command you are about to run." },
+      path: pathProperty,
+    }, ["command"]),
+    makeTool("prismo_loop_check", "Check whether the current coding session is stuck in a loop (repeating the same command or failing repeatedly). Call this when you have retried something more than once.", {
+      path: pathProperty,
+      tool: { type: "string", enum: ["all", "codex", "claude", "cursor"], description: "Which local session logs to inspect." },
+    }),
+    makeTool("prismo_context_guard", "Get what repo you are in, which paths to avoid rereading, files you have already read repeatedly, and the compact context pack to start from. Call this at the start of a session or before broad exploration.", {
+      path: pathProperty,
+      scope: scopeProperty,
+    }),
   ];
 
   function resolveRoot(args) {
@@ -292,6 +343,75 @@ function createMcpTools(deps) {
       }));
     }
 
+    if (name === "prismo_should_shield") {
+      let repeatedCommands = [];
+      try {
+        const summary = getUsageSummary({ cwd: target, limit: 3, tool: "all" });
+        const latest = (summary.sessions || [])[0];
+        repeatedCommands = (latest && latest.repeatedCommands) || [];
+      } catch { /* command classification still works without session context */ }
+      const decision = classifyCommandForShield(args.command, repeatedCommands);
+      return createTextResult({
+        schemaVersion: 1,
+        command: args.command,
+        shouldShield: decision.shouldShield,
+        confidence: decision.confidence,
+        reason: decision.reason,
+        recommended: decision.shouldShield
+          ? `npx -y getprismo@latest shield -- ${String(args.command || "").trim()}`
+          : null,
+        note: "Shield stores full stdout/stderr locally and returns a compact summary, so the output never floods context.",
+      });
+    }
+
+    if (name === "prismo_loop_check") {
+      const summary = getUsageSummary({ cwd: target, limit: 3, tool: args.tool || "all" });
+      const latest = (summary.sessions || [])[0] || null;
+      const repeatedCommands = (latest && latest.repeatedCommands) || [];
+      const looping = Boolean(latest && latest.loopSuspicion) || repeatedCommands.some((c) => Number(c.count || 0) >= 4);
+      const topRepeat = repeatedCommands[0] || null;
+      return createTextResult({
+        schemaVersion: 1,
+        looping,
+        confidence: latest ? (latest.loopConfidence || (looping ? "medium" : "low")) : "low",
+        signals: {
+          repeatedCommands: repeatedCommands.slice(0, 5),
+          failureMentions: latest ? Number(latest.failureMentions || 0) : 0,
+          turns: latest ? Number(latest.turns || 0) : 0,
+        },
+        advice: looping
+          ? `You appear to be looping${topRepeat ? ` on \`${topRepeat.value}\` (${topRepeat.count}x)` : ""}. Stop retrying, change the approach, and capture the command once with \`npx -y getprismo@latest shield -- <command>\` instead of re-running it.`
+          : "No loop detected. Keep going.",
+      });
+    }
+
+    if (name === "prismo_context_guard") {
+      const scope = args.scope || null;
+      const scan = scanRepo(target, { includeUsage: true, usageLimit: 3 });
+      const ctx = createOptimizeContext(target, scope);
+      const usage = scan.realUsage && scan.realUsage.sessions ? scan.realUsage.sessions : [];
+      const repeatedlyRead = [];
+      for (const session of usage) {
+        for (const item of session.repeatedPathMentions || []) {
+          if (Number(item.count || 0) >= 4) repeatedlyRead.push({ path: item.value, reads: item.count });
+        }
+      }
+      const blocked = (scan.recommendedClaudeIgnore || []).slice(0, 24);
+      return createTextResult({
+        schemaVersion: 1,
+        repo: path.basename(path.resolve(target)),
+        avoidRereading: {
+          blockedContext: blocked,
+          alreadyReadRepeatedly: repeatedlyRead.slice(0, 12),
+        },
+        startFrom: {
+          contextFile: scope ? `.prismo/${scope}-summary.md` : ".prismo/architecture-summary.md",
+          starterPrompt: renderStarterPrompt(ctx, scope),
+        },
+        advice: "Read the start-from context pack first. Do not reread blocked paths or files you have already read several times; quote what you already saw instead.",
+      });
+    }
+
     throw new Error(`Unknown MCP tool: ${name}`);
   }
 
@@ -397,6 +517,9 @@ async function runMcpDoctor(deps) {
     "prismo_timeline",
     "prismo_replay",
     "prismo_boundaries",
+    "prismo_should_shield",
+    "prismo_loop_check",
+    "prismo_context_guard",
   ];
   const toolNames = tools.map((tool) => tool.name);
   const missingTools = requiredTools.filter((name) => !toolNames.includes(name));

package/lib/prismo-dev/sessions-report.js

@@ -0,0 +1,196 @@
+module.exports = function createSessionsReport(deps) {
+  const {
+    path,
+    getUsageSummary,
+    estimateWaste,
+    formatTokenCount,
+  } = deps;
+
+  const CAUSE_LABELS = {
+    "tool-output-flood": "Tool-output floods",
+    "repeated-file-reads": "Repeated file reads",
+    "generated-artifacts": "Generated artifacts",
+    "context-loop": "Context loops",
+    "long-session-buildup": "Long-session buildup",
+    "low-signal": "No strong waste signal",
+  };
+
+  const NEXT_ACTION = {
+    "tool-output-flood": "Run noisy commands through `prismo shield -- <command>` so output stays out of context.",
+    "repeated-file-reads": "Run `prismo repair repeated-file-reads`, then start sessions from .prismo context packs.",
+    "generated-artifacts": "Run `prismo repair generated-artifacts` to ignore build output and artifacts.",
+    "context-loop": "Run `prismo repair context-loop` and stop retrying failing commands.",
+    "long-session-buildup": "Split work at task boundaries; start fresh sessions from `prismo context`.",
+    "low-signal": "Nothing urgent. Run `prismo doctor` for a baseline.",
+  };
+
+  function repoBasename(session, fallbackRoot) {
+    const cwd = session && session.cwd ? session.cwd : fallbackRoot;
+    try {
+      return path.basename(path.resolve(cwd || process.cwd()));
+    } catch {
+      return "unknown";
+    }
+  }
+
+  function collect(rootDir, options = {}) {
+    const root = path.resolve(rootDir || process.cwd());
+    const summary = getUsageSummary({
+      cwd: root,
+      tool: options.tool || "all",
+      limit: options.limit || 10,
+      allRepos: Boolean(options.allRepos),
+    });
+    const sessions = (summary.sessions || []).map((session) => {
+      const waste = estimateWaste(session);
+      return {
+        tool: session.tool || "unknown",
+        repo: repoBasename(session, root),
+        title: session.title || null,
+        model: session.model || null,
+        updatedAt: session.updatedAt || session.startedAt || null,
+        risk: session.contextRisk || "Unknown",
+        tokens: Number(waste.tokens || 0),
+        wastedTokens: Number(waste.wastedTokens || 0),
+        wastePercent: Number(waste.wastePercent || 0),
+        topCause: waste.topCause || "low-signal",
+        repeatedCommands: session.repeatedCommands || [],
+        repeatedPaths: session.repeatedPathMentions || [],
+        loopSuspicion: Boolean(session.loopSuspicion),
+      };
+    });
+    return { root, sessions, generatedAt: new Date().toISOString() };
+  }
+
+  function buildSessionsView(rootDir, options = {}) {
+    const { root, sessions, generatedAt } = collect(rootDir, options);
+    const totals = sessions.reduce((acc, s) => {
+      acc.sessions += 1;
+      acc.tokens += s.tokens;
+      acc.wastedTokens += s.wastedTokens;
+      return acc;
+    }, { sessions: 0, tokens: 0, wastedTokens: 0 });
+    totals.wastePercent = totals.tokens > 0 ? Math.round((totals.wastedTokens / totals.tokens) * 100) : 0;
+    return {
+      schemaVersion: 1,
+      command: "sessions",
+      scannedPath: root,
+      allRepos: Boolean(options.allRepos),
+      sessions: sessions.sort((a, b) => String(b.updatedAt || "").localeCompare(String(a.updatedAt || ""))),
+      totals,
+      generatedAt,
+    };
+  }
+
+  function renderSessionsTerminal(view) {
+    const lines = [];
+    lines.push("");
+    lines.push("PrismoDev Sessions");
+    lines.push("");
+    if (!view.sessions.length) {
+      lines.push("No recent local agent sessions found.");
+      lines.push(view.allRepos ? "" : "Tip: add --all-repos to look across every repo on this machine.");
+      return lines.join("\n").trimEnd();
+    }
+    for (const s of view.sessions) {
+      const when = s.updatedAt ? new Date(s.updatedAt).toLocaleString() : "unknown time";
+      lines.push(`${s.tool.padEnd(12)} ${s.repo}  ·  ${when}`);
+      lines.push(`  ${formatTokenCount(s.tokens)} tokens  |  ~${formatTokenCount(s.wastedTokens)} wasted (${s.wastePercent}%)  |  ${s.risk} risk  |  ${CAUSE_LABELS[s.topCause] || s.topCause}`);
+    }
+    lines.push("");
+    lines.push(`Totals: ${view.totals.sessions} session(s)  ·  ${formatTokenCount(view.totals.tokens)} tokens  ·  ~${formatTokenCount(view.totals.wastedTokens)} likely wasted (${view.totals.wastePercent}%)`);
+    return lines.join("\n");
+  }
+
+  function buildLocalReport(rootDir, options = {}) {
+    const { root, sessions, generatedAt } = collect(rootDir, { ...options, allRepos: options.allRepos });
+    const observed = sessions.reduce((sum, s) => sum + s.tokens, 0);
+    const wasted = sessions.reduce((sum, s) => sum + s.wastedTokens, 0);
+
+    const causeTotals = new Map();
+    for (const s of sessions) {
+      if (s.topCause === "low-signal") continue;
+      causeTotals.set(s.topCause, (causeTotals.get(s.topCause) || 0) + s.wastedTokens);
+    }
+    const topCauses = Array.from(causeTotals, ([cause, tokens]) => ({
+      cause,
+      label: CAUSE_LABELS[cause] || cause,
+      tokens,
+    })).sort((a, b) => b.tokens - a.tokens).slice(0, 5);
+
+    const repeatedReads = aggregate(sessions, (s) => s.repeatedPaths).slice(0, 5);
+    const repeatedCommands = aggregate(sessions, (s) => s.repeatedCommands).slice(0, 5);
+    const loopSessions = sessions.filter((s) => s.loopSuspicion).length;
+    const primaryCause = topCauses[0] ? topCauses[0].cause : "low-signal";
+
+    return {
+      schemaVersion: 1,
+      command: "report",
+      scannedPath: root,
+      allRepos: Boolean(options.allRepos),
+      sessions: sessions.length,
+      observedTokens: observed,
+      wastedTokens: wasted,
+      wastePercent: observed > 0 ? Math.round((wasted / observed) * 100) : 0,
+      topCauses,
+      repeatedReads,
+      repeatedCommands,
+      loopSessions,
+      nextAction: NEXT_ACTION[primaryCause] || NEXT_ACTION["low-signal"],
+      note: "Local estimate from your own session logs. Connect with `prismo connect` for verified, dollar-denominated savings.",
+      generatedAt,
+    };
+  }
+
+  function aggregate(sessions, pick) {
+    const totals = new Map();
+    for (const s of sessions) {
+      for (const item of pick(s) || []) {
+        if (!item || !item.value) continue;
+        totals.set(item.value, (totals.get(item.value) || 0) + Number(item.count || 0));
+      }
+    }
+    return Array.from(totals, ([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count);
+  }
+
+  function renderLocalReportTerminal(report) {
+    const lines = [];
+    lines.push("");
+    lines.push("PrismoDev Report");
+    lines.push("");
+    if (!report.sessions) {
+      lines.push("No recent local agent sessions found.");
+      lines.push(report.allRepos ? "" : "Tip: add --all-repos to look across every repo on this machine.");
+      return lines.join("\n").trimEnd();
+    }
+    lines.push(`Observed: ${formatTokenCount(report.observedTokens)} tokens across ${report.sessions} session(s)`);
+    lines.push(`Likely wasted: ${formatTokenCount(report.wastedTokens)} (${report.wastePercent}%)`);
+    if (report.loopSessions) lines.push(`Loop-suspect sessions: ${report.loopSessions}`);
+    if (report.topCauses.length) {
+      lines.push("");
+      lines.push("Top causes:");
+      report.topCauses.forEach((c) => lines.push(`- ${c.label}: ~${formatTokenCount(c.tokens)} tokens`));
+    }
+    if (report.repeatedReads.length) {
+      lines.push("");
+      lines.push("Most repeated reads:");
+      report.repeatedReads.forEach((r) => lines.push(`- ${r.value} (${r.count}x)`));
+    }
+    if (report.repeatedCommands.length) {
+      lines.push("");
+      lines.push("Most repeated commands:");
+      report.repeatedCommands.forEach((r) => lines.push(`- ${r.value} (${r.count}x)`));
+    }
+    lines.push("");
+    lines.push(`Next: ${report.nextAction}`);
+    lines.push(report.note);
+    return lines.join("\n");
+  }
+
+  return {
+    buildSessionsView,
+    renderSessionsTerminal,
+    buildLocalReport,
+    renderLocalReportTerminal,
+  };
+};

package/lib/prismo-dev-scan.js

@@ -355,6 +355,18 @@ const {
   runFirewall,
 });
 
+const {
+  buildSessionsView,
+  renderSessionsTerminal,
+  buildLocalReport,
+  renderLocalReportTerminal,
+} = require("./prismo-dev/sessions-report")({
+  path,
+  getUsageSummary,
+  estimateWaste,
+  formatTokenCount,
+});
+
 const repairPlanner = require("./prismo-dev/repair-planner")({
   fs,
   path,
@@ -510,6 +522,10 @@ const { runCli } = require("./prismo-dev/cli")({
   runDisconnect,
   runStatus,
   runSync,
+  buildSessionsView,
+  renderSessionsTerminal,
+  buildLocalReport,
+  renderLocalReportTerminal,
   renderGuardTerminal,
   runGuard,
   REPAIR_CAUSES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getprismo",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "Local AI coding workflow scanner for Codex, Claude Code, Cursor, and token-waste diagnostics.",
   "license": "MIT",
   "homepage": "https://github.com/shanirsh/prismodev#readme",