Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

56.3 KB
Raw Blame
import { streamText, stepCountIs, tool, zodSchema } from 'ai';
import { exposure, noteExposure, noteTurnModel, runWithExposure, type Exposure, type ExposureSource } from '../security/provenance.js';
import { scanForInjection } from '../security/injection-scan.js';
import { summarizeSilentTurn } from '../core/silent-turn.js';
import { z } from 'zod';
import { withAttachments } from '../core/attachments.js';
import type { ChannelAttachment } from '../types/channel.js';
import type { ModelMessage, Tool } from 'ai';
import { isAbsolute, relative, resolve } from 'node:path';
import type { CapabilityRegistry } from '../capabilities/registry.js';
import type { UserMemoryStore } from '../memory/user-memory.js';
import type { TokenBudget } from '../utils/tokens.js';
import type { BaseProvider } from '../providers/base.js';
import { classifyStreamCompletion } from '../core/stream-completion.js';
import { stepsExhaustedPrompt } from '../core/completion-verdict.js';
import { isFailedToolResult } from '../core/execute-guard.js';
import { MAX_AUTOMATIC_CONTINUATIONS } from '../core/execution-limits.js';
import { formatToolStep } from '../utils/tool-label.js';
import { logger } from '../utils/logger.js';
import { stripLoneSurrogates, truncateText } from '../utils/text-safe.js';
import type { BotManifest, BotTrigger } from './types.js';

/** Mailbox messages injected mid-turn (bot-to-bot or queued user input). */
export interface BotTurnMail {
  from: string;
  content: string;
  /** The sender had read untrusted content when it sent this (ADR-044): its record travels with the mail. */
  taint?: BotTaint;
}

/**
 * What a bot (or the owner's turn) had read when it handed work on: the
 * labels of its untrusted sources and whether hidden instructions were found.
 * Carried on mail and delegated jobs so an injection can't be laundered by
 * passing it to a bot that starts clean.
 */
export interface BotTaint {
  sources: string[];
  suspicious: boolean;
}

/** The current turn's exposure as a taint to hand on, or undefined when it read nothing untrusted. */
export function taintOf(e: Exposure = exposure()): BotTaint | undefined {
  if (!e.sources.length && !e.suspicious) return undefined;
  return { sources: e.sources.map((s) => s.label).slice(0, 6), suspicious: e.suspicious };
}

/** Record mail on the receiving turn: the sender's taint, and hidden instructions in the mail itself. */
function noteMailExposure(m: BotTurnMail): void {
  const scan = scanForInjection(m.content);
  if (!m.taint && !scan.suspicious) return;
  const read = m.taint?.sources.length ? ` (it had read: ${m.taint.sources.slice(0, 3).join(', ')})` : '';
  const source: ExposureSource = { label: `a message from bot ${m.from}${read}` };
  const findings = [...scan.findings, ...(m.taint?.suspicious ? [{ where: 'text' as const, excerpt: `${m.from} had read content with instructions to an AI` }] : [])];
  noteExposure(findings.length ? { ...source, findings } : source);
}

/**
 * Real-time bot activity event — what the bot is doing RIGHT NOW. Emitted at
 * AI SDK callback granularity (step start, tool call start/finish) so the
 * surfaces can show live work instead of the coarse idle/running states.
 */
export type BotActivityEvent = {
  botId: string;
  jobId: string;
  kind: 'turn-start' | 'step' | 'tool' | 'turn-end' | 'thinking' | 'queued';
  /** Human-readable: "read_file ~/cookies" / "step 4 · 12.3k tok in". */
  label: string;
  detail?: string;
  stepIndex: number;
  elapsedMs: number;
  status?: 'running' | 'done' | 'error';
  /** kind 'thinking' only: cumulative rolling tails (raw deltas would force
   *  every consumer to reassemble state — tails render stateless instead). */
  reasoningTail?: string;
  textTail?: string;
  /** Filled by the manager for the live feed: when, which bot by name, what started the run. */
  at?: number;
  botName?: string;
  trigger?: string;
  /** turn-start / queued: the full request (≤ 600 chars). */
  prompt?: string;
  /** turn-start / queued: the bot that sent the work, for crew mail. */
  fromBot?: string;
};

/**
 * What a run is expected to leave behind. Computed by the manager from the
 * trigger and the routine's declaration, never by the model:
 * - work:    a deliverable, an action, or a delegation (cron, self-schedule,
 *            manual runs). A run that only wrote notes is NOT done.
 * - message: a delegated task whose reply text IS the result (crew → lead).
 * - check:   a monitoring routine that is allowed to find nothing to do.
 */
export type BotExpectedOutcome = 'work' | 'message' | 'check';

/**
 * What the run did — the journal's `outcome`. Evidence from the tool trace
 * (deliverable, action, delegated), the bot's own report (message: a finding
 * or answer for the owner; quiet: nothing new, said with bot_no_update;
 * failed: bot_report_failure), else none.
 */
export type BotOutcome = 'deliverable' | 'action' | 'delegated' | 'message' | 'quiet' | 'failed' | 'none';

/**
 * How the bot itself closed the run (Bots 2.0): every unattended run ends with
 * exactly one of these. A result goes to the owner's inbox; no_update is
 * recorded quietly (no notification); failure is a failed run even when the
 * turn itself finished.
 */
export interface BotRunReport {
  kind: 'result' | 'no_update' | 'failure';
  summary: string;
  /** result: the job is finished (a goal met), not just progress. */
  complete?: boolean;
}

/** Hard per-turn limits (ADR-020). Overridable per bot via `autonomy`. */
export interface BotTurnLimits {
  /** Tokens (in + out) a single turn may spend before it is cut off. */
  maxTokensPerTurn: number;
  /** Wall-clock minutes a single turn may run. */
  maxTurnMinutes: number;
  /** Tool results kept verbatim in the context window; older ones are stubbed. */
  keepRecentToolResults: number;
  /** Any single tool result larger than this is truncated before the model sees it. */
  maxToolResultChars: number;
  /** Fleet-shared folder write budget per turn: notes are not work. */
  sharedWrites: { softFiles: number; softBytes: number; hardFiles: number; hardBytes: number };
}

export const DEFAULT_TURN_LIMITS: BotTurnLimits = {
  maxTokensPerTurn: 300_000,
  maxTurnMinutes: 20,
  keepRecentToolResults: 8,
  maxToolResultChars: 24_000,
  sharedWrites: { softFiles: 2, softBytes: 32 * 1024, hardFiles: 6, hardBytes: 128 * 1024 },
};

export interface BotTurnInput {
  manifest: BotManifest;
  trigger: BotTrigger;
  /** Durable job id — correlates activity events with the run. */
  jobId?: string;
  prompt: string;
  /** The bot that sent this work (delegated tasks). */
  fromBot?: string;
  /** What the sender had read when it handed this work on (ADR-044). */
  taint?: BotTaint;
  /**
   * The conversation of an interrupted run of this job (a retry after a
   * provider error, a step-budget pause, a restart mid-run): the turn picks up
   * from it instead of redoing every finished step.
   */
  resume?: ModelMessage[];
  /** After every finished step: the conversation so far (without the system prompt), to resume from. */
  onCheckpoint?: (messages: ModelMessage[]) => void;
  /**
   * Photos and PDFs for this turn, already on disk. The runtime reads them here:
   * a caption-less photo becomes `(Attached: names)` because a provider rejects an
   * empty text block, and a model without vision gets a note instead of pixels.
   */
  attachments?: ChannelAttachment[];
  persona: string;
  /** Pending mailbox messages at turn start (attributed bot-to-bot handoffs). */
  mail: BotTurnMail[];
  /** Callback checked between rounds for newly arrived mailbox messages. */
  pollMail: () => BotTurnMail[];
  /** Sandbox areas granted implicitly (rw+x): private workspace + fleet-shared folder. */
  sandbox: { workspace: string; shared: string };
  /** Where finals go (shown to the bot every turn); absent = legacy outputs zone. */
  deliverablesDir?: string;
  /** Skill roster text (native + the bot's own library); empty when none. */
  skillsPrompt?: string;
  /** Fleet hierarchy context (lead crew roster / crew membership); absent for solos. */
  fleet?: {
    role: 'lead' | 'crew';
    leadName?: string;
    crew: Array<{ id: string; name: string; description?: string; state: string }>;
    maxCrew: number;
  };
  /** Outcome contract for this run (default 'work'). */
  expects?: BotExpectedOutcome;
  /** Journal digest of the last few runs (ADR-021): continuity without records. */
  recentRuns?: string;
  /** The bot's own working-state note (bot_state). */
  stateNote?: string;
  limits?: Partial<BotTurnLimits>;
  capabilities: CapabilityRegistry;
  tools: Record<string, Tool>;
  userMemory: UserMemoryStore | null;
  provider: BaseProvider;
  tokenBudget: TokenBudget;
  abortSignal: AbortSignal;
  /** Real-time activity consumer (roster, live regions, web feed). */
  onActivity?: (ev: BotActivityEvent) => void;
}

/** One tool call as the trace saw it: name, whether it worked, where it wrote. */
export interface BotToolTraceEntry {
  name: string;
  ok: boolean;
  /** `path` / `command` / `target` argument, when the tool has one. */
  arg?: string;
  /** bot_send with task: true. */
  task?: boolean;
}

export interface BotTurnOutput {
  status: 'completed' | 'failed' | 'halted' | 'paused';
  /** What this run read that was untrusted, to carry on with any result it hands to another bot. */
  taint?: BotTaint;
  output: string;
  tokensIn: number;
  tokensOut: number;
  /** Distinct tool names the turn used (drives auto-skill synthesis). */
  toolsUsed: string[];
  error?: string;
  reasonCode?: string;
  /** Wall-clock start of the turn itself (the job's createdAt is the enqueue time). */
  startedAt: number;
  steps: number;
  toolCalls: number;
  /** Largest single-step prompt the provider saw — the context-growth meter. */
  peakInputTokens: number;
  outcome: BotOutcome;
  /** The bot's own close of the run, when it gave one. */
  report?: BotRunReport;
  /** Paths of files delivered via bot_deliver this turn. */
  deliverables: string[];
  /** The reply claimed delivery/execution but the trace shows none. */
  claimedWithoutAction: boolean;
  /** The no-outcome nudge was issued (once per turn). */
  outcomeNudged: boolean;
  trace: BotToolTraceEntry[];
}

const MAX_STEPS_DEFAULT = 25;

/** Said to the model when a run resumes from its checkpoint. */
const RESUME_NOTE = '[Resumed] This run was interrupted (an error, a pause or a restart) and continues here. '
  + 'Everything above already happened: do not redo finished steps or deliver a file twice. Carry on from where it stopped, then close the run as usual.';

/** 'thinking' tail emission cadence — a live preview, not a firehose. */
const THINKING_EMIT_INTERVAL_MS = 300;
/** Rolling tail cap per field; surfaces render the tail bottom-anchored. */
const THINKING_TAIL_CHARS = 600;

/** Steps allowed for the single no-outcome continuation round. */
const NUDGE_STEPS = 8;

/** File tools whose target path decides sandbox (notes) vs outside (action). */
const FILE_WRITE_TOOLS: ReadonlySet<string> = new Set(['write_file', 'create_file', 'edit_file', 'delete_file']);
/** Tools whose success IS an action regardless of arguments. */
const ACTION_TOOLS: ReadonlySet<string> = new Set([
  'git_add', 'git_commit', 'git_push', 'create_pr', 'create_issue', 'github_api', 'use_skill', 'bot_spawn', 'bot_retire',
]);
/** run_command heads that only look: not an action. */
const READ_ONLY_COMMANDS: ReadonlySet<string> = new Set([
  'ls', 'cat', 'head', 'tail', 'wc', 'grep', 'rg', 'find', 'stat', 'file', 'du', 'df', 'pwd', 'echo', 'date', 'which',
  'cmp', 'diff', 'md5', 'md5sum', 'sha1sum', 'sha256sum', 'shasum', 'test', 'true', 'false', 'printf', 'env', 'uname', 'tree', 'less', 'more',
]);

const CLAIM_PATTERN = /\b(delivered|filed|shipped|published|executed|committed|pushed|posted|sent|deployed|uploaded)\b/i;

/**
 * One run of one bot: a fresh-context tool loop over the bot's own provider,
 * persona, toolset, memory namespace, and fail-closed permission manager.
 * Structurally mirrors SubAgent.run() minus the shared-registry hazards:
 * every dependency here is already per-bot.
 *
 * Governed (ADR-020): a hard token and wall-clock cap per turn, tool results
 * compacted as the context grows, a per-turn write budget on the shared
 * folder, and an OUTCOME verdict computed from the tool trace — a run that
 * only wrote notes gets one nudge to deliver or admit it, and is journaled
 * as `none` if it still produced nothing.
 */
/**
 * What the turn says. A provider rejects an empty text block, so a photo sent with no
 * caption names itself instead of arriving as empty text — the same rule the chat route
 * applies (`web/api/chat.ts`).
 */
export function turnCaption(prompt: string, files: ChannelAttachment[]): string {
  const trimmed = prompt.trim();
  if (trimmed) return trimmed;
  if (files.length === 0) return '';
  return `(Attached: ${files.map(f => f.name ?? 'file').join(', ')})`;
}

/**
 * One bot turn, with its own record of the untrusted content it reads
 * (ADR-044): what one bot reads never gates another, or the main agent.
 */
export async function runBotTurn(input: BotTurnInput): Promise<BotTurnOutput> {
  // Work handed on by a tainted bot starts tainted (ADR-044): never clean.
  const start: Exposure = input.taint
    ? { sources: [{ label: `work handed on by ${input.fromBot ?? 'another bot'} (it had read: ${input.taint.sources.slice(0, 3).join(', ') || 'outside content'})`, ...(input.taint.suspicious ? { findings: [{ where: 'text' as const, excerpt: 'the sender had read content with instructions to an AI' }] } : {}) }], suspicious: input.taint.suspicious }
    : { sources: [], suspicious: false };
  return runWithExposure(start, () => runBotTurnInScope(input));
}

async function runBotTurnInScope(input: BotTurnInput): Promise<BotTurnOutput> {
  const { manifest, provider, capabilities, tokenBudget } = input;
  const maxSteps = manifest.autonomy?.maxSteps ?? MAX_STEPS_DEFAULT;
  const limits = resolveTurnLimits(manifest, input.limits);
  const expects: BotExpectedOutcome = input.expects ?? defaultExpectation(input.trigger);
  const startedAt = Date.now();

  // Prompt caching: the stable prefix (identity, persona, rules, folders,
  // fleet protocol — ~10-20k tokens) is re-sent on every step. Marked for
  // Anthropic's cache it costs a tenth from the second step on; the per-run
  // parts (memory, recent runs, state, budget) follow the marker so they
  // never invalidate it. Providers that don't know the option ignore it.
  const prompt = buildBotSystemPrompt(input);
  const messages: ModelMessage[] = [
    { role: 'system', content: prompt.stable, providerOptions: { anthropic: { cacheControl: { type: 'ephemeral' } } } } as ModelMessage,
    ...(prompt.volatile ? [{ role: 'system', content: prompt.volatile } as ModelMessage] : []),
  ];
  const leadingSystem = messages.length;
  const resuming = (input.resume?.length ?? 0) > 0;

  if (resuming) {
    messages.push(...input.resume!, { role: 'user', content: RESUME_NOTE });
  }
  for (const m of resuming ? [] : input.mail) {
    noteMailExposure(m);
    messages.push({ role: 'user', content: `Message from 🤖 ${m.from}:\n\n${m.content}` });
  }
  const files = resuming ? [] : input.attachments ?? [];
  const caption = resuming ? '' : turnCaption(input.prompt, files);
  if (caption) {
    messages.push({ role: 'user', content: caption });
  }
  if (messages.length === leadingSystem) {
    messages.push({ role: 'user', content: 'You have no specific task. Check your inbox; if nothing needs doing, call bot_no_update.' });
  }
  if (files.length > 0) {
    // Same transformation channels get: image/file parts for a model that takes them,
    // a plain note otherwise. Rewrites the last user message in place.
    const turnMessage = {
      id: `bot-${manifest.id}-${Date.now()}`,
      channelId: manifest.id,
      channelType: 'bot',
      senderId: manifest.id,
      content: caption,
      timestamp: Date.now(),
      metadata: { attachments: files },
    } as never;
    const withFiles = withAttachments(messages, turnMessage, provider.name, provider.getModel(), provider.seesImages);
    messages.splice(0, messages.length, ...withFiles);
  }

  let tokensIn = 0;
  let tokensOut = 0;
  let peakInputTokens = 0;
  let lastResult: { text: string; finishReason: unknown } | null = null;
  let stepsRemaining = maxSteps;
  let budgetContinuations = 0;
  let stepIndex = 0;
  let outcomeNudged = false;
  const toolsUsed = new Set<string>();
  const trace: BotToolTraceEntry[] = [];
  const deliveries: string[] = [];
  const onActivity = input.onActivity;
  const emit = (ev: { kind: BotActivityEvent['kind']; label: string; detail?: string; stepIndex: number; status?: BotActivityEvent['status']; elapsedMs?: number; reasoningTail?: string; textTail?: string }): void => {
    if (!onActivity) return;
    try {
      onActivity({
        botId: manifest.id,
        jobId: input.jobId ?? '',
        elapsedMs: ev.elapsedMs ?? Date.now() - startedAt,
        kind: ev.kind,
        label: ev.label,
        detail: ev.detail,
        stepIndex: ev.stepIndex,
        status: ev.status,
        reasoningTail: ev.reasoningTail,
        textTail: ev.textTail,
      });
    } catch { /* activity feedback must never break a turn */ }
  };

  // Turn governor: a local abort the caps trip, chained to the caller's
  // halt signal. The reason tells the two apart in the catch below.
  const governor = new AbortController();
  let governorReason: 'turn_budget' | 'turn_time' | null = null;
  const trip = (reason: 'turn_budget' | 'turn_time'): void => {
    if (governor.signal.aborted) return;
    governorReason = reason;
    governor.abort();
  };
  const onHalt = (): void => governor.abort();
  if (input.abortSignal.aborted) governor.abort();
  else input.abortSignal.addEventListener('abort', onHalt, { once: true });
  const deadline = setTimeout(() => trip('turn_time'), limits.maxTurnMinutes * 60_000);
  deadline.unref?.();
  const halted = (): boolean => input.abortSignal.aborted;

  let report: BotRunReport | undefined;
  const tools = {
    ...wrapBotTools(input.tools, {
      sandbox: input.sandbox,
      limits,
      onDelivered: (path) => deliveries.push(path),
    }),
    ...runReportTools((r) => { report = r; }),
  };

  const baseOutput = () => ({
    ...(taintOf() ? { taint: taintOf() } : {}),
    tokensIn, tokensOut, toolsUsed: [...toolsUsed], startedAt, steps: stepIndex, toolCalls: trace.length,
    peakInputTokens, deliverables: [...deliveries], outcomeNudged, trace: [...trace], ...(report ? { report } : {}),
  });
  const outcomeNow = (text: string): BotOutcome => computeOutcome({ trace, deliveries, expects, text, sandbox: input.sandbox, report });

  try {
    emit({ kind: 'turn-start', stepIndex: 0, label: input.prompt ? input.prompt.slice(0, 80) : 'Checking inbox' });
    while (stepsRemaining > 0 && !governor.signal.aborted) {
      // This round's steps (assistant tool calls + tool results), cumulative: what the next
      // round and a resumed run need to see, not just the round's last words.
      let roundMessages: ModelMessage[] = [];
      // streamText, not generateText: the deltas are the real-time feedback
      // inside the bot's thread (reasoning + reply tails). Same options and
      // step-count semantics; the result's final promises preserve the old
      // result shape exactly (text/finishReason), so all classification below
      // is unchanged.
      let streamError: unknown = null;
      noteTurnModel(provider.getModel());
      const stream = streamText({
        model: provider.getModelInstance(),
        messages,
        tools,
        stopWhen: stepCountIs(stepsRemaining),
        abortSignal: governor.signal,
        experimental_include: { requestBody: false },
        // Context compaction: every step re-sends the whole conversation, so
        // 25 steps of 60KB tool results is a multi-megatoken prompt. Keep
        // the newest results verbatim (capped), stub the rest.
        prepareStep: ({ messages: stepMessages }: { messages: ModelMessage[] }) => ({ messages: compactMessages(stepMessages, limits) }),
        experimental_onStepStart: () => {
          stepIndex++;
          emit({ kind: 'step', stepIndex, label: `step ${stepIndex}` });
        },
        experimental_onToolCallStart: ({ toolCall }: any) => {
          const label = formatToolStep(String(toolCall?.toolName ?? 'tool'), (toolCall?.input ?? {}) as Record<string, any>);
          emit({ kind: 'tool', stepIndex, label, status: 'running' });
        },
        experimental_onToolCallFinish: ({ toolCall, success, error, durationMs }: any) => {
          const label = formatToolStep(String(toolCall?.toolName ?? 'tool'), (toolCall?.input ?? {}) as Record<string, any>);
          emit({
            kind: 'tool',
            stepIndex,
            label,
            detail: error != null ? String(error?.message ?? error).slice(0, 200) : undefined,
            status: success ? 'done' : 'error',
            elapsedMs: typeof durationMs === 'number' ? durationMs : undefined,
          });
        },
        onStepFinish: ({ usage, toolCalls, toolResults, response }: { usage?: { inputTokens?: number; outputTokens?: number }; toolCalls?: unknown[]; toolResults?: unknown[]; response?: { messages?: unknown[] } }) => {
          if (governor.signal.aborted) return;
          stepsRemaining--;
          if (Array.isArray(response?.messages)) {
            roundMessages = response.messages as ModelMessage[];
            try { input.onCheckpoint?.([...messages.slice(leadingSystem), ...roundMessages]); } catch { /* a checkpoint is best effort */ }
          }
          if (usage) {
            tokensIn += usage.inputTokens ?? 0;
            tokensOut += usage.outputTokens ?? 0;
            peakInputTokens = Math.max(peakInputTokens, usage.inputTokens ?? 0);
          }
          for (const tc of (toolCalls ?? []) as Array<{ toolName?: string; toolCallId?: string }>) {
            if (tc?.toolName) toolsUsed.add(String(tc.toolName));
            trace.push(traceEntry(tc, ((toolResults ?? []) as Array<{ toolCallId?: string; output?: ToolOutput }>).find((r) => r?.toolCallId !== undefined && r.toolCallId === tc?.toolCallId)));
          }
          const kIn = Math.round(tokensIn / 100) / 10;
          emit({ kind: 'step', stepIndex, label: `step ${stepIndex} · ${kIn}k tok in` });
          if (tokensIn + tokensOut > limits.maxTokensPerTurn) trip('turn_budget');
        },
      });

      // Live thinking feedback: consume the full stream, accumulate rolling
      // tails, emit at most every THINKING_EMIT_INTERVAL_MS (a TUI re-render
      // per delta would thrash ink). Tails are per-round: a new generation
      // round starts thinking anew. Step boundaries insert a paragraph break
      // so multi-step narrations don't run together (same fix as the main
      // chat's stepAwareTextStream).
      let reasoningTail = '';
      let textTail = '';
      let lastEmit = 0;
      const flushThinking = (): void => {
        if (!onActivity) return;
        if (!reasoningTail && !textTail) return;
        lastEmit = Date.now();
        emit({ kind: 'thinking', stepIndex, label: 'thinking', reasoningTail, textTail });
      };
      for await (const part of stream.fullStream) {
        if (part.type === 'reasoning-delta' && part.text) {
          reasoningTail = (reasoningTail + part.text).slice(-THINKING_TAIL_CHARS);
        } else if (part.type === 'text-delta' && part.text) {
          textTail = (textTail + part.text).slice(-THINKING_TAIL_CHARS);
        } else if (part.type === 'start-step' && (reasoningTail || textTail)) {
          reasoningTail += '\n\n';
          textTail += '\n\n';
        } else if (part.type === 'error') {
          // The provider's real error. Without this, `stream.text` below
          // throws the generic "No output generated" and the journal never
          // learns it was an invalid key or a 429.
          streamError = (part as { error?: unknown }).error ?? streamError;
        }
        if (Date.now() - lastEmit >= THINKING_EMIT_INTERVAL_MS) flushThinking();
      }
      flushThinking();

      let result: { text: string; finishReason: unknown };
      try {
        const [finalText, finishReason] = await Promise.all([stream.text, stream.finishReason]);
        result = { text: finalText, finishReason };
      } catch (err) {
        throw streamError ?? err;
      }
      if (streamError && !result.text) throw streamError;
      lastResult = result;

      const completion = classifyStreamCompletion({
        finishReason: result.finishReason as never,
        hasText: Boolean(result?.text),
        hasToolCalls: true,
      });
      if (completion === 'interrupted') {
        throw new Error('Generation was interrupted before completion (no finish signal from provider)');
      }

      if (roundMessages.length > 0) {
        messages.push(...roundMessages);
      } else if (result.text) {
        messages.push({ role: 'assistant', content: result.text });
      }

      // Step budget exhausted with tool calls still pending is a PAUSE, never
      // a completion (sub-agent completion contract). Mirror the main agent's
      // bounded auto-continuation: refill the budget and resume the SAME
      // conversation in-process — the old path requeued the job and rebuilt
      // the turn from scratch, discarding every completed step and re-burning
      // the budget redoing the first 25 steps. The per-turn token cap is the
      // runaway guard; past the continuation bound the paused return below
      // still applies.
      if (stepsRemaining <= 0 && lastResult?.finishReason === 'tool-calls') {
        if (!governor.signal.aborted && budgetContinuations < MAX_AUTOMATIC_CONTINUATIONS) {
          budgetContinuations++;
          logger.warn(
            { botId: manifest.id, rounds: budgetContinuations, budget: maxSteps },
            'Bot step budget exhausted mid-turn — continuing with a fresh budget',
          );
          messages.push({ role: 'user', content: stepsExhaustedPrompt(input.prompt) });
          stepsRemaining = maxSteps;
          continue;
        }
        break;
      }

      // Consume newly arrived mailbox messages before finishing, so a
      // handoff delivered mid-turn is not lost to the next scheduling gap.
      if (!governor.signal.aborted && stepsRemaining > 0 && !report) {
        const fresh = input.pollMail();
        if (fresh.length > 0) {
          for (const m of fresh) {
            noteMailExposure(m);
            messages.push({ role: 'user', content: `Message from 🤖 ${m.from}:\n\n${m.content}` });
          }
          continue;
        }
      }

      // Outcome gate: the trace, not the reply, says whether work happened.
      // A run expected to produce work that only read and wrote notes gets
      // exactly one nudge — deliver now, or say plainly that nothing was
      // done. Bounded like the execute guard; never a loop.
      if (!governor.signal.aborted && expects === 'work' && !outcomeNudged && !report
        && outcomeNow(result.text) === 'none') {
        outcomeNudged = true;
        emit({ kind: 'step', stepIndex, label: 'no deliverable yet — asking for one' });
        messages.push({ role: 'user', content: noOutcomePrompt(input) });
        stepsRemaining = Math.min(maxSteps, NUDGE_STEPS);
        continue;
      }
      break;
    }

    if (halted()) {
      return { status: 'halted', output: 'Turn was halted.', outcome: 'none', claimedWithoutAction: false, ...baseOutput() };
    }
    if (governorReason) {
      return governedFailure(governorReason, lastResult?.text, limits, baseOutput(), input, trace, deliveries, expects, emit, stepIndex);
    }

    // Step budget exhausted with tool calls still pending — pause, never
    // report success on half-done work (sub-agent completion contract).
    // Last resort only: reached past the in-process continuation bound.
    if (stepsRemaining <= 0 && lastResult?.finishReason === 'tool-calls') {
      emit({ kind: 'turn-end', stepIndex, label: 'paused — step budget', status: 'done' });
      return {
        status: 'paused',
        output: 'Step budget reached before the turn completed — remaining work continues next turn.',
        reasonCode: 'step_budget',
        outcome: outcomeNow(''),
        claimedWithoutAction: false,
        ...baseOutput(),
      };
    }

    // The bot's own report is what the owner reads; its last words are the fallback.
    // Neither a report nor last words: say what the run did, from its own trace.
    const output = (report?.summary || lastResult?.text || '').trim() || summarizeSilentTurn(trace.map((t) => ({
      tool: t.name,
      input: t.arg === undefined ? {} : t.name === 'run_command' ? { command: t.arg } : { path: t.arg },
      ok: t.ok,
    })));
    const outcome = outcomeNow(lastResult?.text ?? '');
    const claimedWithoutAction = outcome === 'none' && CLAIM_PATTERN.test(output);

    tokenBudget.recordUsage({
      provider: provider.name,
      model: provider.getModel(),
      inputTokens: tokensIn,
      outputTokens: tokensOut,
      totalTokens: tokensIn + tokensOut,
      channelType: 'bot',
    });

    emit({ kind: 'turn-end', stepIndex, label: outcome === 'none' && expects === 'work' ? 'completed — no deliverable' : 'completed', status: 'done' });
    return { status: 'completed', output, outcome, claimedWithoutAction, ...baseOutput() };
  } catch (err) {
    if (halted()) {
      emit({ kind: 'turn-end', stepIndex, label: 'halted', status: 'done' });
      return { status: 'halted', output: 'Turn was halted.', outcome: 'none', claimedWithoutAction: false, ...baseOutput() };
    }
    if (governorReason) {
      return governedFailure(governorReason, lastResult?.text, limits, baseOutput(), input, trace, deliveries, expects, emit, stepIndex);
    }
    const message = err instanceof Error ? err.message : String(err);
    emit({ kind: 'turn-end', stepIndex, label: `failed: ${message.slice(0, 80)}`, status: 'error' });
    return {
      status: 'failed',
      output: `Turn failed: ${message}`,
      error: message,
      reasonCode: classifyFailure(err),
      outcome: outcomeNow(''),
      claimedWithoutAction: false,
      ...baseOutput(),
    };
  } finally {
    clearTimeout(deadline);
    input.abortSignal.removeEventListener('abort', onHalt);
  }
}

function governedFailure(
  reason: 'turn_budget' | 'turn_time',
  partialText: string | undefined,
  limits: BotTurnLimits,
  base: ReturnType<() => Omit<BotTurnOutput, 'status' | 'output' | 'outcome' | 'claimedWithoutAction'>>,
  input: BotTurnInput,
  trace: BotToolTraceEntry[],
  deliveries: string[],
  expects: BotExpectedOutcome,
  emit: (ev: { kind: BotActivityEvent['kind']; label: string; stepIndex: number; status?: BotActivityEvent['status'] }) => void,
  stepIndex: number,
): BotTurnOutput {
  const what = reason === 'turn_budget'
    ? `the ${Math.round(limits.maxTokensPerTurn / 1000)}k-token cap for one turn`
    : `the ${limits.maxTurnMinutes}-minute cap for one turn`;
  // Token spend of a cut-off turn is still spend.
  input.tokenBudget.recordUsage({
    provider: input.provider.name,
    model: input.provider.getModel(),
    inputTokens: base.tokensIn,
    outputTokens: base.tokensOut,
    totalTokens: base.tokensIn + base.tokensOut,
    channelType: 'bot',
  });
  emit({ kind: 'turn-end', stepIndex, label: `stopped — ${what}`, status: 'error' });
  return {
    status: 'failed',
    output: `Turn stopped at ${what} (${base.steps} steps, ${base.toolCalls} tool calls).`
      + (partialText ? `\n\nLast reply before the cut-off:\n${partialText.slice(0, 2000)}` : ''),
    error: `turn limit: ${reason}`,
    reasonCode: reason,
    outcome: computeOutcome({ trace, deliveries, expects, text: '', sandbox: input.sandbox }),
    claimedWithoutAction: false,
    ...base,
  };
}

/**
 * The outcome contract when the caller did not set one: a conversation
 * (chat, a bot's mail, a channel message) is answered by its reply; an
 * unattended wake (cron, self-schedule, API) must produce work.
 */
export function defaultExpectation(trigger: BotTrigger): BotExpectedOutcome {
  return trigger === 'cron' || trigger === 'api' || trigger === 'cloud' ? 'work' : 'message';
}

export function resolveTurnLimits(manifest: BotManifest, overrides?: Partial<BotTurnLimits>): BotTurnLimits {
  const a = manifest.autonomy ?? {};
  return {
    ...DEFAULT_TURN_LIMITS,
    ...(overrides ?? {}),
    ...(a.maxTokensPerTurn ? { maxTokensPerTurn: a.maxTokensPerTurn } : {}),
    ...(a.maxTurnMinutes ? { maxTurnMinutes: a.maxTurnMinutes } : {}),
    sharedWrites: { ...DEFAULT_TURN_LIMITS.sharedWrites, ...(overrides?.sharedWrites ?? {}) },
  };
}

/**
 * The text a failure is classified on: the message, and what the error wraps.
 *
 * The AI SDK reports a cut stream as "Failed to process successful response" and keeps the real
 * reason in `cause` — an ECONNRESET, a body cut mid-read, a JSON parse error. Reading only the
 * message sent every one of those to unknown_error: no retry, DLQ, needs-you. A network blip then
 * looked like a permanent fault, and the owner was told a bot had failed when it had merely lost
 * its socket.
 */
function failureText(err: unknown): string {
  const parts: string[] = [];
  const seen = new Set<unknown>();
  let current: unknown = err;
  for (let depth = 0; current != null && depth < 5 && !seen.has(current); depth++) {
    seen.add(current);
    const wrapped = current as { message?: unknown; code?: unknown; cause?: unknown };
    if (typeof wrapped.message === 'string') parts.push(wrapped.message);
    if (typeof wrapped.code === 'string') parts.push(wrapped.code);
    current = wrapped.cause;
  }
  return parts.join(' | ').toLowerCase();
}

/** Map a provider/tool error to a typed reason code (retry vs permanent). */
export function classifyFailure(err: unknown): string {
  let msg = failureText(err);
  // Retry wrappers ("Failed after 3 attempts. Last error: …") carry the
  // real cause after the colon — classify that, not the wrapper.
  const inner = /last error:\s*(.+)$/s.exec(msg);
  if (inner) msg = inner[1];
  if (/rate.?limit|429|too many requests/.test(msg)) return 'provider_rate_limit';
  // Network blips ARE transient — ECONNRESET (connection dropped mid-read)
  // and friends used to fall through to unknown_error, so a plain
  // connection blip went straight to the DLQ with a needs-you flag instead
  // of retrying like every other transient failure. "timed out" (with a
  // space) is how several providers phrase a deadline miss. "terminated" is
  // undici's wording for a response body cut mid-stream; "socket connection
  // was closed" is Node's. Both were 135 DLQ entries in one fleet.
  if (/timeout|timed out|etimedout|econnaborted|econnreset|econnrefused|epipe|enotfound|eai_again|getaddrinfo|fetch failed|socket|terminated|network|interrupted before completion/.test(msg)) return 'provider_timeout';
  // The SDK's "No output generated" means the stream ended before any step:
  // a provider hiccup, not a permanent condition.
  if (/no output generated/.test(msg)) return 'provider_empty';
  // The SDK's wrapper around a 2xx response it could not read or parse. Nothing
  // permanent lives there — a cut stream, a truncated body, an HTML page — and the
  // cause above already claimed the network cases; whatever is left is still a retry.
  if (/failed to process successful response/.test(msg)) return 'provider_empty';
  if (/no llm providers available/.test(msg)) return 'provider_unavailable';
  if (/permission denied|blocked command|no permission/.test(msg)) return 'permission_denied';
  if (/api key|unauthorized|401|authentication/.test(msg)) return 'provider_auth';
  if (/quota|billing|402/.test(msg)) return 'provider_quota';
  if (/context|maximum.*tokens|too long/.test(msg)) return 'context_overflow';
  return 'unknown_error';
}

/** Transient failures may retry; permanent ones go straight to the DLQ. */
export function isTransientFailure(reasonCode: string): boolean {
  return reasonCode === 'provider_rate_limit' || reasonCode === 'provider_timeout' || reasonCode === 'provider_empty';
}

/**
 * Turn-limit failures are terminal for the job but are NOT escalations: the
 * bot was stopped by policy, not by a fault. Settled done, no DLQ, no
 * "needs you" — the owner is told once (ADR-020).
 */
export function isTurnLimitFailure(reasonCode: string | undefined): boolean {
  return reasonCode === 'turn_budget' || reasonCode === 'turn_time';
}

// ---- outcome verdict ------------------------------------------------------

type ToolOutput = { type?: string; value?: unknown } | string | undefined;

function traceEntry(toolCall: { toolName?: string; input?: unknown } | undefined, toolResult: { output?: ToolOutput } | undefined): BotToolTraceEntry {
  const name = String(toolCall?.toolName ?? 'tool');
  const inputArgs = (toolCall?.input ?? {}) as Record<string, unknown>;
  const output = toolResult?.output;
  const text = toolResultText(output);
  const failedOutput = typeof output === 'object' && (output?.type === 'error-text' || output?.type === 'error-json');
  const ok = toolResult !== undefined && !failedOutput && !isFailedToolResult(text);
  const arg = typeof inputArgs.path === 'string' ? inputArgs.path
    : typeof inputArgs.command === 'string' ? inputArgs.command
      : typeof inputArgs.target === 'string' ? inputArgs.target
        : typeof inputArgs.file === 'string' ? inputArgs.file
          : undefined;
  return { name, ok, arg, ...(inputArgs.task === true ? { task: true } : {}) };
}

function toolResultText(output: ToolOutput): string {
  if (!output) return '';
  if (typeof output === 'string') return output;
  if (output.type === 'text' || output.type === 'error-text') return String(output.value ?? '');
  if (output.type === 'json' || output.type === 'error-json') {
    try { return JSON.stringify(output.value ?? ''); } catch { return ''; }
  }
  return '';
}

function insideAny(target: string, roots: string[]): boolean {
  const abs = resolve(target.replace(/^~(?=$|\/|\\)/, process.env.HOME ?? ''));
  return roots.some((root) => {
    const rel = relative(resolve(root), abs);
    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
  });
}

export function isReadOnlyCommand(command: string): boolean {
  const head = command.trim().split(/\s+/)[0]?.replace(/^.*\//, '') ?? '';
  // A pipeline or chain with any non-read head is not read-only.
  const heads = command.split(/\s*(?:\|\||&&|;|\|)\s*/).map((seg) => seg.trim().split(/\s+/)[0]?.replace(/^.*\//, '') ?? '');
  return heads.every((h) => READ_ONLY_COMMANDS.has(h)) && READ_ONLY_COMMANDS.has(head);
}

/**
 * What the run did, by evidence. Order matters: a delivery beats everything;
 * an action outside the sandbox beats a delegation; `message` only counts
 * when the run's contract is a reply.
 */
export function computeOutcome(input: {
  trace: BotToolTraceEntry[];
  deliveries: string[];
  expects: BotExpectedOutcome;
  text: string;
  sandbox: { workspace: string; shared: string };
  report?: BotRunReport;
}): BotOutcome {
  // A reported failure is a failure, whatever else happened on the way.
  if (input.report?.kind === 'failure') return 'failed';
  if (input.deliveries.length > 0) return 'deliverable';
  const roots = [input.sandbox.workspace, input.sandbox.shared];
  for (const t of input.trace) {
    if (!t.ok) continue;
    if (ACTION_TOOLS.has(t.name)) return 'action';
    if (FILE_WRITE_TOOLS.has(t.name) && t.arg && !insideAny(t.arg, roots)) return 'action';
    if (t.name === 'run_command' && t.arg && !isReadOnlyCommand(t.arg)) return 'action';
  }
  if (input.trace.some((t) => t.ok && t.name === 'bot_send' && t.task)) return 'delegated';
  if (input.report?.kind === 'no_update') return 'quiet';
  // A reported finding is a result for the owner, even without a file.
  if (input.report?.kind === 'result' && input.report.summary.trim().length > 0) return 'message';
  if (input.expects === 'message' && input.text.trim().length > 0) return 'message';
  return 'none';
}

function noOutcomePrompt(input: BotTurnInput): string {
  const where = input.deliverablesDir ? ` into ${input.deliverablesDir}` : '';
  return `[outcome check] This run has not been closed: no deliverable, no action, and no report. `
    + `Notes are not work. Do ONE of these now, then stop:\n`
    + `1. A finished file: deliver it with bot_deliver${where}, then call bot_report with what it is.\n`
    + `2. A finding or answer for the owner (no file needed): call bot_report with it.\n`
    + `3. Nothing new or nothing to do: call bot_no_update with one line why. Do not write a record about it.\n`
    + `4. You couldn't do it: call bot_report_failure with the reason.`;
}

// ---- context compaction ---------------------------------------------------

/**
 * Keep the newest tool results verbatim (each capped), replace older ones
 * with a short stub. The model can re-run a tool it still needs; it cannot
 * afford to re-send 60KB of every file it ever read on every step.
 */
type ToolResultPart = { type: 'tool-result'; toolName?: string; output?: ToolOutput };

/**
 * No lone UTF-16 surrogate may reach the JSON body: `JSON.stringify` writes it as `\ud83c`, and
 * DeepSeek then rejects the whole request — "400 Failed to parse the request body as JSON:
 * messages[6].content: unexpected end of hex escape". An index-based cut through an emoji is enough
 * to produce one, and it can come from anywhere (tool result, prompt, deliverable), so everything
 * leaving for the model is cleaned, not just what this function truncates.
 */
function sanitizeString(value: string): string {
  return /[\uD800-\uDFFF]/.test(value) ? stripLoneSurrogates(value) : value;
}

function sanitizeModelMessages(messages: ModelMessage[]): ModelMessage[] {
  let changed = false;
  const out = messages.map((m) => {
    if (typeof m.content === 'string') {
      const clean = sanitizeString(m.content);
      if (clean === m.content) return m;
      changed = true;
      return { ...m, content: clean } as ModelMessage;
    }
    if (!Array.isArray(m.content)) return m;
    let partChanged = false;
    type OutgoingPart = { type?: string; text?: unknown; output?: { type?: string; value?: unknown } };
    const parts = (m.content as unknown as OutgoingPart[]).map((p) => {
      if (p?.type === 'text' && typeof p.text === 'string') {
        const clean = sanitizeString(p.text);
        if (clean !== p.text) {
          partChanged = true;
          return { ...p, text: clean };
        }
        return p;
      }
      if (p?.type === 'tool-result' && typeof p.output?.value === 'string') {
        const clean = sanitizeString(p.output.value);
        if (clean !== p.output.value) {
          partChanged = true;
          return { ...p, output: { ...p.output, value: clean } };
        }
      }
      return p;
    });
    if (!partChanged) return m;
    changed = true;
    return { ...m, content: parts } as unknown as ModelMessage;
  });
  return changed ? out : messages;
}

export function compactMessages(messages: ModelMessage[], limits: Pick<BotTurnLimits, 'keepRecentToolResults' | 'maxToolResultChars'>): ModelMessage[] {
  const resultRefs: Array<{ mi: number; pi: number }> = [];
  messages.forEach((m, mi) => {
    if (m?.role !== 'tool' || !Array.isArray(m.content)) return;
    (m.content as unknown as Array<{ type?: string }>).forEach((p, pi) => {
      if (p?.type === 'tool-result') resultRefs.push({ mi, pi });
    });
  });
  if (resultRefs.length === 0) return sanitizeModelMessages(messages);
  const stubBefore = Math.max(0, resultRefs.length - limits.keepRecentToolResults);
  const out = messages.slice();
  resultRefs.forEach(({ mi, pi }, idx) => {
    const content = out[mi].content as unknown as ToolResultPart[];
    const part = content[pi];
    const output = part.output;
    const text = toolResultText(output);
    if (typeof output === 'object' && output?.type === 'content') return; // media parts: leave alone
    let next: string | null = null;
    if (idx < stubBefore) {
      if (text.length > 400) {
        next = `${truncateText(text, 400)}\n[…${text.length - 400} more chars trimmed from an earlier step — re-run ${part.toolName ?? 'the tool'} if you need it]`;
      }
    } else if (text.length > limits.maxToolResultChars) {
      next = `${truncateText(text, limits.maxToolResultChars)}\n[…truncated ${text.length - limits.maxToolResultChars} chars]`;
    }
    if (next === null) return;
    if (out[mi] === messages[mi]) out[mi] = { ...messages[mi], content: (messages[mi].content as unknown as ToolResultPart[]).slice() } as ModelMessage;
    (out[mi].content as unknown as ToolResultPart[])[pi] = { ...part, output: { type: 'text', value: next } };
  });
  return sanitizeModelMessages(out);
}

// ---- tool wrapping: delivery capture + shared-folder write budget ----------

/**
 * Wrap the bot's toolset so the turn can see what matters without parsing
 * replies: deliveries (bot_deliver's destination) and writes into the
 * fleet-shared folder (budgeted — the shared folder is for data other bots
 * consume, not for narration; a soft limit warns, a hard limit refuses).
 */
export function wrapBotTools(
  tools: Record<string, Tool>,
  ctx: { sandbox: { workspace: string; shared: string }; limits: BotTurnLimits; onDelivered: (path: string) => void },
): Record<string, Tool> {
  const out: Record<string, Tool> = { ...tools };
  const shared = { files: new Set<string>(), bytes: 0 };
  const { sharedWrites } = ctx.limits;
  type ToolArgs = Record<string, unknown>;
  type Exec = (args: ToolArgs, options: unknown) => Promise<unknown>;
  const wrap = (name: string, fn: (original: Exec, args: ToolArgs, options: unknown) => Promise<unknown>): void => {
    const original = tools[name];
    if (!original || typeof original.execute !== 'function') return;
    const exec = original.execute.bind(original) as Exec;
    out[name] = { ...original, execute: (args: ToolArgs, options: unknown) => fn(exec, args, options) } as Tool;
  };

  wrap('bot_deliver', async (exec, args, options) => {
    const result = await exec(args, options);
    const m = /^Delivered to (.+?) —/.exec(String(result ?? ''));
    if (m) ctx.onDelivered(m[1]);
    return result;
  });

  for (const name of ['write_file', 'create_file', 'edit_file']) {
    wrap(name, async (exec, args, options) => {
      const target = typeof args?.path === 'string' ? args.path : '';
      const inShared = target && insideAny(resolve(ctx.sandbox.workspace, target), [ctx.sandbox.shared]);
      if (!inShared) return exec(args, options);
      const bytes = String(args?.content ?? args?.new_string ?? '').length;
      const nextFiles = shared.files.has(target) ? shared.files.size : shared.files.size + 1;
      if (nextFiles > sharedWrites.hardFiles || shared.bytes + bytes > sharedWrites.hardBytes) {
        return `Error: shared-folder write budget for this run is used up (${shared.files.size} files, ${Math.round(shared.bytes / 1024)}KB). `
          + `_shared is for data other bots consume, not for notes or records. Keep working notes in your private workspace, `
          + `and deliver finished results with bot_deliver.`;
      }
      const result = await exec(args, options);
      const text = String(result ?? '');
      if (isFailedToolResult(text)) return result;
      shared.files.add(target);
      shared.bytes += bytes;
      if (shared.files.size > sharedWrites.softFiles || shared.bytes > sharedWrites.softBytes) {
        return `${text}\n\n[Note: this run has written ${shared.files.size} files / ${Math.round(shared.bytes / 1024)}KB to the shared folder. `
          + `That is a lot for one run — the shared folder is for data other bots consume. Notes belong in your private workspace; finals go through bot_deliver.]`;
      }
      return result;
    });
  }
  return out;
}

// ---- closing a run --------------------------------------------------------

/**
 * The three ways a run ends (Bots 2.0). The bot says which — a tool call, not
 * a phrase to match — so "nothing new" is recorded quietly, a finding reaches
 * the owner's inbox, and a run that couldn't do its job is a failure even
 * when the turn itself finished.
 */
export function runReportTools(onReport: (r: BotRunReport) => void): Record<string, Tool> {
  const done = 'Recorded. Stop now: end your turn without further tool calls.';
  return {
    bot_report: tool({
      description:
        'Close this run with a result for the owner: what you did or found, in a few plain sentences (they read it in their inbox). '
        + 'Deliver any finished files with bot_deliver first; they are attached automatically. complete: true when the job is finished, not just progress.',
      inputSchema: zodSchema(z.object({
        summary: z.string().min(1).max(4000).describe('What you did or found, for the owner. Plain sentences; lead with the answer.'),
        complete: z.boolean().optional().describe('true = the job is done (its goal is met); omit for progress.'),
      })),
      execute: async ({ summary, complete }: { summary: string; complete?: boolean }) => {
        onReport({ kind: 'result', summary: summary.trim(), ...(complete ? { complete: true } : {}) });
        return done;
      },
    }) as Tool,
    bot_no_update: tool({
      description:
        'Close this run with nothing new to report (nothing changed, nothing to do). It is recorded quietly: the owner is not notified. '
        + 'Use it instead of writing a status note or saying "nothing to do".',
      inputSchema: zodSchema(z.object({
        reason: z.string().max(300).optional().describe('One line: why there is nothing new.'),
      })),
      execute: async ({ reason }: { reason?: string }) => {
        onReport({ kind: 'no_update', summary: (reason ?? '').trim() || 'Nothing new.' });
        return done;
      },
    }) as Tool,
    bot_report_failure: tool({
      description:
        'Close this run as failed: you could not do the job (missing access, broken input, a service down). Say why, and what would fix it. '
        + 'The owner is told. Do not use it for "nothing to do" (that is bot_no_update).',
      inputSchema: zodSchema(z.object({
        reason: z.string().min(1).max(1000).describe('What stopped you, and what would fix it.'),
      })),
      execute: async ({ reason }: { reason: string }) => {
        onReport({ kind: 'failure', summary: reason.trim() });
        return done;
      },
    }) as Tool,
  };
}

// ---- system prompt --------------------------------------------------------

/**
 * The bot's system prompt in two parts. `stable` is the same on every run of
 * this bot (identity, persona, rules, folders, roster, fleet protocol), so a
 * provider can cache it; `volatile` changes per run (memory retrieved for this
 * prompt, recent runs, state note, crew states, budget) and follows it.
 */
export function buildBotSystemPrompt(input: BotTurnInput): { stable: string; volatile: string } {
  const { manifest } = input;
  let prompt = `You are "${manifest.name}", a Mercury bot (id: ${manifest.id}).\n`;
  if (manifest.description) {
    prompt += `Role: ${manifest.description}\n`;
  }
  prompt += '\n';
  prompt += input.persona;

  prompt += `\n\nOperating rules:
- You run unattended: NEVER ask the user questions or wait for confirmation. If a required input is missing, state the assumption you are proceeding with.
- Actions you lack permission for are denied automatically (fail-closed). Do not attempt workarounds; report what you could not do.
- Stay in your specialty; say so plainly when a request falls outside it.
- Work, don't narrate: a run is judged by what it delivered or changed, not by what it wrote about itself. Do not write records, receipts, logs or status files about your own runs — Mercury keeps the journal.
- END EVERY RUN WITH EXACTLY ONE of: bot_report (a result or finding for the owner; deliver files first), bot_no_update (nothing new — recorded quietly, nobody is notified), bot_report_failure (you couldn't do it, and why). Then stop.`;

  // Sandbox: the bot's always-granted work areas (rw+x, no permission ask).
  prompt += `\n\nSandbox (always granted — read, write, execute; no permission needed):
- Private workspace: ${input.sandbox.workspace} — your scratch area: drafts, intermediate work, compiled artifacts.
- Fleet-shared folder: ${input.sandbox.shared} — one folder shared with all other bots, for DATA other bots consume (a dossier, a dataset, a draft handed to the next stage). Not for notes about your work; writes here are budgeted per run.
Anything outside these two areas and your declared Access grants is denied.`;

  if (input.deliverablesDir) {
    prompt += `\n\nDeliverables — where the owner finds your results: ${input.deliverablesDir}
- When a result is finished, call bot_deliver on the file (give it a human title; mark final: true for the finished piece the owner asked for). Never write there by hand.
- Intermediate stages (research, drafts, checks) are delivered as work, not finals; the lead delivers the final.
- Then close the run with bot_report saying what you delivered.`;
  }

  const roster = manifest.comms?.canMessage ?? [];
  if (roster.length > 0) {
    prompt += `\n\nBots you can message via bot_send: ${roster.join(', ')}.`;
  }

  if (input.skillsPrompt) {
    prompt += `\n\n${input.skillsPrompt}`;
    prompt += `\nSkill scripts are subject to your access grants: a skill whose scripts you cannot run from its own directory can be copied into your sandbox workspace and run from there.`;
  }

  // Fleet hierarchy: the lead orchestrates, the crew executes. The crew list
  // (with live states) is per-run; the protocol is stable.
  if (input.fleet?.role === 'lead') {
    prompt += `\n\nYou lead a fleet of crew bots (the current crew is listed below, under "This run").

Fleet protocol:
- SELF-ORGANIZE: if your crew is empty or lacks a specialist the task needs, BUILD IT FIRST with bot_spawn — design each sub-bot's role and persona from YOUR persona and the current task (e.g. a product lead spawns research/QA/support specialists). Do not report that you lack a team; hire one. Then delegate.
- DELEGATE with fleet_delegate — several typed tasks in one call, each with a goal and what "done" means. You are woken ONCE with a digest when they finish (or the deadline passes): finish your turn after delegating, never poll.
- If you have a pipeline (fleet_pipeline), use it for the standard job: the stages chain themselves and you are woken at the end.
- MONITOR with fleet_status / fleet_tasks only when you need to — results come to you.
- You may create specialists with bot_spawn (crew cap: ${input.fleet.maxCrew}) and retire your own crew with bot_retire.
- Crew run CONCURRENTLY — dispatch independent work in parallel rather than sequentially.
- You SYNTHESIZE: crew results arrive in your mailbox attributed by bot; combine them and report a single coherent outcome with bot_report.${input.fleet.leadName ? `\n- You are also crew of **${input.fleet.leadName}** — your task results return to it automatically; treat it as your manager.` : ''}`;
  } else if (input.fleet?.role === 'crew') {
    prompt += `\n\nYou are crew in **${input.fleet.leadName ?? 'your lead'}'s** fleet. Tasks delegated to you (mailbox messages with a task) return your result to the lead automatically when you finish — make your bot_report a complete, self-contained report. Use bot_send to ask the lead questions mid-task.`;
  }

  // ---- per run -----------------------------------------------------------
  let volatile = '';
  // Scoped memory injection — mirrors the main agent's injection site, but
  // into the bot's own namespace (scope own/shared-read; scope none = null).
  if (input.userMemory) {
    try {
      const query = input.mail.map(m => m.content).join(' ') || input.prompt;
      const relevant = input.userMemory.retrieveRelevant(query, { maxRecords: 5, maxChars: 900 });
      if (relevant?.context) {
        volatile += `\n\n[Bot memory — auto-retrieved context]\n${relevant.context}`;
      }
    } catch (err: any) {
      logger.warn({ botId: manifest.id, err: err?.message }, 'Bot memory retrieval failed — continuing without');
    }
  }
  // Continuity (ADR-021): what the journal already knows, and the bot's own
  // note. Together they replace "records about records" — nothing here
  // needs to be written to disk by the bot.
  if (input.recentRuns) {
    volatile += `\n\nYour recent runs (from the journal — you do not need to record these):\n${input.recentRuns}`;
  }
  if (input.stateNote) {
    volatile += `\n\nYour working state (set with bot_state; replace it when it changes):\n${input.stateNote}`;
  }
  if (input.fleet?.role === 'lead') {
    const crew = input.fleet.crew.length > 0
      ? input.fleet.crew.map(c => `- ${c.name} (${c.id})${c.description ? ` — ${c.description}` : ''} [${c.state}]`).join('\n')
      : '(EMPTY — build your team first, see the fleet protocol)';
    volatile += `\n\nYour crew right now:\n${crew}`;
  }
  volatile += `\n\nToken budget remaining: ${input.tokenBudget.getRemaining()}`;

  return { stable: prompt, volatile: `This run:${volatile}` };
}