gaslamp 2.2.3 → 3.0.0

package/bin/gaslamp.mjs

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-// gaslamp: let Claude Code and Codex consult each other — and Gemini and Grok —
-// from the shell.
+// gaslamp: let coding agents consult each other from the shell — Claude,
+// Codex, Gemini and Grok.
 //
-//   gaslamp claude … / codex …   one blocking consult (the heart of it)
-//   gaslamp gemini … / grok …    the same, against Antigravity CLI / Grok Build
-//   gaslamp fleet <backend> …    fan out a bounded fleet of consults
-//   gaslamp jobs / poll          read the durable consult records
-//   gaslamp setup [--local]      allowlist the command for Claude Code
+//   gaslamp claude|codex|gemini|grok …   one blocking consult (the heart of it)
+//   gaslamp jobs / poll / threads        read the durable records
+//   gaslamp setup                        link the skill, allowlist the command
 //
 // Each agent backgrounds the call with its own facility, so consults run in
 // parallel and replies trickle in as they finish. No MCP servers, no daemon:
@@ -19,114 +17,54 @@ import { fileURLToPath } from "node:url";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
 
-const HELP = `gaslamp ${pkg.version}: let Claude Code and Codex consult each other from the shell
-(and consult Gemini and Grok).
+const HELP = `gaslamp ${pkg.version}: let coding agents consult each other from the shell.
 
 Usage:
-  gaslamp claude [opts] <prompt|->   Consult Claude (blocks until the reply).
-  gaslamp codex  [opts] <prompt|->   Consult Codex  (blocks until the reply).
-  gaslamp gemini [opts] <prompt|->   Consult Gemini via Antigravity CLI (agy).
-  gaslamp grok   [opts] <prompt|->   Consult Grok via Grok Build.
-  gaslamp fleet <backend> [opts]     Fan out a fleet of consults (one command).
-    -n N <prompt>                    Replicate one prompt across N fresh sessions.
-    - < tasks.jsonl                  Or one task per line on stdin (see below).
-  gaslamp fleet --resume <fleet-id>  Finish an interrupted fleet: done children
-                                     replay their recorded replies, killed ones
-                                     are nudged to conclude via their sessions,
-                                     the rest rerun from the stored manifest.
-  gaslamp jobs [-n N] [--json]       List consult records, newest first.
-  gaslamp threads                    List named threads, latest activity first.
-  gaslamp poll <job|fleet|--last> [--json]
-                                     Print one record's reply/status.
-  gaslamp tail <job|--last>          Follow one consult's events as one-liners
-                                     (both backends' schemas, uniformly).
-  gaslamp setup [--local] [--skill]  Allowlist the command in Claude Code so
-                                     consults don't stall on a permission prompt.
-                                     --local pins this checkout's bin path.
-                                     --skill also installs the gaslamp skill
-                                     for BOTH agents (~/.claude/skills/,
-                                     $CODEX_HOME/skills/).
+  gaslamp <claude|codex|gemini|grok> [opts] <prompt|->
+                             Consult one; blocks until the reply. Run it in the
+                             background and keep working.
+  gaslamp jobs [-n N] [--json]       Recent consults, newest first.
+  gaslamp poll <job|--last> [--json] One consult's reply (exit 10 = running).
+  gaslamp threads                    Named conversations, latest first.
+  gaslamp setup                      Link the skill into Claude Code and Codex,
+                                     and allowlist the command for Claude Code.
 
 Consult options:
-  --resume <session|job>   Continue a session (a prior job id works too).
-  --thread <name>          Named session: continue it if the name is bound,
-                           else start fresh and bind it. The pointer chases
-                           claude's forked session ids so the name stays hot.
-  --model <m>              Backend model: an exact id, or a tier word —
-                           claude aliases (fable, opus, sonnet, haiku); codex
-                           (astra, sol, luna) and gemini (argon, flash) tiers
-                           resolve to the newest id in the harness's own
-                           catalog. gemini defaults to argon (Antigravity also
-                           serves non-Gemini models under the same account).
-  --effort <level>         Reasoning effort (claude --effort / codex
-                           model_reasoning_effort / agy --effort /
-                           grok --effort).
-  --label <s>              Tag the job record (shows in gaslamp jobs).
-  --sandbox <mode>         claude: read-only | danger-full-access
-                           codex:  read-only | workspace-write | danger-full-access
-                           gemini: read-only | danger-full-access
-                           grok:   read-only | workspace-write | danger-full-access
-                           Omitted: claude and codex defer to the consulted
-                           agent's own config; gemini and grok run read-only.
-  --cwd <dir>              Working directory for the consult (default: here).
-  --schema <file|json>     JSON Schema for the reply (native on both backends:
-                           claude --json-schema / codex --output-schema). The
-                           --json envelope gains data (the parsed object); a
-                           reply that doesn't parse marks the consult failed.
-  --raw                    Skip the consult preamble (the few fixed lines that
-                           tell the consultee its reply returns verbatim).
-  --json                   Machine envelope on stdout:
-                           {backend, jobId, sessionId, status, exitCode,
-                            content, data?}
-  -                        Read the prompt from stdin (default when piped).
-                           With a prompt argument, piped stdin is instead
-                           appended as a <stdin> evidence block:
-                           git diff | gaslamp codex "review for races:"
+  --thread <name>          Name the conversation: the first consult with a
+                           name starts it, later ones continue it (from the
+                           directory it started in).
+  --resume <job-id>        Continue an unnamed consult's conversation.
+  --model <m>              An exact id, or a tier: claude fable|opus|sonnet|
+                           haiku; codex astra|sol|luna; gemini argon|flash
+                           (default argon).
+  --effort <level>         low|medium|high|xhigh|max (codex astra/sol: ultra).
+  --sandbox <mode>         read-only | workspace-write | danger-full-access.
+                           Omitted: claude and codex use their own config;
+                           gemini and grok run read-only. The fenced modes
+                           are OS-enforced; gemini's needs macOS.
+  --cwd <dir>              Run the consult there (default: here).
+  --schema <file|json>     JSON Schema for the reply; with --json the parsed
+                           reply is in data, and one that doesn't parse fails.
+  --json                   {backend, jobId, status, thread, content, error?, data?}
+  -                        Read the prompt from stdin (the default when piped).
+                           With a prompt argument, piped stdin is appended as
+                           a <stdin> evidence block:
+                             git diff | gaslamp codex "review for races:"
 
-Fleet options (in addition to --model / --sandbox / --cwd / --json, applied to
-every consult unless a per-task field on a stdin manifest overrides it):
-  -n, --count N            Replicate the prompt across N fresh sessions.
-  -j, --concurrency N      Max consults in flight (default 4 — quota-shaped).
-  --stream                 Print each reply the moment it completes instead of
-                           collecting to the end (with --json: JSONL — one
-                           result line per reply, then a fleet.done line).
-  - < tasks.jsonl          One task per line: a {"prompt",…} JSON object (also
-                           model/sandbox/effort/cwd/resume/thread/label/schema/
-                           raw — schema may be an inline JSON object), or a
-                           bare prompt.
-                           A prompt argument + piped stdin shares one <stdin>
-                           evidence block across every replica.
-A fleet defaults its consults to --sandbox read-only (N writers in one cwd
-race); pass --sandbox to opt into writes. It blocks until every consult is in,
-then prints them all (--json: a results array, manifest order). A killed fleet
-leaves each child resumable; gaslamp poll <fleet-id> regroups them later.
-
-Run a consult (or a fleet) as a background shell task and keep working — several
-can run in parallel, replies land as the tasks finish. Every consult writes through to
-~/.gaslamp/jobs/<id>/ (prompt, raw events, reply, stderr), and the session id
-is recorded the moment the backend reports it: a killed consult costs the
-in-flight turn, not the session. Recovery is --resume, not orphans.
+Every consult writes through to ~/.gaslamp/jobs/<id>/ (prompt, raw events,
+stderr, reply), and its session is recorded the moment the backend reports it:
+a killed consult loses the turn in flight, not the conversation.
 
 Exit codes:
-  0 ok · 1 consult failed/killed · 2 usage · 3 nested (one-hop) refusal ·
-  4 network-disabled sandbox · 5 session busy · poll: 10 still running
+  0 ok · 1 failed or killed · 2 usage · 3 nested (one-hop) refusal ·
+  4 can't run here (no network, or no OS sandbox for the mode) ·
+  5 conversation busy · poll: 10 still running
 
-Env knobs:
+Env:
   GASLAMP_HOME             state dir (default ~/.gaslamp)
-  GASLAMP_ALLOWED_TOOLS    tools the claude read-only override permits,
-                           comma-separated (default: Read,Grep,Glob,WebFetch,
-                           WebSearch + read-only git via Bash(git diff:*) etc)
   GASLAMP_ALLOW_RECURSION  let consulted agents consult back (off = one hop)
-  GASLAMP_DEBUG            verbose stderr (spawn argv)
-  CLAUDE_BIN / CODEX_BIN / AGY_BIN / GROK_BIN
-                           backend binaries (autodetected otherwise)
-  GASLAMP_GEMINI_SEATBELT  0 = read-only gemini consults rely on Antigravity's
-                           preset check instead of Seatbelt (macOS default)
-
-Every job record (meta.json) carries provenance: provider, harness version,
-the model the backend reported (or unknown), the vendor system prompt's hash
-where the harness exposes it (grok) or known:false, the retrieval tools the
-consultee had and used, and the gaslamp version and git revision.
+  GASLAMP_DEBUG            print the spawn argv
+  CLAUDE_BIN / CODEX_BIN / AGY_BIN / GROK_BIN   backend binaries
 `;
 
 const [cmd, ...rest] = process.argv.slice(2);
@@ -140,34 +78,24 @@ switch (cmd) {
     runConsult(cmd, rest);
     break;
   }
-  case "fleet": {
-    const { runFleet } = await import(new URL("../src/fleet.mjs", import.meta.url));
-    runFleet(rest[0], rest.slice(1));
-    break;
-  }
   case "jobs": {
     const { runJobs } = await import(new URL("../src/jobs.mjs", import.meta.url));
     runJobs(rest);
     break;
   }
-  case "threads": {
-    const { runThreads } = await import(new URL("../src/threads.mjs", import.meta.url));
-    runThreads();
-    break;
-  }
-  case "tail": {
-    const { runTail } = await import(new URL("../src/tail.mjs", import.meta.url));
-    runTail(rest);
-    break;
-  }
   case "poll": {
     const { runPoll } = await import(new URL("../src/jobs.mjs", import.meta.url));
     runPoll(rest);
     break;
   }
+  case "threads": {
+    const { runThreads } = await import(new URL("../src/threads.mjs", import.meta.url));
+    runThreads();
+    break;
+  }
   case "setup": {
     const { runSetup } = await import(new URL("../src/setup.mjs", import.meta.url));
-    runSetup(rest);
+    runSetup();
     break;
   }
   case "-v":
@@ -179,6 +107,11 @@ switch (cmd) {
   case "--help":
     process.stdout.write(HELP);
     break;
+  case "fleet":
+  case "tail":
+    process.stderr.write(`gaslamp: ${cmd} is gone in gaslamp 3 — run several consults in the background instead (see gaslamp --help)\n`);
+    process.exitCode = 2;
+    break;
   default:
     process.stderr.write(`gaslamp: unknown command "${cmd}"\n\n` + HELP);
     process.exitCode = 2;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gaslamp",
-  "version": "2.2.3",
-  "description": "Let Claude Code and Codex consult each other from the shell, and consult Gemini and Grok.",
+  "version": "3.0.0",
+  "description": "Let coding agents consult each other from the shell: Claude, Codex, Gemini and Grok.",
   "type": "module",
   "bin": {
     "gaslamp": "bin/gaslamp.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "src/",
+    "skill/",
     "README.md",
     "LICENSE"
   ],

package/skill/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gaslamp
+description: Consult another coding agent (Claude, Codex, Gemini or Grok) from the shell for an independent read or a handoff. Use it to verify a fix or proof, spar on a design, review a diff, search, diagnose with fresh context, or hand off a piece of work. Use it when a claim deserves checking before you rely on it, or when asked to consult Claude / Codex / Gemini / Grok, get a second opinion, or hand work off.
+---
+
+# gaslamp
+
+    gaslamp <claude|codex|gemini|grok> [options] "<prompt>"
+    git diff | gaslamp codex "review this for races:"   # piped stdin rides along as <stdin> evidence
+    gaslamp claude - < notes.md                         # the whole prompt from a file
+
+A consult blocks until the reply arrives, so run it in the background (`run_in_background` in Claude Code, a background terminal in Codex) and keep working. Several can run at once. You get the consultee's final message verbatim, then one `[gaslamp]` line with the job id and the command that continues the conversation. A consult is one hop: the consultee can't consult back, so the synthesis is yours.
+
+Send raw evidence, such as errors, diffs and failing output, not just your reading of it.
+
+## Choosing a consultee
+
+| target | `--model` | omitted `--model` | omitted `--sandbox` |
+|--------|-----------|-------------------|---------------------|
+| claude | fable, opus, sonnet, haiku | its own default | its own config |
+| codex  | astra, sol, luna | its own default | its own config |
+| gemini | argon, flash | argon | read-only |
+| grok   | an id from `grok models` | the account default | read-only |
+
+Roughly, strongest first: fable\* > opus ≈ astra > sonnet ≈ argon ≈ sol > haiku ≈ flash ≈ grok ≈ luna. Match the tier to the stakes, as you would when picking a subagent's model.
+
+\* The public fable is a generation behind the others (5.1, against 5.5 for opus, sonnet and haiku), so for now it sits between opus and sonnet.
+
+`--effort low|medium|high|xhigh|max` sets reasoning effort. astra and sol also take `ultra`. sol defaults to `low`, so set it when the consult matters.
+
+## Conversations
+
+`--thread <name>` names a conversation. The first consult with a name starts it, and every later one continues it.
+
+- Name it for its subject (`auth-race-review`, not `review`).
+- For an independent second opinion, use a new name, because a reused name carries the earlier context along.
+- A thread lives in the directory it started in. To continue it from anywhere else, pass `--cwd`.
+
+Without `--thread` a consult is a one-off, though `--resume <job-id>` can still continue it.
+
+## Sandbox
+
+`--sandbox read-only | workspace-write | danger-full-access`
+
+- **read-only:** the consultee writes nothing outside its harness's own state and temp dirs.
+- **workspace-write:** it writes only in the cwd.
+
+The OS sandbox enforces both, and if the sandbox can't start, gaslamp refuses the consult instead of running it unfenced. Gemini's sandbox is macOS-only, so elsewhere only `danger-full-access` runs it.
+
+The sandbox fences the filesystem, not search. A read-only consultee can still look things up: Google for Gemini, web and X for Grok. For a search consult, send the question and ask for source URLs, since a summary of search results isn't verification. For a review, pipe in the material.
+
+## The rest
+
+- `--cwd <dir>` runs the consult in another directory.
+- `--json` prints `{backend, jobId, status, thread, content, error?, data?}`.
+- `--schema <file|json>` with `--json` puts the parsed reply in `.data`. A reply that doesn't parse fails the consult.
+- `gaslamp jobs` lists recent consults, `gaslamp poll <job|--last>` prints one (exit 10 means it's still running), and `gaslamp threads` lists conversations.
+- Each job lives in `~/.gaslamp/jobs/<id>/`, raw events included. A killed consult loses its current turn but keeps its conversation.
+
+Exit codes: 0 ok · 1 failed or killed · 2 usage · 3 nested · 4 can't run here (no network, or no sandbox for the mode) · 5 conversation busy.

package/src/backends.mjs

@@ -1,39 +1,19 @@
-// backends.mjs — the four consult targets and the facts every module needs
-// about them: job-id prefix, who serves the model, which harness binary, which
-// --sandbox values are honest, and what an omitted --sandbox means.
+// backends.mjs — the four consult targets, and the two facts every module
+// needs about them: the job-id prefix, and what an omitted --sandbox means.
 //
-// claude and codex are the original pair, and an omitted --sandbox defers to
-// the consulted agent's own config. gemini (Google's Antigravity CLI, `agy`)
-// and grok (xAI's Grok Build) joined in 2.2 as consult targets with narrow
-// operational trust: an omitted --sandbox means read-only, enforced by the
-// harness (see consult.mjs), and every job records provenance — the vendor's
-// model or system prompt can change under a stable product name.
+// claude and codex defer to the consulted agent's own config, the way a
+// harness's own subagents inherit theirs. gemini (Google's Antigravity CLI,
+// `agy`) and grok (xAI's Grok Build) start read-only: the narrower trust
+// they joined with.
 
 export const BACKENDS = {
-  claude: {
-    prefix: "cl", provider: "anthropic", harness: "claude",
-    sandboxes: ["read-only", "danger-full-access"], defaultSandbox: null,
-  },
-  codex: {
-    prefix: "cx", provider: "openai", harness: "codex",
-    sandboxes: ["read-only", "workspace-write", "danger-full-access"], defaultSandbox: null,
-  },
-  gemini: {
-    // Antigravity has no headless workspace-write: file writes and shell
-    // commands are soft-denied under its default request-review preset, and
-    // --mode accept-edits did not change that in a print-mode run (probed on
-    // 1.4.3). The only escalation is --dangerously-skip-permissions.
-    prefix: "gm", provider: "google", harness: "agy",
-    sandboxes: ["read-only", "danger-full-access"], defaultSandbox: "read-only",
-  },
-  grok: {
-    prefix: "gk", provider: "xai", harness: "grok",
-    sandboxes: ["read-only", "workspace-write", "danger-full-access"], defaultSandbox: "read-only",
-  },
+  claude: { prefix: "cl", defaultSandbox: null },
+  codex: { prefix: "cx", defaultSandbox: null },
+  gemini: { prefix: "gm", defaultSandbox: "read-only" },
+  grok: { prefix: "gk", defaultSandbox: "read-only" },
 };
 
-export const BACKEND_NAMES = Object.keys(BACKENDS);
-export const isBackend = (s) => Object.hasOwn(BACKENDS, s);
+export const SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
 
-const PREFIXES = BACKEND_NAMES.map((b) => BACKENDS[b].prefix).join("|");
+const PREFIXES = Object.values(BACKENDS).map((b) => b.prefix).join("|");
 export const JOB_ID_RE = new RegExp(`^(${PREFIXES})-\\d{8}-\\d{6}-[0-9a-f]{4}$`);