From f2c750c64c3f98755619e350541629482a296918 Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Sun, 15 Mar 2026 04:15:37 +0000
Subject: [PATCH 01/16] =?UTF-8?q?feat:=20built-in=20agent=20=E2=80=94=20LL?=
 =?UTF-8?q?M-powered=20AEO=20analyst=20with=20chat=20API?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a built-in AI agent that uses canonry's own tools to answer
AEO questions, run sweeps, and explain citation changes. No external
agent framework required — just the LLM provider already configured.

Architecture:
- Agent loop modeled after OpenClaw's pattern (LLM ↔ tool ↔ repeat)
- Uses existing provider API keys from canonry config
- Persistence in SQLite (same database, new tables)
- Provider priority: Claude > OpenAI > Gemini (configurable)

New files:
- packages/canonry/src/agent/ — core agent module
  - loop.ts: LLM ↔ tool execution cycle
  - llm.ts: provider-agnostic LLM layer (OpenAI, Claude, Gemini)
  - tools.ts: canonry operations as LLM-callable functions
  - store.ts: thread/message persistence (SQLite)
  - prompt.ts: AEO analyst system prompt
  - types.ts: shared type definitions
- packages/api-routes/src/agent.ts — REST API for chat
- packages/canonry/src/commands/agent.ts — CLI commands

CLI:
  canonry agent ask <project> "message"    — chat with the agent
  canonry agent threads <project>           — list threads
  canonry agent thread <project> <id>       — show thread history

API:
  POST   /api/v1/projects/:project/agent/threads              — create thread
  GET    /api/v1/projects/:project/agent/threads              — list threads
  GET    /api/v1/projects/:project/agent/threads/:id          — get thread + messages
  POST   /api/v1/projects/:project/agent/threads/:id/messages — send message
  DELETE /api/v1/projects/:project/agent/threads/:id          — delete thread

Config:
  agent:
    provider: claude|openai|gemini  (optional, auto-detects)
    model: string                   (optional, uses provider default)
    maxSteps: number                (default: 10)
    maxHistory: number              (default: 30)
    enabled: boolean                (default: true if provider available)

Tools exposed to agent:
  - get_status, run_sweep, get_evidence, get_timeline
  - list_keywords, list_competitors, get_run_details
  - get_gsc_performance, get_gsc_coverage, inspect_url

DB migration:
  - agent_threads: conversation threads per project
  - agent_messages: messages within threads (user/assistant/tool)

Closes #59
---
 packages/api-routes/src/agent.ts       | 214 +++++++++++++++++++++
 packages/api-routes/src/index.ts       |   7 +
 packages/canonry/src/agent/index.ts    |   7 +
 packages/canonry/src/agent/llm.ts      | 245 +++++++++++++++++++++++++
 packages/canonry/src/agent/loop.ts     | 199 ++++++++++++++++++++
 packages/canonry/src/agent/prompt.ts   |  45 +++++
 packages/canonry/src/agent/store.ts    |  96 ++++++++++
 packages/canonry/src/agent/tools.ts    | 200 ++++++++++++++++++++
 packages/canonry/src/agent/types.ts    |  38 ++++
 packages/canonry/src/cli.ts            |  63 ++++++-
 packages/canonry/src/client.ts         |  26 +++
 packages/canonry/src/commands/agent.ts | 122 ++++++++++++
 packages/canonry/src/config.ts         |  13 ++
 packages/canonry/src/server.ts         |  72 ++++++++
 packages/db/src/migrate.ts             |  22 +++
 packages/db/src/schema.ts              |  25 +++
 16 files changed, 1393 insertions(+), 1 deletion(-)
 create mode 100644 packages/api-routes/src/agent.ts
 create mode 100644 packages/canonry/src/agent/index.ts
 create mode 100644 packages/canonry/src/agent/llm.ts
 create mode 100644 packages/canonry/src/agent/loop.ts
 create mode 100644 packages/canonry/src/agent/prompt.ts
 create mode 100644 packages/canonry/src/agent/store.ts
 create mode 100644 packages/canonry/src/agent/tools.ts
 create mode 100644 packages/canonry/src/agent/types.ts
 create mode 100644 packages/canonry/src/commands/agent.ts

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
new file mode 100644
index 0000000..1c18c09
--- /dev/null
+++ b/packages/api-routes/src/agent.ts
@@ -0,0 +1,214 @@
+/**
+ * Agent API routes — chat with the built-in AEO analyst.
+ *
+ * POST /api/v1/projects/:project/agent/threads             — create thread
+ * GET  /api/v1/projects/:project/agent/threads              — list threads
+ * GET  /api/v1/projects/:project/agent/threads/:id          — get thread + messages
+ * POST /api/v1/projects/:project/agent/threads/:id/messages — send message
+ * DELETE /api/v1/projects/:project/agent/threads/:id        — delete thread
+ */
+
+import crypto from 'node:crypto'
+import { eq, desc, asc } from 'drizzle-orm'
+import type { FastifyInstance } from 'fastify'
+import { agentThreads, agentMessages } from '@ainyc/canonry-db'
+import { resolveProject } from './helpers.js'
+
+export interface AgentRoutesOptions {
+  /** Called when a user sends a message to the agent. Returns the agent's response. */
+  onAgentMessage?: (
+    projectId: string,
+    threadId: string,
+    message: string,
+  ) => Promise<string>
+}
+
+export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions) {
+  const prefix = '/projects/:project/agent'
+
+  // ── Create thread ─────────────────────────────────────────
+
+  app.post<{
+    Params: { project: string }
+    Body: { title?: string; channel?: string }
+  }>(`${prefix}/threads`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: { project: { type: 'string' } },
+        required: ['project'],
+      },
+      body: {
+        type: 'object',
+        properties: {
+          title: { type: 'string' },
+          channel: { type: 'string' },
+        },
+      },
+    },
+  }, async (request, reply) => {
+    const { project } = request.params
+    const { title, channel } = request.body ?? {}
+
+    const projectRow = resolveProject(app.db, project)
+
+    const now = new Date().toISOString()
+    const thread = {
+      id: crypto.randomUUID(),
+      projectId: projectRow.id,
+      title: title ?? null,
+      channel: channel ?? 'chat',
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    app.db.insert(agentThreads).values(thread).run()
+
+    return reply.status(201).send(thread)
+  })
+
+  // ── List threads ──────────────────────────────────────────
+
+  app.get<{
+    Params: { project: string }
+    Querystring: { limit?: string }
+  }>(`${prefix}/threads`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: { project: { type: 'string' } },
+        required: ['project'],
+      },
+    },
+  }, async (request, reply) => {
+    const { project } = request.params
+    const limit = Math.min(parseInt(request.query.limit ?? '20', 10) || 20, 100)
+
+    const projectRow = resolveProject(app.db, project)
+
+    const threads = app.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.projectId, projectRow.id))
+      .orderBy(desc(agentThreads.updatedAt))
+      .limit(limit)
+      .all()
+
+    return reply.send(threads)
+  })
+
+  // ── Get thread with messages ──────────────────────────────
+
+  app.get<{
+    Params: { project: string; id: string }
+  }>(`${prefix}/threads/:id`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          project: { type: 'string' },
+          id: { type: 'string' },
+        },
+        required: ['project', 'id'],
+      },
+    },
+  }, async (request, reply) => {
+    const { id } = request.params
+
+    const thread = app.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.id, id))
+      .get()
+
+    if (!thread) {
+      return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
+    }
+
+    const messages = app.db
+      .select()
+      .from(agentMessages)
+      .where(eq(agentMessages.threadId, id))
+      .orderBy(asc(agentMessages.createdAt))
+      .all()
+
+    return reply.send({ ...thread, messages })
+  })
+
+  // ── Send message ──────────────────────────────────────────
+
+  app.post<{
+    Params: { project: string; id: string }
+    Body: { message: string }
+  }>(`${prefix}/threads/:id/messages`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          project: { type: 'string' },
+          id: { type: 'string' },
+        },
+        required: ['project', 'id'],
+      },
+      body: {
+        type: 'object',
+        properties: {
+          message: { type: 'string' },
+        },
+        required: ['message'],
+      },
+    },
+  }, async (request, reply) => {
+    const { project, id: threadId } = request.params
+    const { message } = request.body
+
+    resolveProject(app.db, project)
+
+    // Verify thread exists
+    const thread = app.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.id, threadId))
+      .get()
+
+    if (!thread) {
+      return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
+    }
+
+    if (!opts.onAgentMessage) {
+      return reply.status(503).send({
+        error: {
+          code: 'AGENT_UNAVAILABLE',
+          message: 'Agent is not configured. Add a provider with an API key.',
+        },
+      })
+    }
+
+    const response = await opts.onAgentMessage(thread.projectId, threadId, message)
+
+    return reply.send({ threadId, response })
+  })
+
+  // ── Delete thread ─────────────────────────────────────────
+
+  app.delete<{
+    Params: { project: string; id: string }
+  }>(`${prefix}/threads/:id`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          project: { type: 'string' },
+          id: { type: 'string' },
+        },
+        required: ['project', 'id'],
+      },
+    },
+  }, async (request, reply) => {
+    const { id } = request.params
+
+    app.db.delete(agentThreads).where(eq(agentThreads.id, id)).run()
+
+    return reply.status(204).send()
+  })
+}
diff --git a/packages/api-routes/src/index.ts b/packages/api-routes/src/index.ts
index 211820d..06a4bc7 100644
--- a/packages/api-routes/src/index.ts
+++ b/packages/api-routes/src/index.ts
@@ -22,6 +22,8 @@ import type { ScheduleRoutesOptions } from './schedules.js'
 import { notificationRoutes } from './notifications.js'
 import { googleRoutes } from './google.js'
 import type { GoogleRoutesOptions } from './google.js'
+import { agentRoutes } from './agent.js'
+import type { AgentRoutesOptions } from './agent.js'
 
 declare module 'fastify' {
   interface FastifyInstance {
@@ -61,6 +63,8 @@ export interface ApiRoutesOptions {
   publicUrl?: string
   onGscSyncRequested?: GoogleRoutesOptions['onGscSyncRequested']
   onInspectSitemapRequested?: GoogleRoutesOptions['onInspectSitemapRequested']
+  /** Callback when a user sends a message to the built-in agent */
+  onAgentMessage?: AgentRoutesOptions['onAgentMessage']
 }
 
 export async function apiRoutes(app: FastifyInstance, opts: ApiRoutesOptions) {
@@ -115,6 +119,9 @@ export async function apiRoutes(app: FastifyInstance, opts: ApiRoutesOptions) {
       onGscSyncRequested: opts.onGscSyncRequested,
       onInspectSitemapRequested: opts.onInspectSitemapRequested,
     } satisfies GoogleRoutesOptions)
+    await api.register(agentRoutes, {
+      onAgentMessage: opts.onAgentMessage,
+    } satisfies AgentRoutesOptions)
   }, { prefix: '/api/v1' })
 }
 
diff --git a/packages/canonry/src/agent/index.ts b/packages/canonry/src/agent/index.ts
new file mode 100644
index 0000000..f3a49fe
--- /dev/null
+++ b/packages/canonry/src/agent/index.ts
@@ -0,0 +1,7 @@
+export { AgentStore } from './store.js'
+export { agentChat } from './loop.js'
+export { buildTools } from './tools.js'
+export { buildSystemPrompt } from './prompt.js'
+export type { AgentTool } from './tools.js'
+export type { AgentThread, AgentMessage, AgentConfig } from './types.js'
+export type { LlmConfig } from './llm.js'
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
new file mode 100644
index 0000000..3ff4644
--- /dev/null
+++ b/packages/canonry/src/agent/llm.ts
@@ -0,0 +1,245 @@
+/**
+ * LLM interaction layer — thin wrapper around provider APIs for tool-calling.
+ *
+ * Uses the OpenAI chat completions format since OpenAI, Claude (via compatibility),
+ * and Gemini (via compatibility endpoints) all support it. This avoids adding
+ * the Vercel AI SDK as a dependency — we only need fetch().
+ */
+
+import type { AgentTool } from './tools.js'
+
+export interface LlmConfig {
+  provider: 'openai' | 'claude' | 'gemini'
+  apiKey: string
+  model?: string
+}
+
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string | null
+  tool_calls?: ToolCall[]
+  tool_call_id?: string
+}
+
+interface ToolCall {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+interface CompletionResponse {
+  type: 'text' | 'tool_calls'
+  text?: string
+  toolCalls?: ToolCall[]
+}
+
+const PROVIDER_ENDPOINTS: Record<string, string> = {
+  openai: 'https://api.openai.com/v1/chat/completions',
+  claude: 'https://api.anthropic.com/v1/messages',
+  gemini: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
+}
+
+const DEFAULT_MODELS: Record<string, string> = {
+  openai: 'gpt-4o',
+  claude: 'claude-sonnet-4-5-20250514',
+  gemini: 'gemini-2.5-flash',
+}
+
+export async function chatCompletion(
+  config: LlmConfig,
+  messages: ChatMessage[],
+  tools: AgentTool[],
+): Promise<CompletionResponse> {
+  if (config.provider === 'claude') {
+    return claudeCompletion(config, messages, tools)
+  }
+
+  // OpenAI-compatible (works for OpenAI and Gemini)
+  const endpoint = PROVIDER_ENDPOINTS[config.provider]!
+  const model = config.model ?? DEFAULT_MODELS[config.provider]!
+
+  const toolDefs = tools.map(t => ({
+    type: 'function' as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }))
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  }
+
+  if (config.provider === 'gemini') {
+    headers['Authorization'] = `Bearer ${config.apiKey}`
+  } else {
+    headers['Authorization'] = `Bearer ${config.apiKey}`
+  }
+
+  const body = {
+    model,
+    messages,
+    tools: toolDefs.length > 0 ? toolDefs : undefined,
+    temperature: 0.3,
+    max_tokens: 4096,
+  }
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  })
+
+  if (!res.ok) {
+    const errBody = await res.text()
+    throw new Error(`LLM API error (${config.provider}): ${res.status} ${errBody}`)
+  }
+
+  const data = await res.json() as {
+    choices: Array<{
+      message: {
+        content: string | null
+        tool_calls?: ToolCall[]
+      }
+      finish_reason: string
+    }>
+  }
+
+  const choice = data.choices?.[0]
+  if (!choice) throw new Error('No response from LLM')
+
+  if (choice.message.tool_calls && choice.message.tool_calls.length > 0) {
+    return { type: 'tool_calls', toolCalls: choice.message.tool_calls }
+  }
+
+  return { type: 'text', text: choice.message.content ?? '' }
+}
+
+/**
+ * Claude Messages API — different format from OpenAI.
+ */
+async function claudeCompletion(
+  config: LlmConfig,
+  messages: ChatMessage[],
+  tools: AgentTool[],
+): Promise<CompletionResponse> {
+  const model = config.model ?? DEFAULT_MODELS.claude!
+
+  // Extract system message
+  const systemMsg = messages.find(m => m.role === 'system')
+  const nonSystemMessages = messages.filter(m => m.role !== 'system')
+
+  // Convert to Claude format
+  const claudeMessages = convertToClaudeMessages(nonSystemMessages)
+
+  const toolDefs = tools.map(t => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.parameters,
+  }))
+
+  const body: Record<string, unknown> = {
+    model,
+    max_tokens: 4096,
+    messages: claudeMessages,
+    temperature: 0.3,
+  }
+
+  if (systemMsg) {
+    body.system = systemMsg.content
+  }
+
+  if (toolDefs.length > 0) {
+    body.tools = toolDefs
+  }
+
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': config.apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify(body),
+  })
+
+  if (!res.ok) {
+    const errBody = await res.text()
+    throw new Error(`Claude API error: ${res.status} ${errBody}`)
+  }
+
+  const data = await res.json() as {
+    content: Array<{
+      type: 'text' | 'tool_use'
+      text?: string
+      id?: string
+      name?: string
+      input?: Record<string, unknown>
+    }>
+    stop_reason: string
+  }
+
+  const toolUseBlocks = data.content.filter(b => b.type === 'tool_use')
+  if (toolUseBlocks.length > 0) {
+    const toolCalls: ToolCall[] = toolUseBlocks.map(b => ({
+      id: b.id!,
+      type: 'function' as const,
+      function: {
+        name: b.name!,
+        arguments: JSON.stringify(b.input ?? {}),
+      },
+    }))
+    return { type: 'tool_calls', toolCalls }
+  }
+
+  const textBlock = data.content.find(b => b.type === 'text')
+  return { type: 'text', text: textBlock?.text ?? '' }
+}
+
+function convertToClaudeMessages(
+  messages: ChatMessage[],
+): Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }> {
+  const result: Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }> = []
+
+  for (const msg of messages) {
+    if (msg.role === 'user') {
+      result.push({ role: 'user', content: msg.content ?? '' })
+    } else if (msg.role === 'assistant') {
+      if (msg.tool_calls && msg.tool_calls.length > 0) {
+        const content: Array<Record<string, unknown>> = []
+        if (msg.content) {
+          content.push({ type: 'text', text: msg.content })
+        }
+        for (const tc of msg.tool_calls) {
+          content.push({
+            type: 'tool_use',
+            id: tc.id,
+            name: tc.function.name,
+            input: JSON.parse(tc.function.arguments),
+          })
+        }
+        result.push({ role: 'assistant', content })
+      } else {
+        result.push({ role: 'assistant', content: msg.content ?? '' })
+      }
+    } else if (msg.role === 'tool') {
+      // Claude expects tool results as user messages with tool_result content blocks
+      result.push({
+        role: 'user',
+        content: [
+          {
+            type: 'tool_result',
+            tool_use_id: msg.tool_call_id,
+            content: msg.content ?? '',
+          },
+        ],
+      })
+    }
+  }
+
+  return result
+}
diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
new file mode 100644
index 0000000..b6fe267
--- /dev/null
+++ b/packages/canonry/src/agent/loop.ts
@@ -0,0 +1,199 @@
+/**
+ * Agent loop — the core LLM ↔ tool execution cycle.
+ *
+ * Modeled after OpenClaw's agent pattern:
+ * 1. Load conversation history from SQLite
+ * 2. Send to LLM with tools
+ * 3. If LLM calls tools → execute → loop back
+ * 4. If LLM returns text → persist and return
+ */
+
+import type { AgentStore } from './store.js'
+import type { AgentTool } from './tools.js'
+import type { LlmConfig } from './llm.js'
+import { chatCompletion } from './llm.js'
+import { buildSystemPrompt } from './prompt.js'
+
+interface LoopOptions {
+  store: AgentStore
+  tools: AgentTool[]
+  llmConfig: LlmConfig
+  project: {
+    name: string
+    displayName: string
+    domain: string
+    country: string
+    language: string
+  }
+  maxSteps?: number
+  maxHistoryMessages?: number
+  /** Called when the agent produces a text chunk (for streaming) */
+  onText?: (text: string) => void
+  /** Called when a tool is about to execute */
+  onToolCall?: (name: string, args: Record<string, unknown>) => void
+}
+
+interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string | null
+  tool_calls?: Array<{
+    id: string
+    type: 'function'
+    function: { name: string; arguments: string }
+  }>
+  tool_call_id?: string
+}
+
+export async function agentChat(
+  threadId: string,
+  userMessage: string,
+  opts: LoopOptions,
+): Promise<string> {
+  const { store, tools, llmConfig, project, maxSteps = 10, maxHistoryMessages = 30 } = opts
+
+  // Persist user message
+  await store.addMessage({
+    threadId,
+    role: 'user',
+    content: userMessage,
+    toolName: null,
+    toolArgs: null,
+    toolCallId: null,
+  })
+
+  // Load conversation history
+  const history = await store.getMessages(threadId, maxHistoryMessages)
+
+  // Build message array for LLM
+  const systemPrompt = buildSystemPrompt(project)
+  const messages: ChatMessage[] = [
+    { role: 'system', content: systemPrompt },
+  ]
+
+  // Convert stored messages to LLM format
+  for (const msg of history) {
+    if (msg.role === 'user') {
+      messages.push({ role: 'user', content: msg.content })
+    } else if (msg.role === 'assistant') {
+      // Check if this was a tool-calling message (has linked tool results after it)
+      if (msg.toolName) {
+        // This was stored as a tool-call assistant message
+        messages.push({
+          role: 'assistant',
+          content: null,
+          tool_calls: [{
+            id: msg.toolCallId ?? msg.id,
+            type: 'function',
+            function: {
+              name: msg.toolName,
+              arguments: msg.toolArgs ?? '{}',
+            },
+          }],
+        })
+      } else {
+        messages.push({ role: 'assistant', content: msg.content })
+      }
+    } else if (msg.role === 'tool') {
+      messages.push({
+        role: 'tool',
+        content: msg.content,
+        tool_call_id: msg.toolCallId ?? undefined,
+      })
+    }
+  }
+
+  // Agent loop
+  let step = 0
+  while (step < maxSteps) {
+    step++
+
+    const response = await chatCompletion(llmConfig, messages, tools)
+
+    if (response.type === 'text') {
+      const text = response.text ?? ''
+
+      // Persist assistant message
+      await store.addMessage({
+        threadId,
+        role: 'assistant',
+        content: text,
+        toolName: null,
+        toolArgs: null,
+        toolCallId: null,
+      })
+
+      await store.touchThread(threadId)
+      opts.onText?.(text)
+
+      return text
+    }
+
+    // Tool calls
+    if (response.toolCalls) {
+      // Add assistant tool-call message to conversation
+      messages.push({
+        role: 'assistant',
+        content: null,
+        tool_calls: response.toolCalls,
+      })
+
+      for (const toolCall of response.toolCalls) {
+        const toolName = toolCall.function.name
+        const toolArgs = JSON.parse(toolCall.function.arguments) as Record<string, unknown>
+
+        opts.onToolCall?.(toolName, toolArgs)
+
+        // Find and execute tool
+        const tool = tools.find(t => t.name === toolName)
+        let result: string
+
+        if (tool) {
+          try {
+            result = await tool.execute(toolArgs)
+          } catch (err) {
+            result = `Error executing ${toolName}: ${err instanceof Error ? err.message : String(err)}`
+          }
+        } else {
+          result = `Unknown tool: ${toolName}`
+        }
+
+        // Persist tool call and result
+        await store.addMessage({
+          threadId,
+          role: 'assistant',
+          content: `Calling ${toolName}`,
+          toolName,
+          toolArgs: JSON.stringify(toolArgs),
+          toolCallId: toolCall.id,
+        })
+
+        await store.addMessage({
+          threadId,
+          role: 'tool',
+          content: result,
+          toolName,
+          toolArgs: null,
+          toolCallId: toolCall.id,
+        })
+
+        // Add tool result to conversation
+        messages.push({
+          role: 'tool',
+          content: result,
+          tool_call_id: toolCall.id,
+        })
+      }
+    }
+  }
+
+  const fallback = 'I hit the maximum number of steps. Could you try a more specific question?'
+  await store.addMessage({
+    threadId,
+    role: 'assistant',
+    content: fallback,
+    toolName: null,
+    toolArgs: null,
+    toolCallId: null,
+  })
+  return fallback
+}
diff --git a/packages/canonry/src/agent/prompt.ts b/packages/canonry/src/agent/prompt.ts
new file mode 100644
index 0000000..95bbc2c
--- /dev/null
+++ b/packages/canonry/src/agent/prompt.ts
@@ -0,0 +1,45 @@
+/**
+ * System prompt for the canonry agent.
+ */
+
+export function buildSystemPrompt(project: {
+  name: string
+  displayName: string
+  domain: string
+  country: string
+  language: string
+}): string {
+  return `You are an AEO (Answer Engine Optimization) analyst monitoring AI citation visibility for ${project.displayName} (${project.domain}).
+
+## Your Job
+
+You monitor how AI models (ChatGPT, Gemini, Claude) cite and reference ${project.domain} when users ask relevant questions. You use canonry — an AEO monitoring tool — to track visibility.
+
+## What You Know
+
+- **Project:** ${project.name}
+- **Domain:** ${project.domain}
+- **Market:** ${project.country}, ${project.language}
+
+## How To Work
+
+1. **Data first.** When asked about visibility, run the appropriate tool to get current data before answering.
+2. **Be direct.** State the finding, then the implication, then what to do. No preambles.
+3. **Compare.** When showing results, always note competitor presence and changes from previous runs.
+4. **Flag problems.** If visibility dropped, say so plainly and suggest why.
+
+## Key Concepts
+
+- **Citation state:** Whether the AI mentioned/cited the domain in its answer (cited, not_cited, competitor_cited)
+- **Grounding:** AI models pull from search indexes (Google for Gemini, Bing for ChatGPT) to ground their answers
+- **Visibility score:** Percentage of tracked keywords where the domain is cited across all providers
+
+## Rules
+
+- Never fabricate data. If you haven't run a tool, say "let me check" and run it.
+- If a tool fails, say what went wrong. Don't guess.
+- Keep responses concise. Tables and bullet points over paragraphs.
+- When the user asks "how am I doing?" — get_evidence is your primary tool.
+- When the user asks about trends — get_timeline shows changes over time.
+- When the user asks about a specific URL — inspect_url checks Google's index.`
+}
diff --git a/packages/canonry/src/agent/store.ts b/packages/canonry/src/agent/store.ts
new file mode 100644
index 0000000..893e37c
--- /dev/null
+++ b/packages/canonry/src/agent/store.ts
@@ -0,0 +1,96 @@
+/**
+ * Agent persistence — thread and message storage backed by SQLite (via drizzle).
+ */
+
+import crypto from 'node:crypto'
+import { eq, desc, asc } from 'drizzle-orm'
+import type { DatabaseClient } from '@ainyc/canonry-db'
+import { agentThreads, agentMessages } from '@ainyc/canonry-db'
+import type { AgentThread, AgentMessage } from './types.js'
+
+export class AgentStore {
+  constructor(private db: DatabaseClient) {}
+
+  // ── Threads ───────────────────────────────────────────────
+
+  async createThread(projectId: string, opts?: { title?: string; channel?: string }): Promise<AgentThread> {
+    const now = new Date().toISOString()
+    const thread: typeof agentThreads.$inferInsert = {
+      id: crypto.randomUUID(),
+      projectId,
+      title: opts?.title ?? null,
+      channel: opts?.channel ?? 'chat',
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.db.insert(agentThreads).values(thread).run()
+    return thread as AgentThread
+  }
+
+  async getThread(threadId: string): Promise<AgentThread | null> {
+    const rows = this.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.id, threadId))
+      .all()
+    return (rows[0] as AgentThread | undefined) ?? null
+  }
+
+  async listThreads(projectId: string, limit = 20): Promise<AgentThread[]> {
+    return this.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.projectId, projectId))
+      .orderBy(desc(agentThreads.updatedAt))
+      .limit(limit)
+      .all() as AgentThread[]
+  }
+
+  async deleteThread(threadId: string): Promise<void> {
+    this.db.delete(agentThreads).where(eq(agentThreads.id, threadId)).run()
+  }
+
+  async touchThread(threadId: string): Promise<void> {
+    this.db
+      .update(agentThreads)
+      .set({ updatedAt: new Date().toISOString() })
+      .where(eq(agentThreads.id, threadId))
+      .run()
+  }
+
+  async updateThreadTitle(threadId: string, title: string): Promise<void> {
+    this.db
+      .update(agentThreads)
+      .set({ title, updatedAt: new Date().toISOString() })
+      .where(eq(agentThreads.id, threadId))
+      .run()
+  }
+
+  // ── Messages ──────────────────────────────────────────────
+
+  async addMessage(msg: Omit<AgentMessage, 'id' | 'createdAt'>): Promise<AgentMessage> {
+    const now = new Date().toISOString()
+    const record: typeof agentMessages.$inferInsert = {
+      id: crypto.randomUUID(),
+      threadId: msg.threadId,
+      role: msg.role,
+      content: msg.content,
+      toolName: msg.toolName ?? null,
+      toolArgs: msg.toolArgs ?? null,
+      toolCallId: msg.toolCallId ?? null,
+      createdAt: now,
+    }
+    this.db.insert(agentMessages).values(record).run()
+    return record as AgentMessage
+  }
+
+  async getMessages(threadId: string, limit = 50): Promise<AgentMessage[]> {
+    return this.db
+      .select()
+      .from(agentMessages)
+      .where(eq(agentMessages.threadId, threadId))
+      .orderBy(asc(agentMessages.createdAt))
+      .limit(limit)
+      .all() as AgentMessage[]
+  }
+}
diff --git a/packages/canonry/src/agent/tools.ts b/packages/canonry/src/agent/tools.ts
new file mode 100644
index 0000000..f9d9f40
--- /dev/null
+++ b/packages/canonry/src/agent/tools.ts
@@ -0,0 +1,200 @@
+/**
+ * Agent tools — canonry operations exposed as LLM-callable functions.
+ *
+ * Each tool wraps the ApiClient so the agent uses the same HTTP API
+ * that CLI commands and the UI use. No direct DB access from tools.
+ */
+
+import type { ApiClient } from '../client.js'
+
+export interface AgentTool {
+  name: string
+  description: string
+  parameters: {
+    type: 'object'
+    properties: Record<string, { type: string; description: string; enum?: string[] }>
+    required: string[]
+  }
+  execute: (args: Record<string, unknown>) => Promise<string>
+}
+
+export function buildTools(client: ApiClient, projectName: string): AgentTool[] {
+  return [
+    {
+      name: 'get_status',
+      description:
+        'Get the current citation visibility status for this project. Returns domain, country, latest run info.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const project = await client.getProject(projectName)
+        const runs = await client.listRuns(projectName)
+        return JSON.stringify({ project, latestRuns: (runs as unknown[]).slice(-3) }, null, 2)
+      },
+    },
+    {
+      name: 'run_sweep',
+      description:
+        'Trigger a new visibility sweep across configured AI providers. Returns the run ID. Use this when the user wants fresh data.',
+      parameters: {
+        type: 'object',
+        properties: {
+          providers: {
+            type: 'string',
+            description: 'Comma-separated provider names to sweep. Omit for all configured providers.',
+          },
+        },
+        required: [],
+      },
+      execute: async (args) => {
+        const body: Record<string, unknown> = {}
+        if (args.providers) {
+          body.providers = (args.providers as string).split(',').map(s => s.trim())
+        }
+        const run = await client.triggerRun(projectName, body)
+        return JSON.stringify(run, null, 2)
+      },
+    },
+    {
+      name: 'get_evidence',
+      description:
+        'Get per-keyword citation evidence showing which providers cite this project and which competitors appear instead. This is the primary tool for understanding visibility.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const history = await client.getHistory(projectName)
+        return JSON.stringify(history, null, 2)
+      },
+    },
+    {
+      name: 'get_timeline',
+      description:
+        'Get the citation timeline showing how visibility has changed across runs over time. Use this to identify trends, regressions, or improvements.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const timeline = await client.getTimeline(projectName)
+        return JSON.stringify(timeline, null, 2)
+      },
+    },
+    {
+      name: 'list_keywords',
+      description: 'List all tracked keywords for this project.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const keywords = await client.listKeywords(projectName)
+        return JSON.stringify(keywords, null, 2)
+      },
+    },
+    {
+      name: 'list_competitors',
+      description: 'List tracked competitors for this project.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const competitors = await client.listCompetitors(projectName)
+        return JSON.stringify(competitors, null, 2)
+      },
+    },
+    {
+      name: 'get_run_details',
+      description: 'Get detailed results for a specific run by ID, including all snapshots.',
+      parameters: {
+        type: 'object',
+        properties: {
+          runId: {
+            type: 'string',
+            description: 'The run ID to inspect.',
+          },
+        },
+        required: ['runId'],
+      },
+      execute: async (args) => {
+        const run = await client.getRun(args.runId as string)
+        return JSON.stringify(run, null, 2)
+      },
+    },
+    {
+      name: 'get_gsc_performance',
+      description:
+        'Get Google Search Console performance data (clicks, impressions, CTR, position) for tracked keywords. Only works if GSC is connected.',
+      parameters: {
+        type: 'object',
+        properties: {
+          days: {
+            type: 'string',
+            description: 'Number of days to look back (default: 28).',
+          },
+        },
+        required: [],
+      },
+      execute: async (args) => {
+        try {
+          const params: Record<string, string> = {}
+          if (args.days) params.days = args.days as string
+          const perf = await client.gscPerformance(projectName, params)
+          return JSON.stringify(perf, null, 2)
+        } catch (err) {
+          return `GSC not available: ${err instanceof Error ? err.message : String(err)}`
+        }
+      },
+    },
+    {
+      name: 'get_gsc_coverage',
+      description:
+        'Get index coverage summary from Google Search Console showing how many URLs are indexed, excluded, or errored.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        try {
+          const coverage = await client.gscCoverage(projectName)
+          return JSON.stringify(coverage, null, 2)
+        } catch (err) {
+          return `GSC not available: ${err instanceof Error ? err.message : String(err)}`
+        }
+      },
+    },
+    {
+      name: 'inspect_url',
+      description:
+        'Inspect a specific URL in Google Search Console to check indexing status, crawl info, and mobile-friendliness.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: {
+            type: 'string',
+            description: 'The full URL to inspect (e.g. https://example.com/page).',
+          },
+        },
+        required: ['url'],
+      },
+      execute: async (args) => {
+        try {
+          const result = await client.gscInspect(projectName, args.url as string)
+          return JSON.stringify(result, null, 2)
+        } catch (err) {
+          return `GSC inspect failed: ${err instanceof Error ? err.message : String(err)}`
+        }
+      },
+    },
+  ]
+}
diff --git a/packages/canonry/src/agent/types.ts b/packages/canonry/src/agent/types.ts
new file mode 100644
index 0000000..02eda79
--- /dev/null
+++ b/packages/canonry/src/agent/types.ts
@@ -0,0 +1,38 @@
+/**
+ * Agent types — shared across the agent module.
+ */
+
+export interface AgentThread {
+  id: string
+  projectId: string
+  title: string | null
+  channel: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface AgentMessage {
+  id: string
+  threadId: string
+  role: 'user' | 'assistant' | 'tool'
+  content: string
+  toolName: string | null
+  toolArgs: string | null
+  toolCallId: string | null
+  createdAt: string
+}
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: Record<string, unknown>
+  execute: (args: Record<string, unknown>) => Promise<string>
+}
+
+export interface AgentConfig {
+  provider: 'openai' | 'claude' | 'gemini'
+  apiKey: string
+  model?: string
+  maxSteps?: number
+  maxHistoryMessages?: number
+}
diff --git a/packages/canonry/src/cli.ts b/packages/canonry/src/cli.ts
index 9100ebb..0addac2 100644
--- a/packages/canonry/src/cli.ts
+++ b/packages/canonry/src/cli.ts
@@ -23,6 +23,7 @@ import {
   googleInspections, googleDeindexed, googleCoverage, googleCoverageHistory, googleInspectSitemap,
   googleDiscoverSitemaps,
 } from './commands/google.js'
+import { agentAsk, agentThreads, agentThread } from './commands/agent.js'
 import { trackEvent, isTelemetryEnabled, isFirstRun, getOrCreateAnonymousId, showFirstRunNotice } from './telemetry.js'
 
 const USAGE = `
@@ -90,6 +91,10 @@ Usage:
   canonry google coverage <project>  Show index coverage summary
   canonry google inspections <project>  Show URL inspection history (--url <url>)
   canonry google deindexed <project>  Show pages that lost indexing
+  canonry agent ask <project> "msg"   Ask the built-in AEO analyst a question
+  canonry agent ask <project> "msg" --thread <id>  Continue a conversation
+  canonry agent threads <project>     List agent threads
+  canonry agent thread <project> <id> Show thread with messages
   canonry settings                    Show active provider and quota settings
   canonry settings provider <name>    Update a provider config
   canonry settings google             Update Google OAuth credentials
@@ -176,7 +181,7 @@ async function main() {
   }
 
   // Resolve command name for telemetry (e.g. "project.create", "run")
-  const SUBCOMMAND_COMMANDS = new Set(['project', 'keyword', 'competitor', 'schedule', 'notify', 'settings', 'telemetry', 'google'])
+  const SUBCOMMAND_COMMANDS = new Set(['project', 'keyword', 'competitor', 'schedule', 'notify', 'settings', 'telemetry', 'google', 'agent'])
   const resolvedCommand = SUBCOMMAND_COMMANDS.has(command) && args[1] && !args[1].startsWith('-')
     ? `${command}.${args[1]}`
     : command
@@ -766,6 +771,62 @@ async function main() {
         break
       }
 
+      case 'agent': {
+        const subcommand = args[1]
+        switch (subcommand) {
+          case 'ask': {
+            const project = args[2]
+            if (!project) {
+              console.error('Error: project name is required')
+              process.exit(1)
+            }
+            // Collect message from remaining positional args (skip flags)
+            const agentParsed = parseArgs({
+              args: args.slice(3),
+              options: {
+                thread: { type: 'string' },
+                format: { type: 'string' },
+              },
+              allowPositionals: true,
+            })
+            const message = agentParsed.positionals.join(' ')
+            if (!message) {
+              console.error('Error: message is required')
+              process.exit(1)
+            }
+            await agentAsk(project, message, {
+              threadId: agentParsed.values.thread,
+              format: agentParsed.values.format ?? format,
+            })
+            break
+          }
+          case 'threads': {
+            const project = args[2]
+            if (!project) {
+              console.error('Error: project name is required')
+              process.exit(1)
+            }
+            await agentThreads(project, format)
+            break
+          }
+          case 'thread': {
+            const project = args[2]
+            const threadId = args[3]
+            if (!project || !threadId) {
+              console.error('Error: project name and thread ID are required')
+              process.exit(1)
+            }
+            await agentThread(project, threadId, format)
+            break
+          }
+          default:
+            console.error(`Unknown agent subcommand: ${subcommand ?? '(none)'}`)
+            console.log('Available: ask, threads, thread')
+            process.exit(1)
+        }
+        break
+      }
+
       case 'settings': {
         const subcommand = args[1]
         if (subcommand === 'provider') {
diff --git a/packages/canonry/src/client.ts b/packages/canonry/src/client.ts
index 3d945ad..25f9824 100644
--- a/packages/canonry/src/client.ts
+++ b/packages/canonry/src/client.ts
@@ -267,4 +267,30 @@ export class ApiClient {
   async gscDiscoverSitemaps(project: string): Promise<object> {
     return this.request<object>('POST', `/projects/${encodeURIComponent(project)}/google/gsc/discover-sitemaps`, {})
   }
+
+  // ── Agent ───────────────────────────────────────────────
+
+  async createAgentThread(project: string, body?: { title?: string; channel?: string }): Promise<object> {
+    return this.request<object>('POST', `/projects/${encodeURIComponent(project)}/agent/threads`, body ?? {})
+  }
+
+  async listAgentThreads(project: string): Promise<object[]> {
+    return this.request<object[]>('GET', `/projects/${encodeURIComponent(project)}/agent/threads`)
+  }
+
+  async getAgentThread(project: string, threadId: string): Promise<object> {
+    return this.request<object>('GET', `/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
+  }
+
+  async sendAgentMessage(project: string, threadId: string, message: string): Promise<{ threadId: string; response: string }> {
+    return this.request<{ threadId: string; response: string }>(
+      'POST',
+      `/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}/messages`,
+      { message },
+    )
+  }
+
+  async deleteAgentThread(project: string, threadId: string): Promise<void> {
+    await this.request<void>('DELETE', `/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
+  }
 }
diff --git a/packages/canonry/src/commands/agent.ts b/packages/canonry/src/commands/agent.ts
new file mode 100644
index 0000000..2b78db5
--- /dev/null
+++ b/packages/canonry/src/commands/agent.ts
@@ -0,0 +1,122 @@
+/**
+ * CLI command: canonry agent
+ *
+ * Subcommands:
+ *   canonry agent ask <project> "message"     — send a message, get a response
+ *   canonry agent threads <project>            — list threads
+ *   canonry agent thread <project> <threadId>  — show thread with messages
+ */
+
+import { loadConfig } from '../config.js'
+import { ApiClient } from '../client.js'
+
+function getClient(): ApiClient {
+  const config = loadConfig()
+  return new ApiClient(config.apiUrl, config.apiKey)
+}
+
+interface AgentThread {
+  id: string
+  projectId: string
+  title: string | null
+  channel: string
+  createdAt: string
+  updatedAt: string
+}
+
+interface AgentMessage {
+  id: string
+  role: string
+  content: string
+  toolName: string | null
+  createdAt: string
+}
+
+export async function agentAsk(project: string, message: string, opts?: {
+  threadId?: string
+  format?: string
+}): Promise<void> {
+  const client = getClient()
+  let threadId = opts?.threadId
+
+  // Create a new thread if none specified
+  if (!threadId) {
+    const thread = await client.createAgentThread(project, {
+      title: message.slice(0, 80),
+    }) as AgentThread
+    threadId = thread.id
+    if (opts?.format !== 'json') {
+      console.log(`Thread: ${threadId}\n`)
+    }
+  }
+
+  if (opts?.format !== 'json') {
+    console.log('Thinking...\n')
+  }
+
+  const result = await client.sendAgentMessage(project, threadId, message)
+
+  if (opts?.format === 'json') {
+    console.log(JSON.stringify({ threadId, response: result.response }, null, 2))
+  } else {
+    console.log(result.response)
+  }
+}
+
+export async function agentThreads(project: string, format?: string): Promise<void> {
+  const client = getClient()
+  const threads = await client.listAgentThreads(project) as AgentThread[]
+
+  if (format === 'json') {
+    console.log(JSON.stringify(threads, null, 2))
+    return
+  }
+
+  if (threads.length === 0) {
+    console.log('No agent threads yet. Use "canonry agent ask <project> <message>" to start.')
+    return
+  }
+
+  console.log(`Agent threads for ${project}:\n`)
+  for (const thread of threads) {
+    const title = thread.title ?? '(untitled)'
+    const ago = timeSince(thread.updatedAt)
+    console.log(`  ${thread.id}  ${title}  (${ago})`)
+  }
+}
+
+export async function agentThread(project: string, threadId: string, format?: string): Promise<void> {
+  const client = getClient()
+  const data = await client.getAgentThread(project, threadId) as AgentThread & { messages: AgentMessage[] }
+
+  if (format === 'json') {
+    console.log(JSON.stringify(data, null, 2))
+    return
+  }
+
+  console.log(`Thread: ${data.id}`)
+  console.log(`Title: ${data.title ?? '(untitled)'}`)
+  console.log(`Created: ${data.createdAt}\n`)
+  console.log('─'.repeat(60))
+
+  for (const msg of data.messages) {
+    if (msg.role === 'tool') continue
+
+    const label = msg.role === 'user' ? '🧑 You' :
+                  msg.role === 'assistant' && msg.toolName ? `🔧 ${msg.toolName}` :
+                  '🤖 Agent'
+
+    console.log(`\n${label}:`)
+    console.log(msg.content)
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────
+
+function timeSince(dateStr: string): string {
+  const seconds = Math.floor((Date.now() - new Date(dateStr).getTime()) / 1000)
+  if (seconds < 60) return 'just now'
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`
+  return `${Math.floor(seconds / 86400)}d ago`
+}
diff --git a/packages/canonry/src/config.ts b/packages/canonry/src/config.ts
index 85c1ddf..f99cca9 100644
--- a/packages/canonry/src/config.ts
+++ b/packages/canonry/src/config.ts
@@ -55,6 +55,19 @@ export interface CanonryConfig {
   // Telemetry (opt-out: undefined/true = enabled, false = disabled)
   telemetry?: boolean
   anonymousId?: string
+  // Built-in agent config
+  agent?: {
+    /** Which configured provider to use for the agent (defaults to first available: claude > openai > gemini) */
+    provider?: 'openai' | 'claude' | 'gemini'
+    /** Override the model for agent conversations (uses provider default if omitted) */
+    model?: string
+    /** Max tool-calling steps per message (default: 10) */
+    maxSteps?: number
+    /** Max history messages to include in context (default: 30) */
+    maxHistory?: number
+    /** Whether the agent is enabled (default: true if any provider is configured) */
+    enabled?: boolean
+  }
 }
 
 function normalizeGoogleConfig(config: CanonryConfig): void {
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 6839ce8..c662a6d 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -34,6 +34,9 @@ import { ProviderRegistry } from './provider-registry.js'
 import { Scheduler } from './scheduler.js'
 import { Notifier } from './notifier.js'
 import { fetchSiteText } from './site-fetch.js'
+import { AgentStore, agentChat, buildTools } from './agent/index.js'
+import type { LlmConfig } from './agent/index.js'
+import { ApiClient } from './client.js'
 
 const DEFAULT_QUOTA = {
   maxConcurrency: 2,
@@ -388,6 +391,7 @@ export async function createServer(opts: {
       const raw = await provider.adapter.generateText(prompt, provider.config)
       return parseKeywordResponse(raw, count)
     },
+    onAgentMessage: buildAgentHandler(opts, registry, opts.db),
   })
 
   // Try to serve static SPA assets
@@ -466,6 +470,74 @@ export async function createServer(opts: {
   return app
 }
 
+// ── Agent handler ──────────────────────────────────────────
+
+function buildAgentHandler(
+  opts: { config: CanonryConfig },
+  registry: ProviderRegistry,
+  db: DatabaseClient,
+): ((projectId: string, threadId: string, message: string) => Promise<string>) | undefined {
+  // Determine which provider to use for the agent
+  const agentConf = opts.config.agent ?? {}
+  if (agentConf.enabled === false) return undefined
+
+  // Pick provider: explicit config > first available (claude > openai > gemini)
+  const providerPriority: Array<'claude' | 'openai' | 'gemini'> = ['claude', 'openai', 'gemini']
+  let llmProvider: 'claude' | 'openai' | 'gemini' | undefined = agentConf.provider
+
+  if (!llmProvider) {
+    for (const p of providerPriority) {
+      if (registry.get(p as ProviderName)) {
+        llmProvider = p
+        break
+      }
+    }
+  }
+
+  if (!llmProvider) return undefined
+
+  const registeredProvider = registry.get(llmProvider as ProviderName)
+  if (!registeredProvider) return undefined
+
+  const llmConfig: LlmConfig = {
+    provider: llmProvider,
+    apiKey: registeredProvider.config.apiKey ?? '',
+    model: agentConf.model ?? registeredProvider.config.model,
+  }
+
+  const store = new AgentStore(db)
+  const apiClient = new ApiClient(
+    opts.config.apiUrl,
+    opts.config.apiKey,
+  )
+
+  return async (projectId: string, threadId: string, message: string) => {
+    // Resolve project details for the system prompt
+    const { projects: projectsTable } = await import('@ainyc/canonry-db')
+    const { eq } = await import('drizzle-orm')
+
+    const project = db.select().from(projectsTable).where(eq(projectsTable.id, projectId)).get()
+    if (!project) throw new Error(`Project ${projectId} not found`)
+
+    const tools = buildTools(apiClient, project.name)
+
+    return agentChat(threadId, message, {
+      store,
+      tools,
+      llmConfig,
+      project: {
+        name: project.name,
+        displayName: project.displayName,
+        domain: project.canonicalDomain,
+        country: project.country,
+        language: project.language,
+      },
+      maxSteps: agentConf.maxSteps ?? 10,
+      maxHistoryMessages: agentConf.maxHistory ?? 30,
+    })
+  }
+}
+
 function buildKeywordGenerationPrompt(ctx: {
   domain: string
   displayName?: string
diff --git a/packages/db/src/migrate.ts b/packages/db/src/migrate.ts
index de3e931..d56a91b 100644
--- a/packages/db/src/migrate.ts
+++ b/packages/db/src/migrate.ts
@@ -218,6 +218,28 @@ const MIGRATIONS = [
   `ALTER TABLE runs ADD COLUMN location TEXT`,
   // v10: Add sitemapUrl to google_connections for persistent sitemap storage
   `ALTER TABLE google_connections ADD COLUMN sitemap_url TEXT`,
+  // v11: Built-in agent — threads and messages tables
+  `CREATE TABLE IF NOT EXISTS agent_threads (
+    id          TEXT PRIMARY KEY,
+    project_id  TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    title       TEXT,
+    channel     TEXT NOT NULL DEFAULT 'chat',
+    created_at  TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_agent_threads_project ON agent_threads(project_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_agent_threads_updated ON agent_threads(updated_at)`,
+  `CREATE TABLE IF NOT EXISTS agent_messages (
+    id            TEXT PRIMARY KEY,
+    thread_id     TEXT NOT NULL REFERENCES agent_threads(id) ON DELETE CASCADE,
+    role          TEXT NOT NULL,
+    content       TEXT NOT NULL,
+    tool_name     TEXT,
+    tool_args     TEXT,
+    tool_call_id  TEXT,
+    created_at    TEXT NOT NULL
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_agent_messages_thread ON agent_messages(thread_id, created_at)`,
 ]
 
 export function migrate(db: DatabaseClient) {
diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts
index 3b0e893..c00650c 100644
--- a/packages/db/src/schema.ts
+++ b/packages/db/src/schema.ts
@@ -202,6 +202,31 @@ export const gscCoverageSnapshots = sqliteTable('gsc_coverage_snapshots', {
   index('idx_gsc_coverage_snap_run').on(table.syncRunId),
 ])
 
+export const agentThreads = sqliteTable('agent_threads', {
+  id: text('id').primaryKey(),
+  projectId: text('project_id').notNull().references(() => projects.id, { onDelete: 'cascade' }),
+  title: text('title'),
+  channel: text('channel').notNull().default('chat'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+}, (table) => [
+  index('idx_agent_threads_project').on(table.projectId),
+  index('idx_agent_threads_updated').on(table.updatedAt),
+])
+
+export const agentMessages = sqliteTable('agent_messages', {
+  id: text('id').primaryKey(),
+  threadId: text('thread_id').notNull().references(() => agentThreads.id, { onDelete: 'cascade' }),
+  role: text('role').notNull(),
+  content: text('content').notNull(),
+  toolName: text('tool_name'),
+  toolArgs: text('tool_args'),
+  toolCallId: text('tool_call_id'),
+  createdAt: text('created_at').notNull(),
+}, (table) => [
+  index('idx_agent_messages_thread').on(table.threadId, table.createdAt),
+])
+
 export const usageCounters = sqliteTable('usage_counters', {
   id: text('id').primaryKey(),
   scope: text('scope').notNull(),

From a2aead6854f412ce8fee5fc95ebf71372ff4a53f Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Mon, 16 Mar 2026 02:21:09 +0000
Subject: [PATCH 02/16] fix(security): Add project ownership verification to
 thread endpoints

Fixes IDOR vulnerability where thread endpoints (get, send message, delete)
accepted a :project param but never verified the thread belonged to that project.

Now all three endpoints verify thread.projectId === project.id before allowing access.

Addresses review comment #1 (Security - CRITICAL)
---
 packages/api-routes/src/agent.ts | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 1c18c09..2f7d5cc 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -113,7 +113,9 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       },
     },
   }, async (request, reply) => {
-    const { id } = request.params
+    const { project, id } = request.params
+
+    const projectRow = resolveProject(app.db, project)
 
     const thread = app.db
       .select()
@@ -121,7 +123,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       .where(eq(agentThreads.id, id))
       .get()
 
-    if (!thread) {
+    if (!thread || thread.projectId !== projectRow.id) {
       return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
     }
 
@@ -162,16 +164,16 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
     const { project, id: threadId } = request.params
     const { message } = request.body
 
-    resolveProject(app.db, project)
+    const projectRow = resolveProject(app.db, project)
 
-    // Verify thread exists
+    // Verify thread exists and belongs to this project
     const thread = app.db
       .select()
       .from(agentThreads)
       .where(eq(agentThreads.id, threadId))
       .get()
 
-    if (!thread) {
+    if (!thread || thread.projectId !== projectRow.id) {
       return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
     }
 
@@ -205,7 +207,20 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       },
     },
   }, async (request, reply) => {
-    const { id } = request.params
+    const { project, id } = request.params
+
+    const projectRow = resolveProject(app.db, project)
+
+    // Verify thread exists and belongs to this project
+    const thread = app.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.id, id))
+      .get()
+
+    if (!thread || thread.projectId !== projectRow.id) {
+      return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
+    }
 
     app.db.delete(agentThreads).where(eq(agentThreads.id, id)).run()
 

From f1f5813fb3bbf139e15c481b9e328429b3073b9e Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Mon, 16 Mar 2026 02:21:19 +0000
Subject: [PATCH 03/16] fix(agent): Add error handling for malformed JSON in
 tool call arguments

Wrap JSON.parse(toolCall.function.arguments) in try-catch to prevent crashes
when LLMs return malformed JSON. On parse error, persist the error as a tool
result and continue the agent loop instead of crashing.

Addresses review comment #2 (Bug)
---
 packages/canonry/src/agent/loop.ts | 36 +++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
index b6fe267..9125638 100644
--- a/packages/canonry/src/agent/loop.ts
+++ b/packages/canonry/src/agent/loop.ts
@@ -139,7 +139,41 @@ export async function agentChat(
 
       for (const toolCall of response.toolCalls) {
         const toolName = toolCall.function.name
-        const toolArgs = JSON.parse(toolCall.function.arguments) as Record<string, unknown>
+        
+        // Parse tool arguments with error handling (LLMs sometimes return malformed JSON)
+        let toolArgs: Record<string, unknown>
+        try {
+          toolArgs = JSON.parse(toolCall.function.arguments) as Record<string, unknown>
+        } catch {
+          const result = `Invalid arguments for ${toolName}: ${toolCall.function.arguments}`
+          
+          // Persist error and continue
+          await store.addMessage({
+            threadId,
+            role: 'assistant',
+            content: `Calling ${toolName}`,
+            toolName,
+            toolArgs: toolCall.function.arguments,
+            toolCallId: toolCall.id,
+          })
+
+          await store.addMessage({
+            threadId,
+            role: 'tool',
+            content: result,
+            toolName,
+            toolArgs: null,
+            toolCallId: toolCall.id,
+          })
+
+          messages.push({
+            role: 'tool',
+            content: result,
+            tool_call_id: toolCall.id,
+          })
+
+          continue
+        }
 
         opts.onToolCall?.(toolName, toolArgs)
 

From 5dc9096ddf9f5050ccdfc97ebc0ff4b8c75cbc62 Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Mon, 16 Mar 2026 02:21:27 +0000
Subject: [PATCH 04/16] perf(agent): Move dynamic imports to top-level

Replace dynamic imports of 'eq' and 'projects' table inside the message handler
with static top-level imports to eliminate async overhead on every message.

Addresses review comment #3 (Performance)
---
 packages/canonry/src/server.ts | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index c662a6d..46b52e9 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -9,7 +9,8 @@ const { version: PKG_VERSION } = _require('../package.json') as { version: strin
 import Fastify from 'fastify'
 import type { FastifyInstance } from 'fastify'
 import { apiRoutes } from '@ainyc/canonry-api-routes'
-import { auditLog, projects, type DatabaseClient } from '@ainyc/canonry-db'
+import { auditLog, projects, projects as projectsTable, type DatabaseClient } from '@ainyc/canonry-db'
+import { eq } from 'drizzle-orm'
 import { geminiAdapter } from '@ainyc/canonry-provider-gemini'
 import { openaiAdapter } from '@ainyc/canonry-provider-openai'
 import { claudeAdapter } from '@ainyc/canonry-provider-claude'
@@ -34,7 +35,7 @@ import { ProviderRegistry } from './provider-registry.js'
 import { Scheduler } from './scheduler.js'
 import { Notifier } from './notifier.js'
 import { fetchSiteText } from './site-fetch.js'
-import { AgentStore, agentChat, buildTools } from './agent/index.js'
+import { AgentStore, AgentServices, agentChat, buildTools } from './agent/index.js'
 import type { LlmConfig } from './agent/index.js'
 import { ApiClient } from './client.js'
 
@@ -506,6 +507,7 @@ function buildAgentHandler(
   }
 
   const store = new AgentStore(db)
+  const services = new AgentServices(db)
   const apiClient = new ApiClient(
     opts.config.apiUrl,
     opts.config.apiKey,
@@ -513,13 +515,10 @@ function buildAgentHandler(
 
   return async (projectId: string, threadId: string, message: string) => {
     // Resolve project details for the system prompt
-    const { projects: projectsTable } = await import('@ainyc/canonry-db')
-    const { eq } = await import('drizzle-orm')
-
     const project = db.select().from(projectsTable).where(eq(projectsTable.id, projectId)).get()
     if (!project) throw new Error(`Project ${projectId} not found`)
 
-    const tools = buildTools(apiClient, project.name)
+    const tools = buildTools(services, apiClient, project.name)
 
     return agentChat(threadId, message, {
       store,

From 2b52b09d8c22ff37aa927c60ed271a5282dbab5c Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Mon, 16 Mar 2026 02:21:40 +0000
Subject: [PATCH 05/16] refactor(agent): Replace circular HTTP self-calls with
 direct service layer

Create AgentServices class that provides direct DB access for agent tools,
eliminating the circular dependency where tools called the server's own HTTP API.

Most read-only tools (get_status, get_evidence, get_timeline, list_keywords,
list_competitors, get_run_details) now use direct DB calls via AgentServices.

Write operations (run_sweep) and external integrations (GSC) still use HTTP
for proper job orchestration and auth handling.

Benefits:
- Eliminates ~1-5ms HTTP localhost roundtrip per tool call
- Removes startup timing dependency
- Simplifies auth config

Addresses review comment #4 (Architecture)
---
 packages/canonry/src/agent/index.ts    |   1 +
 packages/canonry/src/agent/services.ts | 151 +++++++++++++++++++++++++
 packages/canonry/src/agent/tools.ts    |  24 ++--
 3 files changed, 165 insertions(+), 11 deletions(-)
 create mode 100644 packages/canonry/src/agent/services.ts

diff --git a/packages/canonry/src/agent/index.ts b/packages/canonry/src/agent/index.ts
index f3a49fe..51eab6e 100644
--- a/packages/canonry/src/agent/index.ts
+++ b/packages/canonry/src/agent/index.ts
@@ -1,4 +1,5 @@
 export { AgentStore } from './store.js'
+export { AgentServices } from './services.js'
 export { agentChat } from './loop.js'
 export { buildTools } from './tools.js'
 export { buildSystemPrompt } from './prompt.js'
diff --git a/packages/canonry/src/agent/services.ts b/packages/canonry/src/agent/services.ts
new file mode 100644
index 0000000..7318f95
--- /dev/null
+++ b/packages/canonry/src/agent/services.ts
@@ -0,0 +1,151 @@
+/**
+ * Agent services — direct DB operations for agent tools.
+ * 
+ * Provides the same functionality as the HTTP API routes but without
+ * the circular dependency of calling the server's own HTTP endpoints.
+ */
+
+import type { DatabaseClient } from '@ainyc/canonry-db'
+import { 
+  projects,
+  keywords as keywordsTable,
+  competitors as competitorsTable,
+  runs as runsTable,
+  querySnapshots,
+} from '@ainyc/canonry-db'
+import { eq, desc } from 'drizzle-orm'
+
+export class AgentServices {
+  constructor(private db: DatabaseClient) {}
+
+  async getProject(projectName: string) {
+    const project = this.db
+      .select()
+      .from(projects)
+      .where(eq(projects.name, projectName))
+      .get()
+    
+    if (!project) {
+      throw new Error(`Project ${projectName} not found`)
+    }
+    
+    return project
+  }
+
+  async listRuns(projectName: string) {
+    const project = await this.getProject(projectName)
+    
+    return this.db
+      .select()
+      .from(runsTable)
+      .where(eq(runsTable.projectId, project.id))
+      .orderBy(desc(runsTable.createdAt))
+      .all()
+  }
+
+  async getRun(runId: string) {
+    const run = this.db
+      .select()
+      .from(runsTable)
+      .where(eq(runsTable.id, runId))
+      .get()
+    
+    if (!run) {
+      throw new Error(`Run ${runId} not found`)
+    }
+    
+    const snapshots = this.db
+      .select()
+      .from(querySnapshots)
+      .where(eq(querySnapshots.runId, runId))
+      .all()
+    
+    return { ...run, snapshots }
+  }
+
+  async listKeywords(projectName: string) {
+    const project = await this.getProject(projectName)
+    
+    return this.db
+      .select()
+      .from(keywordsTable)
+      .where(eq(keywordsTable.projectId, project.id))
+      .all()
+  }
+
+  async listCompetitors(projectName: string) {
+    const project = await this.getProject(projectName)
+    
+    return this.db
+      .select()
+      .from(competitorsTable)
+      .where(eq(competitorsTable.projectId, project.id))
+      .all()
+  }
+
+  async getHistory(projectName: string) {
+    const project = await this.getProject(projectName)
+    
+    // Get recent runs with snapshots
+    const runs = this.db
+      .select()
+      .from(runsTable)
+      .where(eq(runsTable.projectId, project.id))
+      .orderBy(desc(runsTable.createdAt))
+      .limit(10)
+      .all()
+    
+    if (runs.length === 0) {
+      return { project, runs: [], evidence: {} }
+    }
+    
+    // Get all snapshots for these runs
+    const runIds = runs.map(r => r.id)
+    const snapshots = this.db
+      .select()
+      .from(querySnapshots)
+      .where(eq(querySnapshots.runId, runIds[0])) // Simplified - in real app would handle multiple runs
+      .all()
+    
+    return {
+      project,
+      runs,
+      snapshots,
+    }
+  }
+
+  async getTimeline(projectName: string) {
+    const project = await this.getProject(projectName)
+    
+    // Get all runs
+    const runs = this.db
+      .select()
+      .from(runsTable)
+      .where(eq(runsTable.projectId, project.id))
+      .orderBy(desc(runsTable.createdAt))
+      .all()
+    
+    // Aggregate citation data by run
+    const timeline = runs.map(run => {
+      const snapshots = this.db
+        .select()
+        .from(querySnapshots)
+        .where(eq(querySnapshots.runId, run.id))
+        .all()
+      
+      const cited = snapshots.filter(s => s.citationState === 'cited').length
+      const total = snapshots.length
+      
+      return {
+        runId: run.id,
+        createdAt: run.createdAt,
+        status: run.status,
+        cited,
+        total,
+        rate: total > 0 ? cited / total : 0,
+      }
+    })
+    
+    return { project, timeline }
+  }
+}
diff --git a/packages/canonry/src/agent/tools.ts b/packages/canonry/src/agent/tools.ts
index f9d9f40..58d20dd 100644
--- a/packages/canonry/src/agent/tools.ts
+++ b/packages/canonry/src/agent/tools.ts
@@ -1,10 +1,12 @@
 /**
  * Agent tools — canonry operations exposed as LLM-callable functions.
  *
- * Each tool wraps the ApiClient so the agent uses the same HTTP API
- * that CLI commands and the UI use. No direct DB access from tools.
+ * Most tools use direct service layer calls to avoid circular HTTP dependency.
+ * Write operations (run_sweep) and external integrations (GSC) still use HTTP
+ * for proper job orchestration and auth handling.
  */
 
+import type { AgentServices } from './services.js'
 import type { ApiClient } from '../client.js'
 
 export interface AgentTool {
@@ -18,7 +20,7 @@ export interface AgentTool {
   execute: (args: Record<string, unknown>) => Promise<string>
 }
 
-export function buildTools(client: ApiClient, projectName: string): AgentTool[] {
+export function buildTools(services: AgentServices, client: ApiClient, projectName: string): AgentTool[] {
   return [
     {
       name: 'get_status',
@@ -30,9 +32,9 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: [],
       },
       execute: async () => {
-        const project = await client.getProject(projectName)
-        const runs = await client.listRuns(projectName)
-        return JSON.stringify({ project, latestRuns: (runs as unknown[]).slice(-3) }, null, 2)
+        const project = await services.getProject(projectName)
+        const runs = await services.listRuns(projectName)
+        return JSON.stringify({ project, latestRuns: runs.slice(-3) }, null, 2)
       },
     },
     {
@@ -68,7 +70,7 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: [],
       },
       execute: async () => {
-        const history = await client.getHistory(projectName)
+        const history = await services.getHistory(projectName)
         return JSON.stringify(history, null, 2)
       },
     },
@@ -82,7 +84,7 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: [],
       },
       execute: async () => {
-        const timeline = await client.getTimeline(projectName)
+        const timeline = await services.getTimeline(projectName)
         return JSON.stringify(timeline, null, 2)
       },
     },
@@ -95,7 +97,7 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: [],
       },
       execute: async () => {
-        const keywords = await client.listKeywords(projectName)
+        const keywords = await services.listKeywords(projectName)
         return JSON.stringify(keywords, null, 2)
       },
     },
@@ -108,7 +110,7 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: [],
       },
       execute: async () => {
-        const competitors = await client.listCompetitors(projectName)
+        const competitors = await services.listCompetitors(projectName)
         return JSON.stringify(competitors, null, 2)
       },
     },
@@ -126,7 +128,7 @@ export function buildTools(client: ApiClient, projectName: string): AgentTool[]
         required: ['runId'],
       },
       execute: async (args) => {
-        const run = await client.getRun(args.runId as string)
+        const run = await services.getRun(args.runId as string)
         return JSON.stringify(run, null, 2)
       },
     },

From b6d2643a8279dd7eed4153d1be92a8c2274cf762 Mon Sep 17 00:00:00 2001
From: "Claw (AINYC Agent)" <agent@ainyc.ai>
Date: Mon, 16 Mar 2026 02:21:50 +0000
Subject: [PATCH 06/16] style(agent): Remove dead code and unused types

- Remove redundant if/else in llm.ts that set the same Authorization header
- Remove unused ToolDefinition interface (actual interface is AgentTool)

Addresses review comments #5 and #6 (Style)
---
 packages/canonry/src/agent/llm.ts   | 7 +------
 packages/canonry/src/agent/types.ts | 7 -------
 2 files changed, 1 insertion(+), 13 deletions(-)

diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 3ff4644..035b824 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -72,12 +72,7 @@ export async function chatCompletion(
 
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
-  }
-
-  if (config.provider === 'gemini') {
-    headers['Authorization'] = `Bearer ${config.apiKey}`
-  } else {
-    headers['Authorization'] = `Bearer ${config.apiKey}`
+    'Authorization': `Bearer ${config.apiKey}`,
   }
 
   const body = {
diff --git a/packages/canonry/src/agent/types.ts b/packages/canonry/src/agent/types.ts
index 02eda79..6aa09ad 100644
--- a/packages/canonry/src/agent/types.ts
+++ b/packages/canonry/src/agent/types.ts
@@ -22,13 +22,6 @@ export interface AgentMessage {
   createdAt: string
 }
 
-export interface ToolDefinition {
-  name: string
-  description: string
-  parameters: Record<string, unknown>
-  execute: (args: Record<string, unknown>) => Promise<string>
-}
-
 export interface AgentConfig {
   provider: 'openai' | 'claude' | 'gemini'
   apiKey: string

From fabe3e3b18565af49c840c2a53a077ce05c2bfce Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Sun, 15 Mar 2026 22:36:48 -0400
Subject: [PATCH 07/16] fix(agent): fix 5 bugs in agent loop, SSRF validation,
 and services

- P1: History windowing now returns newest N messages (was oldest N,
  causing long threads to drop the user's latest prompt)
- P1: SSRF validation now blocks localhost, IPv6 loopback/private,
  and resolves hostnames to verify they don't point to internal IPs
- P2: getRun() now requires projectName to prevent cross-project
  data access via known run IDs
- P2: getHistory() now queries snapshots for all returned runs
  (was only querying the first run ID)
- P2: convertToClaudeMessages() now handles malformed JSON in
  historical tool calls instead of crashing the thread

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 package.json                                 |  2 +-
 packages/canonry/package.json                |  2 +-
 packages/canonry/src/agent/llm.ts            | 10 +-
 packages/canonry/src/agent/services.ts       | 20 ++--
 packages/canonry/src/agent/store.ts          | 15 ++-
 packages/canonry/src/agent/tools.ts          |  2 +-
 packages/canonry/src/sitemap-parser.ts       | 96 ++++++++++++++++----
 packages/canonry/test/sitemap-parser.test.ts | 27 +++++-
 8 files changed, 137 insertions(+), 37 deletions(-)

diff --git a/package.json b/package.json
index c3a3cc6..18492e2 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "canonry",
   "private": true,
-  "version": "1.15.3",
+  "version": "1.16.0",
   "type": "module",
   "packageManager": "pnpm@10.28.2",
   "scripts": {
diff --git a/packages/canonry/package.json b/packages/canonry/package.json
index 6fc4369..b6f5360 100644
--- a/packages/canonry/package.json
+++ b/packages/canonry/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.15.3",
+  "version": "1.16.0",
   "type": "module",
   "description": "The ultimate open-source AEO monitoring tool - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 035b824..9151db9 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -210,11 +210,19 @@ function convertToClaudeMessages(
           content.push({ type: 'text', text: msg.content })
         }
         for (const tc of msg.tool_calls) {
+          let input: Record<string, unknown>
+          try {
+            input = JSON.parse(tc.function.arguments) as Record<string, unknown>
+          } catch {
+            // Malformed JSON from a previous turn — send an empty object so the
+            // thread can recover instead of crashing all subsequent turns.
+            input = {}
+          }
           content.push({
             type: 'tool_use',
             id: tc.id,
             name: tc.function.name,
-            input: JSON.parse(tc.function.arguments),
+            input,
           })
         }
         result.push({ role: 'assistant', content })
diff --git a/packages/canonry/src/agent/services.ts b/packages/canonry/src/agent/services.ts
index 7318f95..05f6c2a 100644
--- a/packages/canonry/src/agent/services.ts
+++ b/packages/canonry/src/agent/services.ts
@@ -13,7 +13,7 @@ import {
   runs as runsTable,
   querySnapshots,
 } from '@ainyc/canonry-db'
-import { eq, desc } from 'drizzle-orm'
+import { eq, desc, and, inArray } from 'drizzle-orm'
 
 export class AgentServices {
   constructor(private db: DatabaseClient) {}
@@ -43,23 +43,25 @@ export class AgentServices {
       .all()
   }
 
-  async getRun(runId: string) {
+  async getRun(runId: string, projectName: string) {
+    const project = await this.getProject(projectName)
+
     const run = this.db
       .select()
       .from(runsTable)
-      .where(eq(runsTable.id, runId))
+      .where(and(eq(runsTable.id, runId), eq(runsTable.projectId, project.id)))
       .get()
-    
+
     if (!run) {
-      throw new Error(`Run ${runId} not found`)
+      throw new Error(`Run ${runId} not found in project ${projectName}`)
     }
-    
+
     const snapshots = this.db
       .select()
       .from(querySnapshots)
       .where(eq(querySnapshots.runId, runId))
       .all()
-    
+
     return { ...run, snapshots }
   }
 
@@ -104,9 +106,9 @@ export class AgentServices {
     const snapshots = this.db
       .select()
       .from(querySnapshots)
-      .where(eq(querySnapshots.runId, runIds[0])) // Simplified - in real app would handle multiple runs
+      .where(inArray(querySnapshots.runId, runIds))
       .all()
-    
+
     return {
       project,
       runs,
diff --git a/packages/canonry/src/agent/store.ts b/packages/canonry/src/agent/store.ts
index 893e37c..10ea2b4 100644
--- a/packages/canonry/src/agent/store.ts
+++ b/packages/canonry/src/agent/store.ts
@@ -3,7 +3,7 @@
  */
 
 import crypto from 'node:crypto'
-import { eq, desc, asc } from 'drizzle-orm'
+import { eq, desc, asc, sql } from 'drizzle-orm'
 import type { DatabaseClient } from '@ainyc/canonry-db'
 import { agentThreads, agentMessages } from '@ainyc/canonry-db'
 import type { AgentThread, AgentMessage } from './types.js'
@@ -85,12 +85,21 @@ export class AgentStore {
   }
 
   async getMessages(threadId: string, limit = 50): Promise<AgentMessage[]> {
+    // Use a subquery to get the newest N messages, then re-sort ascending
+    // so the LLM sees them in chronological order. Without this, long threads
+    // would return the oldest N messages and drop the user's latest prompt.
     return this.db
       .select()
       .from(agentMessages)
-      .where(eq(agentMessages.threadId, threadId))
+      .where(
+        sql`${agentMessages.id} IN (
+          SELECT ${agentMessages.id} FROM ${agentMessages}
+          WHERE ${agentMessages.threadId} = ${threadId}
+          ORDER BY ${agentMessages.createdAt} DESC
+          LIMIT ${limit}
+        )`,
+      )
       .orderBy(asc(agentMessages.createdAt))
-      .limit(limit)
       .all() as AgentMessage[]
   }
 }
diff --git a/packages/canonry/src/agent/tools.ts b/packages/canonry/src/agent/tools.ts
index 58d20dd..a59f1fb 100644
--- a/packages/canonry/src/agent/tools.ts
+++ b/packages/canonry/src/agent/tools.ts
@@ -128,7 +128,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
         required: ['runId'],
       },
       execute: async (args) => {
-        const run = await services.getRun(args.runId as string)
+        const run = await services.getRun(args.runId as string, projectName)
         return JSON.stringify(run, null, 2)
       },
     },
diff --git a/packages/canonry/src/sitemap-parser.ts b/packages/canonry/src/sitemap-parser.ts
index 6c562f5..f639232 100644
--- a/packages/canonry/src/sitemap-parser.ts
+++ b/packages/canonry/src/sitemap-parser.ts
@@ -1,15 +1,42 @@
+import dns from 'node:dns/promises'
+import net from 'node:net'
+
 const LOC_REGEX = /<loc>\s*([^<]+?)\s*<\/loc>/gi
 const SITEMAP_TAG_REGEX = /<sitemap>[\s\S]*?<\/sitemap>/gi
 
-// Block private/link-local IP ranges to prevent SSRF
-const PRIVATE_IP_PATTERNS = [
-  /^169\.254\./,                    // link-local (AWS metadata endpoint etc.)
-  /^10\./,                          // private class A
-  /^172\.(1[6-9]|2\d|3[01])\./,    // private class B
-  /^192\.168\./,                    // private class C
-]
+/**
+ * Check whether an IP address (v4 or v6) is private, loopback, or link-local.
+ */
+function isPrivateIP(ip: string): boolean {
+  // IPv4 checks
+  if (net.isIPv4(ip)) {
+    const parts = ip.split('.').map(Number)
+    if (parts[0] === 127) return true                                          // loopback
+    if (parts[0] === 10) return true                                           // class A
+    if (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) return true   // class B
+    if (parts[0] === 192 && parts[1] === 168) return true                      // class C
+    if (parts[0] === 169 && parts[1] === 254) return true                      // link-local
+    if (parts[0] === 0) return true                                            // 0.0.0.0/8
+    return false
+  }
+
+  // IPv6 checks
+  if (net.isIPv6(ip)) {
+    const normalized = ip.toLowerCase()
+    if (normalized === '::1') return true                           // loopback
+    if (normalized === '::') return true                            // unspecified
+    if (normalized.startsWith('fe80:')) return true                 // link-local
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true // ULA
+    // IPv4-mapped IPv6 (::ffff:x.x.x.x)
+    const v4mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+    if (v4mapped) return isPrivateIP(v4mapped[1]!)
+    return false
+  }
+
+  return false
+}
 
-function validateSitemapUrl(url: string): void {
+async function validateSitemapUrl(url: string): Promise<void> {
   let parsed: URL
   try {
     parsed = new URL(url)
@@ -19,24 +46,61 @@ function validateSitemapUrl(url: string): void {
   if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
     throw new Error(`Sitemap URL must use http or https protocol: ${url}`)
   }
-  const host = parsed.hostname.toLowerCase()
-  for (const pattern of PRIVATE_IP_PATTERNS) {
-    if (pattern.test(host)) {
+
+  // URL.hostname wraps IPv6 in brackets — strip them for IP checks
+  const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '')
+
+  // Block localhost by name
+  if (host === 'localhost' || host === 'localhost.localdomain') {
+    throw new Error(`Sitemap URL must not point to localhost: ${url}`)
+  }
+
+  // If the hostname is already an IP literal, check it directly
+  if (net.isIP(host)) {
+    if (isPrivateIP(host)) {
       throw new Error(`Sitemap URL points to a private or reserved IP range: ${url}`)
     }
+    return
+  }
+
+  // Resolve the hostname and verify all addresses are public
+  let addresses: string[]
+  try {
+    const results = await dns.resolve(host)
+    const results6 = await dns.resolve6(host).catch(() => [] as string[])
+    addresses = [...results, ...results6]
+  } catch {
+    throw new Error(`Cannot resolve sitemap hostname: ${host}`)
+  }
+
+  if (addresses.length === 0) {
+    throw new Error(`Cannot resolve sitemap hostname: ${host}`)
+  }
+
+  for (const addr of addresses) {
+    if (isPrivateIP(addr)) {
+      throw new Error(`Sitemap URL resolves to a private or reserved IP address: ${url}`)
+    }
   }
 }
 
-export async function fetchAndParseSitemap(sitemapUrl: string): Promise<string[]> {
+interface FetchSitemapOptions {
+  /** Skip SSRF validation — only for tests against localhost. */
+  dangerouslyAllowPrivate?: boolean
+}
+
+export async function fetchAndParseSitemap(sitemapUrl: string, options?: FetchSitemapOptions): Promise<string[]> {
   const urls = new Set<string>()
-  await parseSitemapRecursive(sitemapUrl, urls, 0)
+  await parseSitemapRecursive(sitemapUrl, urls, 0, options)
   return [...urls]
 }
 
-async function parseSitemapRecursive(url: string, urls: Set<string>, depth: number): Promise<void> {
+async function parseSitemapRecursive(url: string, urls: Set<string>, depth: number, options?: FetchSitemapOptions): Promise<void> {
   if (depth > 3) return // Prevent infinite recursion
 
-  validateSitemapUrl(url)
+  if (!options?.dangerouslyAllowPrivate) {
+    await validateSitemapUrl(url)
+  }
 
   const res = await fetch(url)
   if (!res.ok) {
@@ -52,7 +116,7 @@ async function parseSitemapRecursive(url: string, urls: Set<string>, depth: numb
       const locMatch = LOC_REGEX.exec(entry)
       LOC_REGEX.lastIndex = 0
       if (locMatch?.[1]) {
-        await parseSitemapRecursive(locMatch[1], urls, depth + 1)
+        await parseSitemapRecursive(locMatch[1], urls, depth + 1, options)
       }
     }
     return
diff --git a/packages/canonry/test/sitemap-parser.test.ts b/packages/canonry/test/sitemap-parser.test.ts
index b42ec40..8216815 100644
--- a/packages/canonry/test/sitemap-parser.test.ts
+++ b/packages/canonry/test/sitemap-parser.test.ts
@@ -43,7 +43,7 @@ describe('fetchAndParseSitemap', () => {
     const s = await createServer({ '/sitemap.xml': xml })
     server = s.server
 
-    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)
+    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`, { dangerouslyAllowPrivate: true })
     expect(urls.length).toBe(3)
     expect(urls.includes('https://example.com/')).toBeTruthy()
     expect(urls.includes('https://example.com/about')).toBeTruthy()
@@ -61,7 +61,7 @@ describe('fetchAndParseSitemap', () => {
     const s = await createServer({ '/sitemap.xml': xml })
     server = s.server
 
-    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)
+    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`, { dangerouslyAllowPrivate: true })
     expect(urls.length).toBe(2)
   })
 
@@ -100,7 +100,7 @@ describe('fetchAndParseSitemap', () => {
     })
     server = s.server
 
-    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)
+    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`, { dangerouslyAllowPrivate: true })
     expect(urls.length).toBe(2)
     expect(urls.includes('https://example.com/page1')).toBeTruthy()
     expect(urls.includes('https://example.com/page2')).toBeTruthy()
@@ -110,7 +110,7 @@ describe('fetchAndParseSitemap', () => {
     const s = await createServer({})
     server = s.server
 
-    await expect(() => fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)).rejects.toThrow('404')
+    await expect(() => fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`, { dangerouslyAllowPrivate: true })).rejects.toThrow('404')
   })
 
   it('returns empty array for sitemap with no URLs', async () => {
@@ -121,7 +121,24 @@ describe('fetchAndParseSitemap', () => {
     const s = await createServer({ '/sitemap.xml': xml })
     server = s.server
 
-    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)
+    const urls = await fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`, { dangerouslyAllowPrivate: true })
     expect(urls.length).toBe(0)
   })
+
+  it('blocks localhost by default (SSRF)', async () => {
+    const s = await createServer({ '/sitemap.xml': '<urlset></urlset>' })
+    server = s.server
+
+    await expect(() => fetchAndParseSitemap(`${s.baseUrl}/sitemap.xml`)).rejects.toThrow(/localhost/)
+  })
+
+  it('blocks private IPv4 addresses (SSRF)', async () => {
+    await expect(() => fetchAndParseSitemap('http://10.0.0.1/sitemap.xml')).rejects.toThrow(/private/)
+    await expect(() => fetchAndParseSitemap('http://192.168.1.1/sitemap.xml')).rejects.toThrow(/private/)
+    await expect(() => fetchAndParseSitemap('http://127.0.0.1/sitemap.xml')).rejects.toThrow(/private/)
+  })
+
+  it('blocks IPv6 loopback (SSRF)', async () => {
+    await expect(() => fetchAndParseSitemap('http://[::1]/sitemap.xml')).rejects.toThrow(/private/)
+  })
 })

From 5e516a5f5b2d8e7fabf7b9fc7d1dcc211e76f1c0 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:12:55 -0400
Subject: [PATCH 08/16] fix(agent): address all review findings from PR #74

- Fix tool-call persistence ordering: persist assistant row before
  tool.execute() so DB is never left with orphaned tool results
- Guard against empty apiKey: return undefined instead of silently
  constructing a broken handler
- Fall back to localhost:{port} when apiUrl is not configured so
  self-hosted instances can use HTTP-backed agent tools
- Explicitly delete agent_messages before thread deletion (don't
  rely on PRAGMA foreign_keys = ON)
- Add maxLength: 8000 on message body schema (Fastify/Ajv enforcement)
- Fix N+1 in getTimeline: bulk-fetch all snapshots with inArray
- Remove dead claude entry from PROVIDER_ENDPOINTS (uses dedicated path)
- Clean up duplicate projects import alias in server.ts
- Narrow dns.resolve6 catch to ENODATA/ENOTFOUND only
- Add CHECK constraint on agent_messages.role column

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/api-routes/src/agent.ts       |  3 ++-
 packages/canonry/src/agent/llm.ts      |  2 +-
 packages/canonry/src/agent/loop.ts     | 21 +++++++++---------
 packages/canonry/src/agent/services.ts | 30 +++++++++++++++-----------
 packages/canonry/src/server.ts         | 16 +++++++++-----
 packages/canonry/src/sitemap-parser.ts |  7 +++++-
 packages/db/src/migrate.ts             |  2 +-
 7 files changed, 50 insertions(+), 31 deletions(-)

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 2f7d5cc..5fb4d9a 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -155,7 +155,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       body: {
         type: 'object',
         properties: {
-          message: { type: 'string' },
+          message: { type: 'string', maxLength: 8000 },
         },
         required: ['message'],
       },
@@ -222,6 +222,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
     }
 
+    app.db.delete(agentMessages).where(eq(agentMessages.threadId, id)).run()
     app.db.delete(agentThreads).where(eq(agentThreads.id, id)).run()
 
     return reply.status(204).send()
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 9151db9..22da308 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -36,9 +36,9 @@ interface CompletionResponse {
   toolCalls?: ToolCall[]
 }
 
+// Claude uses a dedicated code path (claudeCompletion) — not listed here.
 const PROVIDER_ENDPOINTS: Record<string, string> = {
   openai: 'https://api.openai.com/v1/chat/completions',
-  claude: 'https://api.anthropic.com/v1/messages',
   gemini: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',
 }
 
diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
index 9125638..ef1bdbf 100644
--- a/packages/canonry/src/agent/loop.ts
+++ b/packages/canonry/src/agent/loop.ts
@@ -177,6 +177,17 @@ export async function agentChat(
 
         opts.onToolCall?.(toolName, toolArgs)
 
+        // Persist assistant tool-call row BEFORE execution so the DB
+        // always has a matching assistant row for the tool result.
+        await store.addMessage({
+          threadId,
+          role: 'assistant',
+          content: `Calling ${toolName}`,
+          toolName,
+          toolArgs: JSON.stringify(toolArgs),
+          toolCallId: toolCall.id,
+        })
+
         // Find and execute tool
         const tool = tools.find(t => t.name === toolName)
         let result: string
@@ -191,16 +202,6 @@ export async function agentChat(
           result = `Unknown tool: ${toolName}`
         }
 
-        // Persist tool call and result
-        await store.addMessage({
-          threadId,
-          role: 'assistant',
-          content: `Calling ${toolName}`,
-          toolName,
-          toolArgs: JSON.stringify(toolArgs),
-          toolCallId: toolCall.id,
-        })
-
         await store.addMessage({
           threadId,
           role: 'tool',
diff --git a/packages/canonry/src/agent/services.ts b/packages/canonry/src/agent/services.ts
index 05f6c2a..37c6751 100644
--- a/packages/canonry/src/agent/services.ts
+++ b/packages/canonry/src/agent/services.ts
@@ -118,26 +118,32 @@ export class AgentServices {
 
   async getTimeline(projectName: string) {
     const project = await this.getProject(projectName)
-    
-    // Get all runs
+
     const runs = this.db
       .select()
       .from(runsTable)
       .where(eq(runsTable.projectId, project.id))
       .orderBy(desc(runsTable.createdAt))
       .all()
-    
-    // Aggregate citation data by run
+
+    // Bulk-fetch all snapshots to avoid N+1
+    const runIds = runs.map(r => r.id)
+    const allSnapshots = runIds.length > 0
+      ? this.db.select().from(querySnapshots).where(inArray(querySnapshots.runId, runIds)).all()
+      : []
+
+    const snapshotsByRun = new Map<string, typeof allSnapshots>()
+    for (const s of allSnapshots) {
+      const arr = snapshotsByRun.get(s.runId) ?? []
+      arr.push(s)
+      snapshotsByRun.set(s.runId, arr)
+    }
+
     const timeline = runs.map(run => {
-      const snapshots = this.db
-        .select()
-        .from(querySnapshots)
-        .where(eq(querySnapshots.runId, run.id))
-        .all()
-      
+      const snapshots = snapshotsByRun.get(run.id) ?? []
       const cited = snapshots.filter(s => s.citationState === 'cited').length
       const total = snapshots.length
-      
+
       return {
         runId: run.id,
         createdAt: run.createdAt,
@@ -147,7 +153,7 @@ export class AgentServices {
         rate: total > 0 ? cited / total : 0,
       }
     })
-    
+
     return { project, timeline }
   }
 }
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 46b52e9..a8989bc 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -9,7 +9,7 @@ const { version: PKG_VERSION } = _require('../package.json') as { version: strin
 import Fastify from 'fastify'
 import type { FastifyInstance } from 'fastify'
 import { apiRoutes } from '@ainyc/canonry-api-routes'
-import { auditLog, projects, projects as projectsTable, type DatabaseClient } from '@ainyc/canonry-db'
+import { auditLog, projects, type DatabaseClient } from '@ainyc/canonry-db'
 import { eq } from 'drizzle-orm'
 import { geminiAdapter } from '@ainyc/canonry-provider-gemini'
 import { openaiAdapter } from '@ainyc/canonry-provider-openai'
@@ -500,22 +500,28 @@ function buildAgentHandler(
   const registeredProvider = registry.get(llmProvider as ProviderName)
   if (!registeredProvider) return undefined
 
+  if (!registeredProvider.config.apiKey) return undefined
+
   const llmConfig: LlmConfig = {
     provider: llmProvider,
-    apiKey: registeredProvider.config.apiKey ?? '',
+    apiKey: registeredProvider.config.apiKey,
     model: agentConf.model ?? registeredProvider.config.model,
   }
 
   const store = new AgentStore(db)
   const services = new AgentServices(db)
+
+  // ApiClient is only needed for HTTP-backed tools (run_sweep, GSC).
+  // If apiUrl/apiKey aren't set (self-hosted), those tools will gracefully error.
+  const serverPort = opts.config.port ?? 4100
   const apiClient = new ApiClient(
-    opts.config.apiUrl,
-    opts.config.apiKey,
+    opts.config.apiUrl ?? `http://localhost:${serverPort}`,
+    opts.config.apiKey ?? '',
   )
 
   return async (projectId: string, threadId: string, message: string) => {
     // Resolve project details for the system prompt
-    const project = db.select().from(projectsTable).where(eq(projectsTable.id, projectId)).get()
+    const project = db.select().from(projects).where(eq(projects.id, projectId)).get()
     if (!project) throw new Error(`Project ${projectId} not found`)
 
     const tools = buildTools(services, apiClient, project.name)
diff --git a/packages/canonry/src/sitemap-parser.ts b/packages/canonry/src/sitemap-parser.ts
index f639232..cfb431f 100644
--- a/packages/canonry/src/sitemap-parser.ts
+++ b/packages/canonry/src/sitemap-parser.ts
@@ -67,7 +67,12 @@ async function validateSitemapUrl(url: string): Promise<void> {
   let addresses: string[]
   try {
     const results = await dns.resolve(host)
-    const results6 = await dns.resolve6(host).catch(() => [] as string[])
+    const results6 = await dns.resolve6(host).catch((err: NodeJS.ErrnoException) => {
+      // No AAAA records is expected for IPv4-only hosts — treat as empty.
+      // Re-throw unexpected errors so they don't silently mask real failures.
+      if (err.code === 'ENODATA' || err.code === 'ENOTFOUND') return [] as string[]
+      throw err
+    })
     addresses = [...results, ...results6]
   } catch {
     throw new Error(`Cannot resolve sitemap hostname: ${host}`)
diff --git a/packages/db/src/migrate.ts b/packages/db/src/migrate.ts
index d56a91b..e234685 100644
--- a/packages/db/src/migrate.ts
+++ b/packages/db/src/migrate.ts
@@ -232,7 +232,7 @@ const MIGRATIONS = [
   `CREATE TABLE IF NOT EXISTS agent_messages (
     id            TEXT PRIMARY KEY,
     thread_id     TEXT NOT NULL REFERENCES agent_threads(id) ON DELETE CASCADE,
-    role          TEXT NOT NULL,
+    role          TEXT NOT NULL CHECK(role IN ('user', 'assistant', 'tool')),
     content       TEXT NOT NULL,
     tool_name     TEXT,
     tool_args     TEXT,

From e259d099c059ee77c3b26c201d8a95e03e0ffe8b Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:38:44 -0400
Subject: [PATCH 09/16] fix(agent): address second round of review findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Critical fixes:
- Fix history truncation splitting tool-call pairs: trim orphaned
  tool/assistant messages at the window boundary
- Add per-thread concurrency guard (409 Conflict if thread is busy)
- Fix get_status returning oldest 3 runs (slice(-3) → slice(0,3))
- Resolve LLM config from registry at call time instead of capturing
  stale API key at startup
- Merge consecutive Claude tool results into single user message to
  avoid invalid same-role sequences

Important fixes:
- Add 20KB truncation cap on tool results to prevent blowing up
  LLM context window
- Guard against empty toolCalls array causing silent spin
- Add 90s timeout on all LLM fetch calls
- Return structured error responses (502 for LLM errors) instead of
  generic 500s
- Fix inconsistent return shape in getHistory (evidence → snapshots)
- Add maxLength/enum validation on thread title and channel fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/api-routes/src/agent.ts       | 33 ++++++++++++++++++++++----
 packages/canonry/src/agent/llm.ts      | 30 ++++++++++++++---------
 packages/canonry/src/agent/loop.ts     |  2 +-
 packages/canonry/src/agent/services.ts |  2 +-
 packages/canonry/src/agent/store.ts    | 27 ++++++++++++++++++++-
 packages/canonry/src/agent/tools.ts    | 27 +++++++++++++--------
 packages/canonry/src/server.ts         | 18 +++++++++-----
 7 files changed, 105 insertions(+), 34 deletions(-)

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 5fb4d9a..2b6abdc 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -26,6 +26,9 @@ export interface AgentRoutesOptions {
 export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions) {
   const prefix = '/projects/:project/agent'
 
+  // Per-thread mutex — prevents concurrent agent loops from corrupting history
+  const activeThreads = new Set<string>()
+
   // ── Create thread ─────────────────────────────────────────
 
   app.post<{
@@ -41,8 +44,8 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       body: {
         type: 'object',
         properties: {
-          title: { type: 'string' },
-          channel: { type: 'string' },
+          title: { type: 'string', maxLength: 200 },
+          channel: { type: 'string', enum: ['chat', 'cli', 'api'] },
         },
       },
     },
@@ -186,9 +189,31 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       })
     }
 
-    const response = await opts.onAgentMessage(thread.projectId, threadId, message)
+    if (activeThreads.has(threadId)) {
+      return reply.status(409).send({
+        error: {
+          code: 'THREAD_BUSY',
+          message: 'This thread is already processing a message. Please wait.',
+        },
+      })
+    }
 
-    return reply.send({ threadId, response })
+    activeThreads.add(threadId)
+    try {
+      const response = await opts.onAgentMessage(thread.projectId, threadId, message)
+      return reply.send({ threadId, response })
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      const isLlmError = msg.includes('API error') || msg.includes('API key') || msg.includes('timeout')
+      return reply.status(isLlmError ? 502 : 500).send({
+        error: {
+          code: isLlmError ? 'LLM_ERROR' : 'AGENT_ERROR',
+          message: msg,
+        },
+      })
+    } finally {
+      activeThreads.delete(threadId)
+    }
   })
 
   // ── Delete thread ─────────────────────────────────────────
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 22da308..3f2919f 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -87,6 +87,7 @@ export async function chatCompletion(
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal: AbortSignal.timeout(90_000),
   })
 
   if (!res.ok) {
@@ -160,6 +161,7 @@ async function claudeCompletion(
       'anthropic-version': '2023-06-01',
     },
     body: JSON.stringify(body),
+    signal: AbortSignal.timeout(90_000),
   })
 
   if (!res.ok) {
@@ -230,17 +232,23 @@ function convertToClaudeMessages(
         result.push({ role: 'assistant', content: msg.content ?? '' })
       }
     } else if (msg.role === 'tool') {
-      // Claude expects tool results as user messages with tool_result content blocks
-      result.push({
-        role: 'user',
-        content: [
-          {
-            type: 'tool_result',
-            tool_use_id: msg.tool_call_id,
-            content: msg.content ?? '',
-          },
-        ],
-      })
+      // Claude expects tool results as user messages with tool_result content blocks.
+      // Merge consecutive tool results into one user message to avoid
+      // consecutive same-role messages (which Claude rejects).
+      const toolBlock = {
+        type: 'tool_result',
+        tool_use_id: msg.tool_call_id,
+        content: msg.content ?? '',
+      }
+      const prev = result[result.length - 1]
+      if (prev && prev.role === 'user' && Array.isArray(prev.content)) {
+        prev.content.push(toolBlock)
+      } else {
+        result.push({
+          role: 'user',
+          content: [toolBlock],
+        })
+      }
     }
   }
 
diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
index ef1bdbf..0aae0c9 100644
--- a/packages/canonry/src/agent/loop.ts
+++ b/packages/canonry/src/agent/loop.ts
@@ -129,7 +129,7 @@ export async function agentChat(
     }
 
     // Tool calls
-    if (response.toolCalls) {
+    if (response.toolCalls && response.toolCalls.length > 0) {
       // Add assistant tool-call message to conversation
       messages.push({
         role: 'assistant',
diff --git a/packages/canonry/src/agent/services.ts b/packages/canonry/src/agent/services.ts
index 37c6751..579ea77 100644
--- a/packages/canonry/src/agent/services.ts
+++ b/packages/canonry/src/agent/services.ts
@@ -98,7 +98,7 @@ export class AgentServices {
       .all()
     
     if (runs.length === 0) {
-      return { project, runs: [], evidence: {} }
+      return { project, runs: [], snapshots: [] }
     }
     
     // Get all snapshots for these runs
diff --git a/packages/canonry/src/agent/store.ts b/packages/canonry/src/agent/store.ts
index 10ea2b4..4d0e7c1 100644
--- a/packages/canonry/src/agent/store.ts
+++ b/packages/canonry/src/agent/store.ts
@@ -88,7 +88,7 @@ export class AgentStore {
     // Use a subquery to get the newest N messages, then re-sort ascending
     // so the LLM sees them in chronological order. Without this, long threads
     // would return the oldest N messages and drop the user's latest prompt.
-    return this.db
+    const messages = this.db
       .select()
       .from(agentMessages)
       .where(
@@ -101,5 +101,30 @@ export class AgentStore {
       )
       .orderBy(asc(agentMessages.createdAt))
       .all() as AgentMessage[]
+
+    // Trim orphaned tool-call messages at the start of the window.
+    // The limit boundary may split an (assistant tool-call + tool result) pair,
+    // leaving the LLM with an invalid message sequence.
+    while (messages.length > 0) {
+      const first = messages[0]
+      // Orphaned tool result without its preceding assistant tool-call
+      if (first.role === 'tool') {
+        messages.shift()
+        continue
+      }
+      // Orphaned assistant tool-call whose tool result was truncated
+      if (first.role === 'assistant' && first.toolName) {
+        const hasResult = messages.some(
+          m => m.role === 'tool' && m.toolCallId === first.toolCallId,
+        )
+        if (!hasResult) {
+          messages.shift()
+          continue
+        }
+      }
+      break
+    }
+
+    return messages
   }
 }
diff --git a/packages/canonry/src/agent/tools.ts b/packages/canonry/src/agent/tools.ts
index a59f1fb..0170f63 100644
--- a/packages/canonry/src/agent/tools.ts
+++ b/packages/canonry/src/agent/tools.ts
@@ -20,6 +20,13 @@ export interface AgentTool {
   execute: (args: Record<string, unknown>) => Promise<string>
 }
 
+const MAX_TOOL_RESULT_LENGTH = 20_000
+
+function truncateResult(json: string): string {
+  if (json.length <= MAX_TOOL_RESULT_LENGTH) return json
+  return json.slice(0, MAX_TOOL_RESULT_LENGTH) + '\n... (truncated — result too large)'
+}
+
 export function buildTools(services: AgentServices, client: ApiClient, projectName: string): AgentTool[] {
   return [
     {
@@ -34,7 +41,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       execute: async () => {
         const project = await services.getProject(projectName)
         const runs = await services.listRuns(projectName)
-        return JSON.stringify({ project, latestRuns: runs.slice(-3) }, null, 2)
+        return truncateResult(JSON.stringify({ project, latestRuns: runs.slice(0, 3) }, null, 2))
       },
     },
     {
@@ -57,7 +64,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
           body.providers = (args.providers as string).split(',').map(s => s.trim())
         }
         const run = await client.triggerRun(projectName, body)
-        return JSON.stringify(run, null, 2)
+        return truncateResult(JSON.stringify(run, null, 2))
       },
     },
     {
@@ -71,7 +78,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       },
       execute: async () => {
         const history = await services.getHistory(projectName)
-        return JSON.stringify(history, null, 2)
+        return truncateResult(JSON.stringify(history, null, 2))
       },
     },
     {
@@ -85,7 +92,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       },
       execute: async () => {
         const timeline = await services.getTimeline(projectName)
-        return JSON.stringify(timeline, null, 2)
+        return truncateResult(JSON.stringify(timeline, null, 2))
       },
     },
     {
@@ -98,7 +105,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       },
       execute: async () => {
         const keywords = await services.listKeywords(projectName)
-        return JSON.stringify(keywords, null, 2)
+        return truncateResult(JSON.stringify(keywords, null, 2))
       },
     },
     {
@@ -111,7 +118,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       },
       execute: async () => {
         const competitors = await services.listCompetitors(projectName)
-        return JSON.stringify(competitors, null, 2)
+        return truncateResult(JSON.stringify(competitors, null, 2))
       },
     },
     {
@@ -129,7 +136,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       },
       execute: async (args) => {
         const run = await services.getRun(args.runId as string, projectName)
-        return JSON.stringify(run, null, 2)
+        return truncateResult(JSON.stringify(run, null, 2))
       },
     },
     {
@@ -151,7 +158,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
           const params: Record<string, string> = {}
           if (args.days) params.days = args.days as string
           const perf = await client.gscPerformance(projectName, params)
-          return JSON.stringify(perf, null, 2)
+          return truncateResult(JSON.stringify(perf, null, 2))
         } catch (err) {
           return `GSC not available: ${err instanceof Error ? err.message : String(err)}`
         }
@@ -169,7 +176,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       execute: async () => {
         try {
           const coverage = await client.gscCoverage(projectName)
-          return JSON.stringify(coverage, null, 2)
+          return truncateResult(JSON.stringify(coverage, null, 2))
         } catch (err) {
           return `GSC not available: ${err instanceof Error ? err.message : String(err)}`
         }
@@ -192,7 +199,7 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
       execute: async (args) => {
         try {
           const result = await client.gscInspect(projectName, args.url as string)
-          return JSON.stringify(result, null, 2)
+          return truncateResult(JSON.stringify(result, null, 2))
         } catch (err) {
           return `GSC inspect failed: ${err instanceof Error ? err.message : String(err)}`
         }
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index a8989bc..48841fc 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -502,12 +502,6 @@ function buildAgentHandler(
 
   if (!registeredProvider.config.apiKey) return undefined
 
-  const llmConfig: LlmConfig = {
-    provider: llmProvider,
-    apiKey: registeredProvider.config.apiKey,
-    model: agentConf.model ?? registeredProvider.config.model,
-  }
-
   const store = new AgentStore(db)
   const services = new AgentServices(db)
 
@@ -520,6 +514,18 @@ function buildAgentHandler(
   )
 
   return async (projectId: string, threadId: string, message: string) => {
+    // Resolve LLM config from registry at call time so provider key
+    // updates (via PUT /settings/providers) are picked up immediately.
+    const currentProvider = registry.get(llmProvider! as ProviderName)
+    if (!currentProvider?.config.apiKey) {
+      throw new Error('Agent provider is no longer configured. Update your provider API key.')
+    }
+    const llmConfig: LlmConfig = {
+      provider: llmProvider!,
+      apiKey: currentProvider.config.apiKey,
+      model: agentConf.model ?? currentProvider.config.model,
+    }
+
     // Resolve project details for the system prompt
     const project = db.select().from(projects).where(eq(projects.id, projectId)).get()
     if (!project) throw new Error(`Project ${projectId} not found`)

From 4a4581e1a3cc63ac6e260d1b216276f3ee7eb431 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:17:59 -0400
Subject: [PATCH 10/16] feat(agent): name the agent "Aero" with soul.md and
 memory.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename the agent to "Aero" across CLI output and error messages
- Add soul.md as the agent's identity/personality definition (checked
  into repo as the default, loaded from ~/.canonry/soul.md at runtime
  if the user wants to customize)
- Add memory.md as persistent context that Aero accumulates — loaded
  from ~/.canonry/memory.md at runtime so users can prime the agent
  with project-specific knowledge
- System prompt now composes: soul + project context + tools + memory
- Built-in soul is embedded in prompt.ts so it works after tsup bundling
- Agent remains fully optional: no background processes, only activates
  on explicit user request via CLI or API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/api-routes/src/agent.ts       |   2 +-
 packages/canonry/src/agent/memory.md   |  32 +++++++
 packages/canonry/src/agent/prompt.ts   | 113 +++++++++++++++++++------
 packages/canonry/src/agent/soul.md     |  44 ++++++++++
 packages/canonry/src/commands/agent.ts |   8 +-
 5 files changed, 170 insertions(+), 29 deletions(-)
 create mode 100644 packages/canonry/src/agent/memory.md
 create mode 100644 packages/canonry/src/agent/soul.md

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 2b6abdc..4d3b5f5 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -184,7 +184,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       return reply.status(503).send({
         error: {
           code: 'AGENT_UNAVAILABLE',
-          message: 'Agent is not configured. Add a provider with an API key.',
+          message: 'Aero is not configured. Add a provider API key (claude, openai, or gemini) to enable the agent.',
         },
       })
     }
diff --git a/packages/canonry/src/agent/memory.md b/packages/canonry/src/agent/memory.md
new file mode 100644
index 0000000..c56c012
--- /dev/null
+++ b/packages/canonry/src/agent/memory.md
@@ -0,0 +1,32 @@
+# Aero Memory
+
+This file stores persistent context that Aero accumulates across conversations.
+It can be updated by Aero or by the user to prime the agent with project-specific knowledge.
+
+## Project Knowledge
+
+<!-- Aero will populate this section with learned context about the user's projects,
+     domain, industry, and competitive landscape. Users can also pre-fill this
+     to give Aero a head start. Example entries:
+
+- Project "my-saas" targets B2B SaaS keywords in the US market
+- Main competitors: competitor1.com (strong on Gemini), competitor2.com (strong on ChatGPT)
+- Content refresh on /pricing page improved Gemini citations from 20% → 60%
+- Blog posts with structured data get cited more frequently
+-->
+
+## Patterns Observed
+
+<!-- Aero will note recurring patterns here, such as:
+- Provider X consistently cites competitor Y for keyword Z
+- Visibility tends to drop on weekends (grounding index refresh timing)
+- Keywords with question format ("how to...") have higher citation rates
+-->
+
+## User Preferences
+
+<!-- How the user likes to interact with Aero:
+- Prefers detailed tables over summaries
+- Wants competitor comparison in every report
+- Focuses on Gemini visibility primarily
+-->
diff --git a/packages/canonry/src/agent/prompt.ts b/packages/canonry/src/agent/prompt.ts
index 95bbc2c..7e2d64f 100644
--- a/packages/canonry/src/agent/prompt.ts
+++ b/packages/canonry/src/agent/prompt.ts
@@ -1,7 +1,73 @@
 /**
- * System prompt for the canonry agent.
+ * System prompt for Aero — canonry's built-in AEO analyst.
+ *
+ * Loads soul.md and memory.md from the canonry config directory (~/.canonry/)
+ * if they exist, falling back to built-in defaults. Users can customize
+ * Aero's personality and prime it with project knowledge by editing these files.
  */
 
+import fs from 'node:fs'
+import path from 'node:path'
+
+const BUILT_IN_SOUL = `# Aero — Canonry's Built-in AEO Analyst
+
+## Identity
+
+You are **Aero**, the built-in AI analyst for Canonry. You help users understand and improve how AI answer engines (ChatGPT, Gemini, Claude) cite their domain.
+
+## Personality
+
+- **Direct and data-driven.** Lead with findings, not fluff. When you have data, show it. When you don't, say so and get it.
+- **Technically sharp.** You understand search engines, grounding, citation mechanics, and AEO strategy. Speak with authority but stay approachable.
+- **Action-oriented.** Don't just report — recommend. Every observation should connect to something the user can do.
+- **Concise.** Tables and bullet points over paragraphs. Analysts want to scan, not scroll.
+
+## Communication Style
+
+- Use short, direct sentences.
+- Format data as tables when comparing across providers or keywords.
+- Use bullet points for lists of findings or recommendations.
+- Bold key metrics and takeaways.
+- Never fabricate data. If you haven't checked, say "let me look" and use the right tool.
+- If a tool fails, say what happened plainly. Don't guess.
+
+## Domain Expertise
+
+You are an expert in:
+- **Answer Engine Optimization (AEO)** — how AI models select and cite sources
+- **Grounding mechanics** — Gemini uses Google Search, ChatGPT uses Bing, Claude uses its own web search
+- **Citation visibility** — tracking whether a domain appears in AI-generated answers
+- **Competitive analysis** — identifying which competitors are cited instead
+- **Content strategy** — what makes content more likely to be cited by AI models
+
+## How You Work
+
+1. **Always check data first.** Use \`get_evidence\` for current visibility, \`get_timeline\` for trends, \`get_status\` for project overview.
+2. **Compare across providers.** Different AI models cite different sources. Always note provider-specific patterns.
+3. **Flag changes.** If visibility dropped or improved, highlight it and explain likely causes.
+4. **Connect to action.** Every finding should link to something the user can do — update content, add keywords, investigate a competitor.
+
+## What You Don't Do
+
+- You don't modify project settings or keywords unless explicitly asked.
+- You don't make up data or statistics.
+- You don't provide generic SEO advice disconnected from the user's actual data.
+- You don't run sweeps unless the user asks for fresh data.`
+
+function loadFromConfigDir(filename: string): string | null {
+  try {
+    const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+      path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+    const filePath = path.join(configDir, filename)
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf-8')
+    }
+  } catch {
+    // Config dir not accessible — use defaults
+  }
+  return null
+}
+
 export function buildSystemPrompt(project: {
   name: string
   displayName: string
@@ -9,37 +75,36 @@ export function buildSystemPrompt(project: {
   country: string
   language: string
 }): string {
-  return `You are an AEO (Answer Engine Optimization) analyst monitoring AI citation visibility for ${project.displayName} (${project.domain}).
-
-## Your Job
+  // Load soul (personality) — user override or built-in
+  const soul = loadFromConfigDir('soul.md') || BUILT_IN_SOUL
 
-You monitor how AI models (ChatGPT, Gemini, Claude) cite and reference ${project.domain} when users ask relevant questions. You use canonry — an AEO monitoring tool — to track visibility.
+  // Load memory (persistent context) — user-managed, empty by default
+  const memory = loadFromConfigDir('memory.md')
 
-## What You Know
+  const contextBlock = `## Current Project
 
 - **Project:** ${project.name}
+- **Display Name:** ${project.displayName}
 - **Domain:** ${project.domain}
 - **Market:** ${project.country}, ${project.language}
 
-## How To Work
-
-1. **Data first.** When asked about visibility, run the appropriate tool to get current data before answering.
-2. **Be direct.** State the finding, then the implication, then what to do. No preambles.
-3. **Compare.** When showing results, always note competitor presence and changes from previous runs.
-4. **Flag problems.** If visibility dropped, say so plainly and suggest why.
-
-## Key Concepts
+## Available Tools
 
-- **Citation state:** Whether the AI mentioned/cited the domain in its answer (cited, not_cited, competitor_cited)
-- **Grounding:** AI models pull from search indexes (Google for Gemini, Bing for ChatGPT) to ground their answers
-- **Visibility score:** Percentage of tracked keywords where the domain is cited across all providers
+- \`get_status\` — project overview with latest runs
+- \`get_evidence\` — per-keyword citation data across providers (primary tool for "how am I doing?")
+- \`get_timeline\` — visibility trends over time
+- \`get_run_details\` — detailed results for a specific run
+- \`list_keywords\` — tracked keywords
+- \`list_competitors\` — tracked competitors
+- \`run_sweep\` — trigger a fresh visibility sweep (only when user asks for fresh data)
+- \`get_gsc_performance\` — Google Search Console metrics (if connected)
+- \`get_gsc_coverage\` — index coverage summary (if connected)
+- \`inspect_url\` — check a URL's indexing status in GSC (if connected)`
 
-## Rules
+  const sections = [soul, contextBlock]
+  if (memory?.trim()) {
+    sections.push(memory)
+  }
 
-- Never fabricate data. If you haven't run a tool, say "let me check" and run it.
-- If a tool fails, say what went wrong. Don't guess.
-- Keep responses concise. Tables and bullet points over paragraphs.
-- When the user asks "how am I doing?" — get_evidence is your primary tool.
-- When the user asks about trends — get_timeline shows changes over time.
-- When the user asks about a specific URL — inspect_url checks Google's index.`
+  return sections.filter(Boolean).join('\n\n')
 }
diff --git a/packages/canonry/src/agent/soul.md b/packages/canonry/src/agent/soul.md
new file mode 100644
index 0000000..c9f640f
--- /dev/null
+++ b/packages/canonry/src/agent/soul.md
@@ -0,0 +1,44 @@
+# Aero — Canonry's Built-in AEO Analyst
+
+## Identity
+
+You are **Aero**, the built-in AI analyst for Canonry. You help users understand and improve how AI answer engines (ChatGPT, Gemini, Claude) cite their domain.
+
+## Personality
+
+- **Direct and data-driven.** Lead with findings, not fluff. When you have data, show it. When you don't, say so and get it.
+- **Technically sharp.** You understand search engines, grounding, citation mechanics, and AEO strategy. Speak with authority but stay approachable.
+- **Action-oriented.** Don't just report — recommend. Every observation should connect to something the user can do.
+- **Concise.** Tables and bullet points over paragraphs. Analysts want to scan, not scroll.
+
+## Communication Style
+
+- Use short, direct sentences.
+- Format data as tables when comparing across providers or keywords.
+- Use bullet points for lists of findings or recommendations.
+- Bold key metrics and takeaways.
+- Never fabricate data. If you haven't checked, say "let me look" and use the right tool.
+- If a tool fails, say what happened plainly. Don't guess.
+
+## Domain Expertise
+
+You are an expert in:
+- **Answer Engine Optimization (AEO)** — how AI models select and cite sources
+- **Grounding mechanics** — Gemini uses Google Search, ChatGPT uses Bing, Claude uses its own web search
+- **Citation visibility** — tracking whether a domain appears in AI-generated answers
+- **Competitive analysis** — identifying which competitors are cited instead
+- **Content strategy** — what makes content more likely to be cited by AI models
+
+## How You Work
+
+1. **Always check data first.** Use `get_evidence` for current visibility, `get_timeline` for trends, `get_status` for project overview.
+2. **Compare across providers.** Different AI models cite different sources. Always note provider-specific patterns.
+3. **Flag changes.** If visibility dropped or improved, highlight it and explain likely causes.
+4. **Connect to action.** Every finding should link to something the user can do — update content, add keywords, investigate a competitor.
+
+## What You Don't Do
+
+- You don't modify project settings or keywords unless explicitly asked.
+- You don't make up data or statistics.
+- You don't provide generic SEO advice disconnected from the user's actual data.
+- You don't run sweeps unless the user asks for fresh data.
diff --git a/packages/canonry/src/commands/agent.ts b/packages/canonry/src/commands/agent.ts
index 2b78db5..60b1daf 100644
--- a/packages/canonry/src/commands/agent.ts
+++ b/packages/canonry/src/commands/agent.ts
@@ -51,7 +51,7 @@ export async function agentAsk(project: string, message: string, opts?: {
   }
 
   if (opts?.format !== 'json') {
-    console.log('Thinking...\n')
+    console.log('Aero is thinking...\n')
   }
 
   const result = await client.sendAgentMessage(project, threadId, message)
@@ -73,11 +73,11 @@ export async function agentThreads(project: string, format?: string): Promise<vo
   }
 
   if (threads.length === 0) {
-    console.log('No agent threads yet. Use "canonry agent ask <project> <message>" to start.')
+    console.log('No Aero threads yet. Use "canonry agent ask <project> <message>" to start.')
     return
   }
 
-  console.log(`Agent threads for ${project}:\n`)
+  console.log(`Aero threads for ${project}:\n`)
   for (const thread of threads) {
     const title = thread.title ?? '(untitled)'
     const ago = timeSince(thread.updatedAt)
@@ -104,7 +104,7 @@ export async function agentThread(project: string, threadId: string, format?: st
 
     const label = msg.role === 'user' ? '🧑 You' :
                   msg.role === 'assistant' && msg.toolName ? `🔧 ${msg.toolName}` :
-                  '🤖 Agent'
+                  '🤖 Aero'
 
     console.log(`\n${label}:`)
     console.log(msg.content)

From 5725bd88bfe77e0b7ba6e4d388443a2c1f423700 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:23:19 -0400
Subject: [PATCH 11/16] feat(agent): add per-request LLM provider selection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Users can now choose which LLM provider Aero uses per message:

- CLI: canonry agent ask <project> "msg" --provider claude
- API: POST /agent/threads/:id/messages { message, provider: "gemini" }

The provider field is optional — omitting it uses the default
(configured in agent.provider or auto-detected: claude > openai > gemini).
If the requested provider isn't configured, returns a clear error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/api-routes/src/agent.ts       |  8 +++++---
 packages/canonry/src/cli.ts            |  7 +++++--
 packages/canonry/src/client.ts         |  6 ++++--
 packages/canonry/src/commands/agent.ts |  3 ++-
 packages/canonry/src/server.ts         | 25 ++++++++++++++-----------
 5 files changed, 30 insertions(+), 19 deletions(-)

diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 4d3b5f5..dbc37cf 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -20,6 +20,7 @@ export interface AgentRoutesOptions {
     projectId: string,
     threadId: string,
     message: string,
+    opts?: { provider?: string },
   ) => Promise<string>
 }
 
@@ -144,7 +145,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
 
   app.post<{
     Params: { project: string; id: string }
-    Body: { message: string }
+    Body: { message: string; provider?: string }
   }>(`${prefix}/threads/:id/messages`, {
     schema: {
       params: {
@@ -159,13 +160,14 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
         type: 'object',
         properties: {
           message: { type: 'string', maxLength: 8000 },
+          provider: { type: 'string', enum: ['openai', 'claude', 'gemini'] },
         },
         required: ['message'],
       },
     },
   }, async (request, reply) => {
     const { project, id: threadId } = request.params
-    const { message } = request.body
+    const { message, provider } = request.body
 
     const projectRow = resolveProject(app.db, project)
 
@@ -200,7 +202,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
 
     activeThreads.add(threadId)
     try {
-      const response = await opts.onAgentMessage(thread.projectId, threadId, message)
+      const response = await opts.onAgentMessage(thread.projectId, threadId, message, { provider })
       return reply.send({ threadId, response })
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
diff --git a/packages/canonry/src/cli.ts b/packages/canonry/src/cli.ts
index 0addac2..b9dfd40 100644
--- a/packages/canonry/src/cli.ts
+++ b/packages/canonry/src/cli.ts
@@ -91,9 +91,10 @@ Usage:
   canonry google coverage <project>  Show index coverage summary
   canonry google inspections <project>  Show URL inspection history (--url <url>)
   canonry google deindexed <project>  Show pages that lost indexing
-  canonry agent ask <project> "msg"   Ask the built-in AEO analyst a question
+  canonry agent ask <project> "msg"   Ask Aero (built-in AEO analyst) a question
+  canonry agent ask <project> "msg" --provider claude  Use a specific LLM provider
   canonry agent ask <project> "msg" --thread <id>  Continue a conversation
-  canonry agent threads <project>     List agent threads
+  canonry agent threads <project>     List Aero threads
   canonry agent thread <project> <id> Show thread with messages
   canonry settings                    Show active provider and quota settings
   canonry settings provider <name>    Update a provider config
@@ -786,6 +787,7 @@ async function main() {
               options: {
                 thread: { type: 'string' },
                 format: { type: 'string' },
+                provider: { type: 'string' },
               },
               allowPositionals: true,
             })
@@ -797,6 +799,7 @@ async function main() {
             await agentAsk(project, message, {
               threadId: agentParsed.values.thread,
               format: agentParsed.values.format ?? format,
+              provider: agentParsed.values.provider,
             })
             break
           }
diff --git a/packages/canonry/src/client.ts b/packages/canonry/src/client.ts
index 25f9824..33ba608 100644
--- a/packages/canonry/src/client.ts
+++ b/packages/canonry/src/client.ts
@@ -282,11 +282,13 @@ export class ApiClient {
     return this.request<object>('GET', `/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
   }
 
-  async sendAgentMessage(project: string, threadId: string, message: string): Promise<{ threadId: string; response: string }> {
+  async sendAgentMessage(project: string, threadId: string, message: string, provider?: string): Promise<{ threadId: string; response: string }> {
+    const body: Record<string, unknown> = { message }
+    if (provider) body.provider = provider
     return this.request<{ threadId: string; response: string }>(
       'POST',
       `/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}/messages`,
-      { message },
+      body,
     )
   }
 
diff --git a/packages/canonry/src/commands/agent.ts b/packages/canonry/src/commands/agent.ts
index 60b1daf..23f2e7a 100644
--- a/packages/canonry/src/commands/agent.ts
+++ b/packages/canonry/src/commands/agent.ts
@@ -35,6 +35,7 @@ interface AgentMessage {
 export async function agentAsk(project: string, message: string, opts?: {
   threadId?: string
   format?: string
+  provider?: string
 }): Promise<void> {
   const client = getClient()
   let threadId = opts?.threadId
@@ -54,7 +55,7 @@ export async function agentAsk(project: string, message: string, opts?: {
     console.log('Aero is thinking...\n')
   }
 
-  const result = await client.sendAgentMessage(project, threadId, message)
+  const result = await client.sendAgentMessage(project, threadId, message, opts?.provider)
 
   if (opts?.format === 'json') {
     console.log(JSON.stringify({ threadId, response: result.response }, null, 2))
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 48841fc..069ce86 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -477,27 +477,27 @@ function buildAgentHandler(
   opts: { config: CanonryConfig },
   registry: ProviderRegistry,
   db: DatabaseClient,
-): ((projectId: string, threadId: string, message: string) => Promise<string>) | undefined {
+): ((projectId: string, threadId: string, message: string, opts?: { provider?: string }) => Promise<string>) | undefined {
   // Determine which provider to use for the agent
   const agentConf = opts.config.agent ?? {}
   if (agentConf.enabled === false) return undefined
 
-  // Pick provider: explicit config > first available (claude > openai > gemini)
+  // Pick default provider: explicit config > first available (claude > openai > gemini)
   const providerPriority: Array<'claude' | 'openai' | 'gemini'> = ['claude', 'openai', 'gemini']
-  let llmProvider: 'claude' | 'openai' | 'gemini' | undefined = agentConf.provider
+  let defaultProvider: 'claude' | 'openai' | 'gemini' | undefined = agentConf.provider
 
-  if (!llmProvider) {
+  if (!defaultProvider) {
     for (const p of providerPriority) {
       if (registry.get(p as ProviderName)) {
-        llmProvider = p
+        defaultProvider = p
         break
       }
     }
   }
 
-  if (!llmProvider) return undefined
+  if (!defaultProvider) return undefined
 
-  const registeredProvider = registry.get(llmProvider as ProviderName)
+  const registeredProvider = registry.get(defaultProvider as ProviderName)
   if (!registeredProvider) return undefined
 
   if (!registeredProvider.config.apiKey) return undefined
@@ -513,15 +513,18 @@ function buildAgentHandler(
     opts.config.apiKey ?? '',
   )
 
-  return async (projectId: string, threadId: string, message: string) => {
+  return async (projectId: string, threadId: string, message: string, callOpts?: { provider?: string }) => {
+    // Per-request provider override or fall back to default
+    const llmProvider = (callOpts?.provider as 'claude' | 'openai' | 'gemini' | undefined) ?? defaultProvider!
+
     // Resolve LLM config from registry at call time so provider key
     // updates (via PUT /settings/providers) are picked up immediately.
-    const currentProvider = registry.get(llmProvider! as ProviderName)
+    const currentProvider = registry.get(llmProvider as ProviderName)
     if (!currentProvider?.config.apiKey) {
-      throw new Error('Agent provider is no longer configured. Update your provider API key.')
+      throw new Error(`Provider "${llmProvider}" is not configured. Add an API key for it first.`)
     }
     const llmConfig: LlmConfig = {
-      provider: llmProvider!,
+      provider: llmProvider,
       apiKey: currentProvider.config.apiKey,
       model: agentConf.model ?? currentProvider.config.model,
     }

From dc4ae4d86215b175aa91a51d9350cba723518689 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:58:13 -0400
Subject: [PATCH 12/16] feat(web): add Aero chat UI with project and provider
 selection

Adds the /aero route with a full chat interface for interacting with the
built-in Aero agent. Includes project selector, provider/model selector,
thread management (create/delete), message display with optimistic
rendering, and a thinking animation during API calls.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/web/src/App.tsx    | 296 +++++++++++++++++++++++++++++++++++++++-
 apps/web/src/api.ts     |  53 +++++++
 apps/web/src/styles.css | 119 ++++++++++++++++
 3 files changed, 463 insertions(+), 5 deletions(-)

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 56cf6d2..977bccf 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -5,6 +5,7 @@ import type { MouseEvent, ReactNode } from 'react'
 import * as Dialog from '@radix-ui/react-dialog'
 import {
   Activity,
+  Bot,
   ChevronRight,
   Download,
   Globe,
@@ -13,6 +14,7 @@ import {
   Play,
   Plus,
   Rocket,
+  Send,
   Settings,
   Trash2,
   Users,
@@ -85,6 +87,13 @@ import {
   type ApiGscInspection,
   type ApiGscDeindexedRow,
   type GroundingSource,
+  createAgentThread,
+  fetchAgentThreads,
+  fetchAgentThread,
+  sendAgentMessage,
+  deleteAgentThread,
+  type ApiAgentThread,
+  type ApiAgentMessage,
 } from './api.js'
 import { buildDashboard } from './build-dashboard.js'
 import type { ProjectData } from './build-dashboard.js'
@@ -131,6 +140,7 @@ type AppRoute =
   | { kind: 'runs'; path: '/runs' }
   | { kind: 'settings'; path: '/settings' }
   | { kind: 'setup'; path: '/setup' }
+  | { kind: 'aero'; path: '/aero' }
   | { kind: 'not-found'; path: string }
 
 type DrawerState =
@@ -246,6 +256,10 @@ function resolveRoute(pathname: string, dashboard: DashboardVm): AppRoute {
     return { kind: 'setup', path: '/setup' }
   }
 
+  if (normalized === '/aero') {
+    return { kind: 'aero', path: '/aero' }
+  }
+
   if (normalized === '/projects') {
     return { kind: 'projects', path: '/projects' }
   }
@@ -468,7 +482,7 @@ function createNavigationHandler(navigate: (to: string) => void, to: string) {
   }
 }
 
-function isNavActive(route: AppRoute, section: 'overview' | 'projects' | 'project' | 'runs' | 'settings'): boolean {
+function isNavActive(route: AppRoute, section: 'overview' | 'projects' | 'project' | 'runs' | 'aero' | 'settings'): boolean {
   if (section === 'projects') {
     return route.kind === 'projects' || route.kind === 'project'
   }
@@ -5309,6 +5323,272 @@ function SetupPage({
   )
 }
 
+// ── Aero (Agent Chat) ─────────────────────────────────────────
+
+function AeroPage({ projects, providers }: {
+  projects: Array<{ name: string; displayName?: string }>
+  providers: Array<{ name: string; state: string }>
+}) {
+  const [selectedProject, setSelectedProject] = useState(projects[0]?.name ?? '')
+  const [selectedProvider, setSelectedProvider] = useState('')
+  const [threads, setThreads] = useState<ApiAgentThread[]>([])
+  const [activeThreadId, setActiveThreadId] = useState<string | null>(null)
+  const [messages, setMessages] = useState<ApiAgentMessage[]>([])
+  const [input, setInput] = useState('')
+  const [sending, setSending] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const messagesEndRef = useRef<HTMLDivElement>(null)
+
+  const configuredProviders = providers.filter(p => p.state === 'ready')
+
+  // Load threads when project changes
+  useEffect(() => {
+    if (!selectedProject) return
+    fetchAgentThreads(selectedProject).then(setThreads).catch(() => setThreads([]))
+  }, [selectedProject])
+
+  // Load messages when thread changes
+  useEffect(() => {
+    if (!selectedProject || !activeThreadId) {
+      setMessages([])
+      return
+    }
+    fetchAgentThread(selectedProject, activeThreadId)
+      .then(data => setMessages(data.messages))
+      .catch(() => setMessages([]))
+  }, [selectedProject, activeThreadId])
+
+  // Scroll to bottom on new messages
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
+  }, [messages])
+
+  async function handleNewThread() {
+    if (!selectedProject) return
+    const thread = await createAgentThread(selectedProject, { title: 'New conversation' })
+    setThreads(prev => [thread, ...prev])
+    setActiveThreadId(thread.id)
+    setMessages([])
+    setError(null)
+  }
+
+  async function handleDeleteThread(threadId: string) {
+    if (!selectedProject) return
+    await deleteAgentThread(selectedProject, threadId)
+    setThreads(prev => prev.filter(t => t.id !== threadId))
+    if (activeThreadId === threadId) {
+      setActiveThreadId(null)
+      setMessages([])
+    }
+  }
+
+  async function handleSend() {
+    if (!input.trim() || !selectedProject || !activeThreadId || sending) return
+    const msg = input.trim()
+    setInput('')
+    setError(null)
+    setSending(true)
+
+    // Optimistically add user message
+    const optimisticUser: ApiAgentMessage = {
+      id: `temp-${Date.now()}`,
+      threadId: activeThreadId,
+      role: 'user',
+      content: msg,
+      toolName: null,
+      toolArgs: null,
+      toolCallId: null,
+      createdAt: new Date().toISOString(),
+    }
+    setMessages(prev => [...prev, optimisticUser])
+
+    try {
+      const result = await sendAgentMessage(
+        selectedProject,
+        activeThreadId,
+        msg,
+        selectedProvider || undefined,
+      )
+
+      // Add assistant response
+      const assistantMsg: ApiAgentMessage = {
+        id: `resp-${Date.now()}`,
+        threadId: activeThreadId,
+        role: 'assistant',
+        content: result.response,
+        toolName: null,
+        toolArgs: null,
+        toolCallId: null,
+        createdAt: new Date().toISOString(),
+      }
+      setMessages(prev => [...prev, assistantMsg])
+
+      // Refresh threads to update titles
+      fetchAgentThreads(selectedProject).then(setThreads).catch(() => {})
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setSending(false)
+    }
+  }
+
+  function handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      handleSend()
+    }
+  }
+
+  const visibleMessages = messages.filter(m => m.role !== 'tool')
+
+  return (
+    <div className="page-container">
+      <div className="page-header">
+        <div className="page-header-left">
+          <h1 className="page-title">Aero</h1>
+          <p className="page-subtitle">AI-powered AEO analyst</p>
+        </div>
+        <div className="page-header-right flex items-center gap-3">
+          <select
+            value={selectedProject}
+            onChange={e => { setSelectedProject(e.target.value); setActiveThreadId(null) }}
+            className="aero-select"
+          >
+            {projects.map(p => (
+              <option key={p.name} value={p.name}>{p.displayName || p.name}</option>
+            ))}
+          </select>
+          <select
+            value={selectedProvider}
+            onChange={e => setSelectedProvider(e.target.value)}
+            className="aero-select"
+          >
+            <option value="">Auto (default)</option>
+            {configuredProviders.map(p => (
+              <option key={p.name} value={p.name}>{p.name}</option>
+            ))}
+          </select>
+          <Button onClick={handleNewThread} variant="secondary" className="gap-1.5">
+            <Plus className="h-3.5 w-3.5" />
+            New chat
+          </Button>
+        </div>
+      </div>
+
+      <div className="aero-layout">
+        {/* Thread list sidebar */}
+        <div className="aero-threads">
+          <p className="eyebrow mb-2">Threads</p>
+          {threads.length === 0 ? (
+            <p className="text-[13px] text-zinc-500">No threads yet. Start a new chat.</p>
+          ) : (
+            <div className="flex flex-col gap-0.5">
+              {threads.map(t => (
+                <div
+                  key={t.id}
+                  className={`aero-thread-item ${activeThreadId === t.id ? 'active' : ''}`}
+                >
+                  <button
+                    className="aero-thread-btn"
+                    onClick={() => setActiveThreadId(t.id)}
+                  >
+                    <span className="truncate">{t.title ?? 'Untitled'}</span>
+                    <span className="text-[10px] text-zinc-600 shrink-0">
+                      {new Date(t.updatedAt).toLocaleDateString()}
+                    </span>
+                  </button>
+                  <button
+                    className="aero-thread-delete"
+                    onClick={() => handleDeleteThread(t.id)}
+                    aria-label="Delete thread"
+                  >
+                    <Trash2 className="h-3 w-3" />
+                  </button>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+
+        {/* Chat area */}
+        <div className="aero-chat">
+          {!activeThreadId ? (
+            <div className="aero-empty">
+              <Bot className="h-10 w-10 text-zinc-700" />
+              <h2 className="text-base font-medium text-zinc-300 mt-3">Ask Aero anything</h2>
+              <p className="text-[13px] text-zinc-500 mt-1 max-w-md text-center">
+                Select a project and start a new chat to analyze your AI citation visibility,
+                compare providers, spot trends, and get actionable recommendations.
+              </p>
+              <Button onClick={handleNewThread} variant="secondary" className="mt-4 gap-1.5">
+                <Plus className="h-3.5 w-3.5" />
+                Start a conversation
+              </Button>
+            </div>
+          ) : (
+            <>
+              {/* Messages */}
+              <div className="aero-messages">
+                {visibleMessages.length === 0 && !sending && (
+                  <div className="aero-empty">
+                    <Bot className="h-8 w-8 text-zinc-700" />
+                    <p className="text-[13px] text-zinc-500 mt-2">Send a message to get started.</p>
+                  </div>
+                )}
+                {visibleMessages.map(msg => (
+                  <div key={msg.id} className={`aero-msg ${msg.role}`}>
+                    <div className="aero-msg-label">
+                      {msg.role === 'user' ? 'You' : 'Aero'}
+                    </div>
+                    <div className="aero-msg-content">
+                      {msg.content}
+                    </div>
+                  </div>
+                ))}
+                {sending && (
+                  <div className="aero-msg assistant">
+                    <div className="aero-msg-label">Aero</div>
+                    <div className="aero-msg-content text-zinc-500">
+                      <span className="aero-thinking">Thinking</span>
+                    </div>
+                  </div>
+                )}
+                {error && (
+                  <div className="aero-error">
+                    {error}
+                  </div>
+                )}
+                <div ref={messagesEndRef} />
+              </div>
+
+              {/* Input */}
+              <div className="aero-input-area">
+                <textarea
+                  className="aero-input"
+                  value={input}
+                  onChange={e => setInput(e.target.value)}
+                  onKeyDown={handleKeyDown}
+                  placeholder="Ask about your visibility, trends, competitors..."
+                  rows={1}
+                  disabled={sending}
+                />
+                <button
+                  className="aero-send"
+                  onClick={handleSend}
+                  disabled={!input.trim() || sending}
+                  aria-label="Send message"
+                >
+                  <Send className="h-4 w-4" />
+                </button>
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
 function NotFoundPage({ onNavigate }: { onNavigate: (to: string) => void }) {
   return (
     <div className="page-container">
@@ -6261,6 +6541,7 @@ export function App({
     { label: 'Overview', href: '/', icon: LayoutDashboard, active: isNavActive(route, 'overview') },
     { label: 'Projects', href: '/projects', icon: Globe, active: isNavActive(route, 'projects') },
     { label: 'Runs', href: '/runs', icon: Play, active: isNavActive(route, 'runs') },
+    { label: 'Aero', href: '/aero', icon: Bot, active: isNavActive(route, 'aero') },
     { label: 'Settings', href: '/settings', icon: Settings, active: isNavActive(route, 'settings') },
   ]
 
@@ -6273,10 +6554,12 @@ export function App({
           ? activeProject.project.name
           : route.kind === 'runs'
             ? 'Runs'
-            : route.kind === 'settings'
-              ? 'Settings'
-              : route.kind === 'setup'
-                ? 'Setup'
+            : route.kind === 'aero'
+              ? 'Aero'
+              : route.kind === 'settings'
+                ? 'Settings'
+                : route.kind === 'setup'
+                  ? 'Setup'
                 : 'Not found'
 
   return (
@@ -6464,6 +6747,9 @@ export function App({
                 <ProjectPage model={activeProject} tab={route.tab} onOpenEvidence={openEvidence} onOpenRun={openRun} onTriggerRun={handleTriggerRun} onDeleteProject={handleDeleteProject} onAddKeywords={handleAddKeywords} onDeleteKeywords={handleDeleteKeywords} onAddCompetitors={handleAddCompetitors} onUpdateOwnedDomains={handleUpdateOwnedDomains} onUpdateProject={handleUpdateProject} onNavigate={navigate} />
               ) : null}
               {route.kind === 'runs' ? <RunsPage runs={safeDashboard.runs} onOpenRun={openRun} onTriggerAll={handleTriggerAllRuns} /> : null}
+              {route.kind === 'aero' ? (
+                <AeroPage projects={safeDashboard.projects.map(p => p.project)} providers={safeDashboard.settings.providerStatuses} />
+              ) : null}
               {route.kind === 'settings' ? (
                 <SettingsPage settings={safeDashboard.settings} healthSnapshot={healthSnapshot} onSettingsChanged={refreshData} />
               ) : null}
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
index 0f8dc91..eb8a477 100644
--- a/apps/web/src/api.ts
+++ b/apps/web/src/api.ts
@@ -654,3 +654,56 @@ export function triggerDiscoverSitemaps(project: string): Promise<{ sitemaps: Ap
     body: '{}',
   })
 }
+
+// ── Agent (Aero) ─────────────────────────────────────────────
+
+export interface ApiAgentThread {
+  id: string
+  projectId: string
+  title: string | null
+  channel: string
+  createdAt: string
+  updatedAt: string
+}
+
+export interface ApiAgentMessage {
+  id: string
+  threadId: string
+  role: 'user' | 'assistant' | 'tool'
+  content: string
+  toolName: string | null
+  toolArgs: string | null
+  toolCallId: string | null
+  createdAt: string
+}
+
+export function createAgentThread(project: string, opts?: { title?: string }): Promise<ApiAgentThread> {
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads`, {
+    method: 'POST',
+    body: JSON.stringify({ title: opts?.title, channel: 'chat' }),
+  })
+}
+
+export function fetchAgentThreads(project: string): Promise<ApiAgentThread[]> {
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads`)
+}
+
+export function fetchAgentThread(project: string, threadId: string): Promise<ApiAgentThread & { messages: ApiAgentMessage[] }> {
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
+}
+
+export function sendAgentMessage(project: string, threadId: string, message: string, provider?: string): Promise<{ threadId: string; response: string }> {
+  const body: Record<string, unknown> = { message }
+  if (provider) body.provider = provider
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}/messages`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+}
+
+export function deleteAgentThread(project: string, threadId: string): Promise<void> {
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`, {
+    method: 'DELETE',
+    body: '{}',
+  })
+}
diff --git a/apps/web/src/styles.css b/apps/web/src/styles.css
index 2485828..75ec179 100644
--- a/apps/web/src/styles.css
+++ b/apps/web/src/styles.css
@@ -1393,4 +1393,123 @@
     @apply absolute -m-px h-px w-px overflow-hidden border-0 p-0;
     clip: rect(0 0 0 0);
   }
+
+  /* ── Aero (Agent Chat) ── */
+
+  .aero-select {
+    @apply bg-zinc-900/50 border border-zinc-800/60 rounded-lg px-3 py-1.5
+           text-[13px] text-zinc-300 outline-none
+           focus:border-zinc-600 transition-colors;
+    appearance: auto;
+  }
+
+  .aero-layout {
+    @apply flex gap-4 mt-4;
+    height: calc(100vh - 200px);
+    min-height: 400px;
+  }
+
+  .aero-threads {
+    @apply w-56 shrink-0 bg-zinc-900/30 border border-zinc-800/60 rounded-xl p-3 overflow-y-auto;
+  }
+
+  .aero-thread-item {
+    @apply flex items-center gap-1 rounded-lg transition-colors;
+  }
+
+  .aero-thread-item.active {
+    @apply bg-zinc-800/60;
+  }
+
+  .aero-thread-item:hover {
+    @apply bg-zinc-800/40;
+  }
+
+  .aero-thread-btn {
+    @apply flex-1 flex items-center justify-between gap-2 text-left
+           px-2.5 py-2 text-[13px] text-zinc-300 truncate rounded-lg
+           min-w-0;
+  }
+
+  .aero-thread-delete {
+    @apply p-1.5 text-zinc-600 hover:text-rose-400 transition-colors shrink-0 rounded;
+  }
+
+  .aero-chat {
+    @apply flex-1 flex flex-col bg-zinc-900/30 border border-zinc-800/60 rounded-xl overflow-hidden;
+  }
+
+  .aero-empty {
+    @apply flex-1 flex flex-col items-center justify-center p-6;
+  }
+
+  .aero-messages {
+    @apply flex-1 overflow-y-auto p-4 space-y-4;
+  }
+
+  .aero-msg {
+    @apply max-w-[85%];
+  }
+
+  .aero-msg.user {
+    @apply ml-auto;
+  }
+
+  .aero-msg.assistant {
+    @apply mr-auto;
+  }
+
+  .aero-msg-label {
+    @apply text-[10px] uppercase tracking-[0.18em] text-zinc-500 mb-1;
+  }
+
+  .aero-msg.user .aero-msg-label {
+    @apply text-right;
+  }
+
+  .aero-msg-content {
+    @apply text-[13px] leading-relaxed rounded-xl px-4 py-3 whitespace-pre-wrap;
+  }
+
+  .aero-msg.user .aero-msg-content {
+    @apply bg-zinc-800/60 text-zinc-200;
+  }
+
+  .aero-msg.assistant .aero-msg-content {
+    @apply bg-zinc-900/60 text-zinc-300 border border-zinc-800/40;
+  }
+
+  .aero-error {
+    @apply text-[13px] text-rose-400 bg-rose-950/30 border border-rose-900/40
+           rounded-lg px-4 py-2.5 mr-auto max-w-[85%];
+  }
+
+  .aero-input-area {
+    @apply flex items-end gap-2 border-t border-zinc-800/60 p-3;
+  }
+
+  .aero-input {
+    @apply flex-1 bg-zinc-900/50 border border-zinc-800/60 rounded-xl px-4 py-2.5
+           text-[13px] text-zinc-200 placeholder-zinc-600 outline-none
+           resize-none min-h-[40px] max-h-[120px]
+           focus:border-zinc-600 transition-colors;
+  }
+
+  .aero-send {
+    @apply p-2.5 rounded-xl bg-zinc-800/60 text-zinc-400
+           hover:bg-zinc-700/60 hover:text-zinc-200
+           disabled:opacity-30 disabled:cursor-not-allowed
+           transition-colors shrink-0;
+  }
+
+  @keyframes aero-dots {
+    0%, 20% { content: '.'; }
+    40% { content: '..'; }
+    60%, 100% { content: '...'; }
+  }
+
+  .aero-thinking::after {
+    content: '...';
+    animation: aero-dots 1.2s steps(1) infinite;
+  }
 }

From 8a1c4b92e88f24b8519fbca1790fa596390d333e Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 15:12:33 -0400
Subject: [PATCH 13/16] feat(agent): add memory system, system tools, markdown
 rendering, and background processing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Major Aero agent improvements:

- Memory: get_memory/save_memory tools with pre-seeded domain knowledge
  (citation states, provider grounding mechanics, regression detection)
- Startup sequence: auto-gathers context on new threads, responds naturally
- System tools (opt-in): run_command, read_file, write_file, list_files,
  http_request — gated behind agent.systemTools config flag
- Write tools: add/remove keywords, add/remove competitors, update_project
- Background processing: send-message returns 202, UI polls for completion,
  agent work survives page navigation
- Chat UI: markdown rendering, auto-expanding textarea, inline thread rename,
  relative dates, cleaner thread list, no page scroll
- Claude API fix: bidirectional tool_use/tool_result validation prevents
  orphaned blocks from corrupting conversation history
- CLI polling: agent ask now polls thread status instead of blocking
- Remove unused footer, PATCH endpoint for thread rename, auto-titling

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 apps/web/src/App.tsx                   | 316 +++++++++++++++-----
 apps/web/src/api.ts                    |  11 +-
 apps/web/src/styles.css                |  62 ++--
 packages/api-routes/src/agent.ts       |  81 +++++-
 packages/canonry/src/agent/llm.ts      |  94 +++++-
 packages/canonry/src/agent/loop.ts     |  96 ++++--
 packages/canonry/src/agent/memory.md   |  82 ++++--
 packages/canonry/src/agent/prompt.ts   | 129 +++++++--
 packages/canonry/src/agent/soul.md     |  42 ++-
 packages/canonry/src/agent/tools.ts    | 386 ++++++++++++++++++++++++-
 packages/canonry/src/commands/agent.ts |  33 ++-
 packages/canonry/src/config.ts         |   2 +
 packages/canonry/src/server.ts         |   7 +-
 13 files changed, 1151 insertions(+), 190 deletions(-)

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 977bccf..3f4bd87 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -6,7 +6,10 @@ import * as Dialog from '@radix-ui/react-dialog'
 import {
   Activity,
   Bot,
+  Check,
   ChevronRight,
+  MessageSquare,
+  Pencil,
   Download,
   Globe,
   LayoutDashboard,
@@ -91,6 +94,7 @@ import {
   fetchAgentThreads,
   fetchAgentThread,
   sendAgentMessage,
+  renameAgentThread,
   deleteAgentThread,
   type ApiAgentThread,
   type ApiAgentMessage,
@@ -5325,6 +5329,114 @@ function SetupPage({
 
 // ── Aero (Agent Chat) ─────────────────────────────────────────
 
+function formatRelativeDate(dateStr: string): string {
+  const seconds = Math.floor((Date.now() - new Date(dateStr).getTime()) / 1000)
+  if (seconds < 60) return 'just now'
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`
+  if (seconds < 604800) return `${Math.floor(seconds / 86400)}d ago`
+  return new Date(dateStr).toLocaleDateString()
+}
+
+/** Lightweight markdown → React renderer for chat messages */
+function renderMarkdown(text: string): React.ReactNode {
+  const lines = text.split('\n')
+  const elements: React.ReactNode[] = []
+  let i = 0
+
+  function inlineFormat(s: string): React.ReactNode {
+    const parts: React.ReactNode[] = []
+    // Process inline: code, bold, italic, links
+    const rx = /(`[^`]+`|\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)]+\))/g
+    let last = 0
+    let m: RegExpExecArray | null
+    let ki = 0
+    while ((m = rx.exec(s)) !== null) {
+      if (m.index > last) parts.push(s.slice(last, m.index))
+      const token = m[0]
+      if (token.startsWith('`')) {
+        parts.push(<code key={ki++} className="aero-inline-code">{token.slice(1, -1)}</code>)
+      } else if (token.startsWith('**')) {
+        parts.push(<strong key={ki++} className="text-zinc-100 font-semibold">{token.slice(2, -2)}</strong>)
+      } else if (token.startsWith('*')) {
+        parts.push(<em key={ki++}>{token.slice(1, -1)}</em>)
+      } else if (token.startsWith('[')) {
+        const lm = token.match(/\[([^\]]+)\]\(([^)]+)\)/)
+        if (lm) parts.push(<a key={ki++} href={lm[2]} target="_blank" rel="noreferrer" className="text-emerald-400 underline underline-offset-2">{lm[1]}</a>)
+      }
+      last = m.index + token.length
+    }
+    if (last < s.length) parts.push(s.slice(last))
+    return parts.length === 1 ? parts[0] : parts
+  }
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    // Code block
+    if (line.trimStart().startsWith('```')) {
+      const codeLines: string[] = []
+      i++
+      while (i < lines.length && !lines[i].trimStart().startsWith('```')) {
+        codeLines.push(lines[i])
+        i++
+      }
+      i++ // skip closing ```
+      elements.push(<pre key={elements.length} className="aero-code-block"><code>{codeLines.join('\n')}</code></pre>)
+      continue
+    }
+
+    // Blank line
+    if (line.trim() === '') { i++; continue }
+
+    // Horizontal rule
+    if (/^---+$/.test(line.trim())) {
+      elements.push(<hr key={elements.length} className="border-zinc-700/50 my-3" />)
+      i++
+      continue
+    }
+
+    // Headings
+    const hm = line.match(/^(#{1,4})\s+(.+)/)
+    if (hm) {
+      const level = hm[1].length
+      const cls = level === 1 ? 'text-[15px] font-bold text-zinc-100 mt-4 mb-2'
+        : level === 2 ? 'text-[14px] font-bold text-zinc-100 mt-3 mb-1.5'
+        : 'text-[13px] font-semibold text-zinc-200 mt-2 mb-1'
+      elements.push(<div key={elements.length} className={cls}>{inlineFormat(hm[2])}</div>)
+      i++
+      continue
+    }
+
+    // List items (- or *)
+    if (/^\s*[-*]\s/.test(line)) {
+      const items: React.ReactNode[] = []
+      while (i < lines.length && /^\s*[-*]\s/.test(lines[i])) {
+        items.push(<li key={items.length}>{inlineFormat(lines[i].replace(/^\s*[-*]\s+/, ''))}</li>)
+        i++
+      }
+      elements.push(<ul key={elements.length} className="aero-md-list">{items}</ul>)
+      continue
+    }
+
+    // Numbered list
+    if (/^\s*\d+[.)]\s/.test(line)) {
+      const items: React.ReactNode[] = []
+      while (i < lines.length && /^\s*\d+[.)]\s/.test(lines[i])) {
+        items.push(<li key={items.length}>{inlineFormat(lines[i].replace(/^\s*\d+[.)]\s+/, ''))}</li>)
+        i++
+      }
+      elements.push(<ol key={elements.length} className="aero-md-list aero-md-ol">{items}</ol>)
+      continue
+    }
+
+    // Paragraph
+    elements.push(<p key={elements.length} className="mb-2 last:mb-0">{inlineFormat(line)}</p>)
+    i++
+  }
+  return <>{elements}</>
+}
+
 function AeroPage({ projects, providers }: {
   projects: Array<{ name: string; displayName?: string }>
   providers: Array<{ name: string; state: string }>
@@ -5335,27 +5447,56 @@ function AeroPage({ projects, providers }: {
   const [activeThreadId, setActiveThreadId] = useState<string | null>(null)
   const [messages, setMessages] = useState<ApiAgentMessage[]>([])
   const [input, setInput] = useState('')
-  const [sending, setSending] = useState(false)
+  const [processing, setProcessing] = useState(false)
   const [error, setError] = useState<string | null>(null)
+  const [editingThreadId, setEditingThreadId] = useState<string | null>(null)
+  const [editTitle, setEditTitle] = useState('')
   const messagesEndRef = useRef<HTMLDivElement>(null)
+  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null)
 
   const configuredProviders = providers.filter(p => p.state === 'ready')
 
+  // Stop polling on unmount
+  useEffect(() => {
+    return () => { if (pollRef.current) clearInterval(pollRef.current) }
+  }, [])
+
   // Load threads when project changes
   useEffect(() => {
     if (!selectedProject) return
     fetchAgentThreads(selectedProject).then(setThreads).catch(() => setThreads([]))
   }, [selectedProject])
 
-  // Load messages when thread changes
+  // Load messages when thread changes; start polling if thread is processing
   useEffect(() => {
+    if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null }
     if (!selectedProject || !activeThreadId) {
       setMessages([])
+      setProcessing(false)
       return
     }
-    fetchAgentThread(selectedProject, activeThreadId)
-      .then(data => setMessages(data.messages))
-      .catch(() => setMessages([]))
+
+    function loadThread() {
+      fetchAgentThread(selectedProject, activeThreadId!)
+        .then(data => {
+          setMessages(data.messages.filter(m => m.role !== 'tool' && !m.toolName))
+          if (data.status === 'processing') {
+            setProcessing(true)
+            // Start polling if not already
+            if (!pollRef.current) {
+              pollRef.current = setInterval(loadThread, 1500)
+            }
+          } else {
+            setProcessing(false)
+            if (data.error) setError(data.error)
+            if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null }
+          }
+        })
+        .catch(() => setMessages([]))
+    }
+    loadThread()
+
+    return () => { if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null } }
   }, [selectedProject, activeThreadId])
 
   // Scroll to bottom on new messages
@@ -5363,9 +5504,18 @@ function AeroPage({ projects, providers }: {
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
   }, [messages])
 
+  async function handleRenameThread(threadId: string) {
+    if (!selectedProject || !editTitle.trim()) return
+    try {
+      const updated = await renameAgentThread(selectedProject, threadId, editTitle.trim())
+      setThreads(prev => prev.map(t => t.id === threadId ? { ...t, title: updated.title } : t))
+    } catch { /* ignore */ }
+    setEditingThreadId(null)
+  }
+
   async function handleNewThread() {
     if (!selectedProject) return
-    const thread = await createAgentThread(selectedProject, { title: 'New conversation' })
+    const thread = await createAgentThread(selectedProject)
     setThreads(prev => [thread, ...prev])
     setActiveThreadId(thread.id)
     setMessages([])
@@ -5383,11 +5533,10 @@ function AeroPage({ projects, providers }: {
   }
 
   async function handleSend() {
-    if (!input.trim() || !selectedProject || !activeThreadId || sending) return
+    if (!input.trim() || !selectedProject || !activeThreadId || processing) return
     const msg = input.trim()
     setInput('')
     setError(null)
-    setSending(true)
 
     // Optimistically add user message
     const optimisticUser: ApiAgentMessage = {
@@ -5401,34 +5550,36 @@ function AeroPage({ projects, providers }: {
       createdAt: new Date().toISOString(),
     }
     setMessages(prev => [...prev, optimisticUser])
+    setProcessing(true)
 
     try {
-      const result = await sendAgentMessage(
+      await sendAgentMessage(
         selectedProject,
         activeThreadId,
         msg,
         selectedProvider || undefined,
       )
 
-      // Add assistant response
-      const assistantMsg: ApiAgentMessage = {
-        id: `resp-${Date.now()}`,
-        threadId: activeThreadId,
-        role: 'assistant',
-        content: result.response,
-        toolName: null,
-        toolArgs: null,
-        toolCallId: null,
-        createdAt: new Date().toISOString(),
-      }
-      setMessages(prev => [...prev, assistantMsg])
-
-      // Refresh threads to update titles
-      fetchAgentThreads(selectedProject).then(setThreads).catch(() => {})
+      // Start polling for the response
+      if (pollRef.current) clearInterval(pollRef.current)
+      const tid = activeThreadId
+      pollRef.current = setInterval(() => {
+        fetchAgentThread(selectedProject, tid)
+          .then(data => {
+            setMessages(data.messages.filter(m => m.role !== 'tool' && !m.toolName))
+            if (data.status !== 'processing') {
+              setProcessing(false)
+              if (data.error) setError(data.error)
+              if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null }
+              // Refresh threads to update titles
+              fetchAgentThreads(selectedProject).then(setThreads).catch(() => {})
+            }
+          })
+          .catch(() => {})
+      }, 1500)
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err))
-    } finally {
-      setSending(false)
+      setProcessing(false)
     }
   }
 
@@ -5439,10 +5590,10 @@ function AeroPage({ projects, providers }: {
     }
   }
 
-  const visibleMessages = messages.filter(m => m.role !== 'tool')
+  const visibleMessages = messages.filter(m => m.role !== 'tool' && !m.toolName)
 
   return (
-    <div className="page-container">
+    <div className="page-container aero-page">
       <div className="page-header">
         <div className="page-header-left">
           <h1 className="page-title">Aero</h1>
@@ -5468,42 +5619,78 @@ function AeroPage({ projects, providers }: {
               <option key={p.name} value={p.name}>{p.name}</option>
             ))}
           </select>
-          <Button onClick={handleNewThread} variant="secondary" className="gap-1.5">
-            <Plus className="h-3.5 w-3.5" />
-            New chat
-          </Button>
         </div>
       </div>
 
       <div className="aero-layout">
         {/* Thread list sidebar */}
         <div className="aero-threads">
-          <p className="eyebrow mb-2">Threads</p>
+          <div className="flex items-center justify-between mb-3">
+            <p className="eyebrow">Threads</p>
+            <button
+              onClick={handleNewThread}
+              className="p-1 rounded-md text-zinc-500 hover:text-zinc-300 hover:bg-zinc-800/60 transition-colors"
+              aria-label="New thread"
+            >
+              <Plus className="h-3.5 w-3.5" />
+            </button>
+          </div>
           {threads.length === 0 ? (
-            <p className="text-[13px] text-zinc-500">No threads yet. Start a new chat.</p>
+            <p className="text-[12px] text-zinc-600 px-2">No threads yet.</p>
           ) : (
             <div className="flex flex-col gap-0.5">
               {threads.map(t => (
                 <div
                   key={t.id}
-                  className={`aero-thread-item ${activeThreadId === t.id ? 'active' : ''}`}
+                  className={`aero-thread-item group ${activeThreadId === t.id ? 'active' : ''}`}
+                  onClick={() => { if (editingThreadId !== t.id) setActiveThreadId(t.id) }}
                 >
-                  <button
-                    className="aero-thread-btn"
-                    onClick={() => setActiveThreadId(t.id)}
-                  >
-                    <span className="truncate">{t.title ?? 'Untitled'}</span>
-                    <span className="text-[10px] text-zinc-600 shrink-0">
-                      {new Date(t.updatedAt).toLocaleDateString()}
+                  <MessageSquare className="h-3.5 w-3.5 text-zinc-600 shrink-0 mt-0.5" />
+                  <div className="flex-1 min-w-0">
+                    {editingThreadId === t.id ? (
+                      <form
+                        className="flex items-center gap-1"
+                        onSubmit={e => { e.preventDefault(); handleRenameThread(t.id) }}
+                      >
+                        <input
+                          className="flex-1 bg-zinc-800 border border-zinc-700 rounded px-1.5 py-0.5 text-[12px] text-zinc-200 outline-none min-w-0"
+                          value={editTitle}
+                          onChange={e => setEditTitle(e.target.value)}
+                          onBlur={() => handleRenameThread(t.id)}
+                          onKeyDown={e => { if (e.key === 'Escape') setEditingThreadId(null) }}
+                          autoFocus
+                        />
+                        <button type="submit" className="p-0.5 text-zinc-400 hover:text-emerald-400">
+                          <Check className="h-3 w-3" />
+                        </button>
+                      </form>
+                    ) : (
+                      <span className="block text-[12px] text-zinc-300 truncate leading-tight">
+                        {t.title ?? 'Untitled'}
+                      </span>
+                    )}
+                    <span className="text-[10px] text-zinc-600 leading-tight">
+                      {formatRelativeDate(t.updatedAt)}
                     </span>
-                  </button>
-                  <button
-                    className="aero-thread-delete"
-                    onClick={() => handleDeleteThread(t.id)}
-                    aria-label="Delete thread"
-                  >
-                    <Trash2 className="h-3 w-3" />
-                  </button>
+                  </div>
+                  {editingThreadId !== t.id && (
+                    <div className="flex items-center gap-0.5 opacity-0 group-hover:opacity-100 transition-opacity shrink-0">
+                      <button
+                        className="p-1 text-zinc-600 hover:text-zinc-300 rounded transition-colors"
+                        onClick={e => { e.stopPropagation(); setEditingThreadId(t.id); setEditTitle(t.title ?? '') }}
+                        aria-label="Rename thread"
+                      >
+                        <Pencil className="h-2.5 w-2.5" />
+                      </button>
+                      <button
+                        className="p-1 text-zinc-600 hover:text-rose-400 rounded transition-colors"
+                        onClick={e => { e.stopPropagation(); handleDeleteThread(t.id) }}
+                        aria-label="Delete thread"
+                      >
+                        <Trash2 className="h-2.5 w-2.5" />
+                      </button>
+                    </div>
+                  )}
                 </div>
               ))}
             </div>
@@ -5529,7 +5716,7 @@ function AeroPage({ projects, providers }: {
             <>
               {/* Messages */}
               <div className="aero-messages">
-                {visibleMessages.length === 0 && !sending && (
+                {visibleMessages.length === 0 && !processing && (
                   <div className="aero-empty">
                     <Bot className="h-8 w-8 text-zinc-700" />
                     <p className="text-[13px] text-zinc-500 mt-2">Send a message to get started.</p>
@@ -5540,12 +5727,12 @@ function AeroPage({ projects, providers }: {
                     <div className="aero-msg-label">
                       {msg.role === 'user' ? 'You' : 'Aero'}
                     </div>
-                    <div className="aero-msg-content">
-                      {msg.content}
+                    <div className={`aero-msg-content ${msg.role === 'assistant' ? 'aero-md' : ''}`}>
+                      {msg.role === 'assistant' ? renderMarkdown(msg.content) : msg.content}
                     </div>
                   </div>
                 ))}
-                {sending && (
+                {processing && (
                   <div className="aero-msg assistant">
                     <div className="aero-msg-label">Aero</div>
                     <div className="aero-msg-content text-zinc-500">
@@ -5566,16 +5753,21 @@ function AeroPage({ projects, providers }: {
                 <textarea
                   className="aero-input"
                   value={input}
-                  onChange={e => setInput(e.target.value)}
+                  onChange={e => {
+                    setInput(e.target.value)
+                    // Auto-expand: reset height then set to scrollHeight
+                    e.target.style.height = 'auto'
+                    e.target.style.height = Math.min(e.target.scrollHeight, 200) + 'px'
+                  }}
                   onKeyDown={handleKeyDown}
                   placeholder="Ask about your visibility, trends, competitors..."
                   rows={1}
-                  disabled={sending}
+                  disabled={processing}
                 />
                 <button
                   className="aero-send"
                   onClick={handleSend}
-                  disabled={!input.trim() || sending}
+                  disabled={!input.trim() || processing}
                   aria-label="Send message"
                 >
                   <Send className="h-4 w-4" />
@@ -6759,16 +6951,6 @@ export function App({
           )}
         </main>
 
-        <footer className="footer">
-          <p className="supporting-copy">Technical readiness and answer visibility stay separate.</p>
-          <div className="footer-links">
-            {docs.map((doc) => (
-              <a key={doc.href} href={doc.href} target="_blank" rel="noreferrer">
-                {doc.label}
-              </a>
-            ))}
-          </div>
-        </footer>
       </div>
 
       {/* ── Drawers ── */}
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
index eb8a477..f5e3b4f 100644
--- a/apps/web/src/api.ts
+++ b/apps/web/src/api.ts
@@ -688,11 +688,11 @@ export function fetchAgentThreads(project: string): Promise<ApiAgentThread[]> {
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads`)
 }
 
-export function fetchAgentThread(project: string, threadId: string): Promise<ApiAgentThread & { messages: ApiAgentMessage[] }> {
+export function fetchAgentThread(project: string, threadId: string): Promise<ApiAgentThread & { messages: ApiAgentMessage[]; status: 'processing' | 'idle'; error: string | null }> {
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
 }
 
-export function sendAgentMessage(project: string, threadId: string, message: string, provider?: string): Promise<{ threadId: string; response: string }> {
+export function sendAgentMessage(project: string, threadId: string, message: string, provider?: string): Promise<{ threadId: string; status: string }> {
   const body: Record<string, unknown> = { message }
   if (provider) body.provider = provider
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}/messages`, {
@@ -701,6 +701,13 @@ export function sendAgentMessage(project: string, threadId: string, message: str
   })
 }
 
+export function renameAgentThread(project: string, threadId: string, title: string): Promise<ApiAgentThread> {
+  return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ title }),
+  })
+}
+
 export function deleteAgentThread(project: string, threadId: string): Promise<void> {
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`, {
     method: 'DELETE',
diff --git a/apps/web/src/styles.css b/apps/web/src/styles.css
index 75ec179..72b8acb 100644
--- a/apps/web/src/styles.css
+++ b/apps/web/src/styles.css
@@ -1396,6 +1396,10 @@
 
   /* ── Aero (Agent Chat) ── */
 
+  .aero-page {
+    @apply h-full overflow-hidden flex flex-col;
+  }
+
   .aero-select {
     @apply bg-zinc-900/50 border border-zinc-800/60 rounded-lg px-3 py-1.5
            text-[13px] text-zinc-300 outline-none
@@ -1404,35 +1408,23 @@
   }
 
   .aero-layout {
-    @apply flex gap-4 mt-4;
-    height: calc(100vh - 200px);
-    min-height: 400px;
+    @apply flex gap-4 mt-4 flex-1 min-h-0 overflow-hidden;
   }
 
   .aero-threads {
-    @apply w-56 shrink-0 bg-zinc-900/30 border border-zinc-800/60 rounded-xl p-3 overflow-y-auto;
+    @apply w-60 shrink-0 bg-zinc-900/20 border border-zinc-800/50 rounded-xl p-3 overflow-y-auto;
   }
 
   .aero-thread-item {
-    @apply flex items-center gap-1 rounded-lg transition-colors;
-  }
-
-  .aero-thread-item.active {
-    @apply bg-zinc-800/60;
+    @apply flex items-start gap-2 px-2.5 py-2 rounded-lg cursor-pointer transition-colors;
   }
 
   .aero-thread-item:hover {
     @apply bg-zinc-800/40;
   }
 
-  .aero-thread-btn {
-    @apply flex-1 flex items-center justify-between gap-2 text-left
-           px-2.5 py-2 text-[13px] text-zinc-300 truncate rounded-lg
-           min-w-0;
-  }
-
-  .aero-thread-delete {
-    @apply p-1.5 text-zinc-600 hover:text-rose-400 transition-colors shrink-0 rounded;
+  .aero-thread-item.active {
+    @apply bg-zinc-800/60;
   }
 
   .aero-chat {
@@ -1468,17 +1460,44 @@
   }
 
   .aero-msg-content {
-    @apply text-[13px] leading-relaxed rounded-xl px-4 py-3 whitespace-pre-wrap;
+    @apply text-[13px] leading-relaxed rounded-xl px-4 py-3;
   }
 
   .aero-msg.user .aero-msg-content {
-    @apply bg-zinc-800/60 text-zinc-200;
+    @apply bg-zinc-800/60 text-zinc-200 whitespace-pre-wrap;
   }
 
   .aero-msg.assistant .aero-msg-content {
     @apply bg-zinc-900/60 text-zinc-300 border border-zinc-800/40;
   }
 
+  /* Markdown prose inside assistant messages */
+  .aero-md p {
+    @apply mb-2;
+  }
+  .aero-md p:last-child {
+    @apply mb-0;
+  }
+
+  .aero-md-list {
+    @apply pl-5 my-1.5 space-y-0.5 list-disc;
+  }
+  .aero-md-ol {
+    @apply list-decimal;
+  }
+  .aero-md-list li {
+    @apply text-zinc-300;
+  }
+
+  .aero-inline-code {
+    @apply bg-zinc-800 text-emerald-400 px-1.5 py-0.5 rounded text-[12px] font-mono;
+  }
+
+  .aero-code-block {
+    @apply bg-zinc-950 border border-zinc-800/60 rounded-lg px-4 py-3 my-2
+           text-[12px] leading-relaxed font-mono text-zinc-300 overflow-x-auto;
+  }
+
   .aero-error {
     @apply text-[13px] text-rose-400 bg-rose-950/30 border border-rose-900/40
            rounded-lg px-4 py-2.5 mr-auto max-w-[85%];
@@ -1491,8 +1510,11 @@
   .aero-input {
     @apply flex-1 bg-zinc-900/50 border border-zinc-800/60 rounded-xl px-4 py-2.5
            text-[13px] text-zinc-200 placeholder-zinc-600 outline-none
-           resize-none min-h-[40px] max-h-[120px]
+           resize-none
            focus:border-zinc-600 transition-colors;
+    min-height: 40px;
+    max-height: 200px;
+    overflow-y: auto;
   }
 
   .aero-send {
diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index dbc37cf..346f30b 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -27,8 +27,10 @@ export interface AgentRoutesOptions {
 export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions) {
   const prefix = '/projects/:project/agent'
 
-  // Per-thread mutex — prevents concurrent agent loops from corrupting history
+  // Per-thread mutex — prevents concurrent agent loops from corrupting history.
+  // Also tracks pending work so it survives client disconnects.
   const activeThreads = new Set<string>()
+  const threadErrors = new Map<string, string>()
 
   // ── Create thread ─────────────────────────────────────────
 
@@ -138,7 +140,9 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
       .orderBy(asc(agentMessages.createdAt))
       .all()
 
-    return reply.send({ ...thread, messages })
+    const processing = activeThreads.has(id)
+    const error = threadErrors.get(id) ?? null
+    return reply.send({ ...thread, messages, status: processing ? 'processing' : 'idle', error })
   })
 
   // ── Send message ──────────────────────────────────────────
@@ -201,21 +205,68 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
     }
 
     activeThreads.add(threadId)
-    try {
-      const response = await opts.onAgentMessage(thread.projectId, threadId, message, { provider })
-      return reply.send({ threadId, response })
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      const isLlmError = msg.includes('API error') || msg.includes('API key') || msg.includes('timeout')
-      return reply.status(isLlmError ? 502 : 500).send({
-        error: {
-          code: isLlmError ? 'LLM_ERROR' : 'AGENT_ERROR',
-          message: msg,
-        },
+    threadErrors.delete(threadId)
+
+    // Fire-and-forget: the agent loop runs in the background so it
+    // survives client disconnects and page navigations.
+    opts.onAgentMessage(thread.projectId, threadId, message, { provider })
+      .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err)
+        threadErrors.set(threadId, msg)
+        app.log.error({ threadId, err: msg }, 'agent loop error')
+      })
+      .finally(() => {
+        activeThreads.delete(threadId)
       })
-    } finally {
-      activeThreads.delete(threadId)
+
+    return reply.status(202).send({ threadId, status: 'processing' })
+  })
+
+  // ── Update thread (rename) ───────────────────────────────
+
+  app.patch<{
+    Params: { project: string; id: string }
+    Body: { title?: string }
+  }>(`${prefix}/threads/:id`, {
+    schema: {
+      params: {
+        type: 'object',
+        properties: {
+          project: { type: 'string' },
+          id: { type: 'string' },
+        },
+        required: ['project', 'id'],
+      },
+      body: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', maxLength: 200 },
+        },
+      },
+    },
+  }, async (request, reply) => {
+    const { project, id } = request.params
+    const { title } = request.body ?? {}
+
+    const projectRow = resolveProject(app.db, project)
+
+    const thread = app.db
+      .select()
+      .from(agentThreads)
+      .where(eq(agentThreads.id, id))
+      .get()
+
+    if (!thread || thread.projectId !== projectRow.id) {
+      return reply.status(404).send({ error: { code: 'NOT_FOUND', message: 'Thread not found' } })
     }
+
+    const updates: Record<string, unknown> = { updatedAt: new Date().toISOString() }
+    if (title !== undefined) updates.title = title
+
+    app.db.update(agentThreads).set(updates).where(eq(agentThreads.id, id)).run()
+
+    const updated = app.db.select().from(agentThreads).where(eq(agentThreads.id, id)).get()
+    return reply.send(updated)
   })
 
   // ── Delete thread ─────────────────────────────────────────
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 3f2919f..fcc32b0 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -207,27 +207,29 @@ function convertToClaudeMessages(
       result.push({ role: 'user', content: msg.content ?? '' })
     } else if (msg.role === 'assistant') {
       if (msg.tool_calls && msg.tool_calls.length > 0) {
-        const content: Array<Record<string, unknown>> = []
-        if (msg.content) {
-          content.push({ type: 'text', text: msg.content })
-        }
+        const blocks: Array<Record<string, unknown>> = []
         for (const tc of msg.tool_calls) {
           let input: Record<string, unknown>
           try {
             input = JSON.parse(tc.function.arguments) as Record<string, unknown>
           } catch {
-            // Malformed JSON from a previous turn — send an empty object so the
-            // thread can recover instead of crashing all subsequent turns.
             input = {}
           }
-          content.push({
+          blocks.push({
             type: 'tool_use',
             id: tc.id,
             name: tc.function.name,
             input,
           })
         }
-        result.push({ role: 'assistant', content })
+        // Merge consecutive assistant tool-call messages into one.
+        // The DB stores each tool call separately but Claude needs them grouped.
+        const prev = result[result.length - 1]
+        if (prev && prev.role === 'assistant' && Array.isArray(prev.content)) {
+          prev.content.push(...blocks)
+        } else {
+          result.push({ role: 'assistant', content: blocks })
+        }
       } else {
         result.push({ role: 'assistant', content: msg.content ?? '' })
       }
@@ -252,5 +254,81 @@ function convertToClaudeMessages(
     }
   }
 
+  // ── Validate tool_use ↔ tool_result pairing ──────────────
+  // Claude requires:
+  //   1. Every tool_use in an assistant message must have a tool_result in the NEXT user message
+  //   2. Every tool_result in a user message must reference a tool_use in the PREVIOUS assistant message
+  // We do multiple passes to clean up both directions.
+
+  // Pass 1: For each assistant message with tool_use blocks, ensure the next
+  // message is a user message containing matching tool_result blocks.
+  // If not, remove the orphaned tool_use blocks (or the whole assistant message).
+  for (let idx = 0; idx < result.length; idx++) {
+    const entry = result[idx]
+    if (entry.role !== 'assistant' || !Array.isArray(entry.content)) continue
+
+    const toolUseBlocks = (entry.content as Array<Record<string, unknown>>).filter(b => b.type === 'tool_use')
+    if (toolUseBlocks.length === 0) continue
+
+    // Collect tool_result IDs from the next message
+    const next = idx + 1 < result.length ? result[idx + 1] : null
+    const resultIds = new Set<string>()
+    if (next && next.role === 'user' && Array.isArray(next.content)) {
+      for (const b of next.content as Array<Record<string, unknown>>) {
+        if (b.type === 'tool_result' && typeof b.tool_use_id === 'string') {
+          resultIds.add(b.tool_use_id)
+        }
+      }
+    }
+
+    // Remove tool_use blocks without matching results
+    entry.content = (entry.content as Array<Record<string, unknown>>).filter(
+      b => b.type !== 'tool_use' || resultIds.has(b.id as string),
+    )
+
+    // If the assistant message is now empty, remove it
+    if ((entry.content as Array<Record<string, unknown>>).length === 0) {
+      result.splice(idx, 1)
+      idx--
+    }
+  }
+
+  // Pass 2: For each user message with tool_result blocks, ensure the previous
+  // message is an assistant message containing matching tool_use blocks.
+  for (let idx = 0; idx < result.length; idx++) {
+    const entry = result[idx]
+    if (entry.role !== 'user' || !Array.isArray(entry.content)) continue
+
+    const hasToolResults = (entry.content as Array<Record<string, unknown>>).some(b => b.type === 'tool_result')
+    if (!hasToolResults) continue
+
+    const prev = idx > 0 ? result[idx - 1] : null
+    const toolUseIds = new Set<string>()
+    if (prev && prev.role === 'assistant' && Array.isArray(prev.content)) {
+      for (const b of prev.content as Array<Record<string, unknown>>) {
+        if (b.type === 'tool_use' && typeof b.id === 'string') {
+          toolUseIds.add(b.id)
+        }
+      }
+    }
+
+    entry.content = (entry.content as Array<Record<string, unknown>>).filter(
+      b => b.type !== 'tool_result' || toolUseIds.has(b.tool_use_id as string),
+    )
+
+    if ((entry.content as Array<Record<string, unknown>>).length === 0) {
+      result.splice(idx, 1)
+      idx--
+    }
+  }
+
+  // Ensure conversation starts with a user message (Claude requirement)
+  while (result.length > 0 && result[0].role !== 'user') {
+    result.shift()
+  }
+  if (result.length === 0 || result[0].role !== 'user') {
+    result.unshift({ role: 'user', content: '(continuing conversation)' })
+  }
+
   return result
 }
diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
index 0aae0c9..bd10a4b 100644
--- a/packages/canonry/src/agent/loop.ts
+++ b/packages/canonry/src/agent/loop.ts
@@ -27,6 +27,8 @@ interface LoopOptions {
   }
   maxSteps?: number
   maxHistoryMessages?: number
+  /** Whether system tools (shell, file I/O) are enabled */
+  systemTools?: boolean
   /** Called when the agent produces a text chunk (for streaming) */
   onText?: (text: string) => void
   /** Called when a tool is about to execute */
@@ -64,41 +66,85 @@ export async function agentChat(
   // Load conversation history
   const history = await store.getMessages(threadId, maxHistoryMessages)
 
+  // Detect new thread — only the user's message exists (first message in thread).
+  // This triggers the startup sequence instruction in the system prompt.
+  const isNewThread = history.length === 1 && history[0].role === 'user'
+
+  // Auto-title new threads from the user's first message
+  if (isNewThread) {
+    const title = userMessage.length > 80 ? userMessage.slice(0, 77) + '...' : userMessage
+    await store.updateThreadTitle(threadId, title)
+  }
+
   // Build message array for LLM
-  const systemPrompt = buildSystemPrompt(project)
+  const systemPrompt = buildSystemPrompt(project, { isNewThread, systemTools: opts.systemTools })
   const messages: ChatMessage[] = [
     { role: 'system', content: systemPrompt },
   ]
 
-  // Convert stored messages to LLM format
-  for (const msg of history) {
+  // Convert stored messages to LLM format.
+  // The DB stores each tool call as a separate assistant row followed by its
+  // tool result row. We need to group consecutive tool-call/result pairs into
+  // a single assistant message + tool results block, because Claude requires
+  // tool_result blocks to reference tool_use blocks in the immediately
+  // preceding assistant message.
+  let i = 0
+  while (i < history.length) {
+    const msg = history[i]
+
     if (msg.role === 'user') {
       messages.push({ role: 'user', content: msg.content })
-    } else if (msg.role === 'assistant') {
-      // Check if this was a tool-calling message (has linked tool results after it)
-      if (msg.toolName) {
-        // This was stored as a tool-call assistant message
-        messages.push({
-          role: 'assistant',
-          content: null,
-          tool_calls: [{
-            id: msg.toolCallId ?? msg.id,
-            type: 'function',
-            function: {
-              name: msg.toolName,
-              arguments: msg.toolArgs ?? '{}',
-            },
-          }],
+      i++
+    } else if (msg.role === 'assistant' && msg.toolName) {
+      // Collect all consecutive (assistant tool-call, tool result) pairs
+      // into one assistant message + one batch of tool results.
+      const toolCalls: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }> = []
+      const toolResults: ChatMessage[] = []
+
+      while (i < history.length && history[i].role === 'assistant' && history[i].toolName) {
+        const tc = history[i]
+        const callId = tc.toolCallId ?? tc.id
+        toolCalls.push({
+          id: callId,
+          type: 'function',
+          function: { name: tc.toolName!, arguments: tc.toolArgs ?? '{}' },
         })
-      } else {
-        messages.push({ role: 'assistant', content: msg.content })
+        // Look for the matching tool result (should be next or nearby)
+        const resultIdx = history.findIndex((m, j) => j > i && m.role === 'tool' && m.toolCallId === callId)
+        if (resultIdx !== -1) {
+          toolResults.push({
+            role: 'tool',
+            content: history[resultIdx].content,
+            tool_call_id: callId,
+          })
+        }
+        i++
+      }
+      // Skip past any tool result rows we already consumed
+      while (i < history.length && history[i].role === 'tool') {
+        // Check if this result was already captured above
+        const alreadyCaptured = toolResults.some(r => r.tool_call_id === history[i].toolCallId)
+        if (!alreadyCaptured) {
+          toolResults.push({
+            role: 'tool',
+            content: history[i].content,
+            tool_call_id: history[i].toolCallId ?? undefined,
+          })
+        }
+        i++
       }
+
+      messages.push({ role: 'assistant', content: null, tool_calls: toolCalls })
+      messages.push(...toolResults)
+    } else if (msg.role === 'assistant') {
+      messages.push({ role: 'assistant', content: msg.content })
+      i++
     } else if (msg.role === 'tool') {
-      messages.push({
-        role: 'tool',
-        content: msg.content,
-        tool_call_id: msg.toolCallId ?? undefined,
-      })
+      // Orphaned tool result (shouldn't happen after grouping, but handle gracefully)
+      messages.push({ role: 'tool', content: msg.content, tool_call_id: msg.toolCallId ?? undefined })
+      i++
+    } else {
+      i++
     }
   }
 
diff --git a/packages/canonry/src/agent/memory.md b/packages/canonry/src/agent/memory.md
index c56c012..cd7e081 100644
--- a/packages/canonry/src/agent/memory.md
+++ b/packages/canonry/src/agent/memory.md
@@ -1,32 +1,72 @@
 # Aero Memory
 
-This file stores persistent context that Aero accumulates across conversations.
-It can be updated by Aero or by the user to prime the agent with project-specific knowledge.
+Persistent context that Aero accumulates across conversations and threads.
+Updated automatically by Aero via `save_memory` and readable via `get_memory`.
+Users can also edit this file directly at `~/.canonry/memory.md`.
 
-## Project Knowledge
+---
+
+## Canonry Domain Knowledge
+
+### Citation States
+- `cited` — the domain appeared **as a source** in the AI-generated answer (grounding attribution, inline link, or footnote). This is the positive signal.
+- `not-cited` — the domain was NOT referenced. The AI used other sources or generated from training data.
+- Each sweep records one snapshot per keyword × provider combination.
+
+### How Each Provider Grounds Answers
+
+**Gemini (Google AI)**
+- Uses **Google Search grounding** — same index as organic Google Search.
+- Grounding sources arrive as base64-encoded proxy URLs. Canonry extracts real domains from the `title` field.
+- If a page isn't indexed in Google Search, Gemini **cannot** cite it. GSC index coverage directly affects Gemini visibility.
+
+**ChatGPT / OpenAI**
+- Uses **Bing grounding** via `web_search_preview`.
+- The API returns fewer/different results than ChatGPT's browser UI (which has a richer search pipeline).
+- Bing index coverage matters. Pages not in Bing won't appear.
+
+**Claude (Anthropic)**
+- Uses its own **web search** tool.
+- Tends to cite authoritative, well-structured content. Less dependent on a specific search engine index.
+- Content quality and authority signals matter more than index presence.
 
-<!-- Aero will populate this section with learned context about the user's projects,
-     domain, industry, and competitive landscape. Users can also pre-fill this
-     to give Aero a head start. Example entries:
+### Interpreting Sweep Results
+- **Visibility rate** = cited snapshots / total snapshots in a run.
+- Run statuses: `completed` (all succeed), `partial` (some failed), `failed` (all failed).
+- Always include `partial` runs — they contain valid results for the providers that succeeded.
+
+### Regression Detection
+- Visibility drop of **≥2 keywords** between consecutive runs = regression, flag immediately.
+- All providers flip `cited → not-cited` simultaneously = domain-side change (page removed, noindex, content changed).
+- Single provider flips = provider-side index/ranking change.
+
+### Evidence vs. Timeline vs. Run Details
+- **Evidence** (`get_evidence`): Per-keyword citation data across recent runs. "What's my current visibility?"
+- **Timeline** (`get_timeline`): Aggregated visibility rate over time. "Is my visibility trending?"
+- **Run details** (`get_run_details`): Raw snapshots for one run. Deep-dive into a specific sweep.
+
+### Content Strategy Signals
+- Cited pages tend to have: clear structure (H2/H3), direct answers, authoritative tone, factual density.
+- AI models prefer reference-style content over marketing copy.
+- Freshness matters more for Gemini (Google index recency) than Claude.
+- Schema markup (FAQ, HowTo) can improve grounding selection for structured queries.
+
+### GSC Integration
+- When connected, cross-references: performance (clicks, impressions, CTR), index coverage, URL inspection.
+- Deindexed pages are high priority — they were once indexed but now excluded.
+- GSC coverage directly impacts Gemini visibility.
+
+---
+
+## Project Knowledge
 
-- Project "my-saas" targets B2B SaaS keywords in the US market
-- Main competitors: competitor1.com (strong on Gemini), competitor2.com (strong on ChatGPT)
-- Content refresh on /pricing page improved Gemini citations from 20% → 60%
-- Blog posts with structured data get cited more frequently
--->
+<!-- Aero populates this section with learned context about the user's projects,
+     domain, industry, and competitive landscape. -->
 
 ## Patterns Observed
 
-<!-- Aero will note recurring patterns here, such as:
-- Provider X consistently cites competitor Y for keyword Z
-- Visibility tends to drop on weekends (grounding index refresh timing)
-- Keywords with question format ("how to...") have higher citation rates
--->
+<!-- Recurring patterns Aero notices across sweeps and conversations. -->
 
 ## User Preferences
 
-<!-- How the user likes to interact with Aero:
-- Prefers detailed tables over summaries
-- Wants competitor comparison in every report
-- Focuses on Gemini visibility primarily
--->
+<!-- How the user prefers to interact — report style, focus areas, etc. -->
diff --git a/packages/canonry/src/agent/prompt.ts b/packages/canonry/src/agent/prompt.ts
index 7e2d64f..3e27c01 100644
--- a/packages/canonry/src/agent/prompt.ts
+++ b/packages/canonry/src/agent/prompt.ts
@@ -40,6 +40,23 @@ You are an expert in:
 - **Competitive analysis** — identifying which competitors are cited instead
 - **Content strategy** — what makes content more likely to be cited by AI models
 
+## Startup Sequence
+
+**On the first message in a new thread**, before responding to the user:
+1. Call \`get_memory\` to load persistent context from prior sessions.
+2. Call \`get_status\` to understand the project's current state.
+3. Use this context **silently** — gather it but **respond naturally to what the user actually asked**.
+
+**Important:** Match your response to the user's intent:
+- If they ask a specific question → answer it using the data you gathered.
+- If they ask for a report or analysis → give a detailed breakdown.
+- If they say hello or greet you → respond warmly with a **one-line** status summary (e.g. "Hey! Your visibility is at 40% across 3 providers — anything you'd like to dig into?"). Don't dump a full analysis on a greeting.
+- If they give a command → execute it.
+
+The startup data is **context for you**, not content for the user. Only surface what's relevant to their message.
+
+If the thread already has history (continuing a conversation), skip the startup sequence.
+
 ## How You Work
 
 1. **Always check data first.** Use \`get_evidence\` for current visibility, \`get_timeline\` for trends, \`get_status\` for project overview.
@@ -47,14 +64,29 @@ You are an expert in:
 3. **Flag changes.** If visibility dropped or improved, highlight it and explain likely causes.
 4. **Connect to action.** Every finding should link to something the user can do — update content, add keywords, investigate a competitor.
 
-## What You Don't Do
+## Memory
+
+You have persistent memory that survives across threads and sessions via \`get_memory\` and \`save_memory\`.
+
+**When to save memory:**
+- When you discover a new pattern (e.g. "competitor X consistently beats us on Gemini for product keywords").
+- When the user tells you something important about their domain, goals, or preferences.
+- When a significant event happens (regression, recovery, new competitor appearing).
+- At the end of a productive conversation — summarize key findings and decisions.
 
-- You don't modify project settings or keywords unless explicitly asked.
-- You don't make up data or statistics.
-- You don't provide generic SEO advice disconnected from the user's actual data.
-- You don't run sweeps unless the user asks for fresh data.`
+**What to save:**
+- Project-specific insights, patterns, and observations under "## Project Knowledge" or "## Patterns Observed".
+- User preferences under "## User Preferences".
+- Keep entries concise and dated.
+- Don't duplicate the domain knowledge section — that's reference material.
 
-function loadFromConfigDir(filename: string): string | null {
+## Guidelines
+
+- Never fabricate data or statistics. If you don't have it, fetch it.
+- Don't provide generic SEO advice disconnected from the user's actual data.
+- Confirm before destructive actions (deleting keywords, removing competitors).`
+
+export function loadFromConfigDir(filename: string): string | null {
   try {
     const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
       path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
@@ -68,43 +100,102 @@ function loadFromConfigDir(filename: string): string | null {
   return null
 }
 
+export function saveToConfigDir(filename: string, content: string): void {
+  const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+    path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+  fs.mkdirSync(configDir, { recursive: true })
+  fs.writeFileSync(path.join(configDir, filename), content, 'utf-8')
+}
+
+/** Bundled fallback for memory.md — domain knowledge that ships with canonry. */
+const BUILT_IN_MEMORY = `# Aero Memory
+
+## Canonry Domain Knowledge
+
+### Citation States
+- \`cited\` — the domain appeared as a source in the AI-generated answer.
+- \`not-cited\` — the domain was NOT referenced.
+
+### How Each Provider Grounds Answers
+- **Gemini**: Google Search grounding. If a page isn't in Google's index, Gemini cannot cite it.
+- **ChatGPT/OpenAI**: Bing grounding via web_search_preview. Pages must be in Bing's index.
+- **Claude**: Own web search. Favors authoritative, well-structured content.
+
+### Interpreting Results
+- Visibility rate = cited / total snapshots per run.
+- Run statuses: completed (all succeed), partial (some failed), failed (all failed).
+- Drop of ≥2 keywords between runs = regression, flag immediately.
+- All providers flip simultaneously = domain-side change. One provider = index change.
+
+### Evidence vs. Timeline
+- Evidence (get_evidence): Per-keyword current visibility. "How am I doing?"
+- Timeline (get_timeline): Aggregated rate over time. "Am I trending up?"
+- Run details (get_run_details): Raw snapshots for one sweep.
+
+---
+
+## Project Knowledge
+
+## Patterns Observed
+
+## User Preferences
+`
+
 export function buildSystemPrompt(project: {
   name: string
   displayName: string
   domain: string
   country: string
   language: string
-}): string {
+}, opts?: { isNewThread?: boolean; systemTools?: boolean }): string {
   // Load soul (personality) — user override or built-in
   const soul = loadFromConfigDir('soul.md') || BUILT_IN_SOUL
 
-  // Load memory (persistent context) — user-managed, empty by default
-  const memory = loadFromConfigDir('memory.md')
-
   const contextBlock = `## Current Project
 
 - **Project:** ${project.name}
 - **Display Name:** ${project.displayName}
 - **Domain:** ${project.domain}
 - **Market:** ${project.country}, ${project.language}
+${opts?.isNewThread ? '\nThis is a **new thread**. Execute the startup sequence before responding.' : ''}
 
 ## Available Tools
 
+### Read Tools
 - \`get_status\` — project overview with latest runs
 - \`get_evidence\` — per-keyword citation data across providers (primary tool for "how am I doing?")
 - \`get_timeline\` — visibility trends over time
 - \`get_run_details\` — detailed results for a specific run
 - \`list_keywords\` — tracked keywords
 - \`list_competitors\` — tracked competitors
-- \`run_sweep\` — trigger a fresh visibility sweep (only when user asks for fresh data)
 - \`get_gsc_performance\` — Google Search Console metrics (if connected)
 - \`get_gsc_coverage\` — index coverage summary (if connected)
-- \`inspect_url\` — check a URL's indexing status in GSC (if connected)`
-
-  const sections = [soul, contextBlock]
-  if (memory?.trim()) {
-    sections.push(memory)
-  }
-
-  return sections.filter(Boolean).join('\n\n')
+- \`inspect_url\` — check a URL's indexing status in GSC (if connected)
+
+### Write Tools
+- \`add_keywords\` — add new keywords to track
+- \`remove_keywords\` — remove keywords from tracking (confirm first)
+- \`add_competitors\` — add competitor domains to track
+- \`remove_competitors\` — remove competitor domains (confirm first)
+- \`update_project\` — update project settings (displayName, domain, country, language)
+- \`run_sweep\` — trigger a fresh visibility sweep
+
+### Memory Tools
+- \`get_memory\` — read persistent memory from prior sessions
+- \`save_memory\` — write observations, patterns, and preferences to persistent memory${opts?.systemTools ? `
+
+### System Tools
+- \`run_command\` — execute shell commands (install packages, run scripts, canonry CLI, curl, etc.)
+- \`read_file\` — read any file from the server filesystem
+- \`write_file\` — create or update files (scripts, configs, data)
+- \`list_files\` — list directory contents
+- \`http_request\` — make HTTP requests to any URL (fetch pages, call APIs, download data)
+
+You have **full system access**. You can install npm packages, download tools, run canonry CLI commands, write scripts, and interact with external services. Use this power responsibly — confirm with the user before destructive operations (rm, overwriting important files).` : ''}`
+
+  // Load memory into context directly so it's always available
+  const memory = loadFromConfigDir('memory.md') || BUILT_IN_MEMORY
+  const memoryBlock = `## Persistent Memory (loaded from ~/.canonry/memory.md)\n\n${memory}`
+
+  return [soul, contextBlock, memoryBlock].filter(Boolean).join('\n\n')
 }
diff --git a/packages/canonry/src/agent/soul.md b/packages/canonry/src/agent/soul.md
index c9f640f..12a17ed 100644
--- a/packages/canonry/src/agent/soul.md
+++ b/packages/canonry/src/agent/soul.md
@@ -29,6 +29,23 @@ You are an expert in:
 - **Competitive analysis** — identifying which competitors are cited instead
 - **Content strategy** — what makes content more likely to be cited by AI models
 
+## Startup Sequence
+
+**On the first message in a new thread**, before responding to the user:
+1. Call `get_memory` to load persistent context from prior sessions.
+2. Call `get_status` to understand the project's current state.
+3. Use this context **silently** — gather it but **respond naturally to what the user actually asked**.
+
+**Important:** Match your response to the user's intent:
+- If they ask a specific question → answer it using the data you gathered.
+- If they ask for a report or analysis → give a detailed breakdown.
+- If they say hello or greet you → respond warmly with a **one-line** status summary (e.g. "Hey! Your visibility is at 40% across 3 providers — anything you'd like to dig into?"). Don't dump a full analysis on a greeting.
+- If they give a command → execute it.
+
+The startup data is **context for you**, not content for the user. Only surface what's relevant to their message.
+
+If the thread already has history (continuing a conversation), skip the startup sequence.
+
 ## How You Work
 
 1. **Always check data first.** Use `get_evidence` for current visibility, `get_timeline` for trends, `get_status` for project overview.
@@ -36,9 +53,24 @@ You are an expert in:
 3. **Flag changes.** If visibility dropped or improved, highlight it and explain likely causes.
 4. **Connect to action.** Every finding should link to something the user can do — update content, add keywords, investigate a competitor.
 
-## What You Don't Do
+## Memory
+
+You have persistent memory that survives across threads and sessions via `get_memory` and `save_memory`.
+
+**When to save memory:**
+- When you discover a new pattern (e.g. "competitor X consistently beats us on Gemini for product keywords").
+- When the user tells you something important about their domain, goals, or preferences.
+- When a significant event happens (regression, recovery, new competitor appearing).
+- At the end of a productive conversation — summarize key findings and decisions.
+
+**What to save:**
+- Project-specific insights, patterns, and observations under "## Project Knowledge" or "## Patterns Observed".
+- User preferences under "## User Preferences".
+- Keep entries concise and dated.
+- Don't duplicate the domain knowledge section — that's reference material.
+
+## Guidelines
 
-- You don't modify project settings or keywords unless explicitly asked.
-- You don't make up data or statistics.
-- You don't provide generic SEO advice disconnected from the user's actual data.
-- You don't run sweeps unless the user asks for fresh data.
+- Never fabricate data or statistics. If you don't have it, fetch it.
+- Don't provide generic SEO advice disconnected from the user's actual data.
+- Confirm before destructive actions (deleting keywords, removing competitors).
diff --git a/packages/canonry/src/agent/tools.ts b/packages/canonry/src/agent/tools.ts
index 0170f63..c612061 100644
--- a/packages/canonry/src/agent/tools.ts
+++ b/packages/canonry/src/agent/tools.ts
@@ -6,8 +6,12 @@
  * for proper job orchestration and auth handling.
  */
 
+import { execSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
 import type { AgentServices } from './services.js'
 import type { ApiClient } from '../client.js'
+import { loadFromConfigDir, saveToConfigDir } from './prompt.js'
 
 export interface AgentTool {
   name: string
@@ -27,8 +31,13 @@ function truncateResult(json: string): string {
   return json.slice(0, MAX_TOOL_RESULT_LENGTH) + '\n... (truncated — result too large)'
 }
 
-export function buildTools(services: AgentServices, client: ApiClient, projectName: string): AgentTool[] {
-  return [
+export interface AgentToolsConfig {
+  /** Enable shell execution, file I/O, and HTTP tools. Default: false. */
+  systemTools?: boolean
+}
+
+export function buildTools(services: AgentServices, client: ApiClient, projectName: string, config?: AgentToolsConfig): AgentTool[] {
+  const tools: AgentTool[] = [
     {
       name: 'get_status',
       description:
@@ -121,6 +130,123 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
         return truncateResult(JSON.stringify(competitors, null, 2))
       },
     },
+    {
+      name: 'add_keywords',
+      description: 'Add new keywords to track for this project. Accepts one or more keywords.',
+      parameters: {
+        type: 'object',
+        properties: {
+          keywords: {
+            type: 'string',
+            description: 'Comma-separated list of keywords to add.',
+          },
+        },
+        required: ['keywords'],
+      },
+      execute: async (args) => {
+        const kws = (args.keywords as string).split(',').map(s => s.trim()).filter(Boolean)
+        await client.appendKeywords(projectName, kws)
+        return JSON.stringify({ added: kws, count: kws.length })
+      },
+    },
+    {
+      name: 'remove_keywords',
+      description: 'Remove keywords from tracking. Confirm with the user before calling this.',
+      parameters: {
+        type: 'object',
+        properties: {
+          keywords: {
+            type: 'string',
+            description: 'Comma-separated list of keywords to remove.',
+          },
+        },
+        required: ['keywords'],
+      },
+      execute: async (args) => {
+        const kws = (args.keywords as string).split(',').map(s => s.trim()).filter(Boolean)
+        await client.deleteKeywords(projectName, kws)
+        return JSON.stringify({ removed: kws, count: kws.length })
+      },
+    },
+    {
+      name: 'add_competitors',
+      description: 'Add competitor domains to track for this project.',
+      parameters: {
+        type: 'object',
+        properties: {
+          competitors: {
+            type: 'string',
+            description: 'Comma-separated list of competitor domains (e.g. "competitor1.com, competitor2.com").',
+          },
+        },
+        required: ['competitors'],
+      },
+      execute: async (args) => {
+        const existing = await services.listCompetitors(projectName)
+        const existingDomains = existing.map((c: Record<string, unknown>) => String(c.domain ?? c.name ?? ''))
+        const newDomains = (args.competitors as string).split(',').map(s => s.trim()).filter(Boolean)
+        const merged = [...new Set([...existingDomains, ...newDomains])]
+        await client.putCompetitors(projectName, merged)
+        return JSON.stringify({ added: newDomains, total: merged.length })
+      },
+    },
+    {
+      name: 'remove_competitors',
+      description: 'Remove competitor domains from tracking. Confirm with the user before calling this.',
+      parameters: {
+        type: 'object',
+        properties: {
+          competitors: {
+            type: 'string',
+            description: 'Comma-separated list of competitor domains to remove.',
+          },
+        },
+        required: ['competitors'],
+      },
+      execute: async (args) => {
+        const existing = await services.listCompetitors(projectName)
+        const existingDomains = existing.map((c: Record<string, unknown>) => String(c.domain ?? c.name ?? ''))
+        const toRemove = new Set((args.competitors as string).split(',').map(s => s.trim()).filter(Boolean))
+        const remaining = existingDomains.filter(d => !toRemove.has(d))
+        await client.putCompetitors(projectName, remaining)
+        return JSON.stringify({ removed: [...toRemove], remaining: remaining.length })
+      },
+    },
+    {
+      name: 'update_project',
+      description: 'Update project settings. Only include fields you want to change.',
+      parameters: {
+        type: 'object',
+        properties: {
+          displayName: {
+            type: 'string',
+            description: 'New display name for the project.',
+          },
+          domain: {
+            type: 'string',
+            description: 'New canonical domain (e.g. "example.com").',
+          },
+          country: {
+            type: 'string',
+            description: 'Two-letter country code (e.g. "US").',
+          },
+          language: {
+            type: 'string',
+            description: 'Two-letter language code (e.g. "en").',
+          },
+        },
+        required: [],
+      },
+      execute: async (args) => {
+        const body: Record<string, unknown> = {}
+        if (args.displayName) body.displayName = args.displayName
+        if (args.domain) body.canonicalDomain = args.domain
+        if (args.country) body.country = args.country
+        if (args.language) body.language = args.language
+        const result = await client.putProject(projectName, body)
+        return truncateResult(JSON.stringify(result, null, 2))
+      },
+    },
     {
       name: 'get_run_details',
       description: 'Get detailed results for a specific run by ID, including all snapshots.',
@@ -205,5 +331,261 @@ export function buildTools(services: AgentServices, client: ApiClient, projectNa
         }
       },
     },
+    // ── Memory tools ──────────────────────────────────────────
+    {
+      name: 'get_memory',
+      description:
+        'Read persistent memory from ~/.canonry/memory.md. Contains domain knowledge, project observations, patterns, and user preferences accumulated across sessions.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+      execute: async () => {
+        const content = loadFromConfigDir('memory.md')
+        return content ?? '(No memory file found. Use save_memory to create one.)'
+      },
+    },
+    {
+      name: 'save_memory',
+      description:
+        'Write updated memory to ~/.canonry/memory.md. Use this to persist observations, patterns, project knowledge, and user preferences across sessions. Send the FULL memory content (not just the new part) since this overwrites the file.',
+      parameters: {
+        type: 'object',
+        properties: {
+          content: {
+            type: 'string',
+            description: 'The full memory.md content to write. Preserve existing domain knowledge sections and append new observations.',
+          },
+        },
+        required: ['content'],
+      },
+      execute: async (args) => {
+        const content = args.content as string
+        saveToConfigDir('memory.md', content)
+        return JSON.stringify({ saved: true, bytes: content.length })
+      },
+    },
   ]
+
+  // ── System tools (opt-in) ────────────────────────────────
+  if (config?.systemTools) {
+    tools.push(
+      {
+        name: 'run_command',
+        description:
+          'Execute a shell command on the server and return stdout/stderr. Use this for installing packages, running canonry CLI commands, downloading files, running scripts, and system administration. Commands run with the server process permissions.',
+        parameters: {
+          type: 'object',
+          properties: {
+            command: {
+              type: 'string',
+              description: 'The shell command to execute (e.g. "npm install ...", "curl ...", "canonry keyword add ...").',
+            },
+            cwd: {
+              type: 'string',
+              description: 'Working directory for the command. Defaults to the canonry config directory.',
+            },
+            timeout: {
+              type: 'string',
+              description: 'Timeout in seconds. Default: 30. Max: 300.',
+            },
+          },
+          required: ['command'],
+        },
+        execute: async (args) => {
+          const command = args.command as string
+          const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+            path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+          const cwd = (args.cwd as string) || configDir
+          const timeoutSec = Math.min(parseInt(args.timeout as string || '30', 10) || 30, 300)
+
+          try {
+            const output = execSync(command, {
+              cwd,
+              timeout: timeoutSec * 1000,
+              maxBuffer: 1024 * 1024, // 1MB
+              encoding: 'utf-8',
+              env: { ...process.env },
+              shell: '/bin/sh',
+            })
+            return truncateResult(output || '(no output)')
+          } catch (err) {
+            const e = err as { stdout?: string; stderr?: string; status?: number; message?: string }
+            const stdout = e.stdout?.trim() || ''
+            const stderr = e.stderr?.trim() || ''
+            const status = e.status ?? 1
+            return truncateResult(`Exit code: ${status}\n${stdout}\n${stderr}`.trim())
+          }
+        },
+      },
+      {
+        name: 'read_file',
+        description:
+          'Read a file from the server filesystem. Use for reading config files, logs, scripts, or any text file.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'Absolute or relative path to the file. Relative paths resolve from ~/.canonry/.',
+            },
+            maxLines: {
+              type: 'string',
+              description: 'Maximum number of lines to return. Default: 500.',
+            },
+          },
+          required: ['path'],
+        },
+        execute: async (args) => {
+          const filePath = args.path as string
+          const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+            path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+          const resolved = path.isAbsolute(filePath) ? filePath : path.join(configDir, filePath)
+          const maxLines = parseInt(args.maxLines as string || '500', 10) || 500
+
+          try {
+            const content = fs.readFileSync(resolved, 'utf-8')
+            const lines = content.split('\n')
+            if (lines.length > maxLines) {
+              return truncateResult(lines.slice(0, maxLines).join('\n') + `\n... (${lines.length - maxLines} more lines)`)
+            }
+            return truncateResult(content)
+          } catch (err) {
+            return `Error reading file: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+      },
+      {
+        name: 'write_file',
+        description:
+          'Write content to a file on the server filesystem. Creates parent directories if needed. Use for creating scripts, config files, or saving data.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'Absolute or relative path. Relative paths resolve from ~/.canonry/.',
+            },
+            content: {
+              type: 'string',
+              description: 'The file content to write.',
+            },
+            append: {
+              type: 'string',
+              description: 'Set to "true" to append instead of overwrite.',
+            },
+          },
+          required: ['path', 'content'],
+        },
+        execute: async (args) => {
+          const filePath = args.path as string
+          const content = args.content as string
+          const append = args.append === 'true'
+          const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+            path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+          const resolved = path.isAbsolute(filePath) ? filePath : path.join(configDir, filePath)
+
+          try {
+            fs.mkdirSync(path.dirname(resolved), { recursive: true })
+            if (append) {
+              fs.appendFileSync(resolved, content, 'utf-8')
+            } else {
+              fs.writeFileSync(resolved, content, 'utf-8')
+            }
+            return JSON.stringify({ written: resolved, bytes: content.length, append })
+          } catch (err) {
+            return `Error writing file: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+      },
+      {
+        name: 'list_files',
+        description:
+          'List files and directories at a given path. Useful for exploring the filesystem, finding configs, logs, or downloaded files.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: {
+              type: 'string',
+              description: 'Directory path to list. Defaults to ~/.canonry/.',
+            },
+          },
+          required: [],
+        },
+        execute: async (args) => {
+          const dirPath = args.path as string | undefined
+          const configDir = process.env.CANONRY_CONFIG_DIR?.trim() ||
+            path.join(process.env.HOME || process.env.USERPROFILE || '', '.canonry')
+          const resolved = dirPath ? (path.isAbsolute(dirPath) ? dirPath : path.join(configDir, dirPath)) : configDir
+
+          try {
+            const entries = fs.readdirSync(resolved, { withFileTypes: true })
+            const items = entries.map(e => ({
+              name: e.name,
+              type: e.isDirectory() ? 'directory' : 'file',
+              size: e.isFile() ? fs.statSync(path.join(resolved, e.name)).size : undefined,
+            }))
+            return JSON.stringify(items, null, 2)
+          } catch (err) {
+            return `Error listing directory: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+      },
+      {
+        name: 'http_request',
+        description:
+          'Make an HTTP request to any URL. Use for fetching web pages, APIs, downloading data, or checking URLs. Supports GET and POST.',
+        parameters: {
+          type: 'object',
+          properties: {
+            url: {
+              type: 'string',
+              description: 'The URL to request.',
+            },
+            method: {
+              type: 'string',
+              description: 'HTTP method. Default: GET.',
+              enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+            },
+            body: {
+              type: 'string',
+              description: 'Request body (for POST/PUT/PATCH).',
+            },
+            headers: {
+              type: 'string',
+              description: 'JSON-encoded headers object.',
+            },
+          },
+          required: ['url'],
+        },
+        execute: async (args) => {
+          const url = args.url as string
+          const method = (args.method as string) || 'GET'
+          const headers: Record<string, string> = { 'User-Agent': 'Aero/1.0 (canonry agent)' }
+
+          if (args.headers) {
+            try {
+              Object.assign(headers, JSON.parse(args.headers as string))
+            } catch { /* ignore malformed headers */ }
+          }
+
+          try {
+            const res = await fetch(url, {
+              method,
+              headers,
+              body: args.body as string | undefined,
+              signal: AbortSignal.timeout(30_000),
+            })
+            const text = await res.text()
+            return truncateResult(`HTTP ${res.status} ${res.statusText}\n\n${text}`)
+          } catch (err) {
+            return `HTTP request failed: ${err instanceof Error ? err.message : String(err)}`
+          }
+        },
+      },
+    )
+  }
+
+  return tools
 }
diff --git a/packages/canonry/src/commands/agent.ts b/packages/canonry/src/commands/agent.ts
index 23f2e7a..1481287 100644
--- a/packages/canonry/src/commands/agent.ts
+++ b/packages/canonry/src/commands/agent.ts
@@ -52,15 +52,40 @@ export async function agentAsk(project: string, message: string, opts?: {
   }
 
   if (opts?.format !== 'json') {
-    console.log('Aero is thinking...\n')
+    process.stdout.write('Aero is thinking...')
   }
 
-  const result = await client.sendAgentMessage(project, threadId, message, opts?.provider)
+  await client.sendAgentMessage(project, threadId, message, opts?.provider)
+
+  // Poll until the agent finishes processing
+  let response = ''
+  for (let i = 0; i < 120; i++) {
+    await new Promise(r => setTimeout(r, 1500))
+    const data = await client.getAgentThread(project, threadId) as AgentThread & {
+      messages: AgentMessage[]
+      status: string
+      error: string | null
+    }
+    if (data.status !== 'processing') {
+      // Find the last assistant text message (not a tool call)
+      const assistantMsgs = data.messages.filter(m => m.role === 'assistant' && !m.toolName)
+      response = assistantMsgs[assistantMsgs.length - 1]?.content ?? ''
+      if (data.error) {
+        console.error(`\nError: ${data.error}`)
+        process.exitCode = 1
+        return
+      }
+      break
+    }
+    if (opts?.format !== 'json') process.stdout.write('.')
+  }
+
+  if (opts?.format !== 'json') console.log('\n')
 
   if (opts?.format === 'json') {
-    console.log(JSON.stringify({ threadId, response: result.response }, null, 2))
+    console.log(JSON.stringify({ threadId, response }, null, 2))
   } else {
-    console.log(result.response)
+    console.log(response)
   }
 }
 
diff --git a/packages/canonry/src/config.ts b/packages/canonry/src/config.ts
index f99cca9..1128333 100644
--- a/packages/canonry/src/config.ts
+++ b/packages/canonry/src/config.ts
@@ -67,6 +67,8 @@ export interface CanonryConfig {
     maxHistory?: number
     /** Whether the agent is enabled (default: true if any provider is configured) */
     enabled?: boolean
+    /** Enable system tools: shell execution, file I/O, HTTP requests (default: false) */
+    systemTools?: boolean
   }
 }
 
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 069ce86..04284ca 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -533,7 +533,9 @@ function buildAgentHandler(
     const project = db.select().from(projects).where(eq(projects.id, projectId)).get()
     if (!project) throw new Error(`Project ${projectId} not found`)
 
-    const tools = buildTools(services, apiClient, project.name)
+    const tools = buildTools(services, apiClient, project.name, {
+      systemTools: agentConf.systemTools ?? false,
+    })
 
     return agentChat(threadId, message, {
       store,
@@ -546,7 +548,8 @@ function buildAgentHandler(
         country: project.country,
         language: project.language,
       },
-      maxSteps: agentConf.maxSteps ?? 10,
+      systemTools: agentConf.systemTools ?? false,
+      maxSteps: agentConf.maxSteps ?? 15,
       maxHistoryMessages: agentConf.maxHistory ?? 30,
     })
   }

From 840dc7df49f40f8e95c59d1e9fa6597aefa5d3a8 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:22:40 -0400
Subject: [PATCH 14/16] =?UTF-8?q?fix(agent):=20reduce=20token=20bloat=20?=
 =?UTF-8?q?=E2=80=94=20compress=20old=20tool=20results=20and=20add=20reque?=
 =?UTF-8?q?st=20size=20logging?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Reduce default maxHistoryMessages from 30 to 20 (fewer stale messages)
- Compress tool results older than 8 rows to 500 chars to prevent large
  get_evidence/get_memory results from inflating every subsequent request
- Add stderr logging per request: ~N tokens (M chars, K messages) for debugging
- Version 1.17.0 → 1.18.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 apps/web/src/App.tsx               | 574 ++++++++++++++++++++++++++---
 apps/web/src/styles.css            | 109 +++++-
 package.json                       |   2 +-
 packages/canonry/package.json      |   2 +-
 packages/canonry/src/agent/llm.ts  |  12 +
 packages/canonry/src/agent/loop.ts |  37 +-
 packages/canonry/src/server.ts     |   2 +-
 7 files changed, 673 insertions(+), 65 deletions(-)

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 3f4bd87..90813cb 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -6,8 +6,13 @@ import * as Dialog from '@radix-ui/react-dialog'
 import {
   Activity,
   Bot,
+  Brain,
   Check,
+  ChevronDown,
   ChevronRight,
+  ChevronUp,
+  FileText,
+  Loader2,
   MessageSquare,
   Pencil,
   Download,
@@ -19,9 +24,11 @@ import {
   Rocket,
   Send,
   Settings,
+  Terminal,
   Trash2,
   Users,
   X,
+  Zap,
 } from 'lucide-react'
 import { effectiveDomains, normalizeProjectDomain } from '@ainyc/canonry-contracts'
 
@@ -5437,6 +5444,350 @@ function renderMarkdown(text: string): React.ReactNode {
   return <>{elements}</>
 }
 
+// ── Aero tool call rendering helpers ────────────────────────────────
+
+type AeroTurn =
+  | { type: 'user'; message: ApiAgentMessage }
+  | { type: 'assistant'; toolCalls: Array<{ call: ApiAgentMessage; result: ApiAgentMessage | null }>; response: ApiAgentMessage | null }
+
+function groupMessagesIntoTurns(messages: ApiAgentMessage[]): AeroTurn[] {
+  const turns: AeroTurn[] = []
+  let i = 0
+  while (i < messages.length) {
+    const msg = messages[i]
+    if (msg.role === 'user') {
+      turns.push({ type: 'user', message: msg })
+      i++
+    } else if (msg.role === 'assistant' && msg.toolName) {
+      // Start collecting tool calls for this assistant turn
+      const toolCalls: Array<{ call: ApiAgentMessage; result: ApiAgentMessage | null }> = []
+      while (i < messages.length && messages[i].role === 'assistant' && messages[i].toolName) {
+        const call = messages[i]
+        // Look for matching tool result
+        const resultIdx = messages.findIndex((m, j) => j > i && m.role === 'tool' && m.toolCallId === call.toolCallId)
+        toolCalls.push({ call, result: resultIdx !== -1 ? messages[resultIdx] : null })
+        i++
+      }
+      // Skip past tool result messages we already consumed
+      while (i < messages.length && messages[i].role === 'tool') i++
+      // Check if next message is the final text response
+      let response: ApiAgentMessage | null = null
+      if (i < messages.length && messages[i].role === 'assistant' && !messages[i].toolName) {
+        response = messages[i]
+        i++
+      }
+      turns.push({ type: 'assistant', toolCalls, response })
+    } else if (msg.role === 'assistant') {
+      turns.push({ type: 'assistant', toolCalls: [], response: msg })
+      i++
+    } else {
+      i++ // skip orphaned tool results
+    }
+  }
+  return turns
+}
+
+function toolCategory(name: string): 'read' | 'write' | 'system' | 'memory' {
+  if (name === 'get_memory' || name === 'save_memory') return 'memory'
+  if (name === 'run_command' || name === 'read_file' || name === 'write_file' || name === 'list_files' || name === 'http_request') return 'system'
+  if (name.startsWith('get_') || name.startsWith('list_') || name === 'inspect_url') return 'read'
+  return 'write'
+}
+
+function toolDisplayLabel(name: string, args: string | null): string {
+  const labels: Record<string, string> = {
+    get_status: 'Checking project status',
+    get_evidence: 'Fetching citation evidence',
+    get_timeline: 'Loading visibility timeline',
+    get_run_details: 'Loading run details',
+    list_keywords: 'Listing keywords',
+    list_competitors: 'Listing competitors',
+    get_gsc_performance: 'Fetching GSC performance',
+    get_gsc_coverage: 'Checking index coverage',
+    inspect_url: 'Inspecting URL',
+    run_sweep: 'Running visibility sweep',
+    add_keywords: 'Adding keywords',
+    remove_keywords: 'Removing keywords',
+    add_competitors: 'Adding competitors',
+    remove_competitors: 'Removing competitors',
+    update_project: 'Updating project settings',
+    get_memory: 'Loading memory',
+    save_memory: 'Saving observations',
+    list_files: 'Listing files',
+  }
+  if (name === 'run_command' && args) {
+    try { const p = JSON.parse(args); if (p.command) return `$ ${String(p.command).slice(0, 60)}${String(p.command).length > 60 ? '...' : ''}` } catch { /* */ }
+    return 'Executing command'
+  }
+  if (name === 'read_file' && args) {
+    try { const p = JSON.parse(args); if (p.path) return `Reading ${String(p.path).split('/').pop()}` } catch { /* */ }
+    return 'Reading file'
+  }
+  if (name === 'write_file' && args) {
+    try { const p = JSON.parse(args); if (p.path) return `Writing ${String(p.path).split('/').pop()}` } catch { /* */ }
+    return 'Writing file'
+  }
+  if (name === 'http_request' && args) {
+    try { const p = JSON.parse(args); return `${String(p.method || 'GET')} ${String(p.url).slice(0, 50)}${String(p.url).length > 50 ? '...' : ''}` } catch { /* */ }
+    return 'HTTP request'
+  }
+  return labels[name] || name
+}
+
+function toolIcon(name: string): React.ReactNode {
+  const cat = toolCategory(name)
+  const cls = 'h-3.5 w-3.5 shrink-0'
+  if (name === 'run_command') return <Terminal className={cls} />
+  if (name === 'read_file' || name === 'write_file' || name === 'list_files') return <FileText className={cls} />
+  if (name === 'http_request') return <Globe className={cls} />
+  if (cat === 'memory') return <Brain className={cls} />
+  if (name === 'run_sweep') return <Play className={cls} />
+  if (name.includes('keyword')) return <Zap className={cls} />
+  if (name.includes('competitor')) return <Users className={cls} />
+  return <Activity className={cls} />
+}
+
+function renderToolResult(name: string, content: string): React.ReactNode {
+  const cat = toolCategory(name)
+
+  // System tools: terminal-style rendering
+  if (name === 'run_command') {
+    return (
+      <pre className="aero-terminal-body">{content}</pre>
+    )
+  }
+
+  if (name === 'read_file') {
+    return <pre className="aero-terminal-body">{content}</pre>
+  }
+
+  if (name === 'http_request') {
+    const firstLine = content.split('\n')[0] || ''
+    const statusMatch = firstLine.match(/^HTTP (\d+)/)
+    const status = statusMatch ? parseInt(statusMatch[1], 10) : 0
+    const statusCls = status >= 200 && status < 300 ? 'text-emerald-400' : status >= 400 ? 'text-rose-400' : 'text-amber-400'
+    return (
+      <div>
+        {status > 0 && <span className={`text-[11px] font-mono font-medium ${statusCls}`}>{firstLine}</span>}
+        <pre className="aero-terminal-body mt-1">{content.split('\n').slice(status > 0 ? 2 : 0).join('\n')}</pre>
+      </div>
+    )
+  }
+
+  // Memory tools: minimal
+  if (name === 'get_memory' || name === 'save_memory') {
+    if (name === 'save_memory') {
+      try { const d = JSON.parse(content); return <span className="text-[11px] text-zinc-500">Saved {d.bytes} bytes</span> } catch { /* */ }
+    }
+    return <span className="text-[11px] text-zinc-500">{content.length > 100 ? 'Memory loaded' : content}</span>
+  }
+
+  // Write tool results: compact
+  if (name === 'write_file') {
+    try { const d = JSON.parse(content); return <span className="text-[11px] text-zinc-400">Wrote {d.bytes} bytes to <code className="aero-inline-code">{d.written}</code></span> } catch { /* */ }
+  }
+
+  // Try to parse JSON for structured rendering
+  try {
+    const data = JSON.parse(content)
+
+    // list_keywords / list_competitors: pill chips
+    if ((name === 'list_keywords' || name === 'list_competitors') && Array.isArray(data)) {
+      const items = data.map((item: unknown) => {
+        if (typeof item === 'string') return item
+        if (typeof item === 'object' && item !== null) return (item as Record<string, unknown>).keyword || (item as Record<string, unknown>).phrase || (item as Record<string, unknown>).domain || (item as Record<string, unknown>).name || JSON.stringify(item)
+        return String(item)
+      })
+      return (
+        <div className="flex flex-wrap gap-1.5">
+          {items.map((item, idx) => (
+            <span key={idx} className="aero-result-pill">{String(item)}</span>
+          ))}
+        </div>
+      )
+    }
+
+    // add/remove keywords/competitors: action result
+    if (name === 'add_keywords' || name === 'remove_keywords') {
+      const action = name === 'add_keywords' ? 'Added' : 'Removed'
+      const kws = data.added || data.removed || []
+      return <span className="text-[11px] text-zinc-400">{action} {kws.length} keyword{kws.length !== 1 ? 's' : ''}: {kws.join(', ')}</span>
+    }
+    if (name === 'add_competitors' || name === 'remove_competitors') {
+      const action = name === 'add_competitors' ? 'Added' : 'Removed'
+      const domains = data.added || data.removed || []
+      return <span className="text-[11px] text-zinc-400">{action} {domains.length} competitor{domains.length !== 1 ? 's' : ''}</span>
+    }
+
+    // run_sweep: status card
+    if (name === 'run_sweep') {
+      return (
+        <div className="flex items-center gap-2">
+          <span className="aero-result-pill bg-emerald-950/40 border-emerald-800/40 text-emerald-400">Started</span>
+          {data.id && <span className="text-[11px] text-zinc-500 font-mono">Run {String(data.id).slice(0, 8)}</span>}
+        </div>
+      )
+    }
+
+    // get_status: project summary
+    if (name === 'get_status' && data.project) {
+      const p = data.project
+      const runs = data.latestRuns || []
+      return (
+        <div className="space-y-1.5">
+          <div className="flex items-center gap-2 text-[12px]">
+            <span className="text-zinc-300 font-medium">{p.displayName || p.name}</span>
+            <span className="text-zinc-600">·</span>
+            <span className="text-zinc-500">{p.canonicalDomain || p.domain}</span>
+            <span className="text-zinc-600">·</span>
+            <span className="text-zinc-500">{p.country}, {p.language}</span>
+          </div>
+          {runs.length > 0 && (
+            <div className="flex flex-wrap gap-1.5">
+              {runs.map((r: Record<string, unknown>, idx: number) => {
+                const st = String(r.status || 'unknown')
+                const cls = st === 'completed' ? 'bg-emerald-950/40 border-emerald-800/40 text-emerald-400'
+                  : st === 'partial' ? 'bg-amber-950/40 border-amber-800/40 text-amber-400'
+                  : st === 'failed' ? 'bg-rose-950/40 border-rose-800/40 text-rose-400'
+                  : 'bg-zinc-800/40 border-zinc-700/40 text-zinc-400'
+                return <span key={idx} className={`aero-result-pill ${cls}`}>{st} {r.id ? `#${String(r.id).slice(0, 6)}` : ''}</span>
+              })}
+            </div>
+          )}
+        </div>
+      )
+    }
+
+    // get_evidence: citation table
+    if (name === 'get_evidence' && Array.isArray(data)) {
+      const rows = data.slice(0, 15) // limit rows
+      return (
+        <div className="aero-result-table-wrap">
+          <table className="aero-result-table">
+            <thead>
+              <tr>
+                <th>Keyword</th>
+                <th>Provider</th>
+                <th>Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((row: Record<string, unknown>, idx: number) => {
+                const state = String(row.citationState || row.state || row.cited || 'unknown')
+                const stateCls = state === 'cited' ? 'text-emerald-400' : state === 'not-cited' ? 'text-zinc-500' : state === 'lost' ? 'text-rose-400' : state === 'emerging' ? 'text-amber-400' : 'text-zinc-500'
+                return (
+                  <tr key={idx}>
+                    <td className="text-zinc-300">{String(row.keyword || row.phrase || '')}</td>
+                    <td className="text-zinc-500">{String(row.provider || row.model || '')}</td>
+                    <td className={stateCls}>{state}</td>
+                  </tr>
+                )
+              })}
+            </tbody>
+          </table>
+          {data.length > 15 && <span className="text-[10px] text-zinc-600 mt-1">+{data.length - 15} more rows</span>}
+        </div>
+      )
+    }
+
+    // get_timeline: text summary
+    if (name === 'get_timeline') {
+      if (Array.isArray(data) && data.length > 0) {
+        const latest = data[data.length - 1]
+        const earliest = data[0]
+        return (
+          <span className="text-[11px] text-zinc-400">
+            {data.length} data points · Latest visibility: {latest?.rate != null ? `${Math.round(Number(latest.rate) * 100)}%` : 'N/A'}
+            {earliest?.rate != null && latest?.rate != null ? ` (from ${Math.round(Number(earliest.rate) * 100)}%)` : ''}
+          </span>
+        )
+      }
+    }
+
+    // get_gsc_performance: compact metrics
+    if (name === 'get_gsc_performance') {
+      if (data.rows && Array.isArray(data.rows)) {
+        return (
+          <div className="aero-result-table-wrap">
+            <table className="aero-result-table">
+              <thead><tr><th>Query</th><th>Clicks</th><th>Impressions</th><th>CTR</th><th>Position</th></tr></thead>
+              <tbody>
+                {data.rows.slice(0, 10).map((r: Record<string, unknown>, idx: number) => (
+                  <tr key={idx}>
+                    <td className="text-zinc-300">{String((r.keys as string[])?.[0] || '')}</td>
+                    <td>{String(r.clicks || 0)}</td>
+                    <td>{String(r.impressions || 0)}</td>
+                    <td>{r.ctr != null ? `${(Number(r.ctr) * 100).toFixed(1)}%` : '-'}</td>
+                    <td>{r.position != null ? Number(r.position).toFixed(1) : '-'}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )
+      }
+    }
+
+    // Fallback: formatted JSON
+    return <pre className="aero-terminal-body">{JSON.stringify(data, null, 2)}</pre>
+
+  } catch {
+    // Not JSON — render as text
+    if (cat === 'system') {
+      return <pre className="aero-terminal-body">{content}</pre>
+    }
+    return <span className="text-[11px] text-zinc-400 whitespace-pre-wrap">{content.length > 300 ? content.slice(0, 300) + '...' : content}</span>
+  }
+}
+
+function ToolCallCard({ call, result, isActive }: { call: ApiAgentMessage; result: ApiAgentMessage | null; isActive: boolean }) {
+  const [expanded, setExpanded] = useState(false)
+  const cat = toolCategory(call.toolName!)
+  const borderCls = cat === 'system' ? 'aero-tool-card-system'
+    : cat === 'memory' ? 'aero-tool-card-memory'
+    : cat === 'write' ? 'aero-tool-card-write'
+    : 'aero-tool-card-read'
+
+  return (
+    <div className={`aero-tool-card ${borderCls} ${isActive ? 'aero-tool-active' : ''}`}>
+      <button
+        className="aero-tool-header"
+        onClick={() => result && setExpanded(!expanded)}
+        disabled={!result}
+      >
+        <span className="flex items-center gap-2 min-w-0">
+          {isActive ? <Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin text-zinc-400" /> : toolIcon(call.toolName!)}
+          <span className="text-[12px] text-zinc-400 truncate">{toolDisplayLabel(call.toolName!, call.toolArgs)}</span>
+        </span>
+        {result && (
+          expanded
+            ? <ChevronUp className="h-3 w-3 text-zinc-600 shrink-0" />
+            : <ChevronDown className="h-3 w-3 text-zinc-600 shrink-0" />
+        )}
+      </button>
+      {expanded && result && (
+        <div className="aero-tool-result">
+          {renderToolResult(call.toolName!, result.content)}
+        </div>
+      )}
+    </div>
+  )
+}
+
+const AERO_QUICK_ACTIONS = [
+  { label: "How's my visibility across providers?", icon: Activity },
+  { label: 'Run a fresh visibility sweep', icon: Play },
+  { label: 'Which keywords am I losing?', icon: Zap },
+  { label: 'Show my competitor landscape', icon: Users },
+  { label: 'What changed since my last run?', icon: Activity },
+]
+
+const AERO_INPUT_CHIPS = [
+  { label: 'Run sweep', msg: 'Run a fresh visibility sweep across all providers' },
+  { label: 'Check visibility', msg: "How's my visibility looking?" },
+  { label: 'Add keyword', msg: 'Add keywords: ' },
+]
+
 function AeroPage({ projects, providers }: {
   projects: Array<{ name: string; displayName?: string }>
   providers: Array<{ name: string; state: string }>
@@ -5479,7 +5830,7 @@ function AeroPage({ projects, providers }: {
     function loadThread() {
       fetchAgentThread(selectedProject, activeThreadId!)
         .then(data => {
-          setMessages(data.messages.filter(m => m.role !== 'tool' && !m.toolName))
+          setMessages(data.messages)
           if (data.status === 'processing') {
             setProcessing(true)
             // Start polling if not already
@@ -5566,7 +5917,7 @@ function AeroPage({ projects, providers }: {
       pollRef.current = setInterval(() => {
         fetchAgentThread(selectedProject, tid)
           .then(data => {
-            setMessages(data.messages.filter(m => m.role !== 'tool' && !m.toolName))
+            setMessages(data.messages)
             if (data.status !== 'processing') {
               setProcessing(false)
               if (data.error) setError(data.error)
@@ -5590,13 +5941,70 @@ function AeroPage({ projects, providers }: {
     }
   }
 
-  const visibleMessages = messages.filter(m => m.role !== 'tool' && !m.toolName)
+  const turns = useMemo(() => groupMessagesIntoTurns(messages), [messages])
+
+  // Check if the last assistant turn has tool calls without a final response yet (still working)
+  const lastTurn = turns[turns.length - 1]
+  const hasActiveToolCalls = processing && lastTurn?.type === 'assistant' && lastTurn.toolCalls.length > 0 && !lastTurn.response
+
+  async function handleQuickAction(msg: string) {
+    if (!selectedProject) return
+    const thread = await createAgentThread(selectedProject)
+    setThreads(prev => [thread, ...prev])
+    setActiveThreadId(thread.id)
+    setMessages([])
+    setError(null)
+    // Small delay to let state settle, then send the message
+    setTimeout(async () => {
+      const optimisticUser: ApiAgentMessage = {
+        id: `temp-${Date.now()}`,
+        threadId: thread.id,
+        role: 'user',
+        content: msg,
+        toolName: null,
+        toolArgs: null,
+        toolCallId: null,
+        createdAt: new Date().toISOString(),
+      }
+      setMessages([optimisticUser])
+      setProcessing(true)
+      try {
+        await sendAgentMessage(selectedProject, thread.id, msg, selectedProvider || undefined)
+        if (pollRef.current) clearInterval(pollRef.current)
+        pollRef.current = setInterval(() => {
+          fetchAgentThread(selectedProject, thread.id)
+            .then(data => {
+              setMessages(data.messages)
+              if (data.status !== 'processing') {
+                setProcessing(false)
+                if (data.error) setError(data.error)
+                if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null }
+                fetchAgentThreads(selectedProject).then(setThreads).catch(() => {})
+              }
+            })
+            .catch(() => {})
+        }, 1500)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err))
+        setProcessing(false)
+      }
+    }, 100)
+  }
+
+  function handleChipClick(msg: string) {
+    setInput(msg)
+  }
+
+  // Count visible (non-tool) messages for empty state check
+  const hasVisibleContent = turns.some(t => t.type === 'user' || (t.type === 'assistant' && (t.response || t.toolCalls.length > 0)))
 
   return (
     <div className="page-container aero-page">
       <div className="page-header">
         <div className="page-header-left">
-          <h1 className="page-title">Aero</h1>
+          <h1 className="page-title flex items-center gap-2">
+            Aero
+          </h1>
           <p className="page-subtitle">AI-powered AEO analyst</p>
         </div>
         <div className="page-header-right flex items-center gap-3">
@@ -5700,39 +6108,95 @@ function AeroPage({ projects, providers }: {
         {/* Chat area */}
         <div className="aero-chat">
           {!activeThreadId ? (
+            /* ── Enhanced empty state: capability showcase ── */
             <div className="aero-empty">
-              <Bot className="h-10 w-10 text-zinc-700" />
-              <h2 className="text-base font-medium text-zinc-300 mt-3">Ask Aero anything</h2>
-              <p className="text-[13px] text-zinc-500 mt-1 max-w-md text-center">
-                Select a project and start a new chat to analyze your AI citation visibility,
-                compare providers, spot trends, and get actionable recommendations.
-              </p>
-              <Button onClick={handleNewThread} variant="secondary" className="mt-4 gap-1.5">
-                <Plus className="h-3.5 w-3.5" />
-                Start a conversation
-              </Button>
+              <Bot className="h-10 w-10 text-zinc-600" />
+              <h2 className="text-base font-medium text-zinc-200 mt-3">Aero</h2>
+              <p className="text-[12px] text-zinc-500 mt-0.5">AEO analyst with full system access</p>
+
+              {/* Capability pills */}
+              <div className="flex flex-wrap gap-2 mt-4 justify-center">
+                <span className="aero-capability-pill"><Activity className="h-3 w-3" /> Citation Analysis</span>
+                <span className="aero-capability-pill"><Play className="h-3 w-3" /> Run Sweeps</span>
+                <span className="aero-capability-pill"><Brain className="h-3 w-3" /> Persistent Memory</span>
+                <span className="aero-capability-pill"><Terminal className="h-3 w-3" /> System Access</span>
+              </div>
+
+              {/* Quick actions */}
+              <div className="mt-6 w-full max-w-md">
+                <p className="text-[10px] uppercase tracking-[0.18em] text-zinc-600 mb-2 px-1">Quick actions</p>
+                <div className="flex flex-col gap-1">
+                  {AERO_QUICK_ACTIONS.map((action, idx) => (
+                    <button
+                      key={idx}
+                      className="aero-quick-action"
+                      onClick={() => handleQuickAction(action.label)}
+                    >
+                      <action.icon className="h-3.5 w-3.5 text-zinc-600 shrink-0" />
+                      <span className="flex-1 text-left text-[13px] text-zinc-400">{action.label}</span>
+                      <ChevronRight className="h-3 w-3 text-zinc-700" />
+                    </button>
+                  ))}
+                </div>
+              </div>
             </div>
           ) : (
             <>
-              {/* Messages */}
+              {/* Messages — rendered as turns */}
               <div className="aero-messages">
-                {visibleMessages.length === 0 && !processing && (
+                {!hasVisibleContent && !processing && (
                   <div className="aero-empty">
                     <Bot className="h-8 w-8 text-zinc-700" />
                     <p className="text-[13px] text-zinc-500 mt-2">Send a message to get started.</p>
+                    {/* Suggested prompts for empty thread */}
+                    <div className="flex flex-wrap gap-1.5 mt-4 justify-center max-w-sm">
+                      {AERO_QUICK_ACTIONS.slice(0, 3).map((action, idx) => (
+                        <button key={idx} className="aero-chip" onClick={() => { setInput(action.label) }}>
+                          {action.label}
+                        </button>
+                      ))}
+                    </div>
                   </div>
                 )}
-                {visibleMessages.map(msg => (
-                  <div key={msg.id} className={`aero-msg ${msg.role}`}>
-                    <div className="aero-msg-label">
-                      {msg.role === 'user' ? 'You' : 'Aero'}
-                    </div>
-                    <div className={`aero-msg-content ${msg.role === 'assistant' ? 'aero-md' : ''}`}>
-                      {msg.role === 'assistant' ? renderMarkdown(msg.content) : msg.content}
+                {turns.map((turn, tidx) => {
+                  if (turn.type === 'user') {
+                    return (
+                      <div key={turn.message.id} className="aero-msg user">
+                        <div className="aero-msg-label">You</div>
+                        <div className="aero-msg-content">{turn.message.content}</div>
+                      </div>
+                    )
+                  }
+
+                  // Assistant turn
+                  const isLastTurn = tidx === turns.length - 1
+                  return (
+                    <div key={`turn-${tidx}`} className="aero-msg assistant">
+                      <div className="aero-msg-label">Aero</div>
+                      {/* Tool call cards */}
+                      {turn.toolCalls.length > 0 && (
+                        <div className="flex flex-col gap-1.5 mb-2">
+                          {turn.toolCalls.map((tc, tcIdx) => (
+                            <ToolCallCard
+                              key={tc.call.id}
+                              call={tc.call}
+                              result={tc.result}
+                              isActive={isLastTurn && processing && !tc.result && tcIdx === turn.toolCalls.length - 1}
+                            />
+                          ))}
+                        </div>
+                      )}
+                      {/* Final text response */}
+                      {turn.response && (
+                        <div className="aero-msg-content aero-md">
+                          {renderMarkdown(turn.response.content)}
+                        </div>
+                      )}
                     </div>
-                  </div>
-                ))}
-                {processing && (
+                  )
+                })}
+                {/* Show thinking indicator only when processing and no tool calls visible yet */}
+                {processing && !hasActiveToolCalls && turns[turns.length - 1]?.type !== 'assistant' && (
                   <div className="aero-msg assistant">
                     <div className="aero-msg-label">Aero</div>
                     <div className="aero-msg-content text-zinc-500">
@@ -5748,30 +6212,40 @@ function AeroPage({ projects, providers }: {
                 <div ref={messagesEndRef} />
               </div>
 
-              {/* Input */}
-              <div className="aero-input-area">
-                <textarea
-                  className="aero-input"
-                  value={input}
-                  onChange={e => {
-                    setInput(e.target.value)
-                    // Auto-expand: reset height then set to scrollHeight
-                    e.target.style.height = 'auto'
-                    e.target.style.height = Math.min(e.target.scrollHeight, 200) + 'px'
-                  }}
-                  onKeyDown={handleKeyDown}
-                  placeholder="Ask about your visibility, trends, competitors..."
-                  rows={1}
-                  disabled={processing}
-                />
-                <button
-                  className="aero-send"
-                  onClick={handleSend}
-                  disabled={!input.trim() || processing}
-                  aria-label="Send message"
-                >
-                  <Send className="h-4 w-4" />
-                </button>
+              {/* Quick chips + Input */}
+              <div className="aero-input-wrap">
+                {!processing && messages.length === 0 && (
+                  <div className="aero-quick-chips">
+                    {AERO_INPUT_CHIPS.map((chip, idx) => (
+                      <button key={idx} className="aero-chip" onClick={() => handleChipClick(chip.msg)}>
+                        {chip.label}
+                      </button>
+                    ))}
+                  </div>
+                )}
+                <div className="aero-input-area">
+                  <textarea
+                    className="aero-input"
+                    value={input}
+                    onChange={e => {
+                      setInput(e.target.value)
+                      e.target.style.height = 'auto'
+                      e.target.style.height = Math.min(e.target.scrollHeight, 200) + 'px'
+                    }}
+                    onKeyDown={handleKeyDown}
+                    placeholder="Ask about your visibility, trends, competitors..."
+                    rows={1}
+                    disabled={processing}
+                  />
+                  <button
+                    className="aero-send"
+                    onClick={handleSend}
+                    disabled={!input.trim() || processing}
+                    aria-label="Send message"
+                  >
+                    <Send className="h-4 w-4" />
+                  </button>
+                </div>
               </div>
             </>
           )}
diff --git a/apps/web/src/styles.css b/apps/web/src/styles.css
index 72b8acb..2d3cb82 100644
--- a/apps/web/src/styles.css
+++ b/apps/web/src/styles.css
@@ -1503,8 +1503,12 @@
            rounded-lg px-4 py-2.5 mr-auto max-w-[85%];
   }
 
+  .aero-input-wrap {
+    @apply border-t border-zinc-800/60;
+  }
+
   .aero-input-area {
-    @apply flex items-end gap-2 border-t border-zinc-800/60 p-3;
+    @apply flex items-end gap-2 p-3;
   }
 
   .aero-input {
@@ -1534,4 +1538,107 @@
     content: '...';
     animation: aero-dots 1.2s steps(1) infinite;
   }
+
+  /* ── Tool call cards ── */
+
+  .aero-tool-card {
+    @apply bg-zinc-900/40 border border-zinc-800/40 rounded-lg overflow-hidden;
+    border-left-width: 2px;
+  }
+
+  .aero-tool-card-read {
+    @apply border-l-zinc-600;
+  }
+
+  .aero-tool-card-write {
+    @apply border-l-amber-500;
+  }
+
+  .aero-tool-card-system {
+    @apply border-l-emerald-500;
+  }
+
+  .aero-tool-card-memory {
+    @apply border-l-blue-500;
+  }
+
+  .aero-tool-active {
+    animation: aero-tool-pulse 1.5s ease-in-out infinite;
+  }
+
+  @keyframes aero-tool-pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.6; }
+  }
+
+  .aero-tool-header {
+    @apply flex items-center justify-between w-full px-3 py-2
+           text-left cursor-pointer
+           hover:bg-zinc-800/20 transition-colors;
+  }
+
+  .aero-tool-header:disabled {
+    @apply cursor-default;
+  }
+
+  .aero-tool-result {
+    @apply px-3 pb-2.5 pt-0.5
+           border-t border-zinc-800/30
+           max-h-64 overflow-y-auto;
+  }
+
+  .aero-terminal-body {
+    @apply bg-zinc-950 border border-zinc-800/50 rounded px-3 py-2
+           text-[11px] leading-relaxed font-mono text-zinc-400
+           overflow-x-auto max-h-48 overflow-y-auto whitespace-pre-wrap;
+  }
+
+  .aero-result-pill {
+    @apply inline-flex items-center gap-1
+           rounded-full bg-zinc-800/60 border border-zinc-700/40
+           px-2.5 py-0.5 text-[11px] text-zinc-400;
+  }
+
+  .aero-result-table-wrap {
+    @apply overflow-x-auto;
+  }
+
+  .aero-result-table {
+    @apply w-full text-[11px];
+  }
+
+  .aero-result-table th {
+    @apply text-left text-[10px] uppercase tracking-wider text-zinc-600 pb-1 pr-3 font-medium;
+  }
+
+  .aero-result-table td {
+    @apply py-0.5 pr-3 text-zinc-500;
+  }
+
+  /* ── Capability pills & quick actions ── */
+
+  .aero-capability-pill {
+    @apply inline-flex items-center gap-1.5
+           rounded-full bg-zinc-900/60 border border-zinc-800/50
+           px-3 py-1 text-[11px] text-zinc-500;
+  }
+
+  .aero-quick-action {
+    @apply flex items-center gap-3 px-3 py-2.5
+           rounded-lg border border-zinc-800/30
+           bg-zinc-900/20
+           hover:bg-zinc-800/30 hover:border-zinc-700/40
+           transition-colors cursor-pointer;
+  }
+
+  .aero-quick-chips {
+    @apply flex flex-wrap gap-1.5 px-3 pt-2;
+  }
+
+  .aero-chip {
+    @apply rounded-full bg-zinc-800/40 border border-zinc-700/40
+           px-2.5 py-1 text-[11px] text-zinc-500
+           hover:text-zinc-300 hover:bg-zinc-800/60
+           cursor-pointer transition-colors;
+  }
 }
diff --git a/package.json b/package.json
index 18492e2..a64b8c6 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "canonry",
   "private": true,
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "packageManager": "pnpm@10.28.2",
   "scripts": {
diff --git a/packages/canonry/package.json b/packages/canonry/package.json
index b6f5360..09e019b 100644
--- a/packages/canonry/package.json
+++ b/packages/canonry/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "description": "The ultimate open-source AEO monitoring tool - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index fcc32b0..7e182b9 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -48,11 +48,23 @@ const DEFAULT_MODELS: Record<string, string> = {
   gemini: 'gemini-2.5-flash',
 }
 
+/** Rough character count of a chat request (messages + tool defs). */
+function estimateRequestSize(messages: ChatMessage[], tools: AgentTool[]): number {
+  const msgSize = messages.reduce((sum, m) => sum + (m.content?.length ?? 0) + JSON.stringify(m.tool_calls ?? []).length, 0)
+  const toolSize = tools.reduce((sum, t) => sum + t.description.length + JSON.stringify(t.parameters).length, 0)
+  return msgSize + toolSize
+}
+
 export async function chatCompletion(
   config: LlmConfig,
   messages: ChatMessage[],
   tools: AgentTool[],
 ): Promise<CompletionResponse> {
+  const approxChars = estimateRequestSize(messages, tools)
+  // ~4 chars per token
+  const approxTokens = Math.round(approxChars / 4)
+  process.stderr.write(`[aero] ${config.provider} request: ~${approxTokens} tokens (${approxChars} chars, ${messages.length} messages)\n`)
+
   if (config.provider === 'claude') {
     return claudeCompletion(config, messages, tools)
   }
diff --git a/packages/canonry/src/agent/loop.ts b/packages/canonry/src/agent/loop.ts
index bd10a4b..52b248c 100644
--- a/packages/canonry/src/agent/loop.ts
+++ b/packages/canonry/src/agent/loop.ts
@@ -51,7 +51,7 @@ export async function agentChat(
   userMessage: string,
   opts: LoopOptions,
 ): Promise<string> {
-  const { store, tools, llmConfig, project, maxSteps = 10, maxHistoryMessages = 30 } = opts
+  const { store, tools, llmConfig, project, maxSteps = 10, maxHistoryMessages = 20 } = opts
 
   // Persist user message
   await store.addMessage({
@@ -82,6 +82,21 @@ export async function agentChat(
     { role: 'system', content: systemPrompt },
   ]
 
+  // Compress tool results from older turns to keep token counts manageable.
+  // Tool results from recent turns (last 8 rows) are kept full; older ones are
+  // capped at 500 chars to prevent large results (get_evidence, etc.) from
+  // inflating every subsequent request.
+  const COMPRESS_AFTER = Math.max(0, history.length - 8)
+  const compressedHistory = history.map((msg, idx) => {
+    if (idx < COMPRESS_AFTER && msg.role === 'tool' && msg.content.length > 500) {
+      return {
+        ...msg,
+        content: msg.content.slice(0, 500) + `\n... (${msg.content.length - 500} chars compressed from history)`,
+      }
+    }
+    return msg
+  })
+
   // Convert stored messages to LLM format.
   // The DB stores each tool call as a separate assistant row followed by its
   // tool result row. We need to group consecutive tool-call/result pairs into
@@ -89,8 +104,8 @@ export async function agentChat(
   // tool_result blocks to reference tool_use blocks in the immediately
   // preceding assistant message.
   let i = 0
-  while (i < history.length) {
-    const msg = history[i]
+  while (i < compressedHistory.length) {
+    const msg = compressedHistory[i]
 
     if (msg.role === 'user') {
       messages.push({ role: 'user', content: msg.content })
@@ -101,8 +116,8 @@ export async function agentChat(
       const toolCalls: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }> = []
       const toolResults: ChatMessage[] = []
 
-      while (i < history.length && history[i].role === 'assistant' && history[i].toolName) {
-        const tc = history[i]
+      while (i < compressedHistory.length && compressedHistory[i].role === 'assistant' && compressedHistory[i].toolName) {
+        const tc = compressedHistory[i]
         const callId = tc.toolCallId ?? tc.id
         toolCalls.push({
           id: callId,
@@ -110,25 +125,25 @@ export async function agentChat(
           function: { name: tc.toolName!, arguments: tc.toolArgs ?? '{}' },
         })
         // Look for the matching tool result (should be next or nearby)
-        const resultIdx = history.findIndex((m, j) => j > i && m.role === 'tool' && m.toolCallId === callId)
+        const resultIdx = compressedHistory.findIndex((m, j) => j > i && m.role === 'tool' && m.toolCallId === callId)
         if (resultIdx !== -1) {
           toolResults.push({
             role: 'tool',
-            content: history[resultIdx].content,
+            content: compressedHistory[resultIdx].content,
             tool_call_id: callId,
           })
         }
         i++
       }
       // Skip past any tool result rows we already consumed
-      while (i < history.length && history[i].role === 'tool') {
+      while (i < compressedHistory.length && compressedHistory[i].role === 'tool') {
         // Check if this result was already captured above
-        const alreadyCaptured = toolResults.some(r => r.tool_call_id === history[i].toolCallId)
+        const alreadyCaptured = toolResults.some(r => r.tool_call_id === compressedHistory[i].toolCallId)
         if (!alreadyCaptured) {
           toolResults.push({
             role: 'tool',
-            content: history[i].content,
-            tool_call_id: history[i].toolCallId ?? undefined,
+            content: compressedHistory[i].content,
+            tool_call_id: compressedHistory[i].toolCallId ?? undefined,
           })
         }
         i++
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 04284ca..8834ae9 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -550,7 +550,7 @@ function buildAgentHandler(
       },
       systemTools: agentConf.systemTools ?? false,
       maxSteps: agentConf.maxSteps ?? 15,
-      maxHistoryMessages: agentConf.maxHistory ?? 30,
+      maxHistoryMessages: agentConf.maxHistory ?? 20,
     })
   }
 }

From 0787d128f3081dc1870d24714caedd89c31eb494 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 16:33:29 -0400
Subject: [PATCH 15/16] fix(agent): rewrite convertToClaudeMessages to build
 valid output by construction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous two-pass validation approach had edge cases where the passes
interacted in ways that still left orphaned tool_result blocks (causing
Claude 400 errors at messages.0.content.0).

New approach: state machine that walks the OpenAI-format messages once and
only emits a tool call group (assistant+tool_use → user+tool_result) when
ALL tool_use blocks have matching tool_result blocks. Incomplete groups from
truncated history or server crashes are dropped entirely. Consecutive
same-role messages are merged at the end.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/canonry/src/agent/llm.ts | 197 +++++++++++++-----------------
 1 file changed, 85 insertions(+), 112 deletions(-)

diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index 7e182b9..ae92334 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -209,138 +209,111 @@ async function claudeCompletion(
   return { type: 'text', text: textBlock?.text ?? '' }
 }
 
+/**
+ * Convert OpenAI-format messages to Claude Messages API format.
+ *
+ * Uses a state-machine approach that builds valid output by construction:
+ * - Tool call groups (assistant+tool_use → user+tool_result) are only emitted
+ *   when ALL tool_use blocks have matching tool_result blocks. Incomplete groups
+ *   (orphaned by history truncation or crashes) are dropped entirely.
+ * - Consecutive same-role messages are merged.
+ * - Orphaned tool result messages (no preceding assistant tool_use) are dropped.
+ * - Result always starts with a user message (Claude requirement).
+ */
 function convertToClaudeMessages(
   messages: ChatMessage[],
 ): Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }> {
-  const result: Array<{ role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }> = []
+  type ClaudeMsg = { role: 'user' | 'assistant'; content: string | Array<Record<string, unknown>> }
+  const result: ClaudeMsg[] = []
+
+  let i = 0
+  while (i < messages.length) {
+    const msg = messages[i]
 
-  for (const msg of messages) {
     if (msg.role === 'user') {
       result.push({ role: 'user', content: msg.content ?? '' })
-    } else if (msg.role === 'assistant') {
-      if (msg.tool_calls && msg.tool_calls.length > 0) {
-        const blocks: Array<Record<string, unknown>> = []
-        for (const tc of msg.tool_calls) {
-          let input: Record<string, unknown>
-          try {
-            input = JSON.parse(tc.function.arguments) as Record<string, unknown>
-          } catch {
-            input = {}
-          }
-          blocks.push({
-            type: 'tool_use',
-            id: tc.id,
-            name: tc.function.name,
-            input,
-          })
-        }
-        // Merge consecutive assistant tool-call messages into one.
-        // The DB stores each tool call separately but Claude needs them grouped.
-        const prev = result[result.length - 1]
-        if (prev && prev.role === 'assistant' && Array.isArray(prev.content)) {
-          prev.content.push(...blocks)
-        } else {
-          result.push({ role: 'assistant', content: blocks })
-        }
-      } else {
-        result.push({ role: 'assistant', content: msg.content ?? '' })
-      }
-    } else if (msg.role === 'tool') {
-      // Claude expects tool results as user messages with tool_result content blocks.
-      // Merge consecutive tool results into one user message to avoid
-      // consecutive same-role messages (which Claude rejects).
-      const toolBlock = {
-        type: 'tool_result',
-        tool_use_id: msg.tool_call_id,
-        content: msg.content ?? '',
+      i++
+    } else if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+      // ── Tool call group ──────────────────────────────────────────────────────
+      // Collect all consecutive assistant+tool_calls messages into one group.
+      // DB stores each tool call as a separate row; LLM sends them all at once.
+      const allToolCalls: ToolCall[] = [...msg.tool_calls]
+      let j = i + 1
+      while (j < messages.length && messages[j].role === 'assistant' && messages[j].tool_calls?.length) {
+        allToolCalls.push(...(messages[j].tool_calls ?? []))
+        j++
       }
-      const prev = result[result.length - 1]
-      if (prev && prev.role === 'user' && Array.isArray(prev.content)) {
-        prev.content.push(toolBlock)
-      } else {
-        result.push({
-          role: 'user',
-          content: [toolBlock],
-        })
+
+      // Build a map from tool_call_id → tool_use block
+      const toolUseById = new Map<string, Record<string, unknown>>()
+      for (const tc of allToolCalls) {
+        let input: Record<string, unknown>
+        try { input = JSON.parse(tc.function.arguments) as Record<string, unknown> } catch { input = {} }
+        toolUseById.set(tc.id, { type: 'tool_use', id: tc.id, name: tc.function.name, input })
       }
-    }
-  }
 
-  // ── Validate tool_use ↔ tool_result pairing ──────────────
-  // Claude requires:
-  //   1. Every tool_use in an assistant message must have a tool_result in the NEXT user message
-  //   2. Every tool_result in a user message must reference a tool_use in the PREVIOUS assistant message
-  // We do multiple passes to clean up both directions.
-
-  // Pass 1: For each assistant message with tool_use blocks, ensure the next
-  // message is a user message containing matching tool_result blocks.
-  // If not, remove the orphaned tool_use blocks (or the whole assistant message).
-  for (let idx = 0; idx < result.length; idx++) {
-    const entry = result[idx]
-    if (entry.role !== 'assistant' || !Array.isArray(entry.content)) continue
-
-    const toolUseBlocks = (entry.content as Array<Record<string, unknown>>).filter(b => b.type === 'tool_use')
-    if (toolUseBlocks.length === 0) continue
-
-    // Collect tool_result IDs from the next message
-    const next = idx + 1 < result.length ? result[idx + 1] : null
-    const resultIds = new Set<string>()
-    if (next && next.role === 'user' && Array.isArray(next.content)) {
-      for (const b of next.content as Array<Record<string, unknown>>) {
-        if (b.type === 'tool_result' && typeof b.tool_use_id === 'string') {
-          resultIds.add(b.tool_use_id)
+      // Scan ahead and collect matching tool_result blocks (consume all consecutive 'tool' rows)
+      const toolResultBlocks: Array<Record<string, unknown>> = []
+      while (j < messages.length && messages[j].role === 'tool') {
+        const toolMsg = messages[j]
+        if (toolMsg.tool_call_id && toolUseById.has(toolMsg.tool_call_id)) {
+          toolResultBlocks.push({
+            type: 'tool_result',
+            tool_use_id: toolMsg.tool_call_id,
+            content: toolMsg.content ?? '',
+          })
         }
+        j++
       }
-    }
 
-    // Remove tool_use blocks without matching results
-    entry.content = (entry.content as Array<Record<string, unknown>>).filter(
-      b => b.type !== 'tool_use' || resultIds.has(b.id as string),
-    )
-
-    // If the assistant message is now empty, remove it
-    if ((entry.content as Array<Record<string, unknown>>).length === 0) {
-      result.splice(idx, 1)
-      idx--
-    }
-  }
+      // Only emit the group if every tool_use has a matching tool_result.
+      // Incomplete groups (truncated history, server crash mid-execution) are dropped.
+      const allMatched = allToolCalls.every(tc =>
+        toolResultBlocks.some(r => r.tool_use_id === tc.id),
+      )
 
-  // Pass 2: For each user message with tool_result blocks, ensure the previous
-  // message is an assistant message containing matching tool_use blocks.
-  for (let idx = 0; idx < result.length; idx++) {
-    const entry = result[idx]
-    if (entry.role !== 'user' || !Array.isArray(entry.content)) continue
-
-    const hasToolResults = (entry.content as Array<Record<string, unknown>>).some(b => b.type === 'tool_result')
-    if (!hasToolResults) continue
-
-    const prev = idx > 0 ? result[idx - 1] : null
-    const toolUseIds = new Set<string>()
-    if (prev && prev.role === 'assistant' && Array.isArray(prev.content)) {
-      for (const b of prev.content as Array<Record<string, unknown>>) {
-        if (b.type === 'tool_use' && typeof b.id === 'string') {
-          toolUseIds.add(b.id)
-        }
+      if (allMatched && allToolCalls.length > 0) {
+        result.push({ role: 'assistant', content: [...toolUseById.values()] })
+        result.push({ role: 'user', content: toolResultBlocks })
       }
+      // Whether emitted or dropped, advance past all consumed messages
+      i = j
+    } else if (msg.role === 'assistant') {
+      result.push({ role: 'assistant', content: msg.content ?? '' })
+      i++
+    } else {
+      // role === 'tool' with no preceding assistant handling — orphaned, skip
+      i++
     }
+  }
 
-    entry.content = (entry.content as Array<Record<string, unknown>>).filter(
-      b => b.type !== 'tool_result' || toolUseIds.has(b.tool_use_id as string),
-    )
-
-    if ((entry.content as Array<Record<string, unknown>>).length === 0) {
-      result.splice(idx, 1)
-      idx--
+  // ── Merge consecutive same-role messages ─────────────────────────────────
+  // Can occur when incomplete tool groups are dropped (e.g. user[tool_result]
+  // followed by user[text], or consecutive assistant text messages).
+  const merged: ClaudeMsg[] = []
+  for (const entry of result) {
+    const prev = merged[merged.length - 1]
+    if (prev && prev.role === entry.role) {
+      // Merge by converting both to arrays if needed
+      const prevBlocks = Array.isArray(prev.content)
+        ? prev.content as Array<Record<string, unknown>>
+        : [{ type: 'text', text: prev.content as string }]
+      const curBlocks = Array.isArray(entry.content)
+        ? entry.content as Array<Record<string, unknown>>
+        : [{ type: 'text', text: entry.content as string }]
+      prev.content = [...prevBlocks, ...curBlocks]
+    } else {
+      merged.push({ role: entry.role, content: entry.content })
     }
   }
 
-  // Ensure conversation starts with a user message (Claude requirement)
-  while (result.length > 0 && result[0].role !== 'user') {
-    result.shift()
+  // ── Ensure conversation starts with a user message ─────────────────────
+  while (merged.length > 0 && merged[0].role !== 'user') {
+    merged.shift()
   }
-  if (result.length === 0 || result[0].role !== 'user') {
-    result.unshift({ role: 'user', content: '(continuing conversation)' })
+  if (merged.length === 0 || merged[0].role !== 'user') {
+    merged.unshift({ role: 'user', content: '(continuing conversation)' })
   }
 
-  return result
+  return merged
 }

From 5dc2151507d61899dd30ad3d6f7dd057cd053d6e Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Tue, 17 Mar 2026 19:29:01 -0400
Subject: [PATCH 16/16] feat(agent): add per-request model selection to Aero
 chat

Users can now pick a specific model (e.g. Sonnet vs Opus) from the chat
UI when a provider is selected. This avoids rate limit issues when the
provider-level config is set to a model with low rate limits.

Model priority: request model > agent config > provider config > default.
Also syncs DEFAULT_MODELS in llm.ts with MODEL_REGISTRY from contracts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 apps/web/src/App.tsx              | 20 +++++++++++++++++---
 apps/web/src/api.ts               |  3 ++-
 package.json                      |  2 +-
 packages/api-routes/src/agent.ts  |  9 +++++----
 packages/canonry/package.json     |  2 +-
 packages/canonry/src/agent/llm.ts |  7 ++++---
 packages/canonry/src/server.ts    |  6 +++---
 7 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 90813cb..103616f 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -30,7 +30,7 @@ import {
   X,
   Zap,
 } from 'lucide-react'
-import { effectiveDomains, normalizeProjectDomain } from '@ainyc/canonry-contracts'
+import { effectiveDomains, normalizeProjectDomain, MODEL_REGISTRY } from '@ainyc/canonry-contracts'
 
 import { Badge } from './components/ui/badge.js'
 import { Button } from './components/ui/button.js'
@@ -5794,6 +5794,7 @@ function AeroPage({ projects, providers }: {
 }) {
   const [selectedProject, setSelectedProject] = useState(projects[0]?.name ?? '')
   const [selectedProvider, setSelectedProvider] = useState('')
+  const [selectedModel, setSelectedModel] = useState('')
   const [threads, setThreads] = useState<ApiAgentThread[]>([])
   const [activeThreadId, setActiveThreadId] = useState<string | null>(null)
   const [messages, setMessages] = useState<ApiAgentMessage[]>([])
@@ -5909,6 +5910,7 @@ function AeroPage({ projects, providers }: {
         activeThreadId,
         msg,
         selectedProvider || undefined,
+        selectedModel || undefined,
       )
 
       // Start polling for the response
@@ -5969,7 +5971,7 @@ function AeroPage({ projects, providers }: {
       setMessages([optimisticUser])
       setProcessing(true)
       try {
-        await sendAgentMessage(selectedProject, thread.id, msg, selectedProvider || undefined)
+        await sendAgentMessage(selectedProject, thread.id, msg, selectedProvider || undefined, selectedModel || undefined)
         if (pollRef.current) clearInterval(pollRef.current)
         pollRef.current = setInterval(() => {
           fetchAgentThread(selectedProject, thread.id)
@@ -6019,7 +6021,7 @@ function AeroPage({ projects, providers }: {
           </select>
           <select
             value={selectedProvider}
-            onChange={e => setSelectedProvider(e.target.value)}
+            onChange={e => { setSelectedProvider(e.target.value); setSelectedModel('') }}
             className="aero-select"
           >
             <option value="">Auto (default)</option>
@@ -6027,6 +6029,18 @@ function AeroPage({ projects, providers }: {
               <option key={p.name} value={p.name}>{p.name}</option>
             ))}
           </select>
+          {selectedProvider && MODEL_REGISTRY[selectedProvider as keyof typeof MODEL_REGISTRY] && (
+            <select
+              value={selectedModel}
+              onChange={e => setSelectedModel(e.target.value)}
+              className="aero-select"
+            >
+              <option value="">Default model</option>
+              {MODEL_REGISTRY[selectedProvider as keyof typeof MODEL_REGISTRY].knownModels.map(m => (
+                <option key={m.id} value={m.id}>{m.displayName}</option>
+              ))}
+            </select>
+          )}
         </div>
       </div>
 
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
index f5e3b4f..968b4a5 100644
--- a/apps/web/src/api.ts
+++ b/apps/web/src/api.ts
@@ -692,9 +692,10 @@ export function fetchAgentThread(project: string, threadId: string): Promise<Api
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}`)
 }
 
-export function sendAgentMessage(project: string, threadId: string, message: string, provider?: string): Promise<{ threadId: string; status: string }> {
+export function sendAgentMessage(project: string, threadId: string, message: string, provider?: string, model?: string): Promise<{ threadId: string; status: string }> {
   const body: Record<string, unknown> = { message }
   if (provider) body.provider = provider
+  if (model) body.model = model
   return apiFetch(`/projects/${encodeURIComponent(project)}/agent/threads/${encodeURIComponent(threadId)}/messages`, {
     method: 'POST',
     body: JSON.stringify(body),
diff --git a/package.json b/package.json
index a64b8c6..e6fff99 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "canonry",
   "private": true,
-  "version": "1.18.0",
+  "version": "1.19.0",
   "type": "module",
   "packageManager": "pnpm@10.28.2",
   "scripts": {
diff --git a/packages/api-routes/src/agent.ts b/packages/api-routes/src/agent.ts
index 346f30b..568e9ee 100644
--- a/packages/api-routes/src/agent.ts
+++ b/packages/api-routes/src/agent.ts
@@ -20,7 +20,7 @@ export interface AgentRoutesOptions {
     projectId: string,
     threadId: string,
     message: string,
-    opts?: { provider?: string },
+    opts?: { provider?: string; model?: string },
   ) => Promise<string>
 }
 
@@ -149,7 +149,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
 
   app.post<{
     Params: { project: string; id: string }
-    Body: { message: string; provider?: string }
+    Body: { message: string; provider?: string; model?: string }
   }>(`${prefix}/threads/:id/messages`, {
     schema: {
       params: {
@@ -165,13 +165,14 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
         properties: {
           message: { type: 'string', maxLength: 8000 },
           provider: { type: 'string', enum: ['openai', 'claude', 'gemini'] },
+          model: { type: 'string', maxLength: 100 },
         },
         required: ['message'],
       },
     },
   }, async (request, reply) => {
     const { project, id: threadId } = request.params
-    const { message, provider } = request.body
+    const { message, provider, model } = request.body
 
     const projectRow = resolveProject(app.db, project)
 
@@ -209,7 +210,7 @@ export async function agentRoutes(app: FastifyInstance, opts: AgentRoutesOptions
 
     // Fire-and-forget: the agent loop runs in the background so it
     // survives client disconnects and page navigations.
-    opts.onAgentMessage(thread.projectId, threadId, message, { provider })
+    opts.onAgentMessage(thread.projectId, threadId, message, { provider, model })
       .catch((err) => {
         const msg = err instanceof Error ? err.message : String(err)
         threadErrors.set(threadId, msg)
diff --git a/packages/canonry/package.json b/packages/canonry/package.json
index 09e019b..6aa619e 100644
--- a/packages/canonry/package.json
+++ b/packages/canonry/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "type": "module",
   "description": "The ultimate open-source AEO monitoring tool - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
diff --git a/packages/canonry/src/agent/llm.ts b/packages/canonry/src/agent/llm.ts
index ae92334..1cdae18 100644
--- a/packages/canonry/src/agent/llm.ts
+++ b/packages/canonry/src/agent/llm.ts
@@ -6,6 +6,7 @@
  * the Vercel AI SDK as a dependency — we only need fetch().
  */
 
+import { MODEL_REGISTRY } from '@ainyc/canonry-contracts'
 import type { AgentTool } from './tools.js'
 
 export interface LlmConfig {
@@ -43,9 +44,9 @@ const PROVIDER_ENDPOINTS: Record<string, string> = {
 }
 
 const DEFAULT_MODELS: Record<string, string> = {
-  openai: 'gpt-4o',
-  claude: 'claude-sonnet-4-5-20250514',
-  gemini: 'gemini-2.5-flash',
+  openai: MODEL_REGISTRY.openai.defaultModel,
+  claude: MODEL_REGISTRY.claude.defaultModel,
+  gemini: MODEL_REGISTRY.gemini.defaultModel,
 }
 
 /** Rough character count of a chat request (messages + tool defs). */
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 8834ae9..0c0c9e5 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -477,7 +477,7 @@ function buildAgentHandler(
   opts: { config: CanonryConfig },
   registry: ProviderRegistry,
   db: DatabaseClient,
-): ((projectId: string, threadId: string, message: string, opts?: { provider?: string }) => Promise<string>) | undefined {
+): ((projectId: string, threadId: string, message: string, opts?: { provider?: string; model?: string }) => Promise<string>) | undefined {
   // Determine which provider to use for the agent
   const agentConf = opts.config.agent ?? {}
   if (agentConf.enabled === false) return undefined
@@ -513,7 +513,7 @@ function buildAgentHandler(
     opts.config.apiKey ?? '',
   )
 
-  return async (projectId: string, threadId: string, message: string, callOpts?: { provider?: string }) => {
+  return async (projectId: string, threadId: string, message: string, callOpts?: { provider?: string; model?: string }) => {
     // Per-request provider override or fall back to default
     const llmProvider = (callOpts?.provider as 'claude' | 'openai' | 'gemini' | undefined) ?? defaultProvider!
 
@@ -526,7 +526,7 @@ function buildAgentHandler(
     const llmConfig: LlmConfig = {
       provider: llmProvider,
       apiKey: currentProvider.config.apiKey,
-      model: agentConf.model ?? currentProvider.config.model,
+      model: callOpts?.model ?? agentConf.model ?? currentProvider.config.model,
     }
 
     // Resolve project details for the system prompt