lazyclaw 6.3.1 → 6.5.0

package/tui/run_turn.mjs

@@ -25,6 +25,160 @@
 // turn-completion logic (ReplApp onTurnComplete, legacy `rl.prompt`)
 // runs unconditionally.
 
+import { Chalk } from 'chalk';
+import { chatAgenticGet, chatPlanModeGet, effectiveChatTools } from '../config_features.mjs';
+import { defaultSandboxSpec } from '../sandbox/index.mjs';
+
+// Force ANSI on these turn-status markers regardless of stdout TTY detection:
+// the Ink path routes them through React state (Ink preserves embedded SGR
+// and decides display), and the legacy stdout path always targets a terminal
+// for chat. Without forcing, chalk's auto-level strips color under the
+// non-TTY test/pipe sink and the red error / dim abort marker vanish.
+const _statusChalk = new Chalk({ level: 1 });
+
+// Classify a provider/turn error into a one-line actionable hint (or '' when
+// none applies). Checked auth → model → network so one hint at most. Advisory
+// only — rendered dim under the red error line.
+function _errorHint(err) {
+  const msg = String(err?.message || err || '');
+  const status = err?.status;
+  const code = err?.code;
+  if (status === 401 || status === 403 || /\b(401|403|unauthorized|forbidden|invalid[ _-]?api[ _-]?key|authentication|no api key|missing api key)\b/i.test(msg)) {
+    return 'hint: set a key with /provider, or `lazyclaw auth add <provider>`';
+  }
+  if (status === 404 || /\b(404|model[ _-]?not[ _-]?found|no such model|unknown model|model .* does not exist|not_found_error)\b/i.test(msg)) {
+    return 'hint: run /model to pick a valid model';
+  }
+  if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'EAI_AGAIN'
+      || /\b(ENOTFOUND|ECONNREFUSED|ETIMEDOUT|ECONNRESET|EAI_AGAIN|network|fetch failed|socket hang up|getaddrinfo)\b/i.test(msg)) {
+    return 'hint: check your connection / base URL (/provider to review the endpoint)';
+  }
+  return '';
+}
+
+// Plan-mode addendum — instructs the model to propose, not mutate. Appended
+// to the synthetic chat agent's system prompt only while plan mode is ON.
+const PLAN_MODE_ADDENDUM = 'You are in PLAN mode. Propose a plan; do not mutate '
+  + 'anything. List the steps you would take and the tools you would use, then stop.';
+
+// Per-turn recall injection (roadmap #7). The streaming chat path sends a fixed
+// system prompt, so it never surfaced context relevant to THIS message (only the
+// agentic path, which rebuilds the prompt stack per turn, did). Prepend a fresh
+// recall layer to the CURRENT user message — not the system — because a warm
+// claude-cli persistent session fixes its system at spawn, and every provider
+// reads the user turn. Transient: returns a COPY for the send; the stored
+// session keeps the original message. recallLayer is injected (lazy-imported by
+// the caller) so better-sqlite3 stays off this module's static graph.
+export function _injectRecall(messages, cfgDir, recallLayerFn) {
+  try {
+    if (typeof recallLayerFn !== 'function' || !Array.isArray(messages)) return messages;
+    let idx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i] && messages[i].role === 'user') { idx = i; break; }
+    }
+    if (idx < 0) return messages;
+    const layer = recallLayerFn(cfgDir, String(messages[idx].content || ''), 5);
+    if (!layer || !String(layer).trim()) return messages;
+    return messages.map((m, i) => (i === idx ? { ...m, content: `${layer}\n\n${m.content}` } : m));
+  } catch { return messages; }
+}
+
+// Fire the post-task learning loop on every successful chat turn (v5 Group A
+// C1). Fire-and-forget via queueMicrotask so the next prompt is never blocked
+// on trajectory write / synth. Shared by the streaming and agentic paths.
+// Decide whether a chat turn is worth a learning pass. The hook otherwise
+// spawns TWO extra `claude` processes (skill synth + user-model) on EVERY turn,
+// tripling per-message spawns and competing with the user's next turn for the
+// subscription. Skip greetings/acks, trivially short exchanges, and empty
+// (aborted/failed) replies — none warrant a durable SKILL.md or a user model.
+export function _shouldLearn(messages) {
+  const last2 = (messages || []).slice(-2);
+  const user = String(last2.find((m) => m && m.role === 'user')?.content || '').trim();
+  const reply = String(last2.find((m) => m && m.role !== 'user')?.content || '').trim();
+  if (!reply) return false;
+  if ((user + ' ' + reply).trim().length < 280) return false;
+  if (/^(hi|hey|hello|yo|thanks|thank you|thx|ty|ok|okay|k|sure|nice|cool|got it|ㅇㅇ|ㄱㅅ|ㄳ|고마워|감사|안녕|넵|네)\b/i.test(user)) return false;
+  return true;
+}
+
+function _fireLearningHook(ctx, messages, activeProvName, activeModel, transcript) {
+  try {
+    if (!_shouldLearn(messages)) return;
+    queueMicrotask(() => {
+      import('../mas/learning.mjs').then((mod) => mod.runLearning('post-task', {
+        agent: { name: 'chat', provider: activeProvName, model: activeModel, role: '' },
+        task: {
+          id: ctx.getSessionId() || ctx.syntheticChatSessionId,
+          title: '(chat turn)',
+          turns: messages.slice(-2).map((m) => ({
+            agent: m.role === 'user' ? 'user' : 'chat',
+            text: m.content,
+            ts: new Date().toISOString(),
+          })),
+        },
+        configDir: ctx.cfgDir,
+        cfg: ctx.cfg,
+        transcript: String(transcript || '').slice(0, 8000),
+      })).catch(() => { /* learning loop is best-effort */ });
+    });
+  } catch { /* never let learning hook break the chat */ }
+}
+
+// Drive one agentic chat turn through the MAS tool loop. Builds the synthetic
+// chat agent record, renders compact tool-activity status lines + the final
+// answer into writeChunk, and returns the final assistant text. The approval
+// hook is taken from ctx.approve when present (Ink: _makeInkApprove, legacy:
+// makeReadlineApprove) — when absent the fail-closed gate in tool_runner.mjs
+// simply denies any sensitive tool (no silent ungated execution).
+async function _runAgenticTurn({ ctx, messages, sysMsg, activeProvName, activeModel, planMode, writeChunk, signal }) {
+  const runAgentTurn = ctx.runAgentTurnImpl
+    || (await import('../mas/agent_turn.mjs')).runAgentTurn;
+  const tools = effectiveChatTools(ctx.cfg, { planMode });
+  let role = (sysMsg && sysMsg.content) || '';
+  if (planMode) role = role ? `${role}\n\n${PLAN_MODE_ADDENDUM}` : PLAN_MODE_ADDENDUM;
+  const agent = { name: 'chat', provider: activeProvName, model: activeModel, role, tools };
+  // History excludes the just-pushed user message and the system slot (the
+  // latter is threaded via agent.role); runAgentTurn appends userMessage.
+  const history = messages
+    .slice(0, -1)
+    .filter((m) => m.role !== 'system')
+    .map((m) => ({ role: m.role, content: m.content }));
+  const userMessage = messages[messages.length - 1]?.content || '';
+  let result;
+  try {
+    result = await runAgentTurn({
+      agent, userMessage, history,
+      configDir: ctx.cfgDir,
+      apiKey: ctx.resolveAuthKey(activeProvName),
+      approve: ctx.approve,
+      security: ctx.cfg?.security,
+      // Default-on isolation: an explicit --sandbox spec wins; otherwise confine
+      // by default (cwd-confined fs, secrets blocked, net allowed). Opt out via
+      // cfg.sandbox.confine=false → defaultSandboxSpec returns null (bare).
+      sandbox: ctx.sandboxSpec || defaultSandboxSpec(ctx.cfg, { cwd: process.cwd(), configDir: ctx.cfgDir }),
+      cache: true,
+      usePromptStack: false,
+      signal,
+    });
+  } catch (err) {
+    // No silent catch — surface as a status line; return empty so the caller
+    // still completes the turn (persist + learning) without a half reply.
+    try { writeChunk(`· agentic turn failed: ${err?.message || String(err)}\n`); } catch { /* sink */ }
+    return '';
+  }
+  // Compact tool-activity status lines (dim, not the red provider-error style).
+  for (const c of (result.toolCalls || [])) {
+    const ok = c.ok ? '✓' : '⚠';
+    try { writeChunk(`· ${ok} ${c.name}\n`); } catch { /* sink */ }
+  }
+  if (result.stoppedBy === 'budget') {
+    try { writeChunk(`· stopped after ${result.iterations} tool step(s)\n`); } catch { /* sink */ }
+  }
+  const text = result.text || '';
+  if (text) { try { writeChunk(text); } catch { /* sink */ } }
+  return text;
+}
+
 /**
  * @typedef {Object} RunTurnCtx
  * @property {Object} cfg                                  Active config.
@@ -79,17 +233,72 @@ export function makeRunTurn({ ctx, writeFn }) {
       const prov = ctx.getProv();
       const activeProvName = ctx.getActiveProvName();
       const activeModel = ctx.getActiveModel();
+      // Group 1 — agentic REPL. When cfg.chat.agentic (or plan mode) is ON,
+      // route the turn through the MAS tool loop (runAgentTurn) instead of
+      // the streaming sendMessage path. Plan mode forces agentic-on for the
+      // turn (read-only). Everything else (persistTurn, the post-task
+      // learning hook below) is shared. When OFF — the default — the
+      // streaming path below runs UNCHANGED.
+      const planMode = chatPlanModeGet(ctx.cfg);
+      if (chatAgenticGet(ctx.cfg) || planMode) {
+        const acc2 = await _runAgenticTurn({
+          ctx, messages, sysMsg, activeProvName, activeModel, planMode,
+          writeChunk: _writeChunk, signal,
+        });
+        if (_writeTimer) clearTimeout(_writeTimer);
+        _flush();
+        try { writeFn('\n'); } catch { /* sink failure must not kill the turn */ }
+        messages.push({ role: 'assistant', content: acc2 });
+        ctx.persistTurn('assistant', acc2);
+        _fireLearningHook(ctx, messages, activeProvName, activeModel, acc2);
+        return;
+      }
+      // Configurable max-output-tokens (config.json `maxTokens`). Only
+      // thread it through when it's a positive finite number; otherwise
+      // leave opts.maxTokens unset so each provider's DEFAULT_MAX_TOKENS
+      // applies.
+      const cfgMaxTokens = ctx.cfg?.maxTokens;
+      const maxTokens = (typeof cfgMaxTokens === 'number' && Number.isFinite(cfgMaxTokens) && cfgMaxTokens > 0)
+        ? cfgMaxTokens
+        : undefined;
+      // Roadmap #7 — per-turn recall: surface context relevant to THIS message
+      // by prepending a fresh recall layer to the current user turn (off via
+      // cfg.chat.recall=false). Best-effort + lazy-imported so an empty/missing
+      // index never blocks a reply and better-sqlite3 stays off the static graph.
+      let sendMessages = messages;
+      if (ctx.cfg?.chat?.recall !== false) {
+        try {
+          const { recalledLayer } = await import('../mas/prompt_stack.mjs');
+          sendMessages = _injectRecall(messages, ctx.cfgDir, recalledLayer);
+        } catch { /* recall is best-effort — never block a turn */ }
+      }
       // C8 — prompt-cache the static system prefix. The Anthropic
       // provider prefers `systemStatic` when present; non-Anthropic
       // providers ignore the field and fall back to the legacy
       // single-block path with `cache:true`.
-      for await (const chunk of prov.sendMessage(messages, {
+      let truncated = false;
+      for await (const chunk of prov.sendMessage(sendMessages, {
         apiKey: ctx.resolveAuthKey(activeProvName),
         model: activeModel,
         sandbox: ctx.sandboxSpec,
         signal,
         onUsage: ctx.accumulateUsage,
+        // Streaming providers fire this when a turn hits the model's output-token
+        // limit (finish_reason 'length' / MAX_TOKENS / stop_reason 'max_tokens' /
+        // done_reason 'length'). Warn the user instead of presenting a truncated
+        // answer as complete, mirroring the agentic path (mas/agent_turn.mjs).
+        onTruncated: () => { truncated = true; },
         cache: true,
+        // Default-ON (set cfg.chat.persistentSession=false to disable): reuse one
+        // warm `claude` per conversation so the harness boots once, not every
+        // turn (measured ~1.2s/turn / ~42% faster after the cold first turn).
+        // claude-cli-only (other providers ignore it); the provider falls back to
+        // a one-shot spawn on any session failure, and the session respawns if
+        // the system prompt changes (plan-mode toggle) so it can't go stale.
+        persistent: ctx.cfg?.chat?.persistentSession !== false,
+        sessionKey: (ctx.getSessionId && ctx.getSessionId()) || ctx.syntheticChatSessionId,
+        ...(sysMsg ? { sessionSystem: sysMsg.content } : {}),
+        ...(maxTokens !== undefined ? { maxTokens } : {}),
         ...(sysMsg ? { systemStatic: sysMsg.content } : {}),
       })) {
         _writeChunk(chunk);
@@ -99,39 +308,32 @@ export function makeRunTurn({ ctx, writeFn }) {
       _flush();
       try { writeFn('\n'); }
       catch { /* sink failure must not kill the turn */ }
+      if (truncated) {
+        try { writeFn('[truncated — the model hit its output-token limit; raise maxTokens]\n'); }
+        catch { /* sink failure must not kill the turn */ }
+      }
       messages.push({ role: 'assistant', content: acc });
       ctx.persistTurn('assistant', acc);
-      // v5 Group A (C1): close the post-task learning loop on every
-      // successful chat turn. Fire-and-forget via queueMicrotask so the
-      // next prompt is never blocked on trajectory write / synth.
-      try {
-        queueMicrotask(() => {
-          import('../mas/learning.mjs').then((mod) => mod.runLearning('post-task', {
-            agent: { name: 'chat', provider: activeProvName, model: activeModel, role: '' },
-            task: {
-              id: ctx.getSessionId() || ctx.syntheticChatSessionId,
-              title: '(chat turn)',
-              turns: messages.slice(-2).map((m) => ({
-                agent: m.role === 'user' ? 'user' : 'chat',
-                text: m.content,
-                ts: new Date().toISOString(),
-              })),
-            },
-            configDir: ctx.cfgDir,
-            cfg: ctx.cfg,
-            transcript: acc.slice(0, 8000),
-          })).catch(() => { /* learning loop is best-effort */ });
-        });
-      } catch { /* never let learning hook break the chat */ }
+      _fireLearningHook(ctx, messages, activeProvName, activeModel, acc);
     } catch (err) {
       if (_writeTimer) clearTimeout(_writeTimer);
       _flush();
       // ABORT errors are user-initiated; drop the partial reply (don't
       // push an incomplete assistant message — next turn would treat
-      // it as a complete reply and confuse the model).
-      if (err?.code !== 'ABORT' && !signal?.aborted) {
-        try { writeFn(`error: ${err?.message || String(err)}\n`); }
+      // it as a complete reply and confuse the model). Emit a visible dim
+      // [aborted] marker so the output doesn't just silently stop (the
+      // host onTurnComplete sees reason:'done' because we swallow ABORT).
+      if (err?.code === 'ABORT' || signal?.aborted) {
+        try { writeFn(`${_statusChalk.dim('[aborted]')}\n`); }
+        catch { /* sink failure must not kill the turn */ }
+      } else {
+        // Provider errors render in the red error style (not normal amber
+        // assistant text — the audit gap). The red SGR is embedded so the
+        // Ink scrollback <Text> preserves it and the legacy stdout path shows it.
+        try { writeFn(`${_statusChalk.red(`error: ${err?.message || String(err)}`)}\n`); }
         catch { /* sink failure must not mask err */ }
+        const _hint = _errorHint(err);
+        if (_hint) { try { writeFn(`${_statusChalk.dim(_hint)}\n`); } catch { /* sink */ } }
       }
     }
   };

package/tui/slash_args.mjs

@@ -0,0 +1,159 @@
+// tui/slash_args.mjs — slash-command ARGUMENT completion.
+//
+// Two surfaces, chosen per argument:
+//   • inline  — candidates render directly in the popup (like the /command
+//     popup): ↑/↓ select, Tab/Enter fill the token. For single-value args and
+//     subcommand menus (/login, /hud, /memory, /config, /channels, /task, …).
+//   • modal   — a "↹ pick" hint shows; Tab opens the drill-in modal picker.
+//     For 2-step provider→model specs (/model, /trainer set, /orchestrator).
+//
+// argSpecFor() is the pure resolver the REPL calls on every keystroke. It is
+// position-aware: tokens[0] is the subcommand, later tokens are values gated on
+// it. listArgCandidates() builds the inline list; runArgCompleter() drives the
+// modal. Kept out of slash_commands.mjs (which must stay a pure-data module to
+// avoid the tui/ → cli.mjs circular import); this module may import freely.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pickProviderModel } from './model_pick.mjs';
+import { CLI_LOGIN_PROVIDERS } from '../providers/cli_login.mjs';
+import { KNOWN_CHANNELS } from '../config_features.mjs';
+import { listAgents } from '../agents.mjs';
+import { listSkills } from '../skills.mjs';
+import { listGoals } from '../goals.mjs';
+
+const ONOFF = ['on', 'off'];
+
+const sp = (kind, completer, name) => ({ kind, completer, name });
+
+// Per-command rules: (tokens) => spec | null. `tokens` is the arg portion split
+// on whitespace; the last entry is what the user is typing. A command absent
+// here has no argument completion.
+const ARG_RULES = {
+  '/login':        (t) => (t.length === 1 ? sp('inline', 'loginProvider', 'provider') : null),
+  '/hud':          (t) => (t.length === 1 ? sp('inline', 'onoff', 'on|off') : null),
+  '/memory':       (t) => (t.length === 1 ? sp('inline', 'memoryScope', 'scope') : null),
+  '/context':      (t) => (t.length === 1 ? sp('inline', 'contextSub', 'sub') : null),
+  '/task':         (t) => (t.length === 1 ? sp('inline', 'taskSub', 'sub') : null),
+  '/team':         (t) => (t.length === 1 ? sp('inline', 'teamSub', 'sub') : null),
+  '/handoff':      (t) => (t.length === 1 ? sp('inline', 'channelName', 'channel') : null),
+  '/dashboard':    (t) => (t.length === 1 ? sp('inline', 'dashboardSub', 'sub') : null),
+  '/goal':         (t) => (t.length === 1 ? sp('inline', 'goalFirst', 'goal/sub')
+                          : (t[0] === 'show' || t[0] === 'close') && t.length === 2 ? sp('inline', 'goalName', 'goal')
+                          : t[0] === 'close' && t.length === 3 ? sp('inline', 'goalOutcome', 'outcome') : null),
+  '/skill':        (t) => (t.length === 1 ? sp('inline', 'skillName', 'skill') : null),
+  '/skills':       (t) => (t.length === 1 ? sp('inline', 'skillName', 'skill') : null),
+  '/provider':     (t) => (t.length === 1 ? sp('inline', 'provider', 'provider') : null),
+  '/channels':     (t) => (t.length === 1 ? sp('inline', 'channelFirst', 'channel/setup')
+                          : t.length === 2 ? sp('inline', 'channelAction', 'on|off|setup') : null),
+  '/personality':  (t) => (t.length === 1 ? sp('inline', 'personalitySub', 'sub')
+                          : (t[0] === 'use' || t[0] === 'show' || t[0] === 'remove') && t.length === 2
+                            ? sp('inline', 'personalityName', 'name') : null),
+  '/agent':        (t) => (t.length === 1 ? sp('inline', 'agentSub', 'sub')
+                          : (t[0] === 'edit' || t[0] === 'show' || t[0] === 'remove') && t.length === 2
+                            ? sp('inline', 'agentName', 'name') : null),
+  '/trainer':      (t) => (t.length === 1 ? sp('inline', 'trainerSub', 'sub')
+                          : (t[0] === 'set' || t[0] === 'fallback') && t.length === 2
+                            ? sp('modal', 'trainerSpec', 'spec') : null),
+  '/orchestrator': (t) => (t.length === 1 ? sp('inline', 'orchestratorSub', 'sub')
+                          : t[0] === 'planner' && t.length === 2 ? sp('modal', 'orchestratorSpec', 'spec')
+                          : t[0] === 'worker' && t.length === 2 ? sp('inline', 'workerAction', 'add|remove')
+                          : t[0] === 'worker' && (t[1] === 'add' || t[1] === 'remove' || t[1] === 'rm') && t.length === 3
+                            ? sp('modal', 'orchestratorSpec', 'spec') : null),
+  // 2-step provider→model drill: modal.
+  '/model':        (t) => (t.length === 1 ? sp('modal', 'model', 'model') : null),
+};
+
+// Resolve which argument (if any) is completable for `buffer`. Returns
+// { cmd, kind, completer, name, partial } or null. `catalog` is accepted for
+// back-compat but unused — rules live in ARG_RULES.
+export function argSpecFor(buffer, _catalog) {
+  if (!buffer || !buffer.startsWith('/')) return null;
+  const at = buffer.indexOf(' ');
+  if (at < 0) return null; // still typing the command itself
+  const cmd = buffer.slice(0, at);
+  const rule = ARG_RULES[cmd];
+  if (!rule) return null;
+  const tokens = buffer.slice(at + 1).split(/\s+/);
+  const spec = rule(tokens);
+  if (!spec) return null;
+  return { cmd, ...spec, partial: tokens[tokens.length - 1] };
+}
+
+function safe(fn) { try { return fn() || []; } catch { return []; } }
+function listMdNames(dir) {
+  return safe(() => fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)).sort());
+}
+
+// Inline candidate sources → {value, desc}[] (unfiltered; caller filters).
+const INLINE_SOURCES = {
+  loginProvider:  () => Object.keys(CLI_LOGIN_PROVIDERS).map((v) => ({ value: v, desc: 'connect via CLI login' })),
+  onoff:          () => ONOFF.map((v) => ({ value: v, desc: '' })),
+  memoryScope:    () => ['core', 'recent', 'episodic'].map((v) => ({ value: v, desc: '' })),
+  contextSub:     () => ['status', 'turns', 'tokens'].map((v) => ({ value: v, desc: '' })),
+  taskSub:        () => ['start', 'tick', 'list', 'show', 'transcript', 'abandon', 'done', 'remove'].map((v) => ({ value: v, desc: '' })),
+  teamSub:        () => ['list', 'show', 'add', 'remove'].map((v) => ({ value: v, desc: '' })),
+  dashboardSub:   () => ['stop', 'kill'].map((v) => ({ value: v, desc: '' })),
+  goalOutcome:    () => ['done', 'abandoned'].map((v) => ({ value: v, desc: '' })),
+  goalName:       (ctx) => safe(() => listGoals(ctx.cfgDir).map((g) => ({ value: g.name, desc: g.status || '' })).filter((i) => i.value)),
+  goalFirst:      (ctx) => ['add', 'list', 'show', 'close'].map((v) => ({ value: v, desc: '' }))
+                      .concat(safe(() => listGoals(ctx.cfgDir).map((g) => ({ value: g.name, desc: g.status || 'goal' })).filter((i) => i.value))),
+  personalitySub: () => ['list', 'show', 'install', 'remove', 'use'].map((v) => ({ value: v, desc: '' })),
+  agentSub:       () => ['list', 'show', 'add', 'edit', 'remove'].map((v) => ({ value: v, desc: '' })),
+  trainerSub:     () => ['show', 'set', 'fallback', 'clear'].map((v) => ({ value: v, desc: '' })),
+  orchestratorSub:() => ['status', 'on', 'off', 'planner', 'worker', 'maxsubtasks'].map((v) => ({ value: v, desc: '' })),
+  workerAction:   () => ['add', 'remove'].map((v) => ({ value: v, desc: '' })),
+  channelName:    () => KNOWN_CHANNELS.map((v) => ({ value: v, desc: '' })),
+  channelFirst:   () => [{ value: 'setup', desc: 'set channel credentials' }].concat(KNOWN_CHANNELS.map((v) => ({ value: v, desc: '' }))),
+  channelAction:  () => [...ONOFF, 'setup', 'test'].map((v) => ({ value: v, desc: v === 'setup' ? 'set credentials' : v === 'test' ? 'verify credentials' : '' })),
+  provider:       (_ctx, registry) => Object.keys((registry && registry.PROVIDERS) || {})
+                      .filter((n) => n !== 'mock').sort().map((v) => ({ value: v, desc: '' })),
+  agentName:      (ctx) => safe(() => listAgents(ctx.cfgDir).map((a) => ({ value: a.name, desc: a.model ? `${a.provider}/${a.model}` : a.provider }))),
+  skillName:      (ctx) => safe(() => listSkills(ctx.cfgDir).map((s) => ({ value: s.name, desc: s.summary || '' }))),
+  personalityName:(ctx) => listMdNames(path.join(ctx.cfgDir || '', 'personalities')).map((v) => ({ value: v, desc: '' })),
+};
+
+// Build the inline candidate list for an inline spec, filtered + prefix-sorted
+// by the partial token. Returns {value, desc}[] (empty for non-inline specs).
+export function listArgCandidates(spec, ctx, registry) {
+  if (!spec || spec.kind !== 'inline') return [];
+  const src = INLINE_SOURCES[spec.completer];
+  if (!src) return [];
+  const all = src(ctx || {}, registry) || [];
+  const q = String(spec.partial || '').toLowerCase();
+  const matched = q ? all.filter((i) => String(i.value).toLowerCase().includes(q)) : all.slice();
+  matched.sort((a, b) => {
+    const ap = String(a.value).toLowerCase().startsWith(q) ? 0 : 1;
+    const bp = String(b.value).toLowerCase().startsWith(q) ? 0 : 1;
+    return ap - bp;
+  });
+  return matched;
+}
+
+// Modal completers — run the drill-in picker and return the string to fill.
+// Only reached for spec.kind === 'modal'.
+export const ARG_COMPLETERS = {
+  async model(ctx, registry) {
+    const r = await pickProviderModel(ctx, registry, { includeSwitch: true });
+    if (!r || r.model == null) return null;
+    const active = typeof ctx.getActiveProvName === 'function' ? ctx.getActiveProvName() : '';
+    return r.provider && r.provider !== active ? `${r.provider}/${r.model}` : r.model;
+  },
+  async trainerSpec(ctx, registry) {
+    const r = await pickProviderModel(ctx, registry, { includeAuto: true, includeDefault: true });
+    if (!r || r.model == null) return null;
+    return r.provider === 'auto' ? 'auto' : (r.model ? `${r.provider}:${r.model}` : r.provider);
+  },
+  async orchestratorSpec(ctx, registry) {
+    const r = await pickProviderModel(ctx, registry, { exclude: ['orchestrator', 'mock'], pickProvider: true, includeDefault: true, includeSwitch: false });
+    if (!r || r.model == null) return null;
+    return r.model ? `${r.provider}:${r.model}` : r.provider;
+  },
+};
+
+// Run the modal completer named by spec.completer. Returns the fill string or null.
+export async function runArgCompleter(spec, ctx, registry) {
+  const fn = spec && ARG_COMPLETERS[spec.completer];
+  if (!fn) return null;
+  return fn(ctx, registry);
+}