mixdog 0.9.2 → 0.9.4

package/src/standalone/agent-tool/helpers.mjs

@@ -0,0 +1,237 @@
+// Pure, dependency-light helpers extracted from the agent-tool facade. No
+// module-level mutable state lives here (the frontmatter perm cache and all
+// timers stay in the facade / their owner modules). Behavior-preserving:
+// function bodies are identical to the originals.
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import {
+  normalizeAgentPermissionOrNone,
+  parseMarkdownFrontmatter,
+} from '../../runtime/shared/markdown-frontmatter.mjs';
+import { clearGatewaySessionRoute, writeGatewaySessionRoute } from '../../vendor/statusline/src/gateway/session-routes.mjs';
+import { PRESET_ALIASES } from './tool-def.mjs';
+
+export function envTimeoutMs(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+export function clean(value) {
+  return String(value ?? '').trim();
+}
+
+export function agentTagOf(session) {
+  return clean(session?.agentTag);
+}
+
+export function normalizeAgentName(value) {
+  const id = clean(value).toLowerCase().replace(/[\s_]+/g, '-');
+  if (id === 'explorer') return 'explore';
+  if (id === 'maint' || id === 'maintenance' || id === 'memory') return 'maintainer';
+  if (id === 'heavy' || id === 'heavyworker') return 'heavy-worker';
+  if (id === 'review') return 'reviewer';
+  if (id === 'debug') return 'debugger';
+  return id;
+}
+
+export function positiveInt(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+export function terminalPidForContext(context = {}) {
+  return positiveInt(context?.clientHostPid);
+}
+
+export function agentScope(args = {}, context = {}) {
+  const scope = clean(args.scope || args.terminal || args.term).toLowerCase();
+  if (args.allTerminals === true || scope === 'all' || scope === 'global') return {};
+  return context || {};
+}
+
+export function sessionMatchesContext(session, context = {}) {
+  const wantedPid = terminalPidForContext(context);
+  if (!wantedPid) return true;
+  const sessionPid = positiveInt(session?.clientHostPid);
+  return !!sessionPid && sessionPid === wantedPid;
+}
+
+export function rowMatchesContext(row, context = {}) {
+  const wantedPid = terminalPidForContext(context);
+  if (!wantedPid) return true;
+  const rowPid = positiveInt(row?.clientHostPid);
+  return !!rowPid && rowPid === wantedPid;
+}
+
+export function nonNegativeInt(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+
+export function presetKey(preset) {
+  return clean(preset?.id || preset?.name);
+}
+
+export function bridgeRouteForStatusline(preset = {}) {
+  const provider = clean(preset.provider);
+  const model = clean(preset.model);
+  if (!provider || !model) return null;
+  const out = {
+    mode: 'fixed',
+    defaultProvider: provider,
+    defaultModel: model,
+  };
+  const id = clean(preset.id);
+  const name = clean(preset.name);
+  const modelDisplay = clean(preset.modelDisplay || preset.display || preset.displayName);
+  const effort = clean(preset.effort);
+  if (id) out.presetId = id;
+  if (name) out.presetName = name;
+  if (modelDisplay) out.modelDisplay = modelDisplay;
+  if (effort) {
+    out.effort = effort;
+    out.displayEffort = effort;
+  }
+  if (preset.fast === true || preset.fast === false) out.fast = preset.fast;
+  return out;
+}
+
+export function writeAgentStatuslineRoute(sessionId, preset) {
+  const route = bridgeRouteForStatusline(preset);
+  if (!sessionId || !route) return false;
+  try { return writeGatewaySessionRoute(sessionId, route); } catch { return false; }
+}
+
+export function clearAgentStatuslineRoute(sessionId) {
+  if (!sessionId) return false;
+  try { return clearGatewaySessionRoute(sessionId); } catch { return false; }
+}
+
+export function findPreset(config, key) {
+  const wanted = clean(key).toLowerCase();
+  if (!wanted) return null;
+  const presets = Array.isArray(config?.presets) ? config.presets : [];
+  return presets.find((p) => {
+    return clean(p?.id).toLowerCase() === wanted || clean(p?.name).toLowerCase() === wanted;
+  }) || null;
+}
+
+export function synthesizePreset(config, key) {
+  const alias = PRESET_ALIASES.get(clean(key).toLowerCase());
+  if (!alias) return null;
+  const base = findPreset(config, alias.base);
+  if (!base) return null;
+  return {
+    ...base,
+    id: alias.id,
+    name: alias.name,
+    effort: alias.effort,
+  };
+}
+
+export function normalizeAgentRoute(routeLike, fallbackProvider = '') {
+  const provider = clean(routeLike?.provider) || clean(fallbackProvider);
+  const model = clean(routeLike?.model);
+  if (!provider || !model) return null;
+  return {
+    provider,
+    model,
+    effort: clean(routeLike?.effort) || undefined,
+    fast: routeLike?.fast === true,
+  };
+}
+
+export function agentPresetName(agent) {
+  return `AGENT ${String(agent || '').toUpperCase()}`;
+}
+
+export async function resolvePrompt(args, cwd) {
+  const prompt = clean(args.prompt || args.message);
+  const file = clean(args.file);
+  if (prompt && file) throw new Error('agent: provide only one of prompt/message or file');
+  if (prompt) return prompt;
+  if (file) {
+    const target = isAbsolute(file) ? file : resolve(cwd || process.cwd(), file);
+    return readFileSync(target, 'utf8');
+  }
+  throw new Error('agent: prompt/message/file is required');
+}
+
+export function withCwdHeader(prompt, cwd) {
+  if (!cwd) return prompt;
+  if (String(prompt).startsWith('[effective-cwd]')) return prompt;
+  return `[effective-cwd] ${cwd}\n\n${prompt}`;
+}
+
+export function compactIso(value) {
+  const text = clean(value);
+  if (!text) return '';
+  return text.replace('T', ' ').replace(/\.\d+Z$/, 'Z');
+}
+
+export function formatElapsedMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n < 0) return '';
+  const totalSec = Math.floor(n / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min < 60) return sec ? `${min}m${sec}s` : `${min}m`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return remMin ? `${hr}h${remMin}m` : `${hr}h`;
+}
+
+export function elapsedFromStamps(startedAt, finishedAt, status) {
+  const start = Date.parse(clean(startedAt));
+  if (!Number.isFinite(start)) return null;
+  const finish = Date.parse(clean(finishedAt));
+  const end = Number.isFinite(finish) ? finish : Date.now();
+  const label = formatElapsedMs(end - start);
+  if (!label) return null;
+  return Number.isFinite(finish) ? label : `${label} (running)`;
+}
+
+export function stripFinalAnswerWrapper(value) {
+  const text = String(value ?? '').trim();
+  const match = /^<final-answer\b[^>]*>([\s\S]*?)<\/final-answer>\s*$/i.exec(text);
+  return match ? match[1].trim() : text;
+}
+
+// Process-wide TTL cache for agent AGENT.md frontmatter permission. The file
+// rarely changes, but this otherwise pays several existsSync()+readFileSync()
+// calls on EVERY spawn — multiplied across a parallel fanout that is pure
+// redundant synchronous I/O on the event loop, which blocks every other
+// concurrent spawn. Short TTL keeps edits picked up quickly while collapsing
+// burst reads. Cache + TTL are owned here alongside the sole reader.
+const _frontmatterPermCache = new Map(); // key -> { value, atMs }
+const FRONTMATTER_PERM_CACHE_TTL_MS = envTimeoutMs('MIXDOG_AGENT_FRONTMATTER_TTL_MS', 5_000);
+
+export function readAgentFrontmatterPermission(agent, dataDir, standaloneSourceRoot) {
+  const cleanAgent = clean(agent);
+  if (!cleanAgent) return null;
+  const cacheKey = `${dataDir || ''}\u0000${cleanAgent}`;
+  const cached = _frontmatterPermCache.get(cacheKey);
+  if (cached && Date.now() - cached.atMs < FRONTMATTER_PERM_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  const candidates = [];
+  if (dataDir) {
+    candidates.push(join(dataDir, 'agents', cleanAgent, 'AGENT.md'));
+    candidates.push(join(dataDir, 'agents', `${cleanAgent}.md`));
+  }
+  candidates.push(join(standaloneSourceRoot, 'agents', cleanAgent, 'AGENT.md'));
+  candidates.push(join(standaloneSourceRoot, 'agents', `${cleanAgent}.md`));
+  let resolved = null;
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    const fm = parseMarkdownFrontmatter(readFileSync(file, 'utf8'));
+    const permission = normalizeAgentPermissionOrNone(fm.permission);
+    if (permission) { resolved = permission; break; }
+  }
+  _frontmatterPermCache.set(cacheKey, { value: resolved, atMs: Date.now() });
+  return resolved;
+}

package/src/standalone/agent-tool/notify.mjs

@@ -0,0 +1,107 @@
+// Owner/worker completion-notification helpers, extracted from the agent-tool
+// facade as a factory so the mgr-bound closures stay per agent instance.
+// Behavior-preserving: bodies identical to the originals; deps injected.
+import { modelVisibleToolCompletionMessage } from '../../runtime/shared/tool-execution-contract.mjs';
+import { renderBackgroundTask, sanitizeTaskMeta, setBackgroundTaskEnqueueFallback } from '../../runtime/shared/background-tasks.mjs';
+import { clean } from './helpers.mjs';
+
+export function createNotify(mgr) {
+  function enqueueCompletionMessage(sessionId, text, meta = {}) {
+    const target = clean(sessionId);
+    if (!target || typeof mgr.enqueuePendingMessage !== 'function') return false;
+    try {
+      const visible = modelVisibleToolCompletionMessage(text, meta);
+      return Boolean(visible && mgr.enqueuePendingMessage(target, visible) > 0);
+    } catch {
+      return false;
+    }
+  }
+
+  // Wire the canonical completion fallback to this agent surface's owner-session
+  // enqueue so notifyTaskCompletion can deliver via callerSessionId when no
+  // notifyFn is present or it declines. Registered once per agent (the closure
+  // captures mgr); signatures align: (callerSessionId, message, meta).
+  setBackgroundTaskEnqueueFallback((sessionId, text, meta) => enqueueCompletionMessage(sessionId, text, meta));
+
+  function workerNotifyFn(workerSessionId, notifyContext = {}) {
+    const workerId = clean(workerSessionId);
+    const ownerSessionId = clean(notifyContext?.callerSessionId || notifyContext?.sessionId);
+    const upstream = typeof notifyContext?.notifyFn === 'function' ? notifyContext.notifyFn : null;
+    return (text, meta = {}) => {
+      let ownerDelivered = false;
+      if (upstream) {
+        try {
+          const result = upstream(text, meta);
+          ownerDelivered = result !== false;
+          if (ownerDelivered) Promise.resolve(result).catch(() => {});
+        } catch {
+          ownerDelivered = false;
+        }
+      }
+      if (!ownerDelivered && ownerSessionId) {
+        ownerDelivered = enqueueCompletionMessage(ownerSessionId, text, meta);
+      }
+      const workerDelivered = workerId && workerId !== ownerSessionId
+        ? enqueueCompletionMessage(workerId, text, meta)
+        : ownerDelivered;
+      return ownerSessionId ? ownerDelivered : workerDelivered;
+    };
+  }
+
+  function notifyOwnerAgentCompletionEarly(job, resultValue, notifyContext = {}) {
+    if (!job || job._earlyCompletionNotified === true) return false;
+    const ownerSessionId = clean(notifyContext?.callerSessionId || notifyContext?.sessionId);
+    const upstream = typeof notifyContext?.notifyFn === 'function' ? notifyContext.notifyFn : null;
+    const finishedAt = new Date().toISOString();
+    // An abnormal-empty finish carries an `error` — the early preview must NOT
+    // present it as a benign `completed` card, or the Lead sees success before
+    // the later `failed` reconcile lands. Mirror the terminal status/instruction.
+    const earlyStatus = resultValue && resultValue.error ? 'failed' : 'completed';
+    const snapshot = {
+      ...job,
+      status: earlyStatus,
+      finishedAt,
+      finishedAtMs: Date.now(),
+      result: resultValue,
+      resultType: job.resultType || 'agent_task_result',
+      meta: sanitizeTaskMeta(job.meta || {}),
+      ...(resultValue && resultValue.error ? { error: resultValue.error } : {}),
+    };
+    // An early notification is only a header-only *preview*: it fires before
+    // the worker's session is persisted to signal the running→completed
+    // transition. It deliberately carries NO result body — the canonical
+    // notifyTaskCompletion delivers the body exactly once via the
+    // reconcile/finally path, so omitting it here keeps notifications
+    // exact-once with no duplicate body.
+    const text = renderBackgroundTask(snapshot, { includeResult: false });
+    const meta = {
+      type: snapshot.resultType,
+      execution_surface: 'agent',
+      execution_id: job.taskId || null,
+      status: earlyStatus,
+      instruction: `The async agent task ${job.taskId || ''} has finished (${earlyStatus}) - review this result in your next step.`,
+      ...(ownerSessionId ? { caller_session_id: ownerSessionId } : {}),
+    };
+    let delivered = false;
+    if (upstream) {
+      try {
+        const result = upstream(text, meta);
+        delivered = result !== false;
+        if (delivered) Promise.resolve(result).catch(() => {});
+      } catch {
+        delivered = false;
+      }
+    }
+    if (!delivered && ownerSessionId) {
+      delivered = enqueueCompletionMessage(ownerSessionId, text, meta);
+    }
+    if (delivered) {
+      // Mark only that a header-only preview fired. The canonical
+      // notifyTaskCompletion still owns the single body-carrying notification.
+      job._earlyCompletionNotified = true;
+    }
+    return delivered;
+  }
+
+  return { enqueueCompletionMessage, workerNotifyFn, notifyOwnerAgentCompletionEarly };
+}

package/src/standalone/agent-tool/provider-init.mjs

@@ -0,0 +1,143 @@
+// Provider init de-dup, extracted from the agent-tool facade as a factory so
+// the closure state (`_providerState` / `_providerInitPending`) stays private
+// per agent instance. Behavior-preserving: function bodies are identical to the
+// originals; only `reg` and the chain-gate timeout are injected.
+//
+// Provider init de-dup. Four goals that must not conflict:
+//   (a) a parallel spawn fanout that all targets the SAME provider with the
+//       SAME effective config performs at most ONE initProviders() pass
+//       instead of N serially-awaited registry rebuilds,
+//   (b) a provider CONFIG CHANGE still reaches initProviders() so the
+//       registry's own signature guard can re-initialize it,
+//   (c) two DIFFERENT config signatures for the same provider never init
+//       concurrently — otherwise a slow init of the OLD config could land
+//       after a fast init of the NEW config and revert the live registry to
+//       stale config, and
+//   (d) a SUPERSEDED request never resolves before the provider is actually
+//       ready: even when its own (stale) init is dropped to satisfy (c), the
+//       caller (a spawn about to run prepareSpawn) must still WAIT for the
+//       latest init to finish, or it would proceed against an unprepared /
+//       stale provider.
+//
+// Skip cache + in-flight collapse are keyed on `provider + signature(effective
+// config)`. To satisfy (c) we SERIALIZE all inits per provider on a chain
+// promise and re-check the latest-requested signature inside the chain: a
+// request superseded by a newer signature drops its own init. To satisfy (d)
+// such a dropped request does not resolve immediately — it awaits the
+// provider's latest settled init (tracked as a rolling "ready" promise) so the
+// caller only proceeds once the newest config is live.
+export function createProviderInit(reg, providerChainGateMs) {
+  // Per-provider state. `chain` serializes the ACTUAL initProviders() calls so
+  // two different config signatures never run concurrently (goal c). `latestGen`
+  // / `latestSig` track the newest requested config. `ready` is a rolling
+  // deferred that resolves only when the LATEST requested init has completed —
+  // a superseded caller awaits the ready deferred captured at call time, and
+  // when a newer request arrives the older deferred ADOPTS the newer one, so a
+  // superseded caller transitively waits for the latest init (goal d).
+  const _providerState = new Map(); // provider -> state
+  const _providerInitPending = new Map(); // provider -> { sigKey, promise } identical-sig collapse
+  // Upper bound on how long a queued init waits for the PRIOR chain link before
+  // proceeding anyway. A prior init that HANGS (never settles) must not poison
+  // the chain and wedge every later request behind it. A hung init can never
+  // *complete* against the registry, so it cannot land-after and clobber a
+  // newer config (goal c only fears slow-but-completing inits) — so proceeding
+  // once the gate expires is safe. Defaults to the spawn-prep cap; 0 disables.
+  const PROVIDER_CHAIN_GATE_MS = providerChainGateMs;
+  function providerRegistered(provider) {
+    return typeof reg.getProvider !== 'function' || Boolean(reg.getProvider(provider));
+  }
+  function effectiveProviderConfig(config, provider) {
+    const providers = { ...(config.providers || {}) };
+    providers[provider] = { ...(providers[provider] || {}), enabled: true };
+    return providers;
+  }
+  function providerStateFor(provider) {
+    let s = _providerState.get(provider);
+    if (!s) {
+      s = { chain: Promise.resolve(), completedSig: null, latestSig: null, latestGen: 0, ready: null };
+      _providerState.set(provider, s);
+    }
+    return s;
+  }
+  function providerInitSignature(provider, effectiveProviders) {
+    let body;
+    try { body = JSON.stringify(effectiveProviders); }
+    catch { body = String(Date.now()); } // unserializable → force a fresh init
+    return `${provider}\u0000${body}`;
+  }
+  function gateOnPrior(prior) {
+    const settled = Promise.resolve(prior).catch(() => {});
+    if (!(PROVIDER_CHAIN_GATE_MS > 0)) return settled;
+    return new Promise((resolve) => {
+      let done = false;
+      const finish = () => { if (!done) { done = true; resolve(); } };
+      const timer = setTimeout(finish, PROVIDER_CHAIN_GATE_MS);
+      timer.unref?.();
+      settled.then(() => { clearTimeout(timer); finish(); }, () => { clearTimeout(timer); finish(); });
+    });
+  }
+  function ensureProvider(config, provider) {
+    const effective = effectiveProviderConfig(config, provider);
+    const sigKey = providerInitSignature(provider, effective);
+    const registered = () => providerRegistered(provider);
+    const s = providerStateFor(provider);
+    // Completed-skip: this exact effective config is already live for this
+    // provider. A config change flips sigKey so we fall through; a torn-down
+    // provider (no longer registered) also does.
+    if (s.completedSig === sigKey && registered()) return Promise.resolve();
+    // Identical-sig collapse: a request with the SAME sigKey is already in
+    // flight — share its caller promise.
+    const pending = _providerInitPending.get(provider);
+    if (pending && pending.sigKey === sigKey) return pending.promise;
+    // New generation. Repoint the rolling `ready` deferred to THIS gen and make
+    // the previous gen's deferred ADOPT the new one, so any superseded caller
+    // awaiting an older deferred transitively waits for the newest init (d).
+    const gen = ++s.latestGen;
+    s.latestSig = sigKey;
+    const prevReady = s.ready;
+    let resolveReady;
+    const readyPromise = new Promise((r) => { resolveReady = r; });
+    s.ready = { gen, promise: readyPromise, resolve: resolveReady };
+    if (prevReady && prevReady.gen < gen) {
+      try { prevReady.resolve(readyPromise); } catch { /* already settled */ }
+    }
+    // Serialize the ACTUAL init behind the prior chain link (gated so a hung
+    // prior cannot wedge the chain). A superseded gen's chain link settles
+    // quickly — it never awaits a later gen — so there is no deadlock.
+    const prior = s.chain;
+    const chainLink = gateOnPrior(prior).then(async () => {
+      if (s.latestGen !== gen) {
+        // Superseded before we ran: drop our (stale) init entirely (goal c).
+        // Our `ready` deferred already adopts the newer gen, so the caller below
+        // still waits for the latest init. Settle now to release the chain.
+        return;
+      }
+      try {
+        if (!(s.completedSig === sigKey && registered())) {
+          await reg.initProviders(effective);
+          s.completedSig = sigKey;
+        }
+      } finally {
+        // ALWAYS release this gen's waiters once we are the latest — even on a
+        // registry init failure. Adopting (superseded) callers chained onto this
+        // deferred would otherwise hang forever; instead they proceed and their
+        // own createSession()/prep-timeout surfaces the unprepared provider.
+        resolveReady();
+      }
+    });
+    // Next chain link waits on us (settled, never poisoned).
+    s.chain = chainLink.catch(() => {});
+    // The CALLER awaits the ready deferred (resolves only when the LATEST init
+    // for this provider completes), not just the chain link — so a superseded
+    // caller blocks until the newest config is live (goal d). chainLink is
+    // awaited first so a registry init error surfaces to this caller.
+    const callerPromise = chainLink.then(() => readyPromise).finally(() => {
+      const cur = _providerInitPending.get(provider);
+      if (cur && cur.promise === callerPromise) _providerInitPending.delete(provider);
+    });
+    _providerInitPending.set(provider, { sigKey, promise: callerPromise });
+    return callerPromise;
+  }
+
+  return { ensureProvider };
+}

package/src/standalone/agent-tool/render.mjs

@@ -0,0 +1,152 @@
+// Result-rendering + finish-classification helpers extracted from the
+// agent-tool facade. Pure functions; behavior-preserving (bodies identical to
+// the originals, only cross-module deps are now imported).
+import { appendAgentProgressKv } from '../agent-task-status.mjs';
+import { compactIso, elapsedFromStamps, stripFinalAnswerWrapper } from './helpers.mjs';
+
+// A worker that hits the loop iteration ceiling, gets truncated mid-synthesis,
+// or produces an empty terminal turn returns content:'' but never throws — so
+// the background task would otherwise reconcile as a benign `completed` empty
+// success. That is wrong: an empty final answer is an error. loop.mjs is the
+// single classifier: it tags result.terminationReason for abnormal finishes
+// (carried through manager.mjs terminalResultPreview). We key purely off that
+// here. iteration_cap / truncated are real problems for EVERY agent (hidden
+// too). The plain `empty` case is tagged by the loop ONLY for public agents;
+// hidden agents (explorer/cycle/…) legitimately emit empty terminal turns and
+// are left untagged, so they stay benign.
+export function abnormalEmptyFinishError(result, agent) {
+  // The loop (loop.mjs) is the single classifier: it tags terminationReason
+  // ONLY for abnormal finishes, and gates the `empty` case behind !hidden.
+  // So we key purely off terminationReason here — no separate content/hidden
+  // check, which previously (a) exempted hidden agents from cap/truncated and
+  // (b) let a capped tool-call turn with preamble text slip through as success.
+  const reason = result?.terminationReason;
+  if (!reason) return null;
+  const iterations = result?.iterations ?? 0;
+  const toolCallsTotal = result?.toolCallsTotal ?? 0;
+  const maxLoopIterations = result?.maxLoopIterations ?? 0;
+  const stopReason = result?.stopReason ?? result?.stop_reason ?? null;
+  switch (reason) {
+    case 'iteration_cap':
+      // Real problem for EVERY agent (hidden too): the loop never terminated on
+      // its own contract, so any preamble text is not a trustworthy final answer.
+      return `agent '${agent}' hit the loop iteration ceiling (${maxLoopIterations} iterations, ${toolCallsTotal} tool calls) without producing a final answer`;
+    case 'truncated':
+      return `agent '${agent}' response was truncated (stopReason=${stopReason}) before a final answer (${iterations} iterations, ${toolCallsTotal} tool calls)`;
+    case 'empty':
+      // Only tagged for PUBLIC agents (hidden agents legitimately emit empty
+      // terminal turns and are left untagged by the loop).
+      return `agent '${agent}' finished without a final answer (stopReason=${stopReason ?? 'none'}, ${iterations} iterations, ${toolCallsTotal} tool calls)`;
+    default:
+      return null;
+  }
+}
+
+export function renderResult(value) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') {
+    const lines = [];
+
+    if (Array.isArray(value.workers) || Array.isArray(value.jobs)) {
+      const workers = Array.isArray(value.workers) ? value.workers : [];
+      lines.push(`agents: ${workers.length}`);
+      for (const worker of workers) {
+        const tokens = worker.windowTokens ? ` ctx=${worker.windowTokens}${worker.windowCap ? `/${worker.windowCap}` : ''}` : '';
+        const terminal = worker.clientHostPid ? ` term=${worker.clientHostPid}` : '';
+        const base = `- ${worker.tag} ${worker.agent || 'agent'} ${worker.status || 'idle'}/${worker.worker_stage || worker.stage || 'idle'} ${worker.provider}/${worker.model}${terminal}${tokens}`;
+        lines.push(appendAgentProgressKv(base, worker));
+      }
+      const jobs = Array.isArray(value.jobs) ? value.jobs : [];
+      lines.push(`tasks: ${jobs.length}`);
+      for (const job of jobs) {
+        const target = job.tag || job.sessionId || '-';
+        const terminal = job.clientHostPid ? ` term=${job.clientHostPid}` : '';
+        const base = `- ${job.task_id} ${job.type} ${job.status} target=${target}${terminal}${job.error ? ` error=${job.error}` : ''}`;
+        lines.push(appendAgentProgressKv(base, job));
+      }
+      if (workers.length === 0 && jobs.length === 0) lines.push('(no agents or tasks)');
+      return lines.join('\n');
+    }
+
+    if (value.task_id) {
+      // Spawn/send acks: the task just started, so runtime diagnostics
+      // (worker_stage/last_progress/diagnostic/watchdog/silent_for) are
+      // always in their "not started yet" placeholder state — pure token
+      // cost for the model. Keep the ack minimal (existing surface rule:
+      // minimum characters, maximum information); full diagnostics remain
+      // on explicit status/read recovery calls.
+      const isStartAck = value.status === 'running'
+        && (value.type === 'spawn' || value.type === 'send');
+      lines.push(`agent task: ${value.task_id}`);
+      lines.push(`status: ${value.status}`);
+      if (value.type) lines.push(`type: ${value.type}`);
+      if (value.reused) lines.push('reused: true');
+      if (value.tag || value.sessionId) lines.push(`target: ${value.tag || '-'} ${value.sessionId || ''}`.trim());
+      if (value.agent) lines.push(`agent: ${value.agent}`);
+      if (value.provider && value.model) lines.push(`model: ${value.provider}/${value.model}`);
+      if (value.effort) lines.push(`effort: ${value.effort}`);
+      if (value.fast === true || value.fast === false) lines.push(`fast: ${value.fast ? 'on' : 'off'}`);
+      if (value.maxLoopIterations) {
+        const limitParts = [];
+        if (value.maxLoopIterations) limitParts.push(`loop=${value.maxLoopIterations}`);
+        lines.push(`limits: ${limitParts.join(' ')}`);
+      }
+      if (!isStartAck) {
+        if (value.stage || value.workerStatus) lines.push(`worker: ${value.workerStatus || 'unknown'}/${value.stage || 'unknown'}`);
+        if (value.worker_stage) lines.push(`worker_stage: ${value.worker_stage}`);
+        if (value.last_progress) lines.push(`last_progress: ${value.last_progress}`);
+        if (Number.isFinite(value.silent_for)) lines.push(`silent_for: ${value.silent_for}s`);
+        if (value.watchdog) lines.push(`watchdog: ${value.watchdog}`);
+        if (Number.isFinite(value.queued_followups)) lines.push(`queued_followups: ${value.queued_followups}`);
+        if (value.diagnostic) lines.push(`diagnostic: ${value.diagnostic}`);
+        if (value.startedAt) lines.push(`started: ${compactIso(value.startedAt)}`);
+        if (value.finishedAt) lines.push(`finished: ${compactIso(value.finishedAt)}`);
+        {
+          const elapsed = elapsedFromStamps(value.startedAt, value.finishedAt, value.status);
+          if (elapsed) lines.push(`elapsed: ${elapsed}`);
+        }
+      }
+      if (value.error) lines.push(`error: ${value.error}`);
+      if (value.status === 'running') lines.push('notification: completion will be delivered; end the turn.');
+      if (value.result !== undefined) {
+        const result = value.result;
+        const content = typeof result === 'string' ? result : result?.content;
+        if (content) lines.push('', stripFinalAnswerWrapper(content));
+        else lines.push('', JSON.stringify(result, null, 2));
+      }
+      return lines.join('\n');
+    }
+
+    if (value.queued) {
+      return [
+        'agent message queued',
+        value.reused ? 'reused: true' : null,
+        `target: ${value.tag || '-'} ${value.sessionId || ''}`.trim(),
+        value.agent ? `agent: ${value.agent}` : null,
+        `queueDepth: ${value.queueDepth ?? 1}`,
+      ].filter(Boolean).join('\n');
+    }
+
+    if (value.closed !== undefined) {
+      return [
+        `agent close: ${value.closed ? 'ok' : 'not closed'}`,
+        value.tag ? `tag: ${value.tag}` : null,
+        value.sessionId ? `sessionId: ${value.sessionId}` : null,
+        value.task_id ? `task_id: ${value.task_id}` : null,
+        value.forgotten ? 'forgotten: true' : null,
+      ].filter(Boolean).join('\n');
+    }
+
+    if (value.content !== undefined) {
+      const header = [
+        value.respawned ? 'agent respawned' : 'agent result',
+        value.tag ? `tag=${value.tag}` : null,
+        value.agent ? `agent=${value.agent}` : null,
+        value.provider && value.model ? `${value.provider}/${value.model}` : null,
+      ].filter(Boolean).join(' ');
+      return `${header}\n${stripFinalAnswerWrapper(value.content)}`;
+    }
+  }
+  return JSON.stringify(value, null, 2);
+}