@lasso-ai/cli 1.5.0 → 2.0.0

package/dist/runtime/workspace-guard.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * Workspace Guard - Capture, diff, and roll back project state.
+ *
+ * Lasso's non-negotiable review workflow requires:
+ *   1. Capture the original project state before an agent runs.
+ *   2. Collect resulting file changes after the agent runs.
+ *   3. Roll back to the original state so nothing is applied before review.
+ *   4. On approval, re-apply the changes; on rejection, leave the project untouched.
+ *
+ * The guard backs up every non-ignored file (in memory, or on disk for
+ * oversized files), computes a normalized diff against the captured state,
+ * and can restore the workspace exactly (content + permission bits + deletions).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceGuard = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const DEFAULT_IGNORE_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".hg",
+    ".svn",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".svelte-kit",
+    ".turbo",
+    ".parcel-cache",
+    ".cache",
+    ".vercel",
+    ".netlify",
+    ".lasso",
+    ".yarn",
+    ".pnpm-store",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "target",
+    ".gradle",
+    ".terraform",
+]);
+function hashBuffer(buf) {
+    return node_crypto_1.default.createHash("sha256").update(buf).digest("hex");
+}
+function looksBinary(buf) {
+    const sample = buf.subarray(0, Math.min(buf.length, 8192));
+    return sample.includes(0);
+}
+class WorkspaceGuard {
+    root;
+    files = new Map();
+    skipped = [];
+    tempDir;
+    ignoreDirs;
+    ignoreFn;
+    tempDirCreated = false;
+    disposed = false;
+    constructor(root, ignoreDirs, ignoreFn) {
+        this.root = root;
+        this.ignoreDirs = ignoreDirs;
+        this.ignoreFn = ignoreFn;
+        this.tempDir = node_path_1.default.join(node_os_1.default.tmpdir(), `lasso-guard-${node_crypto_1.default.randomBytes(6).toString("hex")}`);
+    }
+    /**
+     * Capture the full current state of the workspace.
+     */
+    static async capture(projectPath, options = {}) {
+        const root = node_path_1.default.resolve(projectPath);
+        if (!node_fs_1.default.existsSync(root) || !node_fs_1.default.statSync(root).isDirectory()) {
+            throw new Error(`Project path does not exist or is not a directory: ${root}`);
+        }
+        const ignoreDirs = new Set([...DEFAULT_IGNORE_DIRS, ...(options.ignoreDirs || [])]);
+        const maxMemory = options.maxMemoryFileSize ?? 4 * 1024 * 1024;
+        const maxDepth = options.maxDepth ?? 32;
+        const ignoreFn = options.ignore;
+        const guard = new WorkspaceGuard(root, ignoreDirs, ignoreFn);
+        const walk = (dir, relBase, depth) => {
+            if (depth > maxDepth)
+                return;
+            let entries;
+            try {
+                entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const relPath = relBase ? node_path_1.default.join(relBase, entry.name) : entry.name;
+                const absPath = node_path_1.default.join(dir, entry.name);
+                if (entry.isSymbolicLink()) {
+                    guard.skipped.push(relPath);
+                    continue;
+                }
+                const isDir = entry.isDirectory();
+                if (isDir && ignoreDirs.has(entry.name))
+                    continue;
+                if (ignoreFn && ignoreFn(relPath, isDir))
+                    continue;
+                if (isDir) {
+                    walk(absPath, relPath, depth + 1);
+                    continue;
+                }
+                if (!entry.isFile()) {
+                    guard.skipped.push(relPath);
+                    continue;
+                }
+                try {
+                    const stat = node_fs_1.default.statSync(absPath);
+                    let content = node_fs_1.default.readFileSync(absPath);
+                    let tempPath;
+                    if (content.length > maxMemory) {
+                        // Oversized: keep a disk copy so rollback stays possible without holding it in RAM.
+                        guard.ensureTempDir();
+                        tempPath = node_path_1.default.join(guard.tempDir, relPath);
+                        node_fs_1.default.mkdirSync(node_path_1.default.dirname(tempPath), { recursive: true });
+                        node_fs_1.default.copyFileSync(absPath, tempPath);
+                        content = null;
+                    }
+                    guard.files.set(relPath, {
+                        absPath,
+                        content,
+                        tempPath,
+                        hash: hashBuffer(node_fs_1.default.readFileSync(absPath)),
+                        size: stat.size,
+                        mode: stat.mode,
+                        binary: content ? looksBinary(content) : false,
+                    });
+                }
+                catch {
+                    guard.skipped.push(relPath);
+                }
+            }
+        };
+        walk(root, "", 0);
+        return guard;
+    }
+    /** Number of files captured (excludes ignored/skipped entries). */
+    get fileCount() {
+        return this.files.size;
+    }
+    /** Paths that could not be captured (symlinks, unreadable entries). */
+    get skippedPaths() {
+        return [...this.skipped];
+    }
+    /**
+     * Compare the current on-disk state against the captured state.
+     * Must be called BEFORE restore() when collecting an agent's changes.
+     */
+    diff() {
+        const changes = [];
+        const seen = new Set();
+        for (const [relPath, entry] of this.files) {
+            seen.add(relPath);
+            let stat = null;
+            try {
+                stat = node_fs_1.default.statSync(entry.absPath);
+            }
+            catch {
+                stat = null;
+            }
+            if (!stat || !stat.isFile()) {
+                changes.push({ filePath: relPath, operation: "deleted", oldContent: entry.binary ? undefined : entry.content?.toString("utf8") });
+                continue;
+            }
+            let current;
+            try {
+                current = node_fs_1.default.readFileSync(entry.absPath);
+            }
+            catch {
+                continue;
+            }
+            if (hashBuffer(current) === entry.hash)
+                continue;
+            if (entry.binary || looksBinary(current)) {
+                changes.push({ filePath: relPath, operation: "modified", binary: true });
+            }
+            else {
+                changes.push({
+                    filePath: relPath,
+                    operation: "modified",
+                    oldContent: entry.content ? entry.content.toString("utf8") : undefined,
+                    newContent: current.toString("utf8"),
+                });
+            }
+        }
+        // Files that did not exist at capture time.
+        for (const change of this.listNewFiles(seen)) {
+            changes.push(change);
+        }
+        return changes;
+    }
+    /**
+     * Restore the workspace to the captured state:
+     * modified files are reverted, created files are deleted, deleted files are recreated.
+     */
+    async restore() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const [relPath, entry] of this.files) {
+            let currentExists = false;
+            try {
+                currentExists = node_fs_1.default.statSync(entry.absPath).isFile();
+            }
+            catch {
+                currentExists = false;
+            }
+            const desired = entry.content ?? (entry.tempPath ? node_fs_1.default.readFileSync(entry.tempPath) : null);
+            if (!desired)
+                continue;
+            try {
+                if (currentExists) {
+                    const current = node_fs_1.default.readFileSync(entry.absPath);
+                    if (hashBuffer(current) === hashBuffer(desired)) {
+                        // Unchanged — still normalize permissions below.
+                        node_fs_1.default.chmodSync(entry.absPath, entry.mode);
+                        continue;
+                    }
+                }
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(entry.absPath), { recursive: true });
+                node_fs_1.default.writeFileSync(entry.absPath, desired);
+                node_fs_1.default.chmodSync(entry.absPath, entry.mode);
+            }
+            catch {
+                // Best effort: continue restoring remaining files.
+            }
+        }
+        // Delete files created during execution.
+        for (const change of this.listNewFiles(new Set(this.files.keys()))) {
+            try {
+                node_fs_1.default.unlinkSync(node_path_1.default.join(this.root, change.filePath));
+            }
+            catch {
+                // Ignore — file may already be gone.
+            }
+        }
+        this.cleanupTemp();
+    }
+    /** Restore without comparing (used by dispose paths). */
+    async dispose() {
+        if (!this.disposed) {
+            await this.restore();
+        }
+        else {
+            this.cleanupTemp();
+        }
+    }
+    listNewFiles(capturedPaths) {
+        const created = [];
+        const walk = (dir, relBase, depth) => {
+            if (depth > 40)
+                return;
+            let entries;
+            try {
+                entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const relPath = relBase ? node_path_1.default.join(relBase, entry.name) : entry.name;
+                const absPath = node_path_1.default.join(dir, entry.name);
+                if (entry.isSymbolicLink())
+                    continue;
+                if (entry.isDirectory()) {
+                    if (this.ignoreDirs.has(entry.name))
+                        continue;
+                    walk(absPath, relPath, depth + 1);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (this.ignoreFn && this.ignoreFn(relPath, false))
+                    continue;
+                if (capturedPaths.has(relPath))
+                    continue;
+                let binary = false;
+                let content;
+                try {
+                    const buf = node_fs_1.default.readFileSync(absPath);
+                    binary = looksBinary(buf);
+                    content = binary ? undefined : buf.toString("utf8");
+                }
+                catch {
+                    continue;
+                }
+                created.push(binary ? { filePath: relPath, operation: "created", binary: true } : { filePath: relPath, operation: "created", newContent: content });
+            }
+        };
+        walk(this.root, "", 0);
+        return created;
+    }
+    ensureTempDir() {
+        if (this.tempDirCreated)
+            return;
+        node_fs_1.default.mkdirSync(this.tempDir, { recursive: true });
+        this.tempDirCreated = true;
+    }
+    cleanupTemp() {
+        if (!this.tempDirCreated)
+            return;
+        try {
+            node_fs_1.default.rmSync(this.tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Temp cleanup is best effort.
+        }
+        this.tempDirCreated = false;
+    }
+}
+exports.WorkspaceGuard = WorkspaceGuard;

package/docs/local-coding-agents.md

@@ -0,0 +1,183 @@
+# Local Coding Agents
+
+Lasso can drive local coding agents — Claude Code, OpenCode, Codex CLI, and
+Cursor Agent — with the same session management, progress events, review flow,
+verification, and corrective runs as hosted models. Local agents run
+headlessly against your project, but **nothing is applied until you review and
+approve the diff**.
+
+## How it works
+
+Local agents execute **on your machine, inside the `lasso` CLI process**
+(`LocalRuntime`). Prompts, project context, and source code never travel
+through Lasso's server — you can point the CLI at any server URL (or none)
+and local agents keep working. Hosted models are unchanged: they still run
+server-side through the Lasso runtime API and the Model Gateway.
+
+Local agent lifecycle:
+
+1. Before an agent runs, the CLI captures your workspace (a `WorkspaceGuard`
+   snapshot of every non-ignored file).
+2. The agent's CLI is spawned in your project directory and its structured
+   output is normalized into runtime events (progress, tool calls, file
+   operations, completion).
+3. After the run — success **or** failure — the workspace is rolled back to
+   the captured state. The guard's diff becomes the reviewable change set.
+4. Approving a change re-applies it; discarding leaves the project untouched.
+5. After apply, Lasso runs verification (typecheck/build, when configured).
+   Failures are fed back for an automatic corrective run (bounded attempts).
+
+Because the agent writes into the real project directory, the guard's diff is
+the single source of truth for what changed — agent-reported file lists are
+never trusted on their own.
+
+## Installation
+
+Local agents are detected per-machine by the CLI. Install only the ones you want:
+
+| Agent | Provider id | Install |
+| --- | --- | --- |
+| Claude Code | `claude_code` | `npm install -g @anthropic-ai/claude-code` |
+| OpenCode | `opencode` | `npm install -g opencode-ai` |
+| Codex CLI | `codex_cli` | `npm install -g @openai/codex` |
+| Cursor Agent | `cursor` | `curl https://cursor.com/install -fsS \| bash` |
+
+The binary names the CLI probes: `claude`, `opencode`, `codex`, `cursor-agent`
+(Cursor's CLI is `cursor-agent`, not `cursor`).
+
+## Authentication
+
+Each agent is authenticated with its own login flow. Lasso only *reads*
+authentication state via each agent's structured status command:
+
+- **Claude Code** — `claude auth status` (JSON `loggedIn`). Login: run `claude`
+  once and complete the flow, or `claude auth login`.
+- **OpenCode** — `opencode providers list` (stored credentials marker). Login:
+  `opencode auth login` or configure a provider API key.
+- **Codex CLI** — `codex login status` (exit code). Login: `codex login`
+  (ChatGPT account or API key).
+- **Cursor Agent** — `cursor-agent status --format json` (JSON
+  `isAuthenticated`). Login: `cursor-agent login`.
+
+An agent that is installed but not authenticated stays visible in the model
+menu as **locked**, with the fix instructions shown inline.
+
+Account limits (for example Claude "credit balance is too low" or Codex "usage
+limit") are surfaced as authentication-class failures with a clear message —
+they are not treated as code errors.
+
+## Model selection
+
+Model option ids are prefixed with the provider (`claude_code:sonnet`,
+`opencode:big-pickle`, …). The CLI normalizes them for each agent:
+
+- `claude_code:sonnet` → `sonnet` (also `opus`, `haiku`)
+- `opencode:<name>` → `opencode/<name>` (lists real models via `opencode models`
+  when available)
+- `codex_cli:default` → empty (the agent's own configured default model)
+- `cursor:<id>` → passed through (e.g. `sonnet-4`)
+
+An empty `modelId` means "use the agent's default".
+
+## Configuration
+
+Local agents are selected via the backend config attached to a runtime session.
+The CLI bridge builds this automatically from the overlay's model menu:
+
+```ts
+{
+  type: "local_agent",
+  provider: "claude_code" | "opencode" | "codex_cli" | "cursor",
+  modelId: string,        // normalized id, "" = agent default
+  projectPath: string,    // must be the project root
+  permissionMode?: string // claude only, default "acceptEdits"
+}
+```
+
+For programmatic use, `LocalRuntime` (from `@lasso-ai/cli`) implements the
+same session surface as `RuntimeClient` — `createSession`, `runSession`,
+`getSession`, `verifySession`, `switchModel`, `cancelSession` — but executes
+in-process:
+
+```ts
+import { getLocalRuntime } from "@lasso-ai/cli/local-runtime";
+
+const runtime = getLocalRuntime();
+const session = await runtime.createSession({
+  userPrompt: "Add a loading state to the submit button",
+  project: { projectId: "app", hasTypeScript: true },
+  model: { provider: "claude_code", id: "sonnet" },
+  backendConfig: {
+    type: "local_agent",
+    provider: "claude_code",
+    modelId: "sonnet",
+    projectPath: "/path/to/project",
+  },
+});
+await runtime.runSession(session.id, "/path/to/project", (event) => {
+  console.log(event.type);
+});
+```
+
+The shared runtime core (`WorkspaceGuard`, `VerificationEngine`,
+`LocalSessionRunner`, adapters) is published as `@lasso-ai/cli/runtime` and is
+the same code the Lasso server uses for its colocated Mode B deployments.
+
+## Sessions
+
+Local runtime sessions are **in-memory, per CLI process**: they live as long
+as the `lasso` bridge process does and are gone when it exits. Review payloads
+(`pendingChanges`) are persisted in session metadata and applied from the
+review panel regardless. Hosted sessions continue to live server-side (and in
+the server's MongoDB when configured).
+
+## Limitations
+
+- **Review-first is mandatory.** There is no "apply silently" mode; every run
+  ends in a review (or a no-change completion).
+- **Ephemeral local sessions.** Local agent sessions do not survive a CLI
+  restart; hosted sessions do.
+- **Verification is best-effort.** Typecheck runs only when a `tsconfig.json`
+  exists; build only when `package.json` has a `build` script. Missing
+  tooling is reported as *skipped* (inconclusive), never as a pass or a
+  failure.
+- **Session continuation varies.** Claude Code (`--resume`), Codex
+  (`exec resume`), and Cursor (`--resume`) can continue their own external
+  sessions; OpenCode is re-driven with conversation context each run. Agent
+  internal tool-call state is not portable across backends — switching agents
+  mid-task transfers conversation/observations/errors only.
+- **Cancellation** sends SIGTERM (then SIGKILL after 3s) to the agent process.
+  In-flight tool calls are not undone by the agent itself; the workspace guard
+  rollback is what keeps the project clean.
+- **Permissions.** Claude runs with `--permission-mode acceptEdits`; Codex runs
+  with `sandbox_mode="workspace-write"`; agents are instructed not to commit,
+  push, or act outside the project directory.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Backend locked: "not installed" | Binary not on your `PATH` | Install the CLI globally; restart the `lasso` CLI so it picks up `PATH` changes |
+| Backend locked: "not logged in" | Missing agent credentials | Run the agent's login command listed in the fix instructions |
+| "Credit balance is too low" / "usage limit" | Provider account limits | Top up or wait for the limit window; the run is failed cleanly with no partial apply |
+| "finished without reporting a successful result" | Agent exited 0 without a terminal success event | Usually a CLI version mismatch — update the agent |
+| Changes appear, then vanish before review | Expected: workspace is rolled back until you approve | Approve in the review panel to apply |
+| Local agent run works, hosted models don't | Hosted models need the Lasso server API | Check the CLI's server URL / API key; local agents are unaffected |
+
+## API
+
+Local agents do not require any server endpoints — the CLI runs them
+directly. The server API remains for hosted models and backend discovery:
+
+- `GET /api/v1/agent-runtime/backends` — probe hosted providers and (for
+  colocated deployments) local agents.
+- `POST /api/v1/agent-runtime/sessions` — create a hosted-model session (or a
+  colocated local-agent session on self-hosted deployments).
+- `POST /api/v1/agent-runtime/sessions/:id/run` — run (also used for
+  corrective re-runs).
+- `POST /api/v1/agent-runtime/sessions/:id/verify` — post-apply verification;
+  returns `{ passed, errors, observations, command, requiresFix }`.
+- `POST /api/v1/agent-runtime/sessions/:id/model` — switch hosted model or
+  local agent mid-session; reports `transferableContext` / `lostContext`.
+- `POST /api/v1/agent-runtime/sessions/:id/cancel` — abort the running agent
+  and restore the workspace.

package/package.json

@@ -1,9 +1,24 @@
 {
   "name": "@lasso-ai/cli",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "Select any part of your running app, describe a change, and let AI edit the real source code.",
   "type": "commonjs",
   "main": "dist/cli/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./local-runtime": {
+      "types": "./dist/cli/local-runtime.d.ts",
+      "default": "./dist/cli/local-runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "lasso": "dist/cli/index.js"
   },
@@ -15,7 +30,8 @@
     "CONTRIBUTING.md",
     "SECURITY.md",
     "SUPPORT.md",
-    "docs/PUBLISHING.md"
+    "docs/PUBLISHING.md",
+    "docs/local-coding-agents.md"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -33,7 +49,7 @@
     "format": "prettier --write .",
     "deploy": "pnpm build && npm publish --access public",
     "format:check": "prettier --check .",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --import tsx --test src/runtime/__tests__/*.test.ts"
   },
   "keywords": [
     "ai",
@@ -105,5 +121,8 @@
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
     "vite": "^8.3.0"
+  },
+  "overrides": {
+    "@lasso-ai/cli": "link:"
   }
 }