lazyclaw 3.99.27 → 4.2.0

package/README.md

@@ -8,7 +8,11 @@
 
 One Node CLI that talks to every major LLM provider, runs multi-step workflows as a DAG, exposes a local HTTP gateway, and ships with the niceties you actually want at the prompt: an ASCII banner on launch, Cursor-style slash-command ghost autocomplete (right-arrow accepts), persistent chat sessions, and cost rate cards.
 
-> Part of the [LazyClaude](https://github.com/cmblir/LazyClaude) project — published standalone so you can `npm i -g lazyclaw` without cloning the dashboard.
+> Standalone CLI. A companion dashboard, [LazyClaude](https://github.com/cmblir/LazyClaude), wraps the same providers in a web UI — but `lazyclaw` needs nothing from it: `npm i -g lazyclaw` and go.
+
+Every subcommand at a glance — `lazyclaw --help`:
+
+<img src="docs/screenshots/help.png" alt="lazyclaw --help — full subcommand reference" width="760">
 
 ---
 
@@ -31,6 +35,10 @@ lazyclaw doctor          # validate config + provider registry
 
 `onboard` writes `~/.lazyclaw/config.json`. Move it with `LAZYCLAW_CONFIG_DIR=/elsewhere`. For automation: `--non-interactive --provider X --model Y [--api-key Z]`.
 
+<img src="docs/screenshots/onboard.png" alt="lazyclaw onboard --non-interactive — writes config.json, prints JSON result" width="760">
+
+<img src="docs/screenshots/doctor.png" alt="lazyclaw doctor — config + provider registry health check" width="760">
+
 ### Subscription mode (no API key)
 
 If you already have **Claude Code** installed and signed in (Pro / Max / Team subscription), pick the **`claude-cli`** provider during onboard. lazyclaw shells out to the local `claude` binary, so requests bill against your existing subscription quota instead of pay-per-token API credit. No `sk-ant-` key needed.
@@ -184,6 +192,21 @@ Slash commands inside the REPL:
 | `/model` | Open the per-provider model picker (type-filter + live `/v1/models` fetch) |
 | `/model X` | Switch model directly. Accepts unified `provider/model` form |
 | `/skill a,b` | Replace the system prompt with a composition of named skills |
+| `/loop "<prompt>" [--max N] [--until "<regex>"]` | Repeat one prompt N times (default 3, cap 50). `--until` short-circuits when the regex matches. Ctrl-C aborts the loop. |
+| `/loop "..." --use-memory --recall "<query>"` | Inject `~/.lazyclaw/memory/core.md` and the top-3 matching episodic/recent fragments into the system slot per iteration |
+| `/goal` | List active goals |
+| `/goal <name>` | Switch the chat to the goal's session (subsequent turns persist to `goal:<name>.jsonl`) |
+| `/goal add <name> [--desc "..."] [--cron "<spec>"]` | Register a persistent goal; `--cron` schedules `lazyclaw goal tick <name>` |
+| `/goal close <name> [done\|abandoned]` | Close the goal and uninstall its cron entry |
+| `/memory [core\|recent\|episodic [topic]]` | Show layered memory contents |
+| `/dream` | Consolidate `recent.jsonl` into per-topic `episodic/<topic>.md` files |
+| `/agent` / `/agent list` | List registered multi-agent agents |
+| `/agent show <name>` | Print the agent's JSON record |
+| `/agent add <name> [role text…]` | Register an agent with the default tool whitelist `[bash, read, write, grep]` |
+| `/agent remove <name>` | Delete the agent's record |
+| `/team` / `/team list` | List teams + lead + members + Slack channel |
+| `/team add <name> --agents a,b,c [--lead a] [--channel #x]` | Create a team |
+| `/team remove <name>` | Delete the team |
 | `/usage` | Message count + chars + cumulative token totals |
 | `/new` / `/reset` | Wipe history and start over |
 | `/exit` | Leave the chat REPL (returns to the launcher when chat was opened from it) |
@@ -201,6 +224,107 @@ lazyclaw agent "..." --usage                  # token counts on stderr
 lazyclaw agent "..." --cost                   # USD when rates configured
 ```
 
+## Loops and goals (durable agents)
+
+```bash
+# Repeat one prompt N times against the active provider. Foreground
+# blocks the terminal; --detach forks a worker and prints {loopId,
+# pid, statePath}. Worker state under ~/.lazyclaw/loops/<id>/.
+lazyclaw loop "fix the failing tests" --max 5 --until "DONE"
+lazyclaw loop "ship checklist" --max 10 --detach --session daily
+lazyclaw loops list
+lazyclaw loops show <loopId>
+lazyclaw loops tail <loopId>
+lazyclaw loops kill <loopId>      # SIGTERM; repeat within 5s for SIGKILL
+
+# Goals: persistent objectives with optional cron schedule + channel fan-out.
+lazyclaw goal add ship-v4 --desc "Ship v4" --cron "0 9 * * 1-5"
+lazyclaw goal list
+lazyclaw goal tick ship-v4 --force
+lazyclaw goal channel add ship-v4 slack:#deploys
+lazyclaw goal close ship-v4 done  # also uninstalls the cron entry
+
+# Memory: ~/.lazyclaw/memory/{core.md,recent.jsonl,episodic/*.md}
+lazyclaw memory show core
+lazyclaw memory show recent
+lazyclaw memory dream             # consolidate recent → episodic files
+lazyclaw memory edit core         # open $EDITOR
+```
+
+For Slack fan-out, set `SLACK_BOT_TOKEN` (xoxb-...) in `~/.lazyclaw/.env`.
+Tokens never appear in goal records or logs. Socket Mode inbound also
+needs `SLACK_APP_TOKEN` (xapp-...) and `SLACK_SIGNING_SECRET`.
+
+## Multi-agent Slack teams (v4.1)
+
+Drive a small team of named agents through a single Slack thread. The
+lead agent receives the user's request, decides who else on the team
+should weigh in, `@mentions` them, and the router runs each mentioned
+agent in turn through the full tool-use loop (bash / read / write /
+grep) before handing control back. The thread terminates when the lead
+emits the literal marker `[[TASK_DONE]]` or the per-task iteration
+budget runs out. Each agent's reply is mirrored into the Slack thread
+under its own persona (`chat:write.customize` makes the username + icon
+match the agent in Slack's UI).
+
+```bash
+# 1) Register agents — system prompt + provider + per-agent tool whitelist
+lazyclaw agent add planner  --role "Project planner"   --provider anthropic --model claude-opus-4-7
+lazyclaw agent add backend  --role "Backend engineer"  --provider anthropic --model claude-opus-4-7
+lazyclaw agent add frontend --role "Frontend engineer" --provider openai    --model gpt-4.1
+lazyclaw agent list
+
+# 2) Group them into a team that talks in a specific Slack channel
+lazyclaw team add shop --agents planner,backend,frontend --lead planner --channel '#shop'
+
+# 3) Open a task — posts a root message into the team's channel, returns
+#    the task id and the Slack thread_ts.
+lazyclaw task start --team shop --title "ship checkout flow" --description "MVP scope"
+
+# 4) Drive one user turn through the mention router. The lead replies,
+#    @mentions teammates, they run tool-use loops, hand back to the lead.
+lazyclaw task tick t_20260518_xxxxxx "go" --max-turns 12
+
+# 5) Inspect the conversation (text, markdown, or raw JSON)
+lazyclaw task transcript t_20260518_xxxxxx --format md > thread.md
+lazyclaw task show       t_20260518_xxxxxx
+lazyclaw task done       t_20260518_xxxxxx   # or `abandon` — also posts a closing message
+
+# 6) Agent memory carries lessons forward across tasks (v4.2). The
+#    router auto-fires a ≤6-bullet reflection per participating agent
+#    when a task transitions to done. Manual control:
+lazyclaw agent memory show planner
+lazyclaw agent memory edit planner          # opens $EDITOR
+lazyclaw agent memory clear planner
+lazyclaw agent reflect planner --task t_20260518_xxxxxx
+# Flip auto reflection off per agent: edit ~/.lazyclaw/agents/<name>.json
+# and set "memoryWrite": "off" (other values: "auto" default, "manual").
+```
+
+Slack inbound (a user pings `@lazyclaw` in a channel, the bot replies)
+runs through the Socket Mode listener:
+
+```bash
+lazyclaw slack listen     # foreground; connects, reacts with :eyes:, replies in thread
+```
+
+The CLI is mirrored by daemon HTTP routes (`GET/POST/PATCH/DELETE
+/agents|teams|tasks`, `GET /tasks/<id>/transcript`) and by the
+browser dashboard's Agents / Teams / Tasks tabs:
+
+```bash
+lazyclaw dashboard       # opens http://127.0.0.1:<port>/ in the default browser
+```
+
+Slack app prerequisites — bot token scopes `app_mentions:read`,
+`chat:write`, `chat:write.customize`, `im:history`, `im:read`,
+`im:write`, `channels:history`, `reactions:write`; Socket Mode enabled;
+app token scope `connections:write`; invite the bot into every team
+channel. Tokens live exclusively in `~/.lazyclaw/.env` and never appear
+in agent/team/task records or logs.
+
+For the full data model + phase plan, see `docs/multi-agent.md`.
+
 ## Providers / sessions / skills
 
 ```bash
@@ -220,6 +344,8 @@ lazyclaw skills install ./my-skill.md
 lazyclaw skills remove review
 ```
 
+<img src="docs/screenshots/providers.png" alt="lazyclaw providers info anthropic — model list + capabilities" width="760">
+
 ## Workflows (DAG / sequential / persistent)
 
 ```bash
@@ -295,7 +421,7 @@ lazyclaw completion zsh  >> ~/.zshrc
 
 ## Issues / contributing
 
-Source lives in [cmblir/LazyClaude](https://github.com/cmblir/LazyClaude) under [`src/lazyclaw/`](https://github.com/cmblir/LazyClaude/tree/main/src/lazyclaw). Issues and PRs welcome on the parent repo.
+Source lives in [cmblir/lazyclaw](https://github.com/cmblir/lazyclaw). Issues and PRs welcome.
 
 ## License
 

package/agents.mjs

@@ -0,0 +1,179 @@
+// Persistent agent registry for `/agent` REPL command and `lazyclaw agent`
+// subcommand. Backs the Phase 9 piece of docs/multi-agent.md.
+//
+// Storage layout under <configDir>/agents/<name>.json. One file per
+// agent so concurrent edit / remove writes don't race over a global
+// index. Schema field set lives in `defaultShape()` below; new fields
+// default to null/empty so reading an older record stays
+// forward-compatible.
+//
+// Defaults reflect §10 of the multi-agent spec: a freshly created
+// agent gets the full tool whitelist (bash + read + write + grep)
+// because the user opted for "lazyclaw 모든 권한". Callers that want a
+// stricter posture can pass an explicit `tools` array.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { ensureValidName as cronEnsureValidName } from './cron.mjs';
+
+const AGENTS_DIRNAME = 'agents';
+
+export const DEFAULT_TOOLS = ['bash', 'read', 'write', 'grep'];
+export const ALL_TOOLS = ['bash', 'read', 'write', 'grep', 'web_search', 'web_fetch', 'slack_post'];
+
+export class AgentError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'AgentError';
+    this.code = code || 'AGENT_ERR';
+  }
+}
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function agentsDir(configDir = defaultConfigDir()) {
+  return path.join(configDir, AGENTS_DIRNAME);
+}
+
+export function agentPath(name, configDir = defaultConfigDir()) {
+  ensureValidName(name);
+  return path.join(agentsDir(configDir), `${name}.json`);
+}
+
+export function ensureValidName(name) {
+  try { cronEnsureValidName(name); }
+  catch (e) { throw new AgentError(e.message, 'AGENT_BAD_NAME'); }
+}
+
+function validateTools(tools) {
+  if (!Array.isArray(tools)) {
+    throw new AgentError('tools must be an array', 'AGENT_BAD_TOOLS');
+  }
+  const bad = tools.filter(t => !ALL_TOOLS.includes(t));
+  if (bad.length) {
+    throw new AgentError(`unknown tool(s): ${bad.join(', ')} — known: ${ALL_TOOLS.join(', ')}`, 'AGENT_BAD_TOOLS');
+  }
+  // Dedupe while preserving order.
+  return [...new Set(tools)];
+}
+
+function titleCase(s) {
+  return String(s).split(/[-_]/).map(p => p.charAt(0).toUpperCase() + p.slice(1)).join(' ');
+}
+
+function defaultShape(name) {
+  return {
+    version: 1,
+    name,
+    displayName: titleCase(name),
+    role: '',
+    provider: 'claude-cli',
+    model: '',
+    tools: [...DEFAULT_TOOLS],
+    tags: [],
+    iconEmoji: '',
+    // Phase 18 — agent memory write trigger. 'auto' means the router
+    // fires a reflection LLM call on terminal `done`; 'manual' waits
+    // for `lazyclaw agent reflect`; 'off' disables writes entirely.
+    memoryWrite: 'auto',
+    memoryMaxChars: 12 * 1024,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function writeAtomic(filePath, obj) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2));
+  fs.renameSync(tmp, filePath);
+}
+
+const VALID_MEMORY_WRITE = ['auto', 'manual', 'off'];
+
+export function registerAgent({ name, displayName, role = '', provider = 'claude-cli', model = '', tools, tags = [], iconEmoji = '', memoryWrite, memoryMaxChars } = {}, configDir = defaultConfigDir()) {
+  ensureValidName(name);
+  const p = agentPath(name, configDir);
+  if (fs.existsSync(p)) {
+    throw new AgentError(`agent "${name}" already exists`, 'AGENT_EXISTS');
+  }
+  const toolsClean = validateTools(tools ?? DEFAULT_TOOLS);
+  const mw = memoryWrite ?? 'auto';
+  if (!VALID_MEMORY_WRITE.includes(mw)) {
+    throw new AgentError(`memoryWrite must be one of ${VALID_MEMORY_WRITE.join(', ')}`, 'AGENT_BAD_MEMORY_WRITE');
+  }
+  const data = {
+    ...defaultShape(name),
+    displayName: displayName || titleCase(name),
+    role: String(role || ''),
+    provider: String(provider || 'claude-cli'),
+    model: String(model || ''),
+    tools: toolsClean,
+    tags: Array.isArray(tags) ? tags : [],
+    iconEmoji: String(iconEmoji || ''),
+    memoryWrite: mw,
+    memoryMaxChars: Number.isFinite(+memoryMaxChars) && +memoryMaxChars > 0 ? +memoryMaxChars : 12 * 1024,
+  };
+  writeAtomic(p, data);
+  return data;
+}
+
+export function getAgent(name, configDir = defaultConfigDir()) {
+  let p;
+  try { p = agentPath(name, configDir); }
+  catch { return null; }
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+export function listAgents(configDir = defaultConfigDir()) {
+  const dir = agentsDir(configDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.json')) continue;
+    const name = f.slice(0, -5);
+    const a = getAgent(name, configDir);
+    if (a) out.push(a);
+  }
+  out.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+  return out;
+}
+
+export function patchAgent(name, patch, configDir = defaultConfigDir()) {
+  const a = getAgent(name, configDir);
+  if (!a) throw new AgentError(`no agent "${name}"`, 'AGENT_NO_AGENT');
+  const next = { ...a, ...patch, updatedAt: new Date().toISOString() };
+  if (patch.tools !== undefined) {
+    next.tools = validateTools(patch.tools);
+  }
+  if (patch.memoryWrite !== undefined && !VALID_MEMORY_WRITE.includes(patch.memoryWrite)) {
+    throw new AgentError(`memoryWrite must be one of ${VALID_MEMORY_WRITE.join(', ')}`, 'AGENT_BAD_MEMORY_WRITE');
+  }
+  writeAtomic(agentPath(name, configDir), next);
+  return next;
+}
+
+export function removeAgent(name, configDir = defaultConfigDir()) {
+  const p = agentPath(name, configDir);
+  if (!fs.existsSync(p)) {
+    throw new AgentError(`no agent "${name}"`, 'AGENT_NO_AGENT');
+  }
+  fs.unlinkSync(p);
+  return { name, removed: true };
+}
+
+// Parse a comma-separated tool list from CLI flag form. Empty / null
+// input returns null so the caller can decide between "user didn't say"
+// (→ keep existing or default) and "user said []" (→ disallow all).
+export function parseToolsFlag(raw) {
+  if (raw === undefined || raw === null) return null;
+  const s = String(raw).trim();
+  if (s === '') return [];
+  return s.split(',').map(t => t.trim()).filter(Boolean);
+}

package/channels/base.mjs

@@ -0,0 +1,120 @@
+// Abstract base for a daemon channel.
+//
+// A Channel owns a transport (HTTP, Slack Socket Mode, in-memory stub, …).
+// It calls `handler({ channel, threadId, text })` once per inbound message
+// and emits the resolved reply through `send(threadId, text)`.
+//
+// Cross-cutting concerns (auth, rate-limit, allowed-origin, audit) live
+// outside the channel itself: when a Channel wants to apply them, it
+// calls `applyGate(req)` first. Concrete subclasses pass the gate object
+// down at start time so every channel runs the same middleware chain
+// that today's HTTP daemon enforces on `POST /agent`.
+
+export class Channel {
+  constructor(name) {
+    this.name = String(name || 'unnamed');
+    /** @type {((evt: { channel: string, threadId: string, text: string }) => Promise<string>) | null} */
+    this._handler = null;
+    /** @type {{ check: (req: { token?: string|null, key?: string|null }) => { ok: boolean, reason?: string } } | null} */
+    this._gate = null;
+    this._started = false;
+  }
+
+  /**
+   * Begin accepting messages. The concrete subclass starts its transport
+   * here (e.g. createServer + listen for HTTP, Socket Mode for Slack,
+   * nothing for the stub). Must be safe to call once per instance.
+   *
+   * @param {(evt: { channel: string, threadId: string, text: string }) => Promise<string>} handler
+   * @param {{ gate?: { check: (req: any) => { ok: boolean, reason?: string } } }} [opts]
+   */
+  async start(handler, opts = {}) {
+    if (this._started) throw new Error(`channel "${this.name}" already started`);
+    this._handler = handler;
+    this._gate = opts.gate || null;
+    this._started = true;
+  }
+
+  /**
+   * Deliver a reply to the caller identified by threadId. The shape of
+   * threadId is channel-specific (a Slack channel/thread, a stub inbox
+   * key, an HTTP request id). Subclasses override.
+   *
+   * @param {string} threadId
+   * @param {string} text
+   */
+  async send(_threadId, _text) {
+    throw new Error(`${this.constructor.name}.send() not implemented`);
+  }
+
+  /**
+   * Tear down the transport. Must be idempotent — channel managers call
+   * this on every channel during shutdown without first checking whether
+   * the channel ever started.
+   */
+  async stop() {
+    this._started = false;
+    this._handler = null;
+    this._gate = null;
+  }
+
+  /**
+   * Subclasses call this from their inbound paths before invoking the
+   * handler. Returns the handler's reply on success, throws ChannelGated
+   * on auth/rate-limit denial.
+   */
+  async _processInbound({ threadId, text, gateInput }) {
+    if (this._gate) {
+      const verdict = this._gate.check(gateInput || {});
+      if (!verdict.ok) {
+        const err = new Error(verdict.reason || 'denied');
+        err.code = 'CHANNEL_GATED';
+        throw err;
+      }
+    }
+    if (!this._handler) throw new Error(`channel "${this.name}" has no handler`);
+    return await this._handler({ channel: this.name, threadId, text });
+  }
+}
+
+export class ChannelGated extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ChannelGated';
+    this.code = code || 'CHANNEL_GATED';
+  }
+}
+
+// Tiny token-bucket gate used by stub + slack channels. The HTTP channel
+// continues to use daemon.mjs's in-tree limiter so the regression path
+// is byte-identical.
+export function makeBucketGate({ authToken = null, rateLimit = null } = {}) {
+  const limiter = rateLimit
+    ? makeTokenBucket(rateLimit.capacity ?? 20, rateLimit.refillPerSec ?? 1)
+    : null;
+  return {
+    check(req) {
+      if (authToken) {
+        const presented = req.token || req.key || null;
+        if (!presented || presented !== authToken) return { ok: false, reason: 'unauthorized' };
+      }
+      if (limiter && !limiter.take(1)) return { ok: false, reason: 'rate_limited' };
+      return { ok: true };
+    },
+  };
+}
+
+function makeTokenBucket(capacity, refillPerSec) {
+  let tokens = capacity;
+  let last = Date.now();
+  return {
+    take(n) {
+      const now = Date.now();
+      const elapsed = (now - last) / 1000;
+      tokens = Math.min(capacity, tokens + elapsed * refillPerSec);
+      last = now;
+      if (tokens >= n) { tokens -= n; return true; }
+      return false;
+    },
+  };
+}

package/channels/http.mjs

@@ -0,0 +1,54 @@
+// HTTP channel adapter.
+//
+// Phase 7 introduces a Channel abstraction but does NOT relocate the
+// existing daemon's HTTP routing — that surface is large (POST /agent,
+// /chat, /sessions, /workflows, /skills, the dashboard SPA …) and a
+// byte-identical refactor is high-risk. Instead, this adapter wraps
+// daemon.mjs.startDaemon so callers that want a uniform Channel handle
+// (start/send/stop) get one, while the regression path (`lazyclaw
+// daemon` with no --channels flag) stays untouched.
+//
+// `send(threadId, text)` is a no-op for HTTP: the daemon's response is
+// streamed back synchronously via SSE on the original request, not via
+// a separate push. The method exists for interface conformance.
+
+import { Channel } from './base.mjs';
+
+export class HttpChannel extends Channel {
+  constructor(opts = {}) {
+    super('http');
+    this._opts = opts;
+    this._daemon = null;
+  }
+
+  async start(handler, opts = {}) {
+    await super.start(handler, opts);
+    // Lazy import so a `--channels stub` setup doesn't pay the cost of
+    // pulling in the full daemon module.
+    const { startDaemon } = await import('../daemon.mjs');
+    this._daemon = await startDaemon({
+      ...this._opts,
+      // The handler the daemon owns is unchanged — it talks to providers
+      // through ctx.readConfig/providersMod. We're just standing the
+      // existing daemon up under the channel interface so a future
+      // unified runtime can speak HTTP through the same `Channel` shape.
+    });
+    return this._daemon;
+  }
+
+  async send(_threadId, _text) {
+    // HTTP replies are streamed in-line on the original request handler
+    // (SSE chunks for POST /agent). Nothing to push.
+  }
+
+  get port() { return this._daemon?.port ?? this._opts.port ?? null; }
+  get url()  { return this._daemon?.url  ?? null; }
+
+  async stop() {
+    if (this._daemon && typeof this._daemon.close === 'function') {
+      await this._daemon.close();
+    }
+    this._daemon = null;
+    await super.stop();
+  }
+}