lazyclaw 3.99.20 → 3.99.22

package/README.md

@@ -81,6 +81,49 @@ lazyclaw onboard --non-interactive --provider nim \
 
 Need a vendor that's **not** built-in? `+ Add a custom OpenAI-compatible endpoint…` inside the setup picker (or `lazyclaw providers add <name> --base-url <url>`) still works for vLLM / LM Studio / private gateways / anything else that speaks the OpenAI v1 wire format.
 
+### `orchestrator` — multi-agent dispatch as a provider
+
+`orchestrator` is a synthetic provider that composes the others. A chat message hitting `PROVIDERS.orchestrator` triggers a three-phase pipeline instead of a single 1:1 call:
+
+1. **PLAN** — the *planner* provider decomposes the request into 2–5 parallel subtasks (JSON-only system prompt; fences / prose tolerated).
+2. **EXECUTE** — each subtask is dispatched round-robin across the *workers*. Replies stream inline so you watch progress in real time.
+3. **SYNTHESIS** — the planner re-enters with every worker's output and writes the final user-facing answer.
+
+Configure in `~/.lazyclaw/config.json`:
+
+```json
+{
+  "provider": "orchestrator",
+  "orchestrator": {
+    "planner": "claude-cli:claude-opus-4-7",
+    "workers": [
+      "claude-cli:claude-sonnet-4-6",
+      "openai:gpt-4o",
+      "gemini:gemini-2.5-pro",
+      "nim:meta/llama-3.1-405b-instruct"
+    ],
+    "maxSubtasks": 5
+  }
+}
+```
+
+Then `lazyclaw chat` (or any other entry point that ends up calling a provider — `lazyclaw agent`, the daemon's `POST /agent` / `POST /chat`, the dashboard chat tab) routes through the orchestrator. Each worker's api-key is resolved through the same chain a direct chat would use (`authProfiles` → `customProviders` → built-in env var → legacy `cfg['api-key']`).
+
+Defaults fall back gracefully: `planner` defaults to `cfg.provider`/`cfg.model`, `workers` defaults to `[planner]` (single-agent chain, still benefits from plan + synthesis structure). Self-recursion (`planner: "orchestrator"`) is rejected up front.
+
+You can skip the JSON entirely and configure via `lazyclaw onboard` / `lazyclaw setup` (the picker lands on the orchestrator and walks you through a planner + workers wizard) **or** via the dedicated CLI:
+
+```bash
+lazyclaw orchestrator status
+lazyclaw orchestrator set-planner claude-cli:claude-opus-4-7
+lazyclaw orchestrator workers add openai:gpt-4o
+lazyclaw orchestrator workers add gemini:gemini-2.5-pro
+lazyclaw orchestrator workers set claude-cli:claude-sonnet-4-6,nim:meta/llama-3.1-405b-instruct   # bulk replace
+lazyclaw orchestrator set-max-subtasks 5
+lazyclaw orchestrator clear                                                                       # wipe cfg.orchestrator
+lazyclaw config set provider orchestrator                                                          # route chats through it
+```
+
 ## Launcher (no-arg `lazyclaw`)
 
 Running `lazyclaw` with no subcommand drops into an arrow-key launcher with every subcommand laid out as a menu. Navigation:

package/cli.mjs

@@ -707,6 +707,18 @@ async function ensureRegistry() {
       _registryMod.registerCustomProviders(readConfig());
     }
   } catch { /* never let a malformed cfg.customProviders block startup */ }
+  // Wire the orchestrator's live cfg + auth-key resolver. We do this on
+  // every ensureRegistry() call (cheap — just replaces the closure) so a
+  // mid-session config edit (custom provider added, env var exported)
+  // takes effect on the next orchestrator turn without a restart.
+  try {
+    if (typeof _registryMod.registerOrchestrator === 'function') {
+      _registryMod.registerOrchestrator({
+        cfgGetter: readConfig,
+        keyResolver: _resolveAuthKey,
+      });
+    }
+  } catch { /* defensive */ }
   return _registryMod;
 }
 
@@ -902,6 +914,8 @@ const SUBCOMMANDS = [
   'auth', 'pairing', 'nodes', 'message', 'workspace', 'browse', 'cron',
   // v3.99.6 — multi-step setup wizard + lazyclaw-only dashboard
   'setup', 'dashboard',
+  // v3.99.22 — multi-agent orchestrator config
+  'orchestrator',
 ];
 
 const SUBCOMMAND_SUBS = {
@@ -917,6 +931,7 @@ const SUBCOMMAND_SUBS = {
   message:   ['list', 'add', 'remove', 'send'],
   workspace: ['list', 'init', 'show', 'remove', 'path'],
   cron:      ['list', 'add', 'remove', 'show', 'sync', 'run'],
+  orchestrator: ['status', 'set-planner', 'workers', 'set-max-subtasks', 'clear'],
 };
 
 function bashCompletion() {
@@ -1173,6 +1188,7 @@ const HELP_DETAILS = {
   cron: 'Usage: lazyclaw cron <list | add <name> "<cron-spec>" -- <cmd> ... | remove <name> | show <name> | sync | run <name>>\n  Schedule recurring agent runs. macOS uses launchd (~/Library/LaunchAgents/com.lazyclaw.<name>.plist); Linux / WSL uses the user crontab.\n  Cron spec is the standard 5-field form (minute hour dom month dow). Supports *, range a-b, list a,b,c, step */N.\n  add: pass the command after `--`. Typical use:\n      lazyclaw cron add daily-summary "0 9 * * 1-5" -- lazyclaw agent "Summarise today\'s TODOs"\n  list / show: read from cfg.cron[name] (config is the source of truth).\n  sync: re-installs every job in cfg.cron into the system scheduler — handy after a reinstall.\n  run: one-shot in-process execution of the named job; the OS scheduler does the same thing on its trigger.\n  Logs: ~/.lazyclaw/logs/cron-<name>.{out,err}.log (macOS launchd path).',
   setup: 'Usage: lazyclaw setup [--skip-test]\n  OpenClaw-style multi-step first-run wizard. Walks through:\n    1. Provider + model + api-key (delegates to onboard --pick)\n    2. Optional workspace init  (AGENTS.md / SOUL.md / TOOLS.md)\n    3. Optional skill bundle install from GitHub\n    4. Optional outbound webhook (Slack / Discord)\n    5. Reachability test against the picked provider\n  Each optional step takes Enter or "skip" to bypass. Re-runnable safely.\n  Also fires automatically on first run when `lazyclaw` is invoked with no config.',
   dashboard: 'Usage: lazyclaw dashboard [--port <N>] [--no-open]\n  Launches the lazyclaw-only web UI on http://127.0.0.1:<port> (default 19600) and opens it in the default browser.\n  Wraps `lazyclaw daemon` + a static HTML; no Python / lazyclaude dashboard required.\n  Tabs: Chat · Sessions · Skills · Workspace · Providers · Status. Each tab calls existing daemon endpoints.\n  --no-open keeps the browser closed (handy for SSH / headless / dev). The bound URL is always printed to stdout.',
+  orchestrator: 'Usage: lazyclaw orchestrator <status | set-planner <provider[:model]> | workers add <spec> | workers remove <spec> | workers set <spec,spec,...> | workers clear | set-max-subtasks <N> | clear>\n  Read/write cfg.orchestrator without editing config.json by hand.\n  status               — print {planner, workers, maxSubtasks} as JSON; lists registered providers for reference.\n  set-planner          — replace the planner spec ("provider" or "provider:model"). "orchestrator" itself is rejected (self-recursion).\n  workers add          — append a worker (idempotent — duplicates skipped).\n  workers remove       — drop a worker by exact match. Idempotent.\n  workers set          — replace the whole list (comma-separated specs).\n  workers clear        — empty the workers list.\n  set-max-subtasks <N> — cap subtasks per request, clamped 1..10 (default 5).\n  clear                — delete the cfg.orchestrator block entirely.\n  Pair with: `lazyclaw config set provider orchestrator` to route chats through it.',
 };
 
 function cmdHelp(name) {
@@ -1823,7 +1839,17 @@ async function _pickProviderInteractive() {
     provider = picked;
   }
 
-  // ── Step 3 — model ────────────────────────────────────────────
+  // ── Step 3 — model (or, for composite providers, a config wizard) ───
+  // The orchestrator (and any future composite provider) has no model
+  // of its own — it dispatches to other providers. Step 3 routes
+  // through a custom wizard instead of the standard model picker.
+  const providerMeta = (_registryMod.PROVIDER_INFO || {})[provider.id] || {};
+  if (providerMeta.composite || provider.id === 'orchestrator') {
+    const result = await _setupOrchestratorInteractive();
+    if (result === 'CANCEL') return null;
+    if (result === 'BACK')   return _pickProviderInteractive();
+    return { provider: provider.id, model: 'orchestrator' };
+  }
   const picked = await _pickModelInteractive(provider.id, {
     titlePrefix: 'LazyClaw setup — Step 3 of 3:',
     onBack: 'restart',
@@ -1833,6 +1859,125 @@ async function _pickProviderInteractive() {
   return { provider: provider.id, model: picked };
 }
 
+// Step-3 alternative for composite providers (currently only the
+// orchestrator). Builds `cfg.orchestrator = { planner, workers,
+// maxSubtasks }` interactively and persists it before returning.
+//
+// planner: single picker over registered non-composite providers.
+// workers: multi-select with a running list + add/remove/done loop.
+// maxSubtasks: typed integer, default 5.
+async function _setupOrchestratorInteractive() {
+  const accent = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
+  const dim    = (s) => `\x1b[2m${s}\x1b[0m`;
+  const bold   = (s) => `\x1b[1m${s}\x1b[0m`;
+  const ok     = (s) => `\x1b[32m${s}\x1b[0m`;
+  const info = _registryMod.PROVIDER_INFO || {};
+  const eligibleNames = Object.keys(_registryMod.PROVIDERS).filter((n) => n !== 'orchestrator' && n !== 'mock');
+  if (eligibleNames.length === 0) {
+    process.stdout.write('\n' + accent('orchestrator setup') + ': no eligible workers — register a real provider first.\n');
+    await _quickPrompt('  press Enter to continue ');
+    return 'CANCEL';
+  }
+  const cfg = readConfig();
+  const existing = cfg.orchestrator && typeof cfg.orchestrator === 'object' ? cfg.orchestrator : {};
+
+  // ── Pick planner ─────────────────────────────────────────────────
+  const plannerItems = eligibleNames.map((name) => {
+    const m = info[name] || {};
+    const defaultModel = m.defaultModel || '';
+    return {
+      id: `${name}${defaultModel ? ':' + defaultModel : ''}`,
+      label: m.label && m.label !== name ? `${name} — ${m.label}` : name,
+      desc: defaultModel ? `default model: ${defaultModel}` : '',
+    };
+  });
+  const plannerPick = await _arrowMenu({
+    title: 'LazyClaw setup — Step 3 of 3:  orchestrator — pick the planner',
+    subtitle: 'The planner decomposes the user request into subtasks and writes the final synthesis. Strong reasoning models work best here.',
+    items: plannerItems,
+    searchable: true,
+    defaultIdx: Math.max(0, plannerItems.findIndex((p) => p.id === existing.planner)),
+  });
+  if (plannerPick === 'CANCEL') return 'CANCEL';
+  if (plannerPick === 'BACK')   return 'BACK';
+  const planner = plannerPick.id;
+
+  // ── Pick workers (iterative add/remove) ──────────────────────────
+  const workers = Array.isArray(existing.workers) ? existing.workers.slice() : [];
+  while (true) {
+    process.stdout.write('\x1b[2J\x1b[H');
+    process.stdout.write(accent('Orchestrator workers') + '\n');
+    process.stdout.write(dim('Subtasks are dispatched round-robin across this list.') + '\n\n');
+    if (workers.length === 0) {
+      process.stdout.write('  ' + dim('(none yet — add at least one)') + '\n\n');
+    } else {
+      workers.forEach((w, i) => {
+        process.stdout.write(`  ${i + 1}. ${ok(w)}\n`);
+      });
+      process.stdout.write('\n');
+    }
+    const items = [
+      { id: '__add__',    label: '+ Add a worker',     desc: 'pick from registered providers' },
+      { id: '__remove__', label: '- Remove a worker',  desc: workers.length ? 'pick which entry to drop' : '(nothing to remove)' },
+      { id: '__done__',   label: `Done${workers.length ? ` (${workers.length} worker${workers.length === 1 ? '' : 's'})` : ' — at least one worker required'}`, desc: workers.length ? 'save cfg.orchestrator and finish' : 'add one worker first' },
+    ];
+    const action = await _arrowMenu({
+      title: 'LazyClaw setup — orchestrator workers',
+      subtitle: `Planner: ${planner}`,
+      items,
+    });
+    if (action === 'CANCEL') return 'CANCEL';
+    if (action === 'BACK')   return 'BACK';
+    if (action.id === '__add__') {
+      const wPick = await _arrowMenu({
+        title: 'Add worker',
+        subtitle: 'Picked entries are appended to the workers list.',
+        items: plannerItems.filter((p) => !workers.includes(p.id)),
+        searchable: true,
+      });
+      if (wPick === 'CANCEL' || wPick === 'BACK') continue;
+      workers.push(wPick.id);
+      continue;
+    }
+    if (action.id === '__remove__') {
+      if (!workers.length) continue;
+      const rPick = await _arrowMenu({
+        title: 'Remove worker',
+        subtitle: 'Highlighted entry is removed from the list.',
+        items: workers.map((w) => ({ id: w, label: w })),
+      });
+      if (rPick === 'CANCEL' || rPick === 'BACK') continue;
+      const idx = workers.indexOf(rPick.id);
+      if (idx >= 0) workers.splice(idx, 1);
+      continue;
+    }
+    if (action.id === '__done__') {
+      if (workers.length === 0) continue;
+      break;
+    }
+  }
+
+  // ── maxSubtasks ──────────────────────────────────────────────────
+  const defaultMax = Number.isFinite(existing.maxSubtasks) && existing.maxSubtasks > 0
+    ? Math.min(10, existing.maxSubtasks)
+    : 5;
+  const rawMax = (await _quickPrompt(`  ${bold('maxSubtasks')} ${dim(`(2..10, blank → ${defaultMax}):`)} `)).trim();
+  let maxSubtasks = defaultMax;
+  if (rawMax) {
+    const n = parseInt(rawMax, 10);
+    if (Number.isFinite(n) && n >= 1) maxSubtasks = Math.min(10, Math.max(1, n));
+  }
+
+  // ── Persist ──────────────────────────────────────────────────────
+  cfg.orchestrator = { planner, workers, maxSubtasks };
+  writeConfig(cfg);
+  process.stdout.write('\n');
+  process.stdout.write(`  ${ok('✓ orchestrator saved')}  ${dim('→')} ` +
+    `planner ${ok(planner)}  ·  ${workers.length} worker${workers.length === 1 ? '' : 's'}  ·  maxSubtasks ${maxSubtasks}\n`);
+  await _quickPrompt('  press Enter to continue ');
+  return { ok: true };
+}
+
 // Pause the chat REPL's readline + ghost-autocomplete while a sub-picker
 // (provider / model arrow menu) takes over the terminal. The sub-picker
 // installs its own `keypress` listener and toggles raw mode; the chat's
@@ -3710,6 +3855,126 @@ async function cmdProviders(sub, positional, flags = {}) {
   }
 }
 
+// `lazyclaw orchestrator` — read/write the cfg.orchestrator section
+// without editing config.json by hand. Mirrors the shape `lazyclaw
+// providers` / `lazyclaw rates` already use.
+//
+// Subcommands:
+//   status                        Print current planner / workers / maxSubtasks as JSON.
+//   set-planner <provider[:model]>  Replace the planner spec.
+//   workers add <provider[:model]>  Append a worker (idempotent — duplicates skipped).
+//   workers remove <provider[:model]>  Drop a worker by exact match. Idempotent.
+//   workers clear                 Empty the workers list.
+//   workers set <provider[:model],...>  Replace the whole list (comma-separated).
+//   set-max-subtasks <N>          Cap the number of subtasks (clamped 1..10).
+//   clear                         Delete the entire cfg.orchestrator block.
+async function cmdOrchestrator(sub, positional, _flags = {}) {
+  await ensureRegistry();
+  const cfg = readConfig();
+  const orch = cfg.orchestrator && typeof cfg.orchestrator === 'object' ? cfg.orchestrator : {};
+  const known = Object.keys(_registryMod.PROVIDERS);
+  const validateSpec = (spec) => {
+    if (!spec) throw new Error('provider spec required (e.g. "claude-cli" or "openai:gpt-4o")');
+    const colon = spec.indexOf(':');
+    const provName = colon > 0 ? spec.slice(0, colon) : spec;
+    if (provName === 'orchestrator') throw new Error('"orchestrator" cannot reference itself — pick a real provider');
+    if (!known.includes(provName)) {
+      throw new Error(`unknown provider "${provName}" — registered: ${known.join(', ')}`);
+    }
+    return spec;
+  };
+  const saveAndPrint = (next) => {
+    if (next === null) delete cfg.orchestrator;
+    else cfg.orchestrator = next;
+    writeConfig(cfg);
+    console.log(JSON.stringify(cfg.orchestrator || null, null, 2));
+  };
+  switch (sub) {
+    case undefined:
+    case 'status': {
+      console.log(JSON.stringify({
+        ok: true,
+        configured: !!cfg.orchestrator,
+        planner: orch.planner || null,
+        workers: Array.isArray(orch.workers) ? orch.workers : [],
+        maxSubtasks: Number.isFinite(orch.maxSubtasks) ? orch.maxSubtasks : null,
+        knownProviders: known,
+      }, null, 2));
+      return;
+    }
+    case 'set-planner': {
+      try {
+        const spec = validateSpec(positional[0]);
+        saveAndPrint({ ...orch, planner: spec });
+      } catch (e) { console.error(`orchestrator: ${e.message}`); process.exit(2); }
+      return;
+    }
+    case 'workers': {
+      const wsub = positional[0];
+      const workers = Array.isArray(orch.workers) ? orch.workers.slice() : [];
+      switch (wsub) {
+        case 'add': {
+          try {
+            const spec = validateSpec(positional[1]);
+            if (!workers.includes(spec)) workers.push(spec);
+            saveAndPrint({ ...orch, workers });
+          } catch (e) { console.error(`orchestrator: ${e.message}`); process.exit(2); }
+          return;
+        }
+        case 'remove': {
+          const spec = positional[1];
+          if (!spec) { console.error('orchestrator: workers remove <provider[:model]>'); process.exit(2); }
+          const idx = workers.indexOf(spec);
+          if (idx >= 0) workers.splice(idx, 1);
+          saveAndPrint({ ...orch, workers });
+          return;
+        }
+        case 'clear': {
+          saveAndPrint({ ...orch, workers: [] });
+          return;
+        }
+        case 'set': {
+          const raw = positional[1] || '';
+          const specs = raw.split(',').map((s) => s.trim()).filter(Boolean);
+          try {
+            specs.forEach(validateSpec);
+            saveAndPrint({ ...orch, workers: specs });
+          } catch (e) { console.error(`orchestrator: ${e.message}`); process.exit(2); }
+          return;
+        }
+        default: {
+          console.error('Usage: lazyclaw orchestrator workers <add <spec> | remove <spec> | clear | set <spec,spec,...>>');
+          process.exit(2);
+        }
+      }
+    }
+    case 'set-max-subtasks': {
+      const n = parseInt(positional[0], 10);
+      if (!Number.isFinite(n) || n < 1) { console.error('orchestrator: set-max-subtasks <N>  (1..10)'); process.exit(2); }
+      saveAndPrint({ ...orch, maxSubtasks: Math.min(10, Math.max(1, n)) });
+      return;
+    }
+    case 'clear': {
+      saveAndPrint(null);
+      return;
+    }
+    default: {
+      console.error(
+        'Usage:\n' +
+        '  lazyclaw orchestrator status\n' +
+        '  lazyclaw orchestrator set-planner <provider[:model]>\n' +
+        '  lazyclaw orchestrator workers add <provider[:model]>\n' +
+        '  lazyclaw orchestrator workers remove <provider[:model]>\n' +
+        '  lazyclaw orchestrator workers set <provider[:model],...>\n' +
+        '  lazyclaw orchestrator workers clear\n' +
+        '  lazyclaw orchestrator set-max-subtasks <N>\n' +
+        '  lazyclaw orchestrator clear'
+      );
+      process.exit(2);
+    }
+  }
+}
+
 async function cmdSessions(sub, positional, flags = {}) {
   const sessionsMod = await import('./sessions.mjs');
   const cfgDir = path.dirname(configPath());
@@ -4602,6 +4867,11 @@ async function main() {
       await cmdProviders(sub, rest.positional.slice(1), rest.flags);
       break;
     }
+    case 'orchestrator': {
+      const sub = rest.positional[0];
+      await cmdOrchestrator(sub, rest.positional.slice(1), rest.flags);
+      break;
+    }
     case 'skills': {
       const sub = rest.positional[0];
       await cmdSkills(sub, rest.positional.slice(1), rest.flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "3.99.20",
+  "version": "3.99.22",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama and orchestrating multi-step LLM workflows. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",

package/providers/orchestrator.mjs

@@ -0,0 +1,281 @@
+// Orchestrator provider — "openclaw-style" multi-agent dispatch.
+//
+// A user message arriving at PROVIDERS.orchestrator is NOT forwarded
+// 1:1 to a single backend. Instead the provider performs three phases:
+//
+//   1. PLAN     — the configured planner provider decomposes the task
+//                 into 2–5 self-contained subtasks (JSON shape).
+//   2. EXECUTE  — each subtask is dispatched to a worker provider
+//                 (round-robin over cfg.orchestrator.workers). Workers
+//                 stream their replies; the orchestrator surfaces them
+//                 inline so the user can watch progress.
+//   3. SYNTHESIS — the planner re-enters with all subtask outputs and
+//                 produces the final answer.
+//
+// Provider/model spec is "<provider>:<model>" (same shape as the chat
+// REPL's `/model anthropic/claude-opus-4-7` after normalisation). When
+// the model part is omitted, the worker's defaultModel from
+// PROVIDER_INFO is used.
+//
+// Config (~/.lazyclaw/config.json):
+//   {
+//     "orchestrator": {
+//       "planner": "claude-cli:claude-opus-4-7",
+//       "workers": [
+//         "claude-cli:claude-sonnet-4-6",
+//         "openai:gpt-4o",
+//         "gemini:gemini-2.5-pro"
+//       ],
+//       "maxSubtasks": 5,       // optional, default 5
+//       "concurrency": 0        // optional, 0 = sequential (visible streaming)
+//     }
+//   }
+//
+// Defaults: planner = the user's currently configured `cfg.provider`
+// (so `lazyclaw onboard --provider claude-cli` works without any extra
+// step), workers = [planner] (degenerates to a single-agent chain that
+// still benefits from plan + synthesis structure).
+
+import { PROVIDERS, PROVIDER_INFO } from './registry.mjs';
+
+function _parseSpec(spec) {
+  if (!spec || typeof spec !== 'string') return { provider: '', model: '' };
+  const colon = spec.indexOf(':');
+  if (colon < 0) return { provider: spec.trim(), model: '' };
+  return { provider: spec.slice(0, colon).trim(), model: spec.slice(colon + 1).trim() };
+}
+
+function _lookupProvider(spec) {
+  const { provider, model } = _parseSpec(spec);
+  const prov = PROVIDERS[provider];
+  if (!prov) return null;
+  const info = PROVIDER_INFO[provider] || {};
+  return {
+    name: provider,
+    model: model || info.defaultModel || '',
+    prov,
+    info,
+  };
+}
+
+function _bestPlanArray(text) {
+  // Planners sometimes wrap the JSON in prose / code fences. Try the
+  // raw response first, then the largest [...] / [...]-shaped span.
+  const tryParse = (s) => {
+    try { return JSON.parse(s); } catch { return null; }
+  };
+  let arr = tryParse(text);
+  if (Array.isArray(arr)) return arr;
+  // Strip ```json fences
+  const fence = text.match(/```(?:json)?\s*([\s\S]+?)```/);
+  if (fence) {
+    arr = tryParse(fence[1].trim());
+    if (Array.isArray(arr)) return arr;
+  }
+  // Largest [...] substring
+  const start = text.indexOf('[');
+  const end = text.lastIndexOf(']');
+  if (start >= 0 && end > start) {
+    arr = tryParse(text.slice(start, end + 1));
+    if (Array.isArray(arr)) return arr;
+  }
+  return null;
+}
+
+const PLANNER_SYSTEM = `You are an orchestrator that decomposes a user request into independent subtasks for parallel worker agents.
+
+Rules:
+- Output ONLY a JSON array. No prose, no markdown, no code fences.
+- Each entry has shape { "id": <int>, "task": "<one-sentence imperative>", "rationale": "<why this is a useful slice>" }.
+- 2 to 5 subtasks. Each must be doable WITHOUT seeing the others' outputs (parallel-safe).
+- If the request is genuinely atomic (e.g. "say hi"), return a single-element array.
+- Do not add a synthesis / merge step — that runs separately after workers complete.
+- Subtasks must be self-contained: include any context a worker needs to act on the task alone.`;
+
+const SYNTHESIS_SYSTEM = `You are an orchestrator producing the final answer for the user.
+
+You receive: (1) the user's original request, (2) the subtask plan you produced, (3) each worker's response.
+
+Rules:
+- Synthesize a single coherent answer. Distill — do not echo each worker verbatim.
+- Cite worker findings briefly when they meaningfully diverge ("Worker A found …, Worker B confirmed").
+- If a worker failed, acknowledge it but do not let it block the rest of the answer.
+- Match the tone and length the user implied (one-line question → one-line answer; deep dive → deep dive).
+- No JSON; this is the human-facing reply.`;
+
+/**
+ * Build an orchestrator provider. The chat REPL / agent / daemon path
+ * treats it like any other provider — the `sendMessage` async iterable
+ * yields markdown chunks describing plan + subtasks + synthesis.
+ *
+ * @param {Object} [opts]
+ * @param {() => Record<string, unknown>} [opts.cfgGetter] reads ~/.lazyclaw/config.json
+ * @param {(cfg, provider) => string} [opts.keyResolver] returns api-key for a worker provider (mirrors cli.mjs::_resolveAuthKey)
+ */
+export function makeOrchestratorProvider(opts = {}) {
+  const cfgGetter = typeof opts.cfgGetter === 'function' ? opts.cfgGetter : () => ({});
+  const keyResolver = typeof opts.keyResolver === 'function' ? opts.keyResolver : () => '';
+
+  return {
+    name: 'orchestrator',
+    async *sendMessage(messages, callerOpts = {}) {
+      const cfg = cfgGetter() || {};
+      const o = cfg.orchestrator && typeof cfg.orchestrator === 'object' ? cfg.orchestrator : {};
+      const fallbackSpec = cfg.provider && cfg.provider !== 'orchestrator'
+        ? `${cfg.provider}${cfg.model ? ':' + cfg.model : ''}`
+        : 'claude-cli';
+      // First-run hint when cfg.orchestrator is missing entirely. The
+      // fallback path below still works (planner = cfg.provider, single
+      // worker = same), but the user almost certainly meant to opt in
+      // explicitly — surface the shortest valid CLI to set it up.
+      if (!cfg.orchestrator) {
+        yield `> orchestrator: \`cfg.orchestrator\` is not set. Defaulting to a single-agent chain on \`${fallbackSpec}\`.\n` +
+          `> Configure properly:  \`lazyclaw orchestrator set-planner ${fallbackSpec}\` then  \`lazyclaw orchestrator workers add <provider:model>\` (one per agent).\n\n`;
+      }
+      const plannerSpec = String(o.planner || fallbackSpec);
+      const workerSpecs = Array.isArray(o.workers) && o.workers.length
+        ? o.workers.map(String)
+        : [plannerSpec];
+      const maxSubtasks = Number.isFinite(o.maxSubtasks) && o.maxSubtasks > 0 ? Math.min(10, o.maxSubtasks) : 5;
+
+      const planner = _lookupProvider(plannerSpec);
+      if (!planner) {
+        yield `⚠ orchestrator: planner provider "${plannerSpec}" is not registered. ` +
+          `Set cfg.orchestrator.planner to a valid "provider:model" (e.g. "claude-cli:claude-opus-4-7").\n`;
+        return;
+      }
+      // Self-recursion guard: a misconfigured cfg.orchestrator.planner =
+      // "orchestrator" would otherwise spin forever, with each call
+      // dispatching back to itself.
+      if (planner.name === 'orchestrator') {
+        yield `⚠ orchestrator: planner cannot be "orchestrator" — set cfg.orchestrator.planner to a real provider (e.g. "claude-cli:claude-opus-4-7").\n`;
+        return;
+      }
+      const workers = workerSpecs.map(_lookupProvider).filter(Boolean).filter(w => w.name !== 'orchestrator');
+      if (workers.length === 0) {
+        yield `⚠ orchestrator: no usable workers (cfg.orchestrator.workers is empty, all unknown, or only references "orchestrator" itself).\n`;
+        return;
+      }
+
+      const userText = (() => {
+        // Most recent user message becomes the orchestration target. We
+        // pass earlier turns as context to the planner only — workers
+        // see a self-contained subtask string, not chat history.
+        for (let i = messages.length - 1; i >= 0; i--) {
+          if (messages[i].role === 'user') return String(messages[i].content || '');
+        }
+        return '';
+      })();
+
+      // ── Phase 1: PLAN ───────────────────────────────────────────────
+      yield `## 🦞 Orchestrator\n\n`;
+      yield `Planner: \`${planner.name}${planner.model ? ':' + planner.model : ''}\`  ·  Workers: ${workers.map(w => `\`${w.name}${w.model ? ':' + w.model : ''}\``).join(', ')}\n\n`;
+      yield `### 1. Planning\n\n`;
+
+      const plannerMessages = [
+        { role: 'system', content: PLANNER_SYSTEM },
+        ...messages.filter(m => m.role === 'user' || m.role === 'assistant'),
+      ];
+      let planRaw = '';
+      try {
+        for await (const chunk of planner.prov.sendMessage(plannerMessages, {
+          apiKey: keyResolver(cfg, planner.name),
+          model: planner.model || undefined,
+          signal: callerOpts.signal,
+          maxTokens: 1024,
+        })) {
+          planRaw += String(chunk);
+        }
+      } catch (e) {
+        yield `⚠ planner error: ${e?.message || String(e)}\n\n`;
+        // Fallback: hand the user message to the first worker directly.
+        const w = workers[0];
+        yield `Falling back to direct call on \`${w.name}${w.model ? ':' + w.model : ''}\`:\n\n`;
+        for await (const chunk of w.prov.sendMessage(messages, {
+          apiKey: keyResolver(cfg, w.name),
+          model: w.model || undefined,
+          signal: callerOpts.signal,
+        })) yield String(chunk);
+        return;
+      }
+
+      const plan = _bestPlanArray(planRaw);
+      if (!plan || plan.length === 0) {
+        yield `⚠ planner returned no parseable JSON plan. Raw output:\n\n\`\`\`\n${planRaw.trim().slice(0, 800)}\n\`\`\`\n\nFalling back to single-shot on \`${planner.name}${planner.model ? ':' + planner.model : ''}\`:\n\n`;
+        for await (const chunk of planner.prov.sendMessage(messages, {
+          apiKey: keyResolver(cfg, planner.name),
+          model: planner.model || undefined,
+          signal: callerOpts.signal,
+        })) yield String(chunk);
+        return;
+      }
+      const trimmed = plan.slice(0, maxSubtasks).map((p, i) => ({
+        id: Number.isFinite(p?.id) ? p.id : i + 1,
+        task: String(p?.task || '').trim(),
+        rationale: String(p?.rationale || '').trim(),
+      })).filter(p => p.task);
+      if (trimmed.length === 0) {
+        yield `⚠ plan parsed but contained no usable subtasks. Falling back.\n\n`;
+        for await (const chunk of planner.prov.sendMessage(messages, {
+          apiKey: keyResolver(cfg, planner.name),
+          model: planner.model || undefined,
+          signal: callerOpts.signal,
+        })) yield String(chunk);
+        return;
+      }
+
+      for (const p of trimmed) {
+        yield `${p.id}. **${p.task}**${p.rationale ? ` _— ${p.rationale}_` : ''}\n`;
+      }
+      yield `\n`;
+
+      // ── Phase 2: EXECUTE ────────────────────────────────────────────
+      yield `### 2. Executing ${trimmed.length} subtask${trimmed.length === 1 ? '' : 's'}\n\n`;
+      const results = [];
+      for (let i = 0; i < trimmed.length; i++) {
+        const sub = trimmed[i];
+        const worker = workers[i % workers.length];
+        yield `**Subtask ${sub.id}** \`${worker.name}${worker.model ? ':' + worker.model : ''}\` — ${sub.task}\n\n`;
+        let res = '';
+        try {
+          for await (const chunk of worker.prov.sendMessage([{ role: 'user', content: sub.task }], {
+            apiKey: keyResolver(cfg, worker.name),
+            model: worker.model || undefined,
+            signal: callerOpts.signal,
+          })) {
+            const s = String(chunk);
+            res += s;
+            yield s;
+          }
+          results.push({ ...sub, worker: `${worker.name}${worker.model ? ':' + worker.model : ''}`, result: res, error: null });
+        } catch (e) {
+          const msg = e?.message || String(e);
+          yield `\n⚠ worker error: ${msg}\n`;
+          results.push({ ...sub, worker: `${worker.name}${worker.model ? ':' + worker.model : ''}`, result: '', error: msg });
+        }
+        yield `\n\n---\n\n`;
+      }
+
+      // ── Phase 3: SYNTHESIS ──────────────────────────────────────────
+      yield `### 3. Synthesis\n\n`;
+      const synthUser = [
+        `Original request:\n${userText}`,
+        `\nSubtask plan and worker outputs:`,
+        ...results.map(r => `\n#### Subtask ${r.id} — ${r.task}\nWorker: ${r.worker}\n${r.error ? `Error: ${r.error}` : r.result.trim()}`),
+        `\nNow write the final answer for the user.`,
+      ].join('\n');
+      try {
+        for await (const chunk of planner.prov.sendMessage([
+          { role: 'system', content: SYNTHESIS_SYSTEM },
+          { role: 'user', content: synthUser },
+        ], {
+          apiKey: keyResolver(cfg, planner.name),
+          model: planner.model || undefined,
+          signal: callerOpts.signal,
+        })) yield String(chunk);
+      } catch (e) {
+        yield `⚠ synthesis error: ${e?.message || String(e)}. Worker outputs above are the final material — please review them directly.\n`;
+      }
+    },
+  };
+}

package/providers/registry.mjs

@@ -13,6 +13,7 @@ import { ollamaProvider } from './ollama.mjs';
 import { geminiProvider } from './gemini.mjs';
 import { claudeCliProvider } from './claude_cli.mjs';
 import { makeOpenAICompatProvider, fetchOpenAICompatModels } from './openai_compat.mjs';
+import { makeOrchestratorProvider } from './orchestrator.mjs';
 
 /**
  * @typedef {{ role: 'user'|'assistant'|'system', content: string }} ChatMessage
@@ -51,6 +52,7 @@ export const mockProvider = {
 
 export { anthropicProvider, openaiProvider, ollamaProvider, geminiProvider, claudeCliProvider };
 export { makeOpenAICompatProvider, fetchOpenAICompatModels };
+export { makeOrchestratorProvider };
 
 // Built-in OpenAI-compatible vendors. Same wire format → one factory call
 // each. The picker treats these like first-class providers so users don't
@@ -229,6 +231,13 @@ export const PROVIDERS = {
   mock: mockProvider,
 };
 
+// Orchestrator — multi-agent dispatcher that composes other providers.
+// Registered upfront with no cfg/keyResolver so a bare process can list
+// it via `lazyclaw providers list`; `registerOrchestrator(...)` from
+// cli.mjs::ensureRegistry wires in the live cfg + auth-key resolver so
+// sendMessage can reach env vars / authProfiles / customProviders.
+PROVIDERS.orchestrator = makeOrchestratorProvider();
+
 // Wire each OpenAI-compat builtin into PROVIDERS as a callable provider.
 // Insertion is between Tier 2 (anthropic) and Tier 4 (ollama) by reordering
 // the keys after the loop runs — JS objects honour insertion order and
@@ -348,6 +357,21 @@ export const PROVIDER_INFO = {
   },
 };
 
+// Orchestrator metadata. Composes other providers; the planner/workers
+// each carry their own keys (or none for claude-cli / ollama / mock),
+// so the orchestrator itself reports requiresApiKey: false. The setup
+// picker treats it as a CLI/Local-family entry — no api-key prompt.
+PROVIDER_INFO.orchestrator = {
+  name: 'orchestrator',
+  label: 'Orchestrator (multi-agent)',
+  requiresApiKey: false,
+  docs: 'Orchestrator — decomposes the user message into 2-5 parallel subtasks, dispatches each to a worker provider, then synthesizes the answers. Configure cfg.orchestrator = { planner: "provider:model", workers: ["provider:model", ...], maxSubtasks?: 5 }. Composes any registered provider — Claude / OpenAI / Gemini / NIM / Groq / local Ollama / custom OpenAI-compat endpoints.',
+  endpoint: '(composes other providers)',
+  defaultModel: 'orchestrator',
+  suggestedModels: ['orchestrator'],
+  composite: true,
+};
+
 // Mirror the OpenAI-compat builtins into PROVIDER_INFO so picker / docs /
 // `lazyclaw providers info` see them with the same shape as the hand-written
 // entries above.
@@ -370,6 +394,16 @@ for (const [name, def] of Object.entries(OPENAI_COMPAT_BUILTINS)) {
   };
 }
 
+/**
+ * Re-register PROVIDERS.orchestrator with a live config getter + auth-key
+ * resolver, so each phase's worker call can pick up env vars / authProfiles
+ * / customProviders. Called from cli.mjs::ensureRegistry on every entry
+ * — idempotent (overwrites the previous registration in place).
+ */
+export function registerOrchestrator({ cfgGetter, keyResolver } = {}) {
+  PROVIDERS.orchestrator = makeOrchestratorProvider({ cfgGetter, keyResolver });
+}
+
 /**
  * Resolve an api-key for a built-in OpenAI-compatible provider from the
  * environment, scanning {envKey} then any {altEnvKeys}. Returns '' when
@@ -422,6 +456,7 @@ export function parseProviderModel(s) {
 // `makeOpenAICompatProvider` — overriding is well-defined.
 const RESERVED_PROVIDER_NAMES = new Set([
   'mock', 'claude-cli', 'anthropic', 'openai', 'gemini', 'ollama',
+  'orchestrator',
   '__add_custom__', '__custom_model__', '__fetch_models__',
 ]);