@loompad/cli 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Loom — shared types.
+ *
+ * The event log is the source of truth; everything else (agent memory,
+ * board views, phone surfaces) is a projection of it.
+ */
+export type EventKind = "message" | "tool_call" | "tool_result" | "file_edit" | "decision" | "handoff" | "suggestion" | "needs_input" | "run_complete" | "agent_join" | "agent_leave" | "role_change" | "route_started" | "route_step" | "route_paused" | "route_resumed" | "route_completed" | "route_failed" | "turn_diff" | "memory_import" | "memory_add" | "memory_update" | "memory_forget" | "status" | "error";
+/**
+ * The chat every event belongs to. A project can hold several conversations;
+ * they share one brain, one baton and one working tree — only the talking is
+ * split. Events written before chats existed carry no id and read as MAIN.
+ */
+export declare const MAIN_CHAT = "main";
+export interface LoomEvent {
+    id: number;
+    ts: number;
+    kind: EventKind;
+    /** Author agent id; absent for human/system events. */
+    agentId?: string;
+    /** Conversation this belongs to. Absent means the main chat. */
+    chat?: string;
+    payload: Record<string, unknown>;
+}
+export type NewEvent = {
+    kind: EventKind;
+    agentId?: string;
+    chat?: string;
+    payload: Record<string, unknown>;
+    ts?: number;
+};
+/** A named conversation inside a project. */
+export interface ChatInfo {
+    id: string;
+    title: string;
+    createdAt: number;
+}
+/**
+ * An agent's job, in your words. Free text: call an agent "architect",
+ * "tester", "the one that writes docs" — whatever your project actually does.
+ *
+ * A few names carry extra meaning if you use them, and none if you don't:
+ * `buildDefaultRoutes` seeds a plan→execute→review pipeline when it sees
+ * planner/executor/reviewer, the rules router prefers a reviewer last, and a
+ * route step matches an agent by role as well as by id (so a route named
+ * ["architect","tester"] just works). Nothing requires them.
+ */
+export type AgentRole = string;
+/** Roles Loom suggests when it sets a project up. Only suggestions. */
+export declare const SUGGESTED_ROLES: readonly ["planner", "executor", "reviewer", "general"];
+/** Adapter = full-duplex; bridge = read-mostly, never holds the baton. */
+export type AgentTier = "adapter" | "bridge";
+export interface AgentConfig {
+    /** Stable instance id within the project, e.g. "claude-code". */
+    id: string;
+    /** Adapter kind, e.g. "claude-code" | "opencode" | "echo" | "antigravity". */
+    kind: string;
+    role: AgentRole;
+    options?: Record<string, unknown>;
+    /** Override the ADE's native memory files to import into the shared brain. */
+    memoryFiles?: string[];
+}
+/** One ADE's native memory pulled into the unified brain. */
+export interface MemorySource {
+    agentId: string;
+    kind: string;
+    file: string;
+    chars: number;
+}
+export interface UnifiedMemory {
+    projectName: string;
+    decisions: string[];
+    sources: MemorySource[];
+    /** The merged brain document (decisions + imported ADE memories + context). */
+    document: string;
+}
+/**
+ * A route step: which agent (by id or role), and what job it does.
+ *
+ * `role` is the job for THIS step — planner/executor/reviewer/… — chosen when
+ * the task is created, independent of the agent's own default role. So the same
+ * agent can plan in one task and review in another. `instruction` is optional
+ * free-text focus on top of the role.
+ */
+export type RouteStepSpec = string | {
+    step: string;
+    role?: string;
+    instruction?: string;
+};
+/** How shared memory is rendered on handoff. */
+export interface ProjectionConfig {
+    /** "template" (default, free, instant) or "llm" (distilled by a small Claude). */
+    mode?: "template" | "llm";
+    model?: string;
+    timeoutMs?: number;
+}
+/** The brain's phase-2 extractor — learning from each turn. See core/brain-extract.ts. */
+export interface BrainConfig {
+    /**
+     * Who reads finished turns for memory:
+     *   "auto" (default) — a small Claude, when the CLI is available; a no-op when not.
+     *   "off"            — never extract; the brain only holds what you type.
+     */
+    extractor?: "auto" | "off";
+    /** Model for the extractor call; small+fast is right. */
+    model?: string;
+}
+export interface ProjectConfig {
+    name: string;
+    agents: AgentConfig[];
+    /** Agent that receives messages when nobody holds the baton. */
+    defaultAgent?: string;
+    /** Named multi-hop pipelines; steps are agent ids/roles, optionally with instructions. */
+    routes?: Record<string, RouteStepSpec[]>;
+    projection?: ProjectionConfig;
+    brain?: BrainConfig;
+}
+export type RouteStatus = "running" | "waiting_human" | "completed" | "failed" | "aborted";
+export type RouteMode = "static" | "dynamic";
+export type RouterKind = "rules" | "llm";
+export interface RouteState {
+    id: string;
+    name?: string;
+    task: string;
+    /** Resolved agent ids, in order. Dynamic routes grow this per hop. */
+    steps: string[];
+    stepRoles: AgentRole[];
+    /** Optional per-step focus text (parallel to steps; null = role default only). */
+    stepInstructions?: Array<string | null>;
+    /** Index of the step currently executing (or last executed). */
+    current: number;
+    status: RouteStatus;
+    /** static = fixed pipeline; dynamic = a router picks each next hop. */
+    mode: RouteMode;
+    router?: RouterKind;
+    maxHops?: number;
+    startedAt: number;
+    updatedAt: number;
+    reason?: string;
+    pendingQuestion?: string;
+    /** Project cost total when the route started (internal baseline). */
+    costStartUsd?: number;
+    /** Spend attributed to this route (set when it ends). */
+    costUsd?: number;
+}
+export interface ProjectInfo {
+    id: string;
+    name: string;
+    dir: string;
+}
+export interface SendInput {
+    text: string;
+    /** One-shot handoff briefing injected alongside this turn. */
+    briefing?: string;
+}
+export interface AdapterEvent {
+    kind: EventKind;
+    payload: Record<string, unknown>;
+}
+export interface AgentCapabilities {
+    tier: AgentTier;
+    send: boolean;
+    stream: boolean;
+    injectMemory: boolean;
+    interrupt: boolean;
+    diff: boolean;
+}
+export interface BaseAgent {
+    readonly id: string;
+    readonly kind: string;
+    readonly capabilities: AgentCapabilities;
+    /** Is the underlying tool installed/reachable? */
+    available(): Promise<boolean>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Persist Loom's namespaced memory projection for this agent. */
+    injectMemory(projection: string): Promise<void>;
+    /** Subscribe to live events; returns unsubscribe. */
+    onEvent(cb: (e: AdapterEvent) => void): () => void;
+}
+/** Full-duplex adapter — may hold the baton. */
+export interface Adapter extends BaseAgent {
+    send(input: SendInput): Promise<void>;
+    interrupt(): Promise<void>;
+    /** Working-tree changes attributable to the agent (porcelain-ish). */
+    diff(): Promise<string>;
+    busy(): boolean;
+}
+/** Read-mostly bridge — never holds the baton (GUI agents). */
+export interface Bridge extends BaseAgent {
+}
+export type AnyAgent = Adapter | Bridge;
+export declare function isAdapter(a: AnyAgent): a is Adapter;
+export interface AgentStatus {
+    id: string;
+    kind: string;
+    role: AgentRole;
+    tier: AgentTier;
+    available: boolean;
+    busy: boolean;
+    holdsBaton: boolean;
+    /** The model override in effect, or "" for the CLI's own default. */
+    model: string;
+}
+export interface ProjectStatus {
+    id: string;
+    name: string;
+    dir: string;
+    holder: string | null;
+    agents: AgentStatus[];
+    lastEvent: LoomEvent | null;
+    needsInput: boolean;
+    /**
+     * The agent whose question is still unanswered, when `needsInput` — the
+     * board puts a name on the card, not just "someone is blocked".
+     */
+    blockedAgent?: string | null;
+    /** Conversations in this project, main first. */
+    chats?: ChatInfo[];
+    route?: RouteState | null;
+    /** Named pipelines defined in config (for pickers/dropdowns). */
+    routeNames?: string[];
+    /** Lifetime spend across all agents in this project (USD). */
+    costUsd?: number;
+}
+export interface AgentCost {
+    agentId: string;
+    usd: number;
+    turns: number;
+    ms: number;
+}
+export interface CostSummary {
+    totalUsd: number;
+    turns: number;
+    totalMs: number;
+    byAgent: AgentCost[];
+}

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Loom — shared types.
+ *
+ * The event log is the source of truth; everything else (agent memory,
+ * board views, phone surfaces) is a projection of it.
+ */
+/**
+ * The chat every event belongs to. A project can hold several conversations;
+ * they share one brain, one baton and one working tree — only the talking is
+ * split. Events written before chats existed carry no id and read as MAIN.
+ */
+export const MAIN_CHAT = "main";
+/** Roles Loom suggests when it sets a project up. Only suggestions. */
+export const SUGGESTED_ROLES = ["planner", "executor", "reviewer", "general"];
+export function isAdapter(a) {
+    return a.capabilities.tier === "adapter";
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoCH;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC;AA4ChC,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC;AAsKvF,MAAM,UAAU,SAAS,CAAC,CAAW;IACnC,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,KAAK,SAAS,CAAC;AAC3C,CAAC"}

package/docs/SETUP.md

@@ -0,0 +1,265 @@
+# Setting up Loom
+
+Read this before installing. Loom drives other people's coding agents, so most
+of the setup is really *their* setup — and the parts that bite are the ones
+nobody warns you about.
+
+Everything here was hit for real on a machine, not copied from a wiki. Where
+something is a guess, it says so.
+
+---
+
+## 1. The one hard requirement: Node ≥ 22.5
+
+```sh
+node --version
+```
+
+Loom's event log uses `node:sqlite`, which arrived in Node 22.5. On anything
+older Loom still runs and **silently falls back to a JSONL store with no
+history** — the app looks fine and your past turns aren't there.
+
+> **The installed desktop app has this problem too.** Electron 33 bundles Node
+> 20, so `Loom.app` looks for a real `node` on your machine (`$LOOM_NODE`, then
+> the usual install paths, then `PATH`). If it can't find one, it runs on
+> Electron's Node and degrades exactly as above. There is no warning yet. See
+> `desktop/BUILD.md`.
+
+- **macOS**: `brew install node`
+- **Windows**: `winget install OpenJS.NodeJS`
+- **Linux**: your distro's node, or [nodesource](https://github.com/nodesource/distributions)
+
+---
+
+## 2. Install at least one agent
+
+Loom has nothing to drive on its own. A new project is given whichever of these
+it finds — and **an empty roster if it finds none**, which is honest but not
+useful.
+
+| Agent | Install | Sign in | Check |
+|---|---|---|---|
+| **Claude Code** | `npm i -g @anthropic-ai/claude-code` | `claude` (once, interactively) | `claude --version` |
+| **Codex** | [Codex.app](https://openai.com/codex/), or `npm i -g @openai/codex` | `codex login` | `codex login status` |
+| **OpenCode** | `curl -fsSL https://opencode.ai/install \| bash` | `opencode auth login` | `opencode --version` |
+| **Grok Code** | [docs.x.ai](https://docs.x.ai) | `grok` (once, interactively) | `grok --version` |
+
+Two things worth knowing:
+
+**Codex's CLI hides inside its app.** On a Mac with Codex.app installed and
+nothing on `PATH`, the binary is at
+`/Applications/Codex.app/Contents/Resources/codex`. Loom looks there as well as
+on `PATH`, so you don't have to do anything — but that's why `which codex`
+coming up empty doesn't mean it's missing.
+
+**Being logged in is not optional and not detectable in advance.** Loom probes
+whether a CLI *exists*, not whether it's authenticated. An unauthenticated agent
+looks installed, takes your turn, and fails. Run each one once by hand first.
+
+Then ask Loom what it can see:
+
+```sh
+loom doctor
+```
+
+---
+
+## 3. GUI agents: Antigravity IDE and Kiro
+
+These have no API and no headless mode. Loom drives them through the Chrome
+DevTools port they open *only if you ask*, so they need a launch flag.
+
+### Which Antigravity?
+
+There are two apps and only one of them is the right one.
+
+| | What it is | Use it? |
+|---|---|---|
+| **Antigravity.app** | the Manager — a web page behind a Google sign-in | ❌ no chat DOM at all |
+| **Antigravity IDE.app** | the VS Code fork with the agent in it | ✅ this one |
+
+Pointing Loom at the Manager finds nothing and reports that Antigravity has no
+chat. It's the wrong app, not a broken bridge.
+
+### Why port 9333 and not 9222
+
+Antigravity's own Browser Control (the Chrome button in its toolbar) already
+uses **9222**. Ask for it and you get `EADDRINUSE` — and the IDE starts anyway,
+just without a debugger, silently. Use **9333**.
+(Discovered by the [AntiGravity-AutoAccept](https://github.com/yazanbaker94/AntiGravity-AutoAccept)
+project.)
+
+### macOS
+
+```sh
+open -a "Antigravity IDE" --args --remote-debugging-port=9333 /path/to/your/repo
+```
+
+Make it permanent in `~/.zshrc`:
+
+```sh
+alias antigravity='open -a "Antigravity IDE" --args --remote-debugging-port=9333'
+```
+
+If `open -a` doesn't pass the flag through on your build, go direct:
+
+```sh
+alias antigravity='"/Applications/Antigravity IDE.app/Contents/MacOS/Electron" --remote-debugging-port=9333 & disown'
+```
+
+Or make an Automator **Application** with one *Run Shell Script* action
+containing the `open -a` line, and launch that instead of the dock icon.
+
+**Only one instance gets the port.** If Antigravity is already running, a second
+launch just focuses the first window and your flag is ignored — the port stays
+closed and nothing says so. Quit it fully first:
+
+```sh
+pkill -f "Antigravity" && sleep 2
+```
+
+### Windows
+
+Right-click the Antigravity IDE shortcut → **Properties** → append to *Target*:
+
+```
+--remote-debugging-port=9333
+```
+
+Launch from that shortcut afterwards, not from search results or a pinned
+taskbar entry pointing elsewhere.
+
+### Linux
+
+```sh
+# find the launcher
+find /usr/share/applications ~/.local/share/applications -name "*ntigravity*"
+# then edit its Exec line:
+Exec=/path/to/antigravity --remote-debugging-port=9333 %F
+```
+
+or an alias in `~/.bashrc`:
+
+```sh
+alias antigravity='antigravity --remote-debugging-port=9333'
+```
+
+### Kiro
+
+Same idea, **port 9334** so it can't collide with Antigravity:
+
+```sh
+open -a "Kiro" --args --remote-debugging-port=9334        # macOS
+```
+
+Kiro's chat panel must be **open** — on a fresh window its only editable area is
+Monaco, holding your source file, and Loom refuses to type into that on purpose.
+
+### Then check it
+
+```sh
+loom doctor
+```
+
+Loom distinguishes *reachable* from *driveable*, because a signed-out app
+answers the debugger cheerfully and has no usable chat:
+
+- `Antigravity IDE isn't listening — open -a "Antigravity IDE" --args --remote-debugging-port=9333` → the flag didn't take
+- `Antigravity IDE is signed out — log in from its window` → the app is up; **log into it**
+- `no chat panel — open a chat` → it's up and signed in; open a conversation
+
+---
+
+## 4. Permissions
+
+### macOS
+
+| What | Needed for | How |
+|---|---|---|
+| **Notifications** | "your agent needs you" while you're elsewhere | First `loom up` asks. Otherwise: System Settings → Notifications → Loom |
+| **Open a downloaded app** | Loom.app isn't notarized yet | **Right-click → Open** the first time. Double-clicking gives "cannot be opened" with no way forward |
+| **Local Network** | your phone reaching the daemon over LAN | Prompted on first connection. System Settings → Privacy & Security → Local Network |
+
+**Not needed, despite what you might expect:** Accessibility, Screen Recording,
+Automation, Full Disk Access. Loom drives GUI agents through their debugging
+port, not by pretending to be a mouse, so it never asks the OS for control of
+another app. If something tells you to grant Accessibility to Loom, that isn't
+Loom.
+
+### Windows
+
+| What | Needed for | How |
+|---|---|---|
+| **Firewall (private networks)** | your phone reaching the daemon | Windows Defender prompts on first `loom up` — tick **Private networks**. Public: leave off |
+| **SmartScreen** | the installer isn't signed yet | **More info → Run anyway** |
+| **Notifications** | agent alerts | Settings → System → Notifications → Loom |
+
+---
+
+## 5. Staying open, and staying running
+
+**The daemon already outlives the window.** It's spawned detached — close the
+app and your agents keep working; reopen and you're back where you were. That's
+the design, not a leak. To stop it for real:
+
+```sh
+loom down
+```
+
+**Run it at login (optional).** No installer wires this up yet; do it yourself:
+
+- **macOS** — System Settings → General → Login Items → **+** → Loom.app. Or a
+  LaunchAgent running `loom up`.
+- **Windows** — `Win+R` → `shell:startup` → shortcut to Loom.
+- **Linux** — a user systemd unit running `loom up`.
+
+**Always on top** is the window manager's job, not Loom's: right-click the title
+bar (Windows), or use a tiling/stage manager (macOS). Loom doesn't ask for it —
+a tool that forces itself in front of your editor is a tool you'll uninstall.
+
+---
+
+## 6. Your phone
+
+The phone app talks to the daemon on your own machine. Nothing goes through a
+server of ours, because there isn't one.
+
+1. **Install Tailscale** on both, sign into the same tailnet: [tailscale.com/download](https://tailscale.com/download)
+2. **Bind Loom to the tailnet** — by default it listens on localhost only and your phone cannot see it:
+   ```sh
+   loom up --restart --tailnet
+   ```
+3. **Pair**: `loom pair` prints a QR code. Scan it.
+
+Two things that will confuse you otherwise:
+
+- `loom doctor` saying *"binding localhost only — phones can't reach it"* is the
+  whole answer. Re-run with `--tailnet`.
+- The pairing token is single-use and the client token it hands back lives on the
+  phone. Losing the phone means `loom` → unpair that client, not rotating
+  everything.
+
+---
+
+## 7. When it's wrong
+
+```sh
+loom doctor          # what Loom can see, and what it can't
+tail -f ~/.loom/daemon.log
+```
+
+**A change you made isn't showing up.** The daemon is a long-lived process; it
+serves the code it started with. `loom up` compares fingerprints and restarts a
+stale one automatically, but if you're staring at yesterday's behaviour:
+
+```sh
+loom down && loom up
+```
+
+**"daemon already running" but it's on the wrong port.** Something else has
+7420. `lsof -ti tcp:7420` (macOS/Linux) or `netstat -ano | findstr 7420`
+(Windows).
+
+**An agent takes the turn and nothing happens.** It's almost always
+authentication. Run that agent by hand in a terminal once — it'll tell you what
+Loom can't.

package/docs/adapters.md

@@ -0,0 +1,132 @@
+# Writing a Loom adapter or bridge
+
+Loom's integration model has **two tiers**, and picking the right one is the first
+decision:
+
+| | Adapter | Bridge |
+|---|---|---|
+| Can hold the baton (write lock) | ✅ | ❌ never |
+| Must implement | `send`, live events, `injectMemory`, `interrupt`, `diff` | events (best-effort), `injectMemory` |
+| For | agents with a real API / headless mode | GUI agents without a stable control surface |
+| Examples | Claude Code, OpenCode | Antigravity |
+
+This split is deliberate (see [ARCHITECTURE.md](../ARCHITECTURE.md)): the baton
+authorizes *edits to the user's working tree*, so it can only be held by an agent Loom
+can reliably start, stream, interrupt, and account for. If your target tool only exposes
+a debug port and pixels, build a bridge; if it exposes an API, build an adapter. A
+bridge can graduate later.
+
+## The contract
+
+Everything lives in `threadloom/sdk`:
+
+```ts
+import {
+  AdapterBase,      // extend for adapters
+  BridgeBase,       // extend for bridges
+  registerAgentKind,
+  type SendInput,   // { text, briefing? }
+  type AdapterEvent // { kind, payload }
+} from "threadloom/sdk";
+```
+
+### Events you can emit
+
+| kind | payload | when |
+|---|---|---|
+| `message` | `{ text }` | your agent produced prose |
+| `tool_call` | `{ tool, summary }` | it used a tool |
+| `file_edit` | `{ path }` | it changed a file |
+| `needs_input` | `{ question }` | it is blocked on the human → triggers a notification |
+| `run_complete` | `{ durationMs?, costUsd? }` | the turn finished → notification |
+| `status` | `{ state, … }` | lifecycle (ready / interrupted / …) |
+| `error` | `{ message }` | something broke |
+
+Every event you emit is appended to the project's event log — which is exactly what gets
+projected into the *next* agent's memory on handoff. Emit honestly and your agent's work
+becomes context for everyone else.
+
+### A complete adapter
+
+```ts
+import { AdapterBase, registerAgentKind, type SendInput } from "threadloom/sdk";
+
+export class MyAgentAdapter extends AdapterBase {
+  // available(): is the underlying tool installed/reachable?
+  async available(): Promise<boolean> {
+    return true;
+  }
+
+  async start(): Promise<void> {
+    // boot your server / warm your session; emit a status event
+    this.emit({ kind: "status", payload: { state: "ready" } });
+  }
+
+  async stop(): Promise<void> {}
+
+  async send(input: SendInput): Promise<void> {
+    if (this._busy) throw new Error(`${this.id} is busy`);
+    this._busy = true;
+    try {
+      // input.briefing is the one-shot handoff context — inject it however
+      // your agent accepts system/context input. Claude Code uses
+      // --append-system-prompt; OpenCode gets a delimited preamble.
+      const reply = await callMyAgent(input.text, input.briefing);
+      this.emit({ kind: "message", payload: { text: reply } });
+      this.emit({ kind: "run_complete", payload: {} });
+    } finally {
+      this._busy = false;
+    }
+  }
+
+  async interrupt(): Promise<void> {
+    // stop the in-flight turn (kill the process, call the abort route, …)
+  }
+
+  // diff() has a default implementation (git status --porcelain).
+  // injectMemory() has a default implementation writing the namespaced
+  // .loom/memory/<id>.md file — override only if your agent has a richer
+  // native memory surface. NEVER write into user-authored files.
+}
+
+registerAgentKind("my-agent", (cfg, dir) => new MyAgentAdapter(cfg.id, "my-agent", dir));
+```
+
+Users then declare it in `.loom/config.json`:
+
+```json
+{ "id": "my-agent", "kind": "my-agent", "role": "executor", "options": {} }
+```
+
+`cfg.options` arrives in your constructor if you define one — see
+`src/adapters/claude-code.ts` and `src/adapters/opencode.ts` for real examples,
+including session persistence via project state.
+
+### A bridge
+
+```ts
+import { BridgeBase, registerAgentKind } from "threadloom/sdk";
+
+export class MyGuiBridge extends BridgeBase {
+  async available() { return true; }
+  async start() {
+    this.emit({ kind: "status", payload: { state: "observed" } });
+  }
+  async stop() {}
+  // injectMemory() default keeps .loom/memory/<id>.md fresh — the human
+  // driving the GUI agent points it at that file.
+}
+
+registerAgentKind("my-gui", (cfg, dir) => new MyGuiBridge(cfg.id, "my-gui", dir));
+```
+
+## Ground rules
+
+1. **Never block `send()` on user interaction** — emit `needs_input` and finish the turn.
+2. **Interrupt must be safe** — a confirmed handoff interrupts you; leave the tree in a
+   sane state (that's why baton holders are adapters only).
+3. **Emit `run_complete` exactly once per turn** — notifications and suggestions key off it.
+4. **Respect namespacing** — your memory surface is `.loom/memory/<your-id>.md` and
+   whatever *additive* mechanism your agent offers. User files are off-limits.
+5. **Persist session state** via project state (see `readProjectState` /
+   `writeProjectState`) so `--resume`-style continuity survives daemon restarts.