@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/mcp/tools/agent-tools.ts

@@ -0,0 +1,700 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { itemBuild } from '../../local/local-build-summary'
+import type { LocalProject } from '../../local/local-project'
+import { providerRefusal } from '../../local/local-provider-refusal'
+import { plainVariables, redactedVariablesOfTimeline, variablesOfTimeline } from '../../local/local-test-cases'
+import { chatTarget, type ToolCall } from '../../local/local-test-runner'
+import { dropTurn, readTurn, reattachTurn, startTurn, TURN_IDLE_MS, type HeldTurn, type PendingDecision, type TurnRead } from '../mcp-chat'
+import { errorResult, intArg, jsonResult, stringArg, type McpTool, type ToolResult } from '../mcp-protocol'
+import { requireRuntime, serviceCall, studioLink, type RuntimeLink } from '../mcp-runtime'
+import { awaitTurnTrace, conversationTraces, getTrace, listTraces, proceduresOf, readTrace, replyCheckOf, replyChecksOfTrace, type ReplyCheck } from '../mcp-traces'
+
+/**
+ * Talk to an Agent and read what it did: the coding agent changes an Agent,
+ * chats with its draft on the local runtime, and reads the trace, so it can
+ * tell whether the change made things better without asking the person to
+ * open Studio. Every answer carries the Studio links the person can open.
+ */
+
+/** One message of a conversation as `agent_chat` saw it, in the stored messages' shape. */
+export interface SeenMessage {
+  role: 'user' | 'assistant'
+  parts: Array<{ type: string; text?: string; toolName?: string; input?: unknown; state?: string }>
+}
+
+/**
+ * What this MCP connection remembers between calls: the last conversation
+ * with each Agent and its last turn (for `test_save_case`), each
+ * conversation's agent and transcript as `agent_chat` saw it (a test
+ * conversation goes when the draft's test copy is replaced, so a case can
+ * still be saved from it), and the turns that wait on the person's answer.
+ */
+export interface McpMemory {
+  lastConversation: Map<string, { conversationId: string; agentId: string; at: string; lastTurn?: { reply: string; toolCalls: ToolCall[] } }>
+  conversations: Map<string, { agent: string; agentId: string; agentName: string; live: boolean; transcript: SeenMessage[]; realActions?: boolean; realActionsNote?: string | null; variables?: Record<string, unknown> }>
+  waiting: Map<string, { held: HeldTurn; pending: PendingDecision; since: string; before: string[] }>
+}
+
+export function createMemory(): McpMemory {
+  return { lastConversation: new Map(), conversations: new Map(), waiting: new Map() }
+}
+
+export type Decision = 'approve' | 'deny' | 'confirm' | 'cancel'
+export const DECISIONS: readonly Decision[] = ['approve', 'deny', 'confirm', 'cancel']
+
+/** What a decision answers: an approval card (approve, deny) or a person confirmation (confirm, cancel). */
+export function decisionKind(decision: Decision): PendingDecision['kind'] {
+  return decision === 'approve' || decision === 'deny' ? 'approval' : 'confirmation'
+}
+
+/** Everything that waits on the person in a conversation, as the runtime lists it: confirmations, then approvals. */
+async function pendingOnRuntime(link: RuntimeLink, conversationId: string): Promise<PendingDecision[]> {
+  const q = `conversationId=${encodeURIComponent(conversationId)}`
+  const confirmations = await serviceCall<Array<{ id: string; status: string; summary: string; details: string | null; confirmLabel: string; cancelLabel: string; expiresAt?: string }>>(link, `/v1/chat/confirmations?${q}`, { timeoutMs: 15_000 }).catch(() => [])
+  const approvals = await serviceCall<Array<{ id: string; status: string; pauseReason?: string; policyReason?: string | null; askedBecause?: string | null; toolCallId: string | null; toolName: string | null; actionSummary?: string | null; expiresAt?: string | null }>>(link, `/v1/chat/approvals?${q}`, { timeoutMs: 15_000 }).catch(() => [])
+  return [
+    ...(Array.isArray(confirmations) ? confirmations : [])
+      .filter((c) => c.status === 'pending')
+      .map((c): PendingDecision => ({ kind: 'confirmation', id: c.id, summary: c.summary, details: c.details, confirmLabel: c.confirmLabel, cancelLabel: c.cancelLabel, ...(c.expiresAt ? { expiresAt: c.expiresAt } : {}) })),
+    ...(Array.isArray(approvals) ? approvals : [])
+      .filter((a) => a.status === 'pending' && (!a.pauseReason || a.pauseReason === 'needs_approval'))
+      .map((a): PendingDecision => ({ kind: 'approval', id: a.id, toolCallId: a.toolCallId, tool: a.toolName, summary: a.actionSummary ?? null, ...(a.expiresAt ? { expiresAt: String(a.expiresAt) } : {}), ...askedOf(a.policyReason ?? null, a.askedBecause ?? null) })),
+  ]
+}
+
+/**
+ * What waits, as the agent reads it, and how to decide it: `agent_decide`,
+ * an explicit call per decision. Nothing here ever decides for the person.
+ */
+/** Why an approval card asked, from the runtime's answer: its reason and whether the binding or the chat's approval mode asked. */
+function askedOf(reason: string | null, askedBecause: string | null): { reason?: string; askedBecause?: 'binding' | 'approval-mode' } {
+  return {
+    ...(reason ? { reason } : {}),
+    ...(askedBecause === 'binding' || askedBecause === 'approval-mode' ? { askedBecause } : {}),
+  }
+}
+
+export function pendingDecisionView(pending: PendingDecision, conversationId: string): Record<string, unknown> {
+  const choices = pending.kind === 'approval' ? ['approve', 'deny'] : ['confirm', 'cancel']
+  return {
+    kind: pending.kind,
+    id: pending.id,
+    toolName: pending.kind === 'approval' ? pending.tool : null,
+    summary: pending.summary || null,
+    ...(pending.kind === 'confirmation' && pending.details ? { details: pending.details } : {}),
+    ...(pending.kind === 'confirmation' ? { labels: { confirm: pending.confirmLabel, cancel: pending.cancelLabel } } : {}),
+    expiresAt: pending.expiresAt ?? null,
+    ...(pending.kind === 'approval' && pending.reason ? { reason: pending.reason } : {}),
+    ...(pending.kind === 'approval' && pending.askedBecause
+      ? { askedBecause: pending.askedBecause === 'binding' ? 'the binding asks for approval before each run' : 'the chat\'s approval mode asks before a change (an Unattended binding keeps it only in a dataset run on the published Agent)' }
+      : {}),
+    decide: `agent_decide { "conversationId": "${conversationId}", "id": "${pending.id}", "decision": "${choices[0]}" | "${choices[1]}" }: decide it as the person would on the card. Typed words never answer a card.`,
+  }
+}
+
+/** The runtime's 409 `decision_pending` for a message sent while a card waits: what waits, or null for any other answer. */
+export function pendingFromConflict(message: string): PendingDecision[] | null {
+  if (!/answered 409/.test(message)) return null
+  const json = message.slice(message.indexOf('{'))
+  try {
+    const body = JSON.parse(json) as { details?: { reason?: string; pending?: Array<{ kind?: string; id?: string; toolName?: string | null; summary?: string | null; expiresAt?: string | null; reason?: string | null; askedBecause?: string | null }> } }
+    if (body.details?.reason !== 'decision_pending') return null
+    return (body.details.pending ?? [])
+      .filter((p) => typeof p.id === 'string')
+      .map((p): PendingDecision =>
+        p.kind === 'confirmation'
+          ? { kind: 'confirmation', id: p.id!, summary: p.summary ?? '', details: null, confirmLabel: 'Confirm', cancelLabel: 'Cancel', ...(p.expiresAt ? { expiresAt: p.expiresAt } : {}) }
+          : { kind: 'approval', id: p.id!, toolCallId: null, tool: p.toolName ?? null, summary: p.summary ?? null, ...(p.expiresAt ? { expiresAt: p.expiresAt } : {}), ...askedOf(p.reason ?? null, p.askedBecause ?? null) },
+      )
+  } catch {
+    // The body was clipped, or is not the runtime's: the reason is in the words.
+    return /decision_pending/.test(message) ? [] : null
+  }
+}
+
+/** The answer when a message cannot go on until the person decides. */
+function decideFirst(conversationId: string, pending: PendingDecision[]): ToolResult {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            conversationId,
+            status: 'decision_pending',
+            why: 'The Agent waits on the person in this conversation, so a new message cannot go on until it is decided. Decide it with agent_decide (approve or deny a tool, confirm or cancel a confirmation), or start a new conversation.',
+            pendingDecisions: pending.map((p) => pendingDecisionView(p, conversationId)),
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  }
+}
+
+/** The stored conversation's agent and run, or null when it is gone. */
+async function storedConversation(link: RuntimeLink, conversationId: string): Promise<{ agentName: string | null; activeRunId: string | null } | null> {
+  try {
+    const s = await serviceCall<{ agentName?: string | null; activeRunId?: string | null }>(link, `/v1/sessions/${encodeURIComponent(conversationId)}`, { timeoutMs: 15_000 })
+    return { agentName: s.agentName ?? null, activeRunId: s.activeRunId ?? null }
+  } catch (err) {
+    if (/answered 404/.test((err as Error).message)) return null
+    throw err
+  }
+}
+
+/** Why a conversation is gone, in words the agent can act on. */
+export function goneConversation(conversationId: string): string {
+  return `Conversation ${conversationId} is no longer on the local runtime. A conversation with a draft lives on the draft's test copy, which is replaced when the draft changes (an apply), when the Agent is published, or after an hour unused; its conversations go with it. Start a new one: agent_chat without conversationId.`
+}
+
+/**
+ * The model the Agent's file names: the mode its `config.defaultMode` names,
+ * which a chat without a chosen mode runs on; else its first mode by sort order.
+ */
+export function configuredModel(root: string, slug: string): string | null {
+  try {
+    const doc = JSON.parse(readFileSync(join(root, 'agents', slug, 'agent.json'), 'utf8')) as {
+      config?: { defaultMode?: unknown }
+      modelConfigs?: Array<{ modelSlug?: unknown; modeKey?: unknown; sortOrder?: unknown }>
+    }
+    const modes = (doc.modelConfigs ?? []).filter((m) => typeof m.modelSlug === 'string')
+    const defaultMode = doc.config?.defaultMode
+    const named = typeof defaultMode === 'string' ? modes.find((m) => m.modeKey === defaultMode) : undefined
+    const first = named ?? [...modes].sort((a, b) => Number(a.sortOrder ?? 0) - Number(b.sortOrder ?? 0))[0]
+    return (first?.modelSlug as string | undefined) ?? null
+  } catch {
+    return null
+  }
+}
+
+/** The model the local runtime runs instead, from what the last apply recorded ("…names the model X, which this runtime does not have; it uses Y here"). */
+export function substitutedModel(adaptations: readonly string[], configured: string): string | null {
+  for (const text of adaptations) {
+    const match = /names the model (\S+), which this runtime does not have; it uses (\S+) here/i.exec(text)
+    if (match && match[1] === configured) return match[2]!
+  }
+  return null
+}
+
+/** What the Agent's file asks for and what this turn ran on, when they differ or the runtime says so. */
+function modelOf(project: LocalProject, slug: string, ranOn: string[]) {
+  const configured = configuredModel(project.root, slug)
+  if (!configured) return ranOn.length ? { configured: null, used: ranOn[0]!, ...(ranOn.length > 1 ? { ranOn } : {}) } : null
+  const swapped = substitutedModel(itemBuild(project.root, `agent/${slug}`, project.id)?.adaptations ?? [], configured)
+  return {
+    configured,
+    used: swapped ?? configured,
+    ...(swapped ? { substituted: true, why: `The local runtime has no ${configured}; this Agent runs on ${swapped} here. Replies may differ from the workspace.` } : {}),
+    ...(ranOn.length ? { ranOn } : {}),
+  }
+}
+
+/** The tools a turn was offered, from its \`pi.turn N\` spans' metadata (sorted names), or null when the runtime did not record them. */
+export function toolsOfferedOf(spans: Array<{ name: string; metadata?: Record<string, unknown> }>): string[] | null {
+  const names = new Set<string>()
+  let seen = false
+  for (const span of spans) {
+    if (!/^pi\.turn\b/.test(span.name)) continue
+    const offered = span.metadata?.toolsOffered
+    if (!Array.isArray(offered)) continue
+    seen = true
+    for (const n of offered) if (typeof n === 'string') names.add(n)
+  }
+  return seen ? [...names].sort() : null
+}
+
+/**
+ * What the reply check did this turn: from the session's \`reply.blocked\`
+ * events after \`since\`, else the turn's \`reply.blocked\` spans (the same
+ * fields, on the trace). The last check, read as the agent needs it — the
+ * check, what it found, what the person got, both drafts (clipped) — with the
+ * earlier ones this turn when there were several. Null when no check fired.
+ */
+export function replyBlockedOf(
+  timeline: Array<{ type?: string; createdAt?: string; payload?: Record<string, unknown> | null }>,
+  since: string,
+  spans: Array<{ name: string; startTime?: string | null; level?: string; statusMessage?: string | null; output?: unknown; metadata?: Record<string, unknown> | null }> = [],
+): (ReplyCheck & { times?: number; earlier?: ReplyCheck[] }) | null {
+  const events = timeline.filter((e) => e.type === 'reply.blocked' && (!e.createdAt || Date.parse(e.createdAt) >= Date.parse(since)))
+  const checks = events.length ? events.map((e) => replyCheckOf(e.payload ?? {}, e.createdAt)) : replyChecksOfTrace(spans)
+  const last = checks.at(-1)
+  if (!last) return null
+  return checks.length > 1 ? { ...last, times: checks.length, earlier: checks.slice(0, -1) } : last
+}
+
+/**
+ * Whether a test conversation runs actions for real, from its Test setup
+ * (the `TRY_SETUP` event the Try route records when the conversation starts):
+ * true or false, or null when the conversation has no setup recorded.
+ */
+export function realActionsOfTimeline(timeline: Array<{ type?: string; payload?: Record<string, unknown> | null }>): boolean | null {
+  const setup = timeline.find((e) => e.payload?.event === 'TRY_SETUP')
+  if (!setup) return null
+  return setup.payload?.simulateActions === false
+}
+
+/** Whether a conversation runs actions for real: as this connection started it, else as its Test setup recorded. */
+export async function conversationRunsRealActions(memory: McpMemory, link: RuntimeLink, agentId: string, conversationId: string): Promise<{ realActions: boolean; realActionsNote: string | null }> {
+  const known = memory.conversations.get(conversationId)
+  if (known?.realActions !== undefined) return { realActions: known.realActions, realActionsNote: known.realActionsNote ?? null }
+  const recorded = agentId ? realActionsOfTimeline(await sessionTimeline(link, agentId, conversationId)) : null
+  if (known && recorded !== null) known.realActions = recorded
+  return { realActions: recorded === true, realActionsNote: null }
+}
+
+/**
+ * The variables a conversation started with (`customer_id: CST-00028`), so a
+ * case saved from it replays with them: as this connection set them, else as
+ * its Test setup recorded them (`variables` on the `TRY_SETUP` event, when the
+ * runtime records them). Only plain values, which is what a case file holds;
+ * `redacted` names the sensitive ones the setup recorded without a value.
+ */
+export async function conversationVariables(
+  memory: McpMemory,
+  link: RuntimeLink,
+  agentId: string,
+  conversationId: string,
+): Promise<{ variables: Record<string, string | number | boolean> | undefined; redacted: string[] }> {
+  const known = memory.conversations.get(conversationId)?.variables
+  if (known) return { variables: plainVariables(known), redacted: [] }
+  if (!agentId) return { variables: undefined, redacted: [] }
+  // Read from the Test setup: a sensitive variable is named there (`redactedVariables`), never its value.
+  const timeline = await sessionTimeline(link, agentId, conversationId)
+  return { variables: variablesOfTimeline(timeline), redacted: redactedVariablesOfTimeline(timeline) }
+}
+
+/** The conversation's session events, through the Agent's Try route; none when it cannot be read. */
+async function sessionTimeline(link: RuntimeLink, agentId: string, conversationId: string) {
+  try {
+    const session = await serviceCall<{ timeline?: Array<{ type?: string; createdAt?: string; payload?: Record<string, unknown> | null }> } | null>(
+      link,
+      `/v1/config/agents/${encodeURIComponent(agentId)}/try/conversations/${encodeURIComponent(conversationId)}/session`,
+      { timeoutMs: 15_000 },
+    )
+    return session?.timeline ?? []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * What the reply check did to a conversation's last reply, for a test case
+ * that failed: the checks of the last turn (after its last
+ * \`message.received\`), and how many fired on earlier turns. Read from the
+ * session timeline when it records one, else from the conversation's traces
+ * (a test copy that is gone keeps its traces). Null when no check fired.
+ */
+export function lastReplyChecks(
+  timeline: Array<{ type?: string; createdAt?: string; payload?: Record<string, unknown> | null }>,
+  traces: Array<{ timestamp: string; observations: Array<{ name: string; type?: string; startTime?: string | null; metadata?: Record<string, unknown> | null; statusMessage?: string | null }> }>,
+): { lastReply: string; checks: ReplyCheck[]; earlierTurns?: number } | null {
+  let checks: ReplyCheck[] = []
+  let earlier = 0
+  if (timeline.some((e) => e.type === 'reply.blocked')) {
+    const lastMessage = timeline.map((e) => e.type).lastIndexOf('message.received')
+    timeline.forEach((e, i) => {
+      if (e.type !== 'reply.blocked') return
+      if (i > lastMessage) checks.push(replyCheckOf(e.payload ?? {}, e.createdAt))
+      else earlier += 1
+    })
+  } else {
+    // A turn's trace has its \`pi.turn N\` spans (a title or summary written afterwards is a trace without them); the newest is the last turn.
+    const isTurn = (t: (typeof traces)[number]) => t.observations.some((o) => /^pi\.turn\b/.test(o.name))
+    const turns = (traces.some(isTurn) ? traces.filter(isTurn) : traces).sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+    const blocked = turns.map((t) => replyChecksOfTrace(t.observations))
+    checks = blocked.at(-1) ?? []
+    earlier = blocked.slice(0, -1).reduce((n, list) => n + list.length, 0)
+  }
+  if (!checks.length && !earlier) return null
+  const last = checks.at(-1)
+  const lastReply = !last
+    ? 'not changed by the reply check (it fired on an earlier turn)'
+    : last.replacedWithFixedReply
+      ? `replaced with the fixed safe reply: the ${last.check} check failed both drafts`
+      : `changed by the reply check (${last.check}, ${last.outcome}): the graded reply is not the Agent's first draft`
+  return { lastReply, checks, ...(earlier ? { earlierTurns: earlier } : {}) }
+}
+
+/** The reply checks of a test case's conversation, read as \`lastReplyChecks\` does; null when nothing can be read. */
+export async function caseReplyChecks(link: RuntimeLink, agentId: string | undefined, conversationId: string | undefined) {
+  if (!conversationId) return null
+  const timeline = agentId ? await sessionTimeline(link, agentId, conversationId) : []
+  // The trace records a check even when the session record of it was lost.
+  return lastReplyChecks(timeline, []) ?? lastReplyChecks([], await conversationTraces(link, conversationId).catch(() => []))
+}
+
+export function agentTools(project: LocalProject, memory: McpMemory): McpTool[] {
+  /**
+   * The turn as the agent reads it: the reply so far, what the Agent waits
+   * on (kept, with its stream, for the answer), or why the turn stopped
+   * without finishing; then the trace, the model and the links.
+   */
+  async function finishTurn(args: {
+    conversationId: string
+    agentId: string
+    held: HeldTurn
+    read: TurnRead
+    since: string
+    before: string[]
+    started: number
+    live: boolean
+    realActions: boolean
+    realActionsNote: string | null
+    answered?: Record<string, unknown>
+  }): Promise<ToolResult> {
+    const link = requireRuntime(project)
+    const { conversationId, read } = args
+    const slug = memory.conversations.get(conversationId)?.agent ?? ''
+    const ms = Date.now() - args.started
+    memory.lastConversation.set(slug, { conversationId, agentId: args.agentId, at: new Date().toISOString(), lastTurn: { reply: read.reply, toolCalls: read.toolCalls } })
+    const remembered = memory.conversations.get(conversationId)
+    if (read.end.status === 'waiting') {
+      const end = read.end
+      // The stream names the card; the runtime's list adds what it says and when it expires.
+      const listed = (await pendingOnRuntime(link, conversationId)).find((p) => p.id === end.pending.id)
+      if (listed) end.pending = { ...listed, ...(end.pending.kind === 'approval' && end.pending.tool && listed.kind === 'approval' && !listed.tool ? { tool: end.pending.tool } : {}) } as PendingDecision
+      memory.waiting.set(conversationId, { held: args.held, pending: end.pending, since: args.since, before: args.before })
+    } else {
+      memory.waiting.delete(conversationId)
+      dropTurn(args.held)
+      if (remembered && (read.reply || read.toolCalls.length)) {
+        remembered.transcript.push({
+          role: 'assistant',
+          parts: [
+            ...read.toolCalls.map((t) => ({ type: `tool-${t.name}`, input: t.args, state: t.ok ? 'output-available' : 'output-error' })),
+            ...(read.reply ? [{ type: 'text', text: read.reply }] : []),
+          ],
+        })
+      }
+    }
+    // A turn that waits has not ended, so its trace may still be open: look, but do not wait long.
+    const turn = await awaitTurnTrace(link, conversationId, { before: new Set(args.before), since: args.since, ...(read.end.status === 'finished' ? {} : { waitMs: 3_000 }) })
+    const blocked = replyBlockedOf(await sessionTimeline(link, args.agentId, conversationId), args.since, turn?.trace.observations ?? [])
+    const model = modelOf(project, slug, turn?.models ?? [])
+    // The tools the turn was offered, as the runtime records them on each \`pi.turn N\` span.
+    const toolsOffered = toolsOfferedOf(turn?.trace.observations ?? [])
+    // Each action the draft did not run is an `action.simulated` span on the turn's trace.
+    const simulated = (turn?.trace.observations ?? []).filter((o) => o.name === 'action.simulated').map((o) => ({ ...(o.metadata ?? {}), ...(o.input ? { input: o.input } : {}) }))
+    // The procedure each model turn ran under, and why (`procedure.active`), and the ones the model loaded.
+    const procedures = proceduresOf(turn?.trace.observations ?? [])
+    const stopped =
+      read.end.status === 'idle'
+        ? `The runtime took the turn but sent nothing for ${Math.round(read.end.silentMs / 1000)} s${read.lastEvent ? ` after "${read.lastEvent}"` : ' (no event at all)'}${read.runId ? `; its run is ${read.runId}` : ''}. The Agent did not answer: trace_get the trace${turn ? '' : ' (trace_list with this conversationId finds it)'} and \`frontera local logs service\` show why. The conversation can go on once the run ends.`
+        : read.end.status === 'timeout'
+          ? `The turn did not finish within ${Math.round(read.end.elapsedMs / 1000)} s (events so far: ${JSON.stringify(read.events)}). It may still be running: trace_list with this conversationId shows it.`
+          : null
+    const result = {
+      agent: slug,
+      version: args.live ? 'live' : 'draft',
+      conversationId,
+      ...(args.answered ? { answered: args.answered } : {}),
+      reply: read.reply,
+      ...(read.end.status === 'waiting' ? { pendingDecision: pendingDecisionView(read.end.pending, conversationId), runId: read.runId } : {}),
+      ...(toolsOffered ? { toolsOffered } : {}),
+      ...(stopped ? { stopped, status: read.end.status } : {}),
+      ...(blocked ? { replyBlocked: blocked } : {}),
+      ...(procedures ? { procedure: procedures.active, ...(procedures.turns ? { procedureByTurn: procedures.turns } : {}), ...(procedures.loaded ? { proceduresLoaded: procedures.loaded } : {}) } : {}),
+      toolCalls: read.toolCalls.map((t) => ({ name: t.name, ok: t.ok, args: t.args })),
+      ...(args.live
+        ? {}
+        : {
+            actions:
+              args.realActions && !args.realActionsNote
+                ? 'real: this conversation runs Functions and Workflows that change something for real'
+                : 'Functions and Workflows that only read run for real; ones that change something are not run (realActions: true in a new conversation runs them)',
+            ...(args.realActionsNote ? { realActionsNote: args.realActionsNote } : {}),
+            ...(simulated.length ? { notRun: simulated } : {}),
+          }),
+      ...(model ? { model } : {}),
+      ms,
+      traceId: turn?.summary.id ?? null,
+      ...(turn
+        ? { tokens: turn.summary.tokens, ...(turn.tokensPartial ? { tokensPartial: true, tokensNote: 'Not all of the trace had arrived, or the model reported no usage: trace_get shows it whole.' } : {}) }
+        : { traceNote: 'The trace has not arrived yet; trace_list with this conversationId finds it shortly.' }),
+      links: {
+        conversation: studioLink(link, `/agents/${encodeURIComponent(args.agentId)}/c/${encodeURIComponent(conversationId)}`),
+        ...(turn ? { trace: turn.summary.link } : {}),
+      },
+    }
+    return stopped ? { ...jsonResult(result), isError: true } : jsonResult(result)
+  }
+
+  /**
+   * A turn the model provider refused (no credit, a rate limit, a refused key, an outage), said as its cause and
+   * fix like test_run's couldNotRun, with the model to switch to when another held key offers one; null for any
+   * other failure, which keeps its own words.
+   */
+  async function refusedTurn(err: unknown, args: { conversationId: string; agentId: string; since: string; before: string[] }): Promise<ToolResult | null> {
+    const link = requireRuntime(project)
+    const refusal = providerRefusal((err as Error)?.message ?? String(err), { providers: link.creds.modelProviders, again: 'send the message again (agent_chat)' })
+    if (!refusal) return null
+    memory.waiting.delete(args.conversationId)
+    const slug = memory.conversations.get(args.conversationId)?.agent ?? ''
+    // The refused turn still leaves a trace: name it when it is there, without waiting long.
+    const turn = await awaitTurnTrace(link, args.conversationId, { before: new Set(args.before), since: args.since, waitMs: 3_000 }).catch(() => null)
+    const { providerSaid, ...couldNotRun } = refusal
+    return {
+      ...jsonResult({
+        agent: slug,
+        conversationId: args.conversationId,
+        reply: '',
+        couldNotRun,
+        providerSaid,
+        note: 'The model provider refused this turn before the Agent replied: nothing about the Agent was tested. Keys and provider accounts are the person’s: tell them the fix.',
+        traceId: turn?.summary.id ?? null,
+        links: {
+          conversation: studioLink(link, `/agents/${encodeURIComponent(args.agentId)}/c/${encodeURIComponent(args.conversationId)}`),
+          ...(turn ? { trace: turn.summary.link } : {}),
+        },
+      }),
+      isError: true,
+    }
+  }
+
+  /** Decide what the Agent waits on, as the person would on its card, and read the rest of the turn. */
+  async function decide(conversationId: string, id: string, decision: Decision): Promise<ToolResult> {
+    const link = requireRuntime(project)
+    const waiting = memory.waiting.get(conversationId)
+    const listed = await pendingOnRuntime(link, conversationId)
+    const pending = (waiting?.pending.id === id ? waiting.pending : null) ?? listed.find((p) => p.id === id) ?? null
+    if (!pending) {
+      const stored = await storedConversation(link, conversationId)
+      if (!stored) return errorResult(goneConversation(conversationId))
+      const open = [...(waiting ? [waiting.pending] : []), ...listed.filter((p) => p.id !== waiting?.pending.id)]
+      return open.length
+        ? decideFirst(conversationId, open)
+        : errorResult(`Nothing in conversation ${conversationId} waits on a decision with id ${id}: it was decided, it expired, or the id is another conversation's. When the Agent asks in words ("Shall I go ahead?"), answer with agent_chat and a message.`)
+    }
+    if (decisionKind(decision) !== pending.kind) {
+      return errorResult(`${id} is ${pending.kind === 'approval' ? 'a tool approval: decide it with approve or deny' : 'a confirmation: decide it with confirm or cancel'}.`)
+    }
+    const path = pending.kind === 'confirmation' ? `/v1/chat/confirmations/${encodeURIComponent(pending.id)}` : `/v1/chat/approvals/${encodeURIComponent(pending.id)}`
+    const decided = await serviceCall<{ status?: string }>(link, path, { body: { decision } })
+    const answered = { kind: pending.kind, id: pending.id, decision, ...(decided?.status ? { status: decided.status } : {}) }
+    if (decided?.status === 'expired') {
+      memory.waiting.delete(conversationId)
+      return errorResult(`The ${pending.kind} ${pending.id} had expired before the decision arrived; the run went on without it. trace_list with this conversationId shows what it did.`)
+    }
+    const known = memory.conversations.get(conversationId)
+    const agentId = known?.agentId ?? ''
+    let held = waiting?.pending.id === id ? waiting.held : undefined
+    if (!held || !held.reader) {
+      // The stream is gone (another connection, or it dropped): the run keeps going; read the rest from its journal.
+      const stored = await storedConversation(link, conversationId)
+      const runId = held?.runId ?? stored?.activeRunId ?? null
+      if (!runId) return jsonResult({ conversationId, answered, reply: '', note: 'Decided. The run that waited has ended, so its reply is in the conversation: agent_chat on with a message, or trace_list with this conversationId.' })
+      held = await reattachTurn(link, held ?? { reader: null, buffer: '', runId, chunks: 0, reply: '', calls: new Map(), events: {}, lastEvent: null, seen: new Set([pending.id]) })
+    }
+    const since = waiting?.since ?? new Date(Date.now() - 1_000).toISOString()
+    let read: TurnRead
+    try {
+      read = await readTurn(held, { idleMs: TURN_IDLE_MS })
+    } catch (err) {
+      const refused = await refusedTurn(err, { conversationId, agentId, since, before: waiting?.before ?? [] })
+      if (refused) return refused
+      throw err
+    }
+    const real = known?.live ? { realActions: false, realActionsNote: null } : await conversationRunsRealActions(memory, link, agentId, conversationId)
+    return finishTurn({
+      conversationId,
+      agentId,
+      held,
+      read,
+      since: waiting?.since ?? new Date(Date.now() - 1_000).toISOString(),
+      before: waiting?.before ?? [],
+      started: Date.now(),
+      live: known?.live ?? false,
+      ...real,
+      answered,
+    })
+  }
+
+  return [
+    {
+      name: 'agent_chat',
+      description:
+        "Send a message to an Agent on the local runtime and get its reply, the tools it called, the tokens it used and the trace id. Talks to the Agent's draft (the files as last applied) unless live is true. A draft runs Functions and Workflows that only read for real and reports the ones that change something as not run, unless realActions is true. Pass conversationId to continue a conversation (it keeps the draft it started on: after an apply, start a new one); leave it out to start one. When the answer has pendingDecision, the turn waits on the person's card (a tool approval, or a Function's confirmation): decide it with agent_decide, and the turn goes on; typed words never answer a card. When the reply check changed the reply, replyBlocked says which check fired, what it found, what the person got and both drafts. Read the trace with trace_get.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          agent: { type: 'string', description: 'The Agent\'s slug, its folder under agents/.' },
+          message: { type: 'string', minLength: 1, maxLength: 8000, description: 'What the person says.' },
+          conversationId: { type: 'string', description: 'Continue this conversation, from an earlier agent_chat.' },
+          live: { type: 'boolean', description: 'Talk to the published version instead of the draft (default false).' },
+          realActions: {
+            type: 'boolean',
+            description:
+              "Run the draft's Functions and Workflows that change something for real in this conversation, against the local runtime's records (default false: they are simulated and answer as a success with an empty result; ones that only read always run). Only when starting a conversation, and only for the draft.",
+          },
+          variables: {
+            type: 'object',
+            additionalProperties: { type: ['string', 'number', 'boolean'] },
+            description: "The conversation's variables, by name ({ customer_id: 'CST-00060' }), as a channel would set them: what the instructions read as {{customer_id}} and what operating.json dataScopes narrow the Agent's reads by. Only when starting a conversation on the draft.",
+          },
+        },
+        required: ['agent', 'message'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Chat with an Agent', readOnlyHint: false, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const slug = stringArg(input, 'agent', { required: true })
+        const message = stringArg(input, 'message', { required: true })
+        let live = input.live === true
+        let realActions = input.realActions === true
+        let conversationId = stringArg(input, 'conversationId')
+        if (realActions && conversationId) return errorResult('realActions is chosen when a conversation starts: leave out conversationId to start one that runs actions for real.')
+        if (realActions && live) return errorResult('realActions is for the draft: the published version always runs its actions for real.')
+        const variables = input.variables && typeof input.variables === 'object' && !Array.isArray(input.variables) && Object.keys(input.variables).length ? (input.variables as Record<string, unknown>) : undefined
+        if (variables && conversationId) return errorResult('variables are set when a conversation starts: leave out conversationId to start one with them.')
+        if (variables && live) return errorResult('variables are for the draft here: the published version gets them from its channel.')
+
+        let target: { agentId: string; agentName: string }
+        let realActionsNote: string | null = null
+        const known = conversationId ? memory.conversations.get(conversationId) : undefined
+        if (conversationId) {
+          // A follow-up: the conversation's own agent (its draft's test copy as it started), never a new copy.
+          const stored = await storedConversation(link, conversationId)
+          if (!stored) return errorResult(goneConversation(conversationId))
+          const remembered = memory.waiting.get(conversationId)?.pending
+          const waiting = remembered ? [remembered] : await pendingOnRuntime(link, conversationId)
+          if (waiting.length) return decideFirst(conversationId, waiting)
+          const agentId = known?.agentId ?? (await chatTarget({ serviceUrl: link.serviceUrl, creds: link.creds }, slug, true)).agentId
+          target = { agentId, agentName: stored.agentName ?? known?.agentName ?? (await chatTarget({ serviceUrl: link.serviceUrl, creds: link.creds }, slug, live)).agentName }
+          // A follow-up keeps what the conversation started with: the version it talks to, and whether its actions run for real.
+          if (known) live = known.live
+          if (!live) ({ realActions, realActionsNote } = await conversationRunsRealActions(memory, link, agentId, conversationId))
+        } else {
+          target = await chatTarget({ serviceUrl: link.serviceUrl, creds: link.creds }, slug, live)
+          const session = await serviceCall<{ id: string }>(link, '/v1/sessions', { body: { agentName: target.agentName, workspaceId: link.creds.workspaceId } })
+          conversationId = session.id
+          if (realActions || variables) {
+            // The Try setup Studio's "Run actions for real" sends, before the first message, to the Agent itself (not its
+            // draft copy): ONE call (the runtime refuses a second), with the variables, and `simulateActions` said either way.
+            try {
+              await serviceCall(link, `/v1/config/agents/${encodeURIComponent(target.agentId)}/try/conversations/${encodeURIComponent(conversationId)}`, {
+                method: 'PUT',
+                body: { ...(variables ? { variables } : {}), simulateActions: !realActions },
+              })
+            } catch (err) {
+              const reason = (err as Error).message
+              if (!/answered 400/.test(reason)) throw new Error(`Could not set up this conversation${realActions ? ' to run actions for real' : ''}: ${reason}`)
+              const why = reason.replace(/^.*answered 400:\s*/, '').slice(0, 300)
+              // The variables are the case's to fix: refused, the turn is not sent with none.
+              if (variables) return errorResult(`The conversation's variables were refused: ${why}`)
+              realActionsNote = `Real actions could not be turned on (${why}). Functions and Workflows that only read run for real; the ones that change something stay not run in this test.`
+            }
+          }
+        }
+        const remembered = memory.conversations.get(conversationId) ?? { agent: slug, agentId: target.agentId, agentName: target.agentName, live, transcript: [], realActions: realActions && !realActionsNote, realActionsNote, ...(variables ? { variables } : {}) }
+        memory.conversations.set(conversationId, remembered)
+        remembered.transcript.push({ role: 'user', parts: [{ type: 'text', text: message }] })
+        // The traces already there, so this turn's is the one that is new.
+        const since = new Date(Date.now() - 1_000).toISOString()
+        const before = (await conversationTraces(link, conversationId).catch(() => [])).map((t) => t.id)
+        const started = Date.now()
+        let held: HeldTurn
+        try {
+          held = await startTurn(link, { conversationId, agentName: target.agentName, message })
+        } catch (err) {
+          // The runtime refuses a message while a card waits (409 decision_pending): say what to decide.
+          const pending = pendingFromConflict((err as Error).message)
+          if (!pending) {
+            remembered.transcript.pop()
+            const refused = await refusedTurn(err, { conversationId, agentId: target.agentId, since, before })
+            if (refused) return refused
+            throw err
+          }
+          remembered.transcript.pop()
+          return decideFirst(conversationId, pending.length ? pending : await pendingOnRuntime(link, conversationId))
+        }
+        let read: TurnRead
+        try {
+          read = await readTurn(held)
+        } catch (err) {
+          const refused = await refusedTurn(err, { conversationId, agentId: target.agentId, since, before })
+          if (refused) return refused
+          throw err
+        }
+        return finishTurn({ conversationId, agentId: target.agentId, held, read, since, before, started, live, realActions, realActionsNote })
+      },
+    },
+    {
+      name: 'agent_decide',
+      description:
+        "Decide what an Agent's turn waits on, as the person would on its card: approve or deny a tool approval, or confirm or cancel a Function's confirmation (agent_chat's pendingDecision gives the id). The run picks up where it parked, and the answer is the rest of the turn like agent_chat's: reply, tool calls, trace and tokens. Each decision is yours to make explicitly; nothing is ever decided for you.",
+      inputSchema: {
+        type: 'object',
+        properties: {
+          conversationId: { type: 'string', description: 'The conversation, from agent_chat.' },
+          id: { type: 'string', description: 'The decision\'s id: pendingDecision.id.' },
+          decision: { type: 'string', enum: [...DECISIONS], description: 'approve or deny for a tool approval; confirm or cancel for a confirmation.' },
+        },
+        required: ['conversationId', 'id', 'decision'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Decide an approval or confirmation', readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      async run(input) {
+        const conversationId = stringArg(input, 'conversationId', { required: true })
+        const id = stringArg(input, 'id', { required: true })
+        const decision = stringArg(input, 'decision', { required: true }) as Decision
+        if (!DECISIONS.includes(decision)) return errorResult('decision is approve, deny, confirm or cancel.')
+        return decide(conversationId, id, decision)
+      },
+    },
+    {
+      name: 'trace_get',
+      description: 'Read one trace: the span tree, every tool call with its input and output, tokens, latency and errors; toolsOffered: the tools each model call was offered (what the Agent could have called); dataScopes: the data scopes its Blueprint reads ran under; agentVersion/draftOf when a draft ran; and replyChecks: each time the reply check changed a reply (the check, what it found, what the person got, both drafts). Set detail to false for the tree without inputs and outputs.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          traceId: { type: 'string', description: 'From agent_chat or trace_list.' },
+          detail: { type: 'boolean', description: 'Include each span\'s input and output, clipped (default true).' },
+        },
+        required: ['traceId'],
+        additionalProperties: false,
+      },
+      annotations: { title: 'Read a trace', readOnlyHint: true, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const id = stringArg(input, 'traceId', { required: true })
+        const trace = await getTrace(link, id)
+        if (!trace) return errorResult(`no trace "${id}" on the local runtime; trace_list shows the recent ones`)
+        return jsonResult(readTrace(link, trace, { detail: input.detail !== false }))
+      },
+    },
+    {
+      name: 'trace_list',
+      description: 'Recent traces on the local runtime, newest first: Agent turns, workflow runs and Function calls. Filter by conversation, name or errors.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          limit: { type: 'integer', minimum: 1, maximum: 50, description: 'At most this many (default 10).' },
+          conversationId: { type: 'string', description: 'Only this conversation\'s turns.' },
+          name: { type: 'string', description: 'Only traces whose name contains this, e.g. an Agent\'s slug.' },
+          errorsOnly: { type: 'boolean', description: 'Only traces with an error.' },
+          sinceMinutes: { type: 'integer', minimum: 1, maximum: 10080, description: 'Only the last this many minutes.' },
+        },
+        additionalProperties: false,
+      },
+      annotations: { title: 'List traces', readOnlyHint: true, openWorldHint: false },
+      async run(input) {
+        const link = requireRuntime(project)
+        const minutes = input.sinceMinutes === undefined ? null : intArg(input, 'sinceMinutes', 60, 1, 10080)
+        const traces = await listTraces(link, {
+          limit: intArg(input, 'limit', 10, 1, 50),
+          conversationId: stringArg(input, 'conversationId'),
+          name: stringArg(input, 'name'),
+          errorsOnly: input.errorsOnly === true,
+          since: minutes === null ? undefined : new Date(Date.now() - minutes * 60_000).toISOString(),
+        })
+        return jsonResult({ traces, link: studioLink(link, '/traces') })
+      },
+    },
+  ]
+}