@alumbwe/anvil 1.0.0

package/src/commands/copy-conversation.ts

@@ -0,0 +1,392 @@
+/**
+ * `/copy` command — serialize the entire conversation (user + assistant text,
+ * reasoning, tool calls with their inputs and outputs, sub-agents) into clean
+ * Markdown and write it to the system clipboard.
+ *
+ * Over SSH the clipboard path is OSC 52, which caps the base64 payload at 32 KB
+ * (see clipboard.ts). A real back-and-forth easily exceeds that, so when we're on
+ * a remote session and the transcript is too large, we progressively drop the
+ * largest tool results (then, if still needed, large tool inputs) — replacing each
+ * with a short omission note — until it fits. Local sessions first try a native
+ * clipboard tool with the full transcript, then use the same bounded rendering
+ * as an OSC 52 fallback when no native clipboard tool is available.
+ */
+
+import { copyTextToClipboard, showClipboardMessage } from '../utils/clipboard'
+import { useChatStore } from '../state/chat-store'
+import { IS_FREEBUFF } from '../utils/constants'
+
+import type { RouterParams } from './command-registry'
+import type { ChatMessage, ContentBlock } from '../types/chat'
+
+// OSC 52 caps its base64 payload at 32 KB (clipboard.ts OSC52_MAX_PAYLOAD).
+// base64 is ~4/3 of the raw byte count, so the raw-text ceiling is ~24 KB. Leave
+// headroom for tmux/screen passthrough wrapping and the message framing.
+const OSC52_TEXT_BUDGET_BYTES = 22_000
+
+const byteLen = (text: string): number => Buffer.byteLength(text, 'utf8')
+
+/** Human-friendly tool label, e.g. `read_files` -> `Read Files`. */
+function toolDisplayName(toolName: string): string {
+  if (toolName === 'list_directory') return 'List Directories'
+  return toolName.replace(/_/g, ' ').replace(/\b\w/g, (l) => l.toUpperCase())
+}
+
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  return `${(bytes / 1024).toFixed(1)} KB`
+}
+
+/**
+ * Return the longest suffix of `s` that fits in `maxBytes`, cut on a UTF-8
+ * codepoint boundary (and a line boundary when one is close by) so the result
+ * is valid text. Used as the last-resort fallback when dropping tool bodies
+ * still can't get the transcript under the clipboard budget.
+ */
+function keepTailBytes(s: string, maxBytes: number): string {
+  if (maxBytes <= 0) return ''
+  const buf = Buffer.from(s, 'utf8')
+  if (buf.length <= maxBytes) return s
+
+  let start = buf.length - maxBytes
+  // Advance off any UTF-8 continuation byte (0b10xxxxxx) to a codepoint start.
+  while (start < buf.length && (buf[start] & 0xc0) === 0x80) start++
+  // Prefer cutting at the next line boundary if it's nearby, for cleaner output.
+  const nl = buf.indexOf(0x0a, start)
+  if (nl !== -1 && nl - start < 200) start = nl + 1
+  return buf.toString('utf8', start)
+}
+
+/**
+ * A segment of the rendered transcript whose body can be dropped to save space.
+ * `full` is the normal rendering; `note` is the compact omission replacement.
+ */
+interface Droppable {
+  kind: 'output' | 'input'
+  full: string
+  note: string
+}
+
+type Segment = string | Droppable
+
+const isDroppable = (segment: Segment): segment is Droppable =>
+  typeof segment !== 'string'
+
+function fence(content: string, lang = ''): string {
+  // Avoid breaking out of the fence if the content itself contains ```.
+  const ticks = content.includes('```') ? '````' : '```'
+  return `${ticks}${lang}\n${content}\n${ticks}`
+}
+
+function renderToolInput(input: unknown): string {
+  if (input == null) return ''
+  try {
+    return JSON.stringify(input, null, 2)
+  } catch {
+    return String(input)
+  }
+}
+
+/**
+ * Tool results are stored as strings; many are a JSON envelope (e.g. the
+ * `[{"type":"json","value":{...}}]` shape from terminal/tool calls). Pretty-print
+ * when the string parses as JSON so the transcript is readable; otherwise keep
+ * the raw text. Returns the fence language to use alongside the body.
+ */
+function renderToolOutput(output: string): { body: string; lang: string } {
+  const trimmed = output.trim()
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      return {
+        body: JSON.stringify(JSON.parse(trimmed), null, 2),
+        lang: 'json',
+      }
+    } catch {
+      // Not valid JSON — fall through to raw.
+    }
+  }
+  return { body: output, lang: '' }
+}
+
+function roleHeading(message: ChatMessage): string {
+  switch (message.variant) {
+    case 'user':
+      return '## User'
+    case 'error':
+      return '## Error'
+    default:
+      return '## Assistant'
+  }
+}
+
+/**
+ * Render a single content block into the segment list. Recurses for sub-agents.
+ * Pushes plain strings for fixed text and `Droppable` objects for tool bodies.
+ */
+function renderBlock(block: ContentBlock, out: Segment[]): void {
+  switch (block.type) {
+    case 'text': {
+      const text = block.content?.trim()
+      if (!text) return
+      if (block.textType === 'reasoning') {
+        // Reasoning as a blockquote so it reads as model thinking, not output.
+        const quoted = text
+          .split('\n')
+          .map((line) => `> ${line}`)
+          .join('\n')
+        out.push(`> _Reasoning_\n${quoted}`)
+      } else {
+        out.push(text)
+      }
+      return
+    }
+
+    case 'tool': {
+      const name = toolDisplayName(block.toolName)
+      const inputText = renderToolInput(block.input)
+      const hasInput = inputText.trim().length > 0
+      const output = block.output ?? ''
+      const hasOutput = output.trim().length > 0
+
+      // A tool call with no input and no output (e.g. still running) gets a
+      // compact one-liner rather than a header with nothing beneath it.
+      if (!hasInput && !hasOutput) {
+        out.push(`**🛠 ${name}** _(no input or output)_`)
+        return
+      }
+
+      out.push(`**🛠 ${name}**`)
+      if (hasInput) {
+        out.push({
+          kind: 'input',
+          full: fence(inputText, 'json'),
+          note: `_Input omitted (${formatBytes(byteLen(inputText))}) to fit clipboard._`,
+        })
+      }
+      if (hasOutput) {
+        const rendered = renderToolOutput(output)
+        out.push({
+          kind: 'output',
+          full: fence(rendered.body, rendered.lang),
+          note: `_Result omitted (${formatBytes(byteLen(rendered.body))}) to fit clipboard._`,
+        })
+      }
+      return
+    }
+
+    case 'agent': {
+      const label = block.agentName || block.agentType
+      out.push(
+        `### ⤷ Subagent: ${label}${block.agentName ? ` (${block.agentType})` : ''}`,
+      )
+      if (block.initialPrompt?.trim()) {
+        out.push(`_Prompt:_ ${block.initialPrompt.trim()}`)
+      }
+      if (block.content?.trim()) {
+        out.push(block.content.trim())
+      }
+      for (const child of block.blocks ?? []) {
+        renderBlock(child, out)
+      }
+      out.push('### ⤶ End subagent')
+      return
+    }
+
+    case 'plan': {
+      if (block.content?.trim()) {
+        out.push(`**Plan**\n\n${block.content.trim()}`)
+      }
+      return
+    }
+
+    case 'ask-user': {
+      for (const [i, q] of block.questions.entries()) {
+        const answer = block.answers?.find((a) => a.questionIndex === i)
+        const selected =
+          answer?.selectedOptions?.join(', ') ??
+          answer?.selectedOption ??
+          answer?.otherText ??
+          (block.skipped ? '(skipped)' : '(no answer)')
+        out.push(`**Question:** ${q.question}\n_Answer:_ ${selected}`)
+      }
+      return
+    }
+
+    case 'image': {
+      out.push(`_[image: ${block.filename ?? block.mediaType}]_`)
+      return
+    }
+
+    case 'agent-list': {
+      const names = block.agents.map((a) => a.displayName).join(', ')
+      if (names) out.push(`_[available agents: ${names}]_`)
+      return
+    }
+
+    // mode-divider and html carry no transcript-worthy text.
+    default:
+      return
+  }
+}
+
+function renderMessage(message: ChatMessage, out: Segment[]): void {
+  out.push(roleHeading(message))
+
+  if (message.blocks?.length) {
+    for (const block of message.blocks) {
+      renderBlock(block, out)
+    }
+  } else if (message.content?.trim()) {
+    out.push(message.content.trim())
+  }
+
+  // Attachments live on the message, not in blocks — note them for context.
+  const fileNames = message.fileAttachments?.map((f) => f.filename) ?? []
+  const imageNames = message.attachments?.map((a) => a.filename) ?? []
+  const textCount = message.textAttachments?.length ?? 0
+  if (fileNames.length) out.push(`> Attached files: ${fileNames.join(', ')}`)
+  if (imageNames.length) out.push(`> Attached images: ${imageNames.join(', ')}`)
+  if (textCount) out.push(`> Attached ${textCount} pasted text snippet(s)`)
+}
+
+export interface SerializedConversation {
+  text: string
+  /** Number of droppable tool bodies omitted to fit the clipboard budget. */
+  omittedCount: number
+  /** True if the transcript was hard-truncated as a last resort. */
+  truncated: boolean
+}
+
+const TRUNCATION_MARKER =
+  '_[…earlier conversation truncated to fit clipboard…]_'
+
+function copySuccessMessage(
+  messageCount: number,
+  { omittedCount, truncated }: SerializedConversation,
+): string {
+  const count = `${messageCount} message${messageCount === 1 ? '' : 's'}`
+  const trimNotes: string[] = []
+  if (omittedCount > 0) {
+    trimNotes.push(
+      `${omittedCount} large tool call${omittedCount === 1 ? '' : 's'} trimmed`,
+    )
+  }
+  if (truncated) trimNotes.push('older messages truncated')
+  return trimNotes.length > 0
+    ? `Copied conversation · ${count} (${trimNotes.join(', ')} to fit clipboard)`
+    : `Copied conversation · ${count}`
+}
+
+function conversationClipboardContent(
+  messages: ChatMessage[],
+  maxBytes?: number,
+): { text: string; successMessage: string } {
+  const serialized = serializeConversation(messages, { maxBytes })
+  return {
+    text: serialized.text,
+    successMessage: copySuccessMessage(messages.length, serialized),
+  }
+}
+
+/**
+ * Serialize the conversation to Markdown. When `maxBytes` is provided and the
+ * full transcript exceeds it, the largest tool results (then large tool inputs)
+ * are replaced with a short omission note. If that still isn't enough (e.g. a
+ * single huge text block), the oldest content is hard-truncated so the copy
+ * always fits.
+ */
+export function serializeConversation(
+  messages: ChatMessage[],
+  options: { maxBytes?: number } = {},
+): SerializedConversation {
+  const segments: Segment[] = []
+  for (const message of messages) {
+    renderMessage(message, segments)
+  }
+
+  const product = IS_FREEBUFF ? 'Freebuff' : 'Anvil'
+  const header = `# ${product} conversation\n_${messages.length} message${messages.length === 1 ? '' : 's'}_`
+  const prefix = `${header}\n\n---\n\n`
+
+  const assembleBody = (dropped: Set<Droppable>): string =>
+    segments
+      .map((seg) =>
+        isDroppable(seg) ? (dropped.has(seg) ? seg.note : seg.full) : seg,
+      )
+      .join('\n\n')
+
+  const dropped = new Set<Droppable>()
+  let body = assembleBody(dropped)
+  let truncated = false
+
+  const { maxBytes } = options
+  if (maxBytes) {
+    // The body must fit in maxBytes minus the prefix and the trailing newline.
+    const bodyBudget = maxBytes - byteLen(prefix) - 1
+
+    if (byteLen(body) > bodyBudget) {
+      // Tier 1: drop tool outputs first (the bulk of the noise), then inputs.
+      // Within each tier, largest first so we drop as few blocks as possible.
+      // Pre-measure savings once rather than recomputing inside the comparator.
+      const candidates = segments
+        .filter(isDroppable)
+        .map((d) => ({ d, save: byteLen(d.full) - byteLen(d.note) }))
+        .filter((c) => c.save > 0)
+        .sort((a, b) => {
+          if (a.d.kind !== b.d.kind) return a.d.kind === 'output' ? -1 : 1
+          return b.save - a.save
+        })
+
+      const needed = byteLen(body) - bodyBudget
+      let saved = 0
+      for (const { d, save } of candidates) {
+        if (saved >= needed) break
+        dropped.add(d)
+        saved += save
+      }
+      body = assembleBody(dropped)
+    }
+
+    if (byteLen(body) > bodyBudget) {
+      // Tier 2: nothing droppable left to cut (e.g. a giant text block). Keep
+      // the most recent content and mark the truncation so the copy never fails.
+      const marker = `${TRUNCATION_MARKER}\n\n`
+      body = marker + keepTailBytes(body, bodyBudget - byteLen(marker))
+      truncated = true
+    }
+  }
+
+  return { text: `${prefix}${body}\n`, omittedCount: dropped.size, truncated }
+}
+
+export async function handleCopyConversationCommand(
+  params: RouterParams,
+): Promise<void> {
+  const messages = useChatStore.getState().messages
+
+  params.saveToHistory(params.inputValue.trim())
+  params.setInputValue({ text: '', cursorPosition: 0, lastEditDueToNav: false })
+
+  if (messages.length === 0) {
+    showClipboardMessage('Nothing to copy — the conversation is empty.', {
+      durationMs: 3000,
+    })
+    return
+  }
+
+  const primary = conversationClipboardContent(messages)
+
+  try {
+    await copyTextToClipboard(primary.text, {
+      successMessage: primary.successMessage,
+      durationMs: 4000,
+      getOsc52Fallback:
+        byteLen(primary.text) > OSC52_TEXT_BUDGET_BYTES
+          ? () =>
+              conversationClipboardContent(messages, OSC52_TEXT_BUDGET_BYTES)
+          : undefined,
+    })
+  } catch {
+    // copyTextToClipboard already surfaces a failure/guidance message.
+  }
+}

package/src/commands/help.ts

@@ -0,0 +1,13 @@
+import { useChatStore } from '../state/chat-store'
+
+import type { PostUserMessageFn } from '../types/contracts/send-message'
+
+export async function handleHelpCommand(): Promise<{
+  postUserMessage: PostUserMessageFn
+}> {
+  // Show the help banner with keyboard shortcuts
+  useChatStore.getState().setInputMode('help')
+
+  const postUserMessage: PostUserMessageFn = (prev) => prev
+  return { postUserMessage }
+}

package/src/commands/image.ts

@@ -0,0 +1,20 @@
+import { getProjectRoot } from '../project-files'
+import { validateAndAddImage } from '../utils/pending-attachments'
+
+/**
+ * Handle the /image command to attach an image file.
+ * Usage: /image <path> [message]
+ * Example: /image ./screenshot.png please analyze this
+ * 
+ * Returns the optional message as transformedPrompt (empty string if none).
+ * Errors are shown in the pending images banner with auto-remove.
+ */
+export async function handleImageCommand(args: string): Promise<string> {
+  const [imagePath, ...rest] = args.trim().split(/\s+/)
+  
+  if (imagePath) {
+    await validateAndAddImage(imagePath, getProjectRoot())
+  }
+  
+  return rest.join(' ')
+}

package/src/commands/init.ts

@@ -0,0 +1,121 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import path from 'path'
+
+import { AnalyticsEvent } from '@anvil/common/constants/analytics-events'
+import { KNOWLEDGE_FILE_NAMES } from '@anvil/common/constants/knowledge'
+
+// @ts-expect-error - Bun text import attribute not supported by TypeScript
+import agentDefinitionSource from '../../../common/src/templates/initial-agents-dir/types/agent-definition' with { type: 'text' }
+// @ts-expect-error - Bun text import attribute not supported by TypeScript
+import toolsSource from '../../../common/src/templates/initial-agents-dir/types/tools' with { type: 'text' }
+// @ts-expect-error - Bun text import attribute not supported by TypeScript
+import utilTypesSource from '../../../common/src/templates/initial-agents-dir/types/util-types' with { type: 'text' }
+import { getProjectRoot } from '../project-files'
+import { trackEvent } from '../utils/analytics'
+import { IS_FREEBUFF } from '../utils/constants'
+import { getSystemMessage } from '../utils/message-history'
+
+import type { PostUserMessageFn } from '../types/contracts/send-message'
+
+const brandName = IS_FREEBUFF ? 'Freebuff' : 'Anvil'
+
+const INITIAL_KNOWLEDGE_FILE = `# Project knowledge
+
+This file gives ${brandName} context about your project: goals, commands, conventions, and gotchas.
+
+## Quickstart
+- Setup:
+- Dev:
+- Test:
+
+## Architecture
+- Key directories:
+- Data flow:
+
+## Conventions
+- Formatting/linting:
+- Patterns to follow:
+- Things to avoid:
+`
+
+const COMMON_TYPE_FILES = [
+  {
+    fileName: 'agent-definition.ts',
+    source: agentDefinitionSource,
+  },
+  {
+    fileName: 'tools.ts',
+    source: toolsSource,
+  },
+  {
+    fileName: 'util-types.ts',
+    source: utilTypesSource,
+  },
+]
+
+export function handleInitializationFlowLocally(): {
+  postUserMessage: PostUserMessageFn
+} {
+  const projectRoot = getProjectRoot()
+  const knowledgePath = path.join(projectRoot, KNOWLEDGE_FILE_NAMES[0])
+  const messages: string[] = []
+
+  if (existsSync(knowledgePath)) {
+    messages.push(`📋 \`${KNOWLEDGE_FILE_NAMES[0]}\` already exists.`)
+  } else {
+    writeFileSync(knowledgePath, INITIAL_KNOWLEDGE_FILE)
+    messages.push(`✅ Created \`${KNOWLEDGE_FILE_NAMES[0]}\``)
+
+    // Track knowledge file creation
+    trackEvent(AnalyticsEvent.KNOWLEDGE_FILE_UPDATED, {
+      action: 'created',
+      fileName: KNOWLEDGE_FILE_NAMES[0],
+      fileSizeBytes: Buffer.byteLength(INITIAL_KNOWLEDGE_FILE, 'utf8'),
+    })
+  }
+
+  const agentsDir = path.join(projectRoot, '.agents')
+  const agentsTypesDir = path.join(agentsDir, 'types')
+
+  if (existsSync(agentsDir)) {
+    messages.push('📋 `.agents/` already exists.')
+  } else {
+    mkdirSync(agentsDir, { recursive: true })
+    messages.push('✅ Created `.agents/`')
+  }
+
+  if (existsSync(agentsTypesDir)) {
+    messages.push('📋 `.agents/types/` already exists.')
+  } else {
+    mkdirSync(agentsTypesDir, { recursive: true })
+    messages.push('✅ Created `.agents/types/`')
+  }
+
+  for (const { fileName, source } of COMMON_TYPE_FILES) {
+    const targetPath = path.join(agentsTypesDir, fileName)
+    if (existsSync(targetPath)) {
+      messages.push(`📋 \`.agents/types/${fileName}\` already exists.`)
+      continue
+    }
+
+    try {
+      if (!source || source.trim().length === 0) {
+        throw new Error('Source content is empty')
+      }
+      writeFileSync(targetPath, source)
+      messages.push(`✅ Copied \`.agents/types/${fileName}\``)
+    } catch (error) {
+      messages.push(
+        `⚠️ Failed to copy \`.agents/types/${fileName}\`: ${
+          error instanceof Error ? error.message : String(error ?? 'Unknown')
+        }`,
+      )
+    }
+  }
+
+  const postUserMessage: PostUserMessageFn = (prev) => [
+    ...prev,
+    ...messages.map((message) => getSystemMessage(message)),
+  ]
+  return { postUserMessage }
+}

package/src/commands/process-diagnostics.ts

@@ -0,0 +1,120 @@
+import { getActiveTerminalCommandProcesses } from '@anvil/sdk'
+
+import { getTerminalWatchdogDiagnostics } from '../utils/terminal-watchdog'
+import { getCliEnv } from '../utils/env'
+import { IS_FREEBUFF } from '../utils/constants'
+
+export type ProcessDiagnosticsSnapshot = {
+  product: string
+  version: string
+  runtime: string
+  platform: string
+  architecture: string
+  uptimeSeconds: number
+  cpuUserMicros: number
+  cpuSystemMicros: number
+  memory: NodeJS.MemoryUsage
+  parentPid: number
+  cliPid: number
+  watchdog: {
+    armed: boolean
+    external: boolean
+    pid?: number
+  }
+  activeTools: Array<{
+    pid: number
+    processGroupId?: number
+  }>
+}
+
+const formatBytes = (bytes: number): string => {
+  const units = ['B', 'KiB', 'MiB', 'GiB']
+  let value = bytes
+  let unit = units[0]
+  for (let i = 1; i < units.length && value >= 1024; i++) {
+    value /= 1024
+    unit = units[i]
+  }
+  return `${value.toFixed(value >= 10 || unit === 'B' ? 0 : 1)} ${unit}`
+}
+
+const formatDuration = (seconds: number): string => {
+  const wholeSeconds = Math.max(0, Math.floor(seconds))
+  const hours = Math.floor(wholeSeconds / 3600)
+  const minutes = Math.floor((wholeSeconds % 3600) / 60)
+  const remainingSeconds = wholeSeconds % 60
+  return [hours, minutes, remainingSeconds]
+    .map((value) => value.toString().padStart(2, '0'))
+    .join(':')
+}
+
+const formatWatchdog = (
+  watchdog: ProcessDiagnosticsSnapshot['watchdog'],
+): string => {
+  if (watchdog.pid) return `PID ${watchdog.pid}`
+  if (!watchdog.armed) return 'not running'
+  return watchdog.external
+    ? 'armed externally (PID unavailable on Windows)'
+    : 'armed'
+}
+
+export function formatProcessDiagnostics(
+  snapshot: ProcessDiagnosticsSnapshot,
+): string {
+  const cpuSeconds =
+    (snapshot.cpuUserMicros + snapshot.cpuSystemMicros) / 1_000_000
+  const lines = [
+    `### ${snapshot.product} process diagnostics`,
+    '',
+    `- Version: ${snapshot.version}`,
+    `- Runtime: ${snapshot.runtime}`,
+    `- Platform: ${snapshot.platform} ${snapshot.architecture}`,
+    `- CLI uptime: ${formatDuration(snapshot.uptimeSeconds)}`,
+    `- CLI CPU time: ${cpuSeconds.toFixed(1)}s`,
+    `- CLI memory: ${formatBytes(snapshot.memory.rss)} RSS, ${formatBytes(snapshot.memory.heapUsed)} heap used`,
+    '',
+    'Processes:',
+    `- parent/wrapper: PID ${snapshot.parentPid}`,
+    `- CLI binary: PID ${snapshot.cliPid}`,
+    `- terminal watchdog: ${formatWatchdog(snapshot.watchdog)}`,
+    '',
+    'Active terminal tools:',
+  ]
+
+  if (snapshot.activeTools.length === 0) {
+    lines.push('- none')
+  } else {
+    for (const child of snapshot.activeTools) {
+      lines.push(
+        `- PID ${child.pid}${child.processGroupId ? `, PGID ${child.processGroupId}` : ''}`,
+      )
+    }
+  }
+  lines.push(
+    '',
+    'Command lines and environment variables are omitted for safety.',
+  )
+  return lines.join('\n')
+}
+
+export function collectProcessDiagnostics(): ProcessDiagnosticsSnapshot {
+  const cpuUsage = process.cpuUsage()
+  return {
+    product: IS_FREEBUFF ? 'Freebuff' : 'Anvil',
+    version: getCliEnv().ANVIL_CLI_VERSION ?? 'dev',
+    runtime:
+      typeof Bun !== 'undefined'
+        ? `Bun ${Bun.version}`
+        : `${process.release.name} ${process.version}`,
+    platform: process.platform,
+    architecture: process.arch,
+    uptimeSeconds: process.uptime(),
+    cpuUserMicros: cpuUsage.user,
+    cpuSystemMicros: cpuUsage.system,
+    memory: process.memoryUsage(),
+    parentPid: process.ppid,
+    cliPid: process.pid,
+    watchdog: getTerminalWatchdogDiagnostics(),
+    activeTools: getActiveTerminalCommandProcesses(),
+  }
+}