mixdog 0.9.3 → 0.9.4

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);
+}

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

@@ -0,0 +1,55 @@
+// Static agent-tool descriptor + spawn/route constants. Extracted from the
+// agent-tool facade as a behavior-preserving split; values are byte-identical
+// to the originals.
+
+export const PRESET_ALIASES = new Map([
+  ['opus-xhigh', { base: 'opus-high', effort: 'xhigh', id: 'opus-xhigh', name: 'OPUS XHIGH' }],
+]);
+
+export const DEFAULT_AGENT_PRESETS = Object.freeze({
+  explore: 'sonnet-high',
+  maintainer: 'haiku',
+  worker: 'sonnet-high',
+  'heavy-worker': 'sonnet-high',
+  reviewer: 'opus-xhigh',
+  debugger: 'opus-xhigh',
+});
+
+// Mirrors DEFAULT_PROVIDER in mixdog-session-runtime.mjs. Used only as the
+// last-resort fallback when a stored agent route omits its provider and the
+// config carries no defaultProvider.
+export const DEFAULT_PROVIDER = 'anthropic-oauth';
+
+export const WORKER_INDEX_FILE = 'agent-workers.json';
+
+export const ACTIVE_STAGES = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
+
+export const AGENT_TOOL = {
+  name: 'agent',
+  title: 'Agent',
+  annotations: {
+    title: 'Agent',
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+    agentHidden: true,
+  },
+  description: 'Delegate scoped work. Agent handoffs always start background tasks and return task IDs immediately. Spawn independent scopes in parallel with distinct tags; for the same scope/tag, use send or spawn with the same tag to reuse the live session. Wait for the completion notification before dependent work. Do not call status/read after spawn; status/read are manual recovery only.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      type: { type: 'string', enum: ['spawn', 'send', 'list', 'close', 'cancel', 'status', 'read', 'cleanup'], description: 'Action. Default spawn.' },
+      task_id: { type: 'string', description: 'Manual recovery task ID.' },
+      agent: { type: 'string', description: 'Workflow agent id.' },
+      tag: { type: 'string', description: 'Stable scope handle. Reuse the same tag for follow-up on the same scope; use distinct tags only for independent scopes.' },
+      sessionId: { type: 'string', description: 'Raw sess_ id.' },
+      prompt: { type: 'string', description: 'Scoped task brief.' },
+      message: { type: 'string', description: 'Follow-up for send/reuse, or brief.' },
+      file: { type: 'string', description: 'Prompt file.' },
+      cwd: { type: 'string', description: 'Working directory.' },
+      context: { type: 'string', description: 'Extra agent context.' },
+    },
+    additionalProperties: true,
+  },
+};