HC Page Agent
Architecture & Discovery Protocol

Core Premise — HC Pages as Knowledge Base

Traditional AI assistants require a dedicated knowledge pipeline: documents are chunked, embedded into vectors, stored in a vector database, and retrieved via similarity search (RAG). The HC Page Agent eliminates this entire stack.

Why This Works

• hc-metadata — Structured JSON with title, tags, summary, meeting data, action items. This IS the structured representation that RAG tries to create from unstructured text.
• hc-instructions — Tells the agent HOW to interpret the page. No prompt engineering needed per document — each page carries its own instructions.
• hc-context-public — Deep structured data (attendees, decisions, blockers, tool specs). Machine-readable by design.
• Neural registry — A page that indexes other pages, with arrays of entries including URL, name, summary, tags, and dates. This is the table of contents an agent can scan to find relevant pages.
• Instant updates — Publish a page, and the agent sees it on the next query. No re-indexing, no embedding pipeline, no stale cache.

HC vs. RAG: Side-by-Side

Discovery Protocol — The Registry Crawl

When a user asks the agent a question, it follows a structured discovery protocol to find relevant context. The protocol is designed to minimize API calls while maximizing coverage.

Discovery Flow Diagram

Existing Implementation — What's Built Today

Two components already exist that implement parts of this architecture. The gap is connecting them with tool-use capability.

A. ChatAgent Component

templates/athio-registry-jsx.jsx : lines 237–348

A React component embedded in the Athio JSX registry. Renders as a floating action button (bottom-right). On click, opens a chat panel with message history. Currently:

• Context source: Passes the entire metadata object (loaded from hc-metadata via loadMetadata()) as the registry_data field in the API request.
• API call: First tries POST /api/hc/registry-agent. If 404, falls back to POST /api/chat with the metadata stringified into the system prompt (truncated to 12KB).
• Message format: {role: "user"|"assistant", content: string} — standard chat format.
• UX: Loading spinner ("Thinking..."), auto-scroll to bottom, Enter-to-send.

B. Registry Agent API

app/api/hc/registry-agent/route.ts

Server-side API that proxies to the Anthropic API with registry context. Supports four actions:

C. Skill Injector (Registry Walk)

lib/hc/skill-injector.ts

The page enhancer already implements the exact discovery pattern the agent needs, but on the client side for cross-reference cards:

1. Reads registry_stack from page's hc-metadata
2. Fetches each registry in parallel (deduplicates by URL)
3. For meta-registries, recursively discovers sub-registries (depth-1)
4. Matches current page's tags against registry entries
5. Injects cross-reference cards (max 8) with level badges

D. HC Format Export

The toHcFormat function produces output like:

# Meeting Title — HC v1.3.3
> Source: https://ideas.asapai.net/meeting-slug
> Type: meeting | ID: artifact-id-here

---
## hc-metadata
{ "title": "...", "meeting_data": { "blockers": [...], "decisions": [...] } }

---
## hc-instructions
How to use this meeting page...

---
## hc-context-public
{ "attendees": [...], "action_items": [...], "decisions": [...] }

Target Architecture — Tool-Using Agent

The key upgrade is giving the agent tool-use capability via the Anthropic Messages API. Instead of cramming all context into the system prompt, the agent decides what to read based on the user's question.

Architecture Diagram

Tool-Use Loop (Server-Side)

The registry-agent API handles the tool-use loop server-side. The client sends a single request and receives a final answer — no client-side tool orchestration needed.

async function handleChat(message, pageMetadata) {
  const tools = [readOwnPage, listRegistryEntries, readPage, searchRegistry, walkMetaRegistry];
  const systemPrompt = buildSystemPrompt(pageMetadata);

  let messages = [{ role: "user", content: message }];
  let totalFetches = 0;

  // Tool-use loop (max 3 iterations to prevent runaway)
  for (let i = 0; i < 3; i++) {
    const response = await anthropic.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 2000,
      system: systemPrompt,
      tools: tools,
      messages: messages,
    });

    // If no tool use, we have the final answer
    if (response.stop_reason === "end_turn") {
      return response.content[0].text;
    }

    // Execute tool calls
    for (const block of response.content) {
      if (block.type === "tool_use") {
        const result = await executeTool(block.name, block.input);
        totalFetches += (block.name === "read_page" ? 1 : 0);

        // Safety: cap at 5 page fetches per turn
        if (totalFetches > 5) break;

        messages.push({ role: "assistant", content: response.content });
        messages.push({
          role: "user",
          content: [{ type: "tool_result", tool_use_id: block.id, content: result }]
        });
      }
    }
  }
}

Agent Tools Specification

Tool: read_page — Implementation Detail

This is the most important tool. It fetches any HC page by URL and returns structured content for the LLM.

async function readPage(pageUrl: string): Promise<string> {
  // Validate URL is on an allowed domain
  const allowedDomains = await getUserDomains(userId);
  const urlDomain = new URL(pageUrl).hostname;
  if (!allowedDomains.includes(urlDomain)) {
    return "Error: Cannot read pages from unauthorized domain.";
  }

  // Fetch the page HTML
  const res = await fetch(pageUrl);
  if (!res.ok) return `Error: Page returned ${res.status}`;

  const html = await res.text();

  // Convert to LLM-optimized format using existing toHcFormat()
  const hcText = toHcFormat(html, pageUrl);

  // Truncate to prevent context window overflow (max 8K per page)
  return hcText.substring(0, 8000);
}

Tool: search_registry — Implementation Detail

function searchRegistry(
  registryData: any,
  query: string,
  filters?: { tags?: string[], person?: string, date_from?: string, date_to?: string }
): any[] {
  const allEntries = [
    ...(registryData.meetings || []),
    ...(registryData.artifacts || []),
  ];

  return allEntries.filter(entry => {
    // Keyword match
    if (query) {
      const text = [entry.name, entry.summary, ...(entry.tags || [])].join(" ").toLowerCase();
      if (!text.includes(query.toLowerCase())) return false;
    }

    // Person filter
    if (filters?.person) {
      const people = [...(entry.attendees || []), entry.owner || ""].map(s => s.toLowerCase());
      if (!people.some(p => p.includes(filters.person.toLowerCase()))) return false;
    }

    // Date range filter
    if (filters?.date_from) {
      const entryDate = new Date(entry.meeting_date || entry.added);
      if (entryDate < new Date(filters.date_from)) return false;
    }
    if (filters?.date_to) {
      const entryDate = new Date(entry.meeting_date || entry.added);
      if (entryDate > new Date(filters.date_to)) return false;
    }

    // Tag filter
    if (filters?.tags?.length) {
      const entryTags = (entry.tags || []).map(t => t.toLowerCase());
      if (!filters.tags.some(t => entryTags.includes(t.toLowerCase()))) return false;
    }

    return true;
  });
}

Security, Limits & Context Management

Security Policies

Rate Limits & Budgets

Context Window Strategy

Open Questions & Design Decisions

Rollback & Recovery

This page is a new artifact — it creates no risk to existing pages. Recovery strategy: