getprismo 0.1.32 → 0.1.34

package/README.md

@@ -30,18 +30,21 @@ prismodev covers the full AI coding session:
 
 ```
 before you code     npx getprismo doctor
-while you code      npx getprismo watch
+while you code      npx getprismo guard --watch
 noisy commands      npx getprismo shield -- npm test
 after you code      npx getprismo receipt
 postmortem          npx getprismo replay
+workspace agent     npx getprismo agent --watch
 agent-native        npx getprismo mcp
 ```
 
 **doctor** diagnoses the repo, applies safe fixes, and shows the before/after score.
-**watch** monitors context pressure live and warns when things go wrong.
-**receipt** explains what repeated, what output dominated, what artifacts leaked, and what likely influenced the run.
+**guard** runs live guardrails, context throttle, rescue prompts, context firewall, and dashboard-ready prevention events.
+**watch** monitors context pressure live and is the lower-level diagnostic view behind guard.
+**receipt** explains what repeated, what output dominated, what artifacts leaked, what likely influenced the run, and a heuristic context-efficiency score.
 **replay** reconstructs why a session went sideways and prints a recovery prompt.
 **shield** runs noisy commands without dumping full output back into the agent context.
+**agent** connects Prismo Cloud to your local repo so dashboard actions can safely run on this machine.
 **mcp** exposes PrismoDev as local tools so compatible agents can scan, search shield output, and request scoped context directly.
 
 ---
@@ -269,9 +272,54 @@ this is intentionally not magic interception yet. it is a safe local-first primi
 
 ---
 
+## workspace agent
+
+Prismo Cloud can guide the work from the dashboard, but your repo still lives on your machine. `agent` is the local bridge.
+
+```bash
+npx getprismo connect --token <your Prismo API key>
+npx getprismo agent --watch
+```
+
+After that, the Prismo workspace can queue safe actions like `doctor`, `sync`, `guard`, `context`, `optimize`, and allowlisted `shield` commands. The local agent claims those actions, executes them in the selected repo, and reports the status back to Prismo Cloud.
+
+This keeps the product flow simple:
+
+```text
+dashboard recommends fix -> local agent runs safe command -> dashboard refreshes with the result
+```
+
+`agent` does not upload prompts, source code, file contents, stdout, stderr, or full command logs. It uploads action status and safe aggregate metrics. Cloud actions are intentionally limited; arbitrary shell commands and shell metacharacters are rejected.
+
+For CI-style polling or debugging, run one pass:
+
+```bash
+npx getprismo agent --once
+npx getprismo agent --once --json
+```
+
+---
+
 ## new: live guardrails mode
 
-the easiest proactive mode is:
+the easiest proactive mode is guard:
+
+```bash
+npx getprismo connect --token <your Prismo API key>
+npx getprismo guard --watch
+```
+
+`guard` packages the local prevention loop: live guardrails, context throttling, context firewall updates, guard event history, and dashboard-ready prevention events. it never uploads prompts, source code, file contents, stdout, stderr, or full command logs.
+
+run it once for a snapshot:
+
+```bash
+npx getprismo guard
+npx getprismo guard --json
+npx getprismo guard --no-sync
+```
+
+the lower-level watch mode is:
 
 ```bash
 npx getprismo watch --auto
@@ -600,7 +648,7 @@ npx getprismo receipt
 npx getprismo receipt codex --json
 ```
 
-it summarizes repeated reads, generated artifacts, tool-output floods, repeated commands, likely influence, and the next scoped action to take.
+it summarizes repeated reads, generated artifacts, tool-output floods, repeated commands, likely influence, and the next scoped action to take. it also reports a heuristic context-efficiency metric: decision/progress signals per 1k tokens, with drag factors such as repeated reads, artifact leaks, tool-output floods, and command loops.
 
 `replay` is the postmortem view:
 
@@ -623,9 +671,10 @@ it surfaces recurring waste patterns such as the same lockfile leaking into many
 ```bash
 npx getprismo instructions audit
 npx getprismo instructions ablate --dry-run
+npx getprismo instructions apply --dry-run
 ```
 
-it scores rules in `CLAUDE.md`, `AGENTS.md`, `.codex/AGENTS.md`, `.codex/instructions.md`, and `.openai/instructions.md`, then separates observable violations, partial compliance, duplicated rules, trim candidates, and influence-unknown rules. `instructions ablate --dry-run` creates a conservative ablation plan with candidates, sample-count guidance, rollback notes, and variance warnings; it does not edit files.
+it scores rules in `CLAUDE.md`, `AGENTS.md`, `.codex/AGENTS.md`, `.codex/instructions.md`, and `.openai/instructions.md`, then separates observable violations, partial compliance, duplicated rules, trim candidates, and influence-unknown rules. `instructions ablate --dry-run` creates a conservative ablation plan with candidates, sample-count guidance, rollback notes, and variance warnings; it does not edit files. `instructions apply` safely removes exact duplicate instruction lines only, writes backups first, and leaves uncertain rules as recommendations.
 
 `boundaries` checks parallel-agent isolation:
 
@@ -717,11 +766,12 @@ no install needed. npx runs it directly.
 | `cc` | claude code cost breakdown |
 | `cc timeline` | session reconstruction with events |
 | `cursor` | cursor session tracking and ai authorship |
-| `receipt` | run receipt for reads, repeats, output, artifacts, likely influence, and next-run scope |
+| `receipt` | run receipt for reads, repeats, output, artifacts, context efficiency, likely influence, and next-run scope |
 | `replay` | incident replay with root cause and recovery prompt |
 | `timeline` | recurring context-waste patterns across recent sessions |
 | `instructions audit` | instruction ROI audit for CLAUDE.md / AGENTS.md violations, partial compliance, duplicates, and influence-unknown rules |
 | `instructions ablate --dry-run` | conservative ablation plan for instruction candidates without editing files |
+| `instructions apply` | safely dedupe exact duplicate instruction lines with backups |
 | `boundaries` | multi-agent boundary check for shared files/artifacts and worktree overlap |
 | `scan --usage` | full repo scan with local usage data |
 | `scan --optimizer-fit` | recommend which token-optimization path fits your repo/session |
@@ -733,6 +783,7 @@ no install needed. npx runs it directly.
 | `optimize` | generate `.prismo/` context packs |
 | `context` | print paste-ready prompt for agents |
 | `shield` | run noisy commands while keeping full output out of chat |
+| `agent` | claim and execute safe Prismo Cloud workspace actions locally |
 | `mcp` | expose PrismoDev tools over local MCP stdio |
 | `setup` | detect tools, logs, proxy readiness |
 | `usage` | show raw session token usage |
@@ -759,6 +810,14 @@ npx getprismo doctor --json              # machine-readable output
 
 ## watch modes
 
+```bash
+npx getprismo guard                     # proactive local guard snapshot
+npx getprismo guard --watch             # keep guardrails active and sync prevention events
+npx getprismo guard --no-sync           # keep all guard events local
+npx getprismo guard --dry-run           # preview guard actions without writing state
+npx getprismo guard --json              # dashboard-ready guard payload
+```
+
 ```bash
 npx getprismo watch                      # live refresh
 npx getprismo watch --once               # single snapshot
@@ -790,6 +849,17 @@ npx getprismo shield last
 npx getprismo shield search "auth failure"
 ```
 
+### workspace agent mode
+
+```bash
+npx getprismo agent                      # claim queued workspace actions once
+npx getprismo agent --watch              # keep polling Prismo Cloud for safe actions
+npx getprismo agent --interval 15        # poll every 15 seconds
+npx getprismo agent --limit 3            # claim up to 3 actions per poll
+npx getprismo agent --json               # machine-readable action result
+npx getprismo agent /path/to/repo         # run actions against a specific repo
+```
+
 ### mcp mode
 
 ```bash

package/lib/prismo-dev/agent.js

@@ -0,0 +1,399 @@
+module.exports = function createAgent(deps) {
+  const {
+    fs,
+    http,
+    https,
+    path,
+    NPX_COMMAND,
+    PACKAGE_VERSION,
+    loadConfig,
+    runDoctor,
+    runSync,
+    runGuard,
+    runShield,
+    runOptimize,
+  } = deps;
+
+  const DEFAULT_API_URL = "https://api.getprismo.dev";
+  const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+  const SAFE_SHIELD_COMMANDS = new Set(["npm", "pnpm", "yarn", "bun", "npx", "pytest", "python", "python3", "node"]);
+  const VALID_MODES = new Set(["observe", "suggest", "autopilot"]);
+
+  function apiBase(config) {
+    return String(config?.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
+  }
+
+  function requestJson(method, urlValue, token, payload, timeoutMs = 15000) {
+    return new Promise((resolve, reject) => {
+      let parsed;
+      try {
+        parsed = new URL(urlValue);
+      } catch {
+        reject(new Error(`Invalid URL: ${urlValue}`));
+        return;
+      }
+      const body = payload ? JSON.stringify(payload) : null;
+      const client = parsed.protocol === "https:" ? https : http;
+      const request = client.request({
+        method,
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: `${parsed.pathname}${parsed.search}`,
+        timeout: timeoutMs,
+        headers: {
+          "content-type": "application/json",
+          "user-agent": `prismodev-agent/${PACKAGE_VERSION}`,
+          ...(token ? { authorization: `Bearer ${token}` } : {}),
+          ...(body ? { "content-length": Buffer.byteLength(body) } : {}),
+        },
+      }, (response) => {
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          let data = null;
+          try {
+            data = text ? JSON.parse(text) : null;
+          } catch {
+            data = { text };
+          }
+          if (response.statusCode >= 200 && response.statusCode < 300) {
+            resolve({ statusCode: response.statusCode, data });
+          } else {
+            reject(new Error(`HTTP ${response.statusCode}: ${text || response.statusMessage}`));
+          }
+        });
+      });
+      request.on("timeout", () => {
+        request.destroy();
+        reject(new Error("Request timed out"));
+      });
+      request.on("error", reject);
+      if (body) request.write(body);
+      request.end();
+    });
+  }
+
+  function parseCommand(command) {
+    const parts = String(command || "").trim().split(/\s+/).filter(Boolean);
+    const getprismoIndex = parts.findIndex((part) => part === "getprismo" || part === "prismo" || part === "getprismo@latest");
+    const commandIndex = getprismoIndex >= 0 ? getprismoIndex + 1 : 0;
+    return {
+      raw: parts,
+      command: parts[commandIndex] || "",
+      args: parts.slice(commandIndex + 1),
+    };
+  }
+
+  function parseShieldArgs(args) {
+    const separatorIndex = args.indexOf("--");
+    const commandArgs = separatorIndex >= 0 ? args.slice(separatorIndex + 1) : args.slice(1);
+    if (!commandArgs.length) return null;
+    const binary = commandArgs[0];
+    if (!SAFE_SHIELD_COMMANDS.has(binary)) return null;
+    if (commandArgs.some((arg) => /[;&|`$<>]/.test(arg))) return null;
+    return commandArgs;
+  }
+
+  function repoRoot(rootDir, action) {
+    if (action.repo && path.basename(rootDir) !== action.repo) {
+      const sibling = path.join(path.dirname(rootDir), action.repo);
+      if (fs.existsSync(sibling) && fs.statSync(sibling).isDirectory()) return sibling;
+    }
+    return rootDir;
+  }
+
+  async function updateAction(config, actionId, payload, options = {}) {
+    const endpoint = options.endpoint || `${apiBase(config)}/v1/dev/workspace/actions/${actionId}`;
+    const response = await requestJson("PATCH", endpoint, config.token, payload, options.timeoutMs || 15000);
+    return response.data;
+  }
+
+  async function claimActions(config, options = {}) {
+    const limit = Number(options.limit || 5);
+    const endpoint = options.endpoint || `${apiBase(config)}/v1/dev/workspace/actions/claim?limit=${encodeURIComponent(limit)}`;
+    const response = await requestJson("POST", endpoint, config.token, null, options.timeoutMs || 15000);
+    return response.data?.actions || [];
+  }
+
+  async function sendHeartbeat(config, payload = {}, options = {}) {
+    const endpoint = options.heartbeatEndpoint || `${apiBase(config)}/v1/dev/workspace/heartbeat`;
+    const body = {
+      agent: `prismodev/${PACKAGE_VERSION}`,
+      mode: payload.mode || "autopilot",
+      status: payload.status || "online",
+      ...(payload.lastPollAt ? { lastPollAt: payload.lastPollAt } : {}),
+    };
+    const response = await requestJson("POST", endpoint, config.token, body, options.timeoutMs || 10000);
+    return response.data;
+  }
+
+  async function executeAction(action, rootDir, options = {}) {
+    const root = repoRoot(path.resolve(rootDir || process.cwd()), action);
+    const parsed = parseCommand(action.command);
+    const startedAt = new Date().toISOString();
+
+    if (parsed.command === "doctor" || action.actionType === "doctor") {
+      const result = runDoctor(root, { limit: options.limit || 3, applySuggestions: true, json: true });
+      return {
+        status: "completed",
+        statusMessage: "Doctor completed and applied safe ignore/context fixes.",
+        result: {
+          command: "doctor",
+          startedAt,
+          completedAt: new Date().toISOString(),
+          score: result.after?.score ?? result.scan?.score ?? null,
+          generatedFiles: result.generatedFiles || result.optimize?.generatedFiles || [],
+        },
+      };
+    }
+
+    if (parsed.command === "sync" || action.actionType === "sync") {
+      const result = await runSync(root, { limit: options.limit || 20 });
+      return {
+        status: result.synced ? "completed" : "failed",
+        statusMessage: result.synced ? "Sync completed." : "Sync could not run because this machine is not connected.",
+        result: {
+          command: "sync",
+          startedAt,
+          completedAt: new Date().toISOString(),
+          synced: Boolean(result.synced),
+          aggregate: result.aggregate || null,
+          error: result.error || null,
+        },
+      };
+    }
+
+    if (parsed.command === "guard" || action.actionType === "guard") {
+      const result = await runGuard(root, {
+        tool: "all",
+        limit: options.limit || 5,
+        tokenBudget: options.tokenBudget || 600000,
+        noSync: false,
+        watch: false,
+      });
+      return {
+        status: "completed",
+        statusMessage: "Guard snapshot completed. Start agent watch mode for continuous protection.",
+        result: {
+          command: "guard",
+          startedAt,
+          completedAt: new Date().toISOString(),
+          guardRunning: Boolean(result.guardRunning),
+          events: result.events?.length || 0,
+        },
+      };
+    }
+
+    if (parsed.command === "context" || parsed.command === "optimize" || action.actionType === "context") {
+      const scope = parsed.args.find((arg) => !arg.startsWith("-")) || null;
+      const result = runOptimize(root, { scope });
+      return {
+        status: "completed",
+        statusMessage: "Context pack generated.",
+        result: {
+          command: "context",
+          startedAt,
+          completedAt: new Date().toISOString(),
+          scope,
+          generatedFiles: result.generatedFiles || [],
+        },
+      };
+    }
+
+    if (parsed.command === "shield" || action.actionType === "shield") {
+      const commandArgs = parseShieldArgs(parsed.args);
+      if (!commandArgs) {
+        return {
+          status: "failed",
+          statusMessage: "Shield action was rejected because the command is not on the safe allowlist.",
+          result: { command: "shield", rejected: true, reason: "unsafe-shield-command" },
+        };
+      }
+      const result = runShield(root, commandArgs);
+      return {
+        status: result.exitCode === 0 ? "completed" : "failed",
+        statusMessage: result.exitCode === 0 ? "Shielded command completed." : "Shielded command exited with an error.",
+        result: {
+          command: "shield",
+          startedAt,
+          completedAt: new Date().toISOString(),
+          exitCode: result.exitCode,
+          summary: result.summary || null,
+          runDir: result.runDir || null,
+        },
+      };
+    }
+
+    return {
+      status: "failed",
+      statusMessage: `Unsupported workspace action: ${action.actionType || parsed.command || "unknown"}`,
+      result: {
+        rejected: true,
+        reason: "unsupported-action",
+        actionType: action.actionType,
+        command: action.command,
+      },
+    };
+  }
+
+  async function runAgentOnce(rootDir = process.cwd(), options = {}) {
+    const config = loadConfig();
+    if (!config || !config.token) {
+      return {
+        schemaVersion: 1,
+        command: "agent",
+        connected: false,
+        mode: options.mode || "autopilot",
+        actionsClaimed: 0,
+        actionsCompleted: 0,
+        actionsFailed: 0,
+        actionsObserved: 0,
+        error: "not-connected",
+        next: [`${NPX_COMMAND} connect --token <token>`],
+      };
+    }
+
+    const mode = options.mode || "autopilot";
+    const pollTime = new Date().toISOString();
+
+    try {
+      await sendHeartbeat(config, { mode, status: "online", lastPollAt: pollTime }, options);
+    } catch (_) {}
+
+    const actions = await claimActions(config, options);
+    const results = [];
+    for (const action of actions) {
+      if (TERMINAL_STATUSES.has(action.status)) continue;
+
+      if (mode === "observe") {
+        results.push({ id: action.id, label: action.label, status: "observed", statusMessage: "Agent is in observe mode. Action not executed." });
+        continue;
+      }
+
+      if (mode === "suggest") {
+        await updateAction(config, action.id, {
+          status: "pending_approval",
+          statusMessage: "Agent recommends this action. Waiting for approval in workspace.",
+        }, options);
+        results.push({ id: action.id, label: action.label, status: "pending_approval", statusMessage: "Suggested; awaiting approval." });
+        continue;
+      }
+
+      await updateAction(config, action.id, {
+        status: "running",
+        statusMessage: "Running locally through PrismoDev agent.",
+      }, options);
+      const result = await executeAction(action, rootDir, options);
+      await updateAction(config, action.id, result, options);
+      results.push({ id: action.id, label: action.label, ...result });
+    }
+
+    return {
+      schemaVersion: 1,
+      command: "agent",
+      connected: true,
+      mode,
+      apiUrl: apiBase(config),
+      actionsClaimed: actions.length,
+      actionsCompleted: results.filter((item) => item.status === "completed").length,
+      actionsFailed: results.filter((item) => item.status === "failed").length,
+      actionsObserved: results.filter((item) => item.status === "observed" || item.status === "pending_approval").length,
+      results,
+      privacy: {
+        rawPrompts: false,
+        rawCode: false,
+        rawStdout: false,
+        rawStderr: false,
+        fileContents: false,
+      },
+    };
+  }
+
+  function renderAgentTerminal(result) {
+    const lines = [];
+    lines.push("");
+    lines.push("PrismoDev Agent");
+    lines.push("");
+    if (!result.connected) {
+      lines.push("Status: not connected");
+      lines.push(`Mode: ${result.mode || "autopilot"}`);
+      lines.push("");
+      lines.push("Next");
+      result.next.forEach((item, index) => lines.push(`${index + 1}. ${item}`));
+      return lines.join("\n");
+    }
+    lines.push("Status: connected");
+    lines.push(`Mode: ${result.mode}`);
+    lines.push(`API: ${result.apiUrl}`);
+    lines.push(`Actions claimed: ${result.actionsClaimed}`);
+    lines.push(`Completed: ${result.actionsCompleted}`);
+    lines.push(`Failed: ${result.actionsFailed}`);
+    if (result.actionsObserved > 0) {
+      lines.push(`Observed/Suggested: ${result.actionsObserved}`);
+    }
+    if (result.results.length) {
+      lines.push("");
+      lines.push("Actions");
+      result.results.forEach((item) => {
+        lines.push(`- ${item.status}: ${item.label}`);
+        if (item.statusMessage) lines.push(`  ${item.statusMessage}`);
+      });
+    } else {
+      lines.push("");
+      lines.push("No queued workspace actions.");
+    }
+    return lines.join("\n");
+  }
+
+  async function runAgent(rootDir = process.cwd(), options = {}) {
+    if (!options.watch) return runAgentOnce(rootDir, options);
+
+    const intervalMs = Math.max(5, Number(options.interval || 15)) * 1000;
+    let running = true;
+    let sleepResolve = null;
+
+    async function shutdown() {
+      if (!running) return;
+      running = false;
+      if (sleepResolve) sleepResolve();
+      try {
+        const config = loadConfig();
+        if (config?.token) {
+          await sendHeartbeat(config, { mode: options.mode || "autopilot", status: "offline" }, options);
+        }
+      } catch (_) {}
+      if (options.json) console.log(JSON.stringify({ event: "shutdown", status: "offline" }));
+      else console.log("\nAgent going offline.");
+    }
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+
+    while (running) {
+      const result = await runAgentOnce(rootDir, options);
+      if (!running) break;
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else console.log(renderAgentTerminal(result));
+      await new Promise((resolve) => {
+        sleepResolve = resolve;
+        setTimeout(resolve, intervalMs);
+      });
+    }
+
+    process.removeListener("SIGINT", shutdown);
+    process.removeListener("SIGTERM", shutdown);
+  }
+
+  return {
+    claimActions,
+    executeAction,
+    parseCommand,
+    renderAgentTerminal,
+    runAgent,
+    runAgentOnce,
+    sendHeartbeat,
+    updateAction,
+    VALID_MODES,
+  };
+};