@swarmclawai/swarmclaw 0.8.4 → 0.8.7

package/src/lib/server/stream-continuation.ts

@@ -0,0 +1,412 @@
+/**
+ * Continuation logic for stream-agent-chat.
+ *
+ * Determines whether an LLM iteration should continue (and why),
+ * builds the appropriate follow-up prompts, and resolves final
+ * response text from tool-heavy turns.
+ */
+import type { MessageToolEvent } from '@/types'
+import { extractSuggestions } from './suggestions'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ContinuationType =
+  | 'recursion'
+  | 'transient'
+  | 'required_tool'
+  | 'attachment_followthrough'
+  | 'execution_followthrough'
+  | 'deliverable_followthrough'
+  | 'tool_summary'
+  | false
+
+// ---------------------------------------------------------------------------
+// Message classification helpers
+// ---------------------------------------------------------------------------
+
+export function isBroadGoal(text: string): boolean {
+  if (text.length < 50) return false
+  if (/```/.test(text)) return false
+  if (/\/(src|lib|app|pages|components|api)\//.test(text)) return false
+  if (/^\s*\d+[.)]\s/m.test(text)) return false
+  if (text.length < 80 && text.endsWith('?')) return false
+  return true
+}
+
+export function looksLikeExternalWalletTask(text: string): boolean {
+  const normalized = text.toLowerCase()
+  if (!normalized.trim()) return false
+  return /\b(wallet|wallet connect|walletconnect|trade|trading|exchange|dex|bridge|swap|deposit|withdraw|onchain|token|gas|hyperliquid|arbitrum|ethereum|solana|base|usdc|eth|sol)\b/.test(normalized)
+}
+
+export function looksLikeBoundedExternalExecutionTask(text: string): boolean {
+  const normalized = text.toLowerCase()
+  if (!looksLikeExternalWalletTask(text)) return false
+  return /\b(live|swap|trade|buy|purchase|sell|mint|claim|execute|transact|transaction|approve|broadcast)\b/.test(normalized)
+}
+
+export function looksLikeOpenEndedDeliverableTask(text: string): boolean {
+  const normalized = text.toLowerCase()
+  if (!normalized.trim()) return false
+  if (/```|package\.json|tsconfig|\btsx?\b|\bjsx?\b|pytest|vitest|npm run|src\/|components\/|api\//.test(normalized)) return false
+  if (/\b(revise|revision|iterate|iteration|draft|deliverable|deliverables|offer|brief|copy|proposal|landing|outreach|plan|strategy|report|memo|document|docs?)\b/.test(normalized)) return true
+  if (
+    /\b(create|build|generate|make|write|produce)\b/.test(normalized)
+    && /\b(save|write|output|export)\b[^.!?\n]{0,60}\b(to|as|in)\b[^.!?\n]{0,40}(\/|~\/|\.\/|\.[a-z]{2,5}\b)/.test(normalized)
+  ) {
+    return true
+  }
+  if (
+    isBroadGoal(text)
+    && /\b(create|build|generate|make|write|research|capture|take|start|produce)\b/.test(normalized)
+    && /\b(screenshot|screenshots|image|images|markdown|\.md\b|md\b|md files?|pdf|pdf files?|html|html\s+(?:page|file)|dashboard|site|sites|website|web page|webpage|dev server|dev servers|artifact|artifacts|topic|topics)\b/.test(normalized)
+  ) {
+    return true
+  }
+  return isBroadGoal(text) && /(\.md\b|\.txt\b|\.html\b|\.json\b|copy|brief|proposal|plan|report|draft|document|dashboard)/.test(normalized)
+}
+
+function looksLikeIncompleteDeliverableResponse(text: string): boolean {
+  const trimmed = text.trim()
+  if (!trimmed) return true
+  if (trimmed.endsWith(':') || trimmed.endsWith('...') || trimmed.endsWith('…')) return true
+  const lastChunk = trimmed.slice(-400).toLowerCase()
+  return /\b(?:next|now|then|after that|moving on to|proceeding to)\b[^.!?\n]{0,120}\b(?:i(?:'ll| will)|create|build|write|capture|take|start|finish|generate)\b/.test(lastChunk)
+    || /\b(?:i(?:'ll| will)|let me)\s+(?:now|next)?\s*(?:create|build|write|capture|take|start|finish|generate|continue)\b/.test(lastChunk)
+}
+
+// ---------------------------------------------------------------------------
+// Tool evidence analysis
+// ---------------------------------------------------------------------------
+
+export function hasStateChangingWalletEvidence(toolEvents: MessageToolEvent[]): boolean {
+  return toolEvents.some((event) => {
+    const input = `${event.input || ''}\n${event.output || ''}`
+    return event.name === 'wallet_tool' && (
+      /"action":"send_transaction"/.test(input)
+      || /"action":"send"/.test(input)
+      || /"action":"sign_transaction"/.test(input)
+      || /"type":"plugin_wallet_action_request"/.test(input)
+      || /"type":"plugin_wallet_transfer_request"/.test(input)
+      || /"status":"broadcast"/.test(input)
+    )
+  })
+}
+
+export function countExternalExecutionResearchSteps(toolEvents: MessageToolEvent[]): number {
+  return toolEvents.filter((event) => {
+    if (['http_request', 'web', 'web_search', 'web_fetch', 'browser'].includes(event.name)) return true
+    if (event.name !== 'wallet_tool') return false
+    return /"action":"(balance|address|transactions|call_contract|encode_contract_call)"/.test(event.input || '')
+  }).length
+}
+
+export function countDistinctExternalResearchHosts(toolEvents: MessageToolEvent[]): number {
+  const hosts = new Set<string>()
+  for (const event of toolEvents) {
+    const candidates = [event.input || '', event.output || '']
+    for (const candidate of candidates) {
+      const matches = candidate.match(/https?:\/\/[^"'\\\s)]+/g) || []
+      for (const match of matches) {
+        try {
+          hosts.add(new URL(match).host.toLowerCase())
+        } catch {
+          // Ignore malformed URLs in model/tool text.
+        }
+      }
+    }
+  }
+  return hosts.size
+}
+
+// ---------------------------------------------------------------------------
+// Continuation decision helpers
+// ---------------------------------------------------------------------------
+
+export function shouldForceExternalExecutionFollowthrough(params: {
+  userMessage: string
+  finalResponse: string
+  hasToolCalls: boolean
+  toolEvents: MessageToolEvent[]
+}): boolean {
+  if (!looksLikeBoundedExternalExecutionTask(params.userMessage)) return false
+  if (!params.hasToolCalls || params.toolEvents.length < 4) return false
+  if (hasStateChangingWalletEvidence(params.toolEvents)) return false
+  const distinctHosts = countDistinctExternalResearchHosts(params.toolEvents)
+  const trimmed = params.finalResponse.trim()
+  if (!trimmed) return countExternalExecutionResearchSteps(params.toolEvents) >= 4 || distinctHosts >= 3
+  if (/\b(last reversible step|exact blocker|safest next action|blocked|cannot|can't|missing capability|no-key route unavailable)\b/i.test(trimmed)) {
+    return false
+  }
+  if (countExternalExecutionResearchSteps(params.toolEvents) < 4 && distinctHosts < 3) return false
+  return /(let me|i'll|i will|trying|research|query|check|look|promising|now let me|good -|good,)/i.test(trimmed) || trimmed.length < 500
+}
+
+export function shouldForceDeliverableFollowthrough(params: {
+  userMessage: string
+  finalResponse: string
+  hasToolCalls: boolean
+  toolEvents: MessageToolEvent[]
+}): boolean {
+  if (!looksLikeOpenEndedDeliverableTask(params.userMessage)) return false
+  if (!params.hasToolCalls || params.toolEvents.length === 0) return false
+  const trimmed = params.finalResponse.trim()
+  if (!trimmed) return params.toolEvents.length >= 2
+  if (
+    /\b(task complete|completed|finished|done|delivered|shared|sent|uploaded|attached)\b/i.test(trimmed)
+    && /(?:\/api\/uploads\/|https?:\/\/|`[^`\n]+\.(?:md|pdf|png|jpe?g|webp|gif|html|txt|zip)`)/i.test(trimmed)
+  ) {
+    return false
+  }
+  const userNormalized = params.userMessage.toLowerCase()
+  if (/\b(save|write|output)\b[^.!?\n]{0,60}\b(to|as)\b[^.!?\n]{0,40}(\/|~\/|\.[a-z]{2,5}\b)/.test(userNormalized)) {
+    const usedFileWriteTools = params.toolEvents.some((e) => {
+      if (!e.name) return false
+      if (['write_file', 'edit_file'].includes(e.name)) return true
+      if (e.name === 'shell' || e.name === 'execute_command') return true
+      if (e.name === 'files') {
+        const input = e.input || ''
+        return /"action"\s*:\s*"write"/i.test(input)
+      }
+      return false
+    })
+    if (!usedFileWriteTools) return true
+  }
+  if (looksLikeIncompleteDeliverableResponse(trimmed)) return true
+  return trimmed.length < 120 && params.toolEvents.length >= 3
+}
+
+// ---------------------------------------------------------------------------
+// Tool evidence rendering (shared with buildForcedExternalServiceSummary)
+// ---------------------------------------------------------------------------
+
+export function renderToolEvidence(events: MessageToolEvent[]): string {
+  return events
+    .slice(-10)
+    .map((event, index) => [
+      `Tool ${index + 1}: ${event.name}`,
+      event.input ? `Input: ${event.input}` : '',
+      event.output ? `Output: ${event.output.slice(0, 1200)}` : '',
+    ].filter(Boolean).join('\n'))
+    .join('\n\n')
+}
+
+// ---------------------------------------------------------------------------
+// Continuation prompt builders
+// ---------------------------------------------------------------------------
+
+function buildExternalExecutionFollowthroughPrompt(params: {
+  userMessage: string
+  fullText: string
+  toolEvents: MessageToolEvent[]
+}): string {
+  return [
+    'You are in a bounded external execution task and have already done enough research.',
+    'Do not restart broad discovery. Do not ask the user for another prompt.',
+    'Do not spend this continuation on more venue shopping. Use the already confirmed route unless one last fetch is strictly required to prepare execution.',
+    'If several venue or aggregator APIs already failed, stop searching for more venues. Either use a direct onchain read path with the available wallet tools, or state the blocker.',
+    'A prose approval request does not count as completion. If the next step is a sign/send/approve action, call the real wallet tool action so the runtime can create the approval request.',
+    'Do not mutate already confirmed token addresses, router addresses, spender addresses, or network identifiers unless newer tool evidence proves the earlier value was wrong.',
+    'Within this continuation, do exactly one of the following:',
+    '1. Take the next concrete execution step now using the existing tools and stop at the first approval boundary for a state-changing action.',
+    '2. If no safe executable step exists with the current tools, state the exact blocker with evidence.',
+    'A successful continuation ends with one of these outcomes only: an approval request, a broadcast transaction, or a final blocker summary.',
+    'Prefer the route sources and facts already confirmed in the tool evidence below. Do not keep shopping for new venues unless the current options are clearly unusable.',
+    'If the tool evidence already includes enough information to prepare a contract call, approval, quote read, or transaction simulation, do that now instead of making another search or HTTP request.',
+    '',
+    `Objective:\n${params.userMessage}`,
+    '',
+    `Current partial response:\n${params.fullText || '(none)'}`,
+    '',
+    `Recent tool evidence:\n${renderToolEvidence(params.toolEvents) || '(none)'}`,
+  ].join('\n')
+}
+
+function buildDeliverableFollowthroughPrompt(params: {
+  userMessage: string
+  fullText: string
+  toolEvents: MessageToolEvent[]
+}): string {
+  const lines = [
+    'You are in the middle of a multi-step deliverable and stopped after only a partial batch of work.',
+    'Continue from the existing workspace and artifacts. Do not restart from scratch and do not ask the user to restate the request.',
+    'Do not stop after one partial batch. Finish every requested deliverable that is still outstanding before concluding.',
+    'If a requested artifact cannot be produced, say exactly which artifact is missing, what blocked it, and what you already completed.',
+    'Use the existing files, screenshots, and generated outputs first. Inspect them if needed, then complete the remaining work.',
+    'Preserve hard structural constraints from the original request: exact counts stay exact, required titled sections stay present, and source coverage gaps should be filled instead of skipped.',
+    'End with a concise grouped completion summary that lists exact file paths, upload URLs, localhost URLs/ports, and screenshots you produced.',
+  ]
+
+  const userNormalized = params.userMessage.toLowerCase()
+  const fileOutputMatch = userNormalized.match(/\b(?:save|write|output|export)\b[^.!?\n]{0,80}\b(?:to|as|at|in)\b[^.!?\n]{0,60}(\/[^\s,'"]+|~\/[^\s,'"]+|\.\/[^\s,'"]+)/i)
+  if (fileOutputMatch) {
+    const fileToolNames = ['write_file', 'edit_file', 'files', 'shell', 'execute_command']
+    const usedFileTools = params.toolEvents.some((e) => e.name && fileToolNames.includes(e.name))
+    if (!usedFileTools) {
+      lines.push(
+        '',
+        `CRITICAL: The user asked you to save output to a file path (${fileOutputMatch[1] || 'see objective'}). You have NOT used any file-writing tool yet.`,
+        'You MUST use the `files` or `write_file` tool to write the content to the requested path. Do not just include the content in your text response — actually write the file.',
+      )
+    }
+  }
+
+  lines.push(
+    '',
+    `Objective:\n${params.userMessage}`,
+    '',
+    `Current partial response:\n${params.fullText || '(none)'}`,
+    '',
+    `Recent tool evidence:\n${renderToolEvidence(params.toolEvents) || '(none)'}`,
+  )
+  return lines.join('\n')
+}
+
+function buildAttachmentFollowthroughPrompt(params: {
+  message: string
+  fullText: string
+}): string {
+  return [
+    'The current thread already includes user attachments as inline context.',
+    'Image attachments are directly visible to you in the message content. Text and PDF attachments are also available inline when present.',
+    'Do not claim that you cannot use images, attachments, or external tools when they are available in this session.',
+    'If the user wants you to look something up from an attachment, first extract the identifier or details from the attachment/history, then use the enabled tools to continue.',
+    'Only state a blocker if the attachment is genuinely unreadable or a needed tool is actually unavailable after a real attempt.',
+    '',
+    `Original request:\n${params.message}`,
+    '',
+    `Your previous response:\n${params.fullText || '(none)'}`,
+    '',
+    'Now continue and handle the attachment-aware task correctly.',
+  ].join('\n')
+}
+
+function buildToolSummaryPrompt(params: {
+  message: string
+  fullText: string
+  toolEvents: MessageToolEvent[]
+}): string {
+  const toolSummaryLines = params.toolEvents
+    .filter((e) => e.output)
+    .map((e) => `[${e.name}]: ${(e.output || '').slice(0, 500)}`)
+    .slice(0, 6)
+  const preambleNote = params.fullText.trim()
+    ? `You started with "${params.fullText.trim().slice(0, 100)}..." but did not follow through with actual results.`
+    : 'Your tool calls completed but you did not provide a response.'
+  return [
+    preambleNote,
+    'Here are the tool results:',
+    ...toolSummaryLines,
+    '',
+    `Original request: ${params.message.slice(0, 500)}`,
+    '',
+    'Now answer the original request using these tool results. Be concise and direct. Present the findings clearly.',
+  ].join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// buildContinuationPrompt — unified prompt builder for all continuation types
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the human-message prompt for a given continuation type,
+ * or `null` for types that don't push a message (e.g. `transient`).
+ */
+export function buildContinuationPrompt(params: {
+  type: ContinuationType
+  message: string
+  fullText: string
+  toolEvents: MessageToolEvent[]
+  requiredToolReminderNames: string[]
+}): string | null {
+  switch (params.type) {
+    case 'recursion':
+      return 'Continue where you left off. Complete the remaining steps of the objective.'
+
+    case 'required_tool':
+      return `You have not yet completed the required explicit tool step(s): ${params.requiredToolReminderNames.join(', ')}. Use those enabled tools now before declaring success. Do not replace ask_human with a plain-text request, do not replace outbound delivery tools with prose, and do not replace screenshot requests with text-only summaries.`
+
+    case 'attachment_followthrough':
+      return buildAttachmentFollowthroughPrompt({
+        message: params.message,
+        fullText: params.fullText,
+      })
+
+    case 'execution_followthrough':
+      return buildExternalExecutionFollowthroughPrompt({
+        userMessage: params.message,
+        fullText: params.fullText,
+        toolEvents: params.toolEvents,
+      })
+
+    case 'deliverable_followthrough':
+      return buildDeliverableFollowthroughPrompt({
+        userMessage: params.message,
+        fullText: params.fullText,
+        toolEvents: params.toolEvents,
+      })
+
+    case 'tool_summary':
+      return buildToolSummaryPrompt({
+        message: params.message,
+        fullText: params.fullText,
+        toolEvents: params.toolEvents,
+      })
+
+    case 'transient':
+    case false:
+      return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Response text resolution
+// ---------------------------------------------------------------------------
+
+function resolveToolOnlyFinalResponse(toolEvents: MessageToolEvent[] | undefined): string {
+  const events = Array.isArray(toolEvents) ? toolEvents : []
+  for (let index = events.length - 1; index >= 0; index--) {
+    const event = events[index]
+    const output = typeof event?.output === 'string'
+      ? extractSuggestions(event.output).clean.trim()
+      : ''
+    if (!output) continue
+    if (/^error[:\s]/i.test(output)) continue
+    if (output.startsWith('{') || output.startsWith('[')) continue
+    return output
+  }
+  return ''
+}
+
+export function resolveFinalStreamResponseText(params: {
+  fullText: string
+  lastSegment: string
+  lastSettledSegment: string
+  hasToolCalls: boolean
+  toolEvents?: MessageToolEvent[]
+}): string {
+  const fullText = params.fullText || ''
+  if (!params.hasToolCalls) return fullText
+
+  const candidates = [
+    extractSuggestions(params.lastSegment || '').clean.trim(),
+    extractSuggestions(params.lastSettledSegment || '').clean.trim(),
+    extractSuggestions(fullText).clean.trim(),
+    resolveToolOnlyFinalResponse(params.toolEvents),
+  ]
+
+  return candidates.find((candidate) => candidate.length > 0) || ''
+}
+
+export function resolveContinuationAssistantText(params: {
+  iterationText: string
+  lastSegment: string
+}): string {
+  const candidates = [
+    extractSuggestions(params.iterationText || '').clean.trim(),
+    extractSuggestions(params.lastSegment || '').clean.trim(),
+  ]
+  return candidates.find((candidate) => candidate.length > 0) || ''
+}