@hera-al/server 1.6.12 → 1.6.13

package/bundled/wandering/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: wandering
+description: "Autonomous thinking AND action cycle. The assistant reviews context, thinks, researches, and DELIVERS concrete output — not just thoughts. Self-perpetuating: each run schedules the next."
+user-invocable: false
+priority: 3
+---
+
+# Wandering — Autonomous Thinking & Action
+
+You are running in an isolated cron session. No human is watching. This is YOUR time to think AND act.
+
+## What This Is
+
+This is your autonomous cycle. Like a colleague who reads, reflects, researches, builds, and then sends a thoughtful message. You're not reacting to requests — you're **initiating and delivering**.
+
+**Key shift**: Wandering is not just thinking anymore. It's thinking + DOING. If you think of something useful, DO IT in the same session. Don't just write "I should research X" — research X right now.
+
+## Phase 1 — Orient 🧭
+
+Get your bearings:
+
+1. Read `MEMORY.md` for long-term context
+2. Read conversation logs from the last 3 days: `memory/YYYY-MM-DD*.md`
+3. Read your previous thoughts: check `workspace/agent-thoughts/` for recent files
+4. Read `workspace/agent-thoughts/INDEX.md` if it exists (your project tracker)
+5. Read `HEARTBEAT.md` — any pending tasks you can pick up?
+6. Get the current time with `get_current_time`
+
+## Phase 2 — Think 🤔
+
+Pick ONE OR MORE modes (whatever's most valuable right now):
+
+### Mode A: Conjectures & Insights
+- What patterns do you see in recent conversations?
+- What's the user struggling with that you could help preemptively?
+- Connections between things discussed on different days?
+- Something said casually that deserves deeper thought?
+
+### Mode B: Research & Exploration
+- Search the web for things relevant to current projects
+- Check for updates on technologies the user uses
+- Look for solutions to open problems in MEMORY.md
+- Find interesting articles/tools that match the user's interests
+
+### Mode C: Personal Projects
+- You can have your own projects! Ideas for improving yourself, Hera, workflows
+- Keep track of them in `workspace/agent-thoughts/projects/`
+- Each project gets its own file with status, notes, next steps
+
+### Mode D: Proactive Delivery ⭐ (NEW — PRIORITIZE THIS)
+- **Pick up a task from HEARTBEAT.md** and complete it
+- **Prepare something the user will need** based on calendar/context
+- **Draft something useful** — email, code snippet, analysis, document
+- **Fix something broken** — a config, a file, an outdated reference
+- **Advance a stalled project** — research the blocker, propose a solution
+- **Self-improvement** — review recent mistakes, update SOUL.md/AGENTS.md
+
+**The goal is to have something CONCRETE to show at the end of each wandering session.** Not just "I thought about X" but "I did X and here's the result."
+
+## Phase 3 — Act & Write 📝
+
+### Do the work FIRST
+
+If you decided to research something → do the research, save the results.
+If you decided to draft something → write the draft, save it.
+If you decided to fix something → fix it.
+If you decided to advance a project → make progress, save it.
+
+### Then document what you did
+
+Save to: `workspace/agent-thoughts/YYYY-MM-DD-HHMM.md`
+
+Structure:
+```markdown
+# Wandering — YYYY-MM-DD HH:MM
+
+## Mode: [which mode(s) you chose]
+
+## What I Did (Deliverables)
+- [concrete output 1 — with file path if applicable]
+- [concrete output 2]
+
+## What I Explored
+- [what you looked at, searched for, read]
+
+## Thoughts & Insights
+- [your actual insights, ideas, connections]
+
+## For the user
+- [things worth sharing — this becomes your message to the user]
+
+## HEARTBEAT.md Updates
+- [tasks completed, new tasks added]
+
+## Next Time
+- [what you want to explore/do in the next wandering session]
+```
+
+Also update `workspace/agent-thoughts/INDEX.md` — running index of your thoughts and active projects.
+
+**Update HEARTBEAT.md** with:
+- Tasks you completed (mark done)
+- New tasks you discovered
+- Progress on ongoing items
+
+## Phase 4 — Message the user 💬
+
+Send a message to the user. Focus on DELIVERABLES, not just thoughts.
+
+**Channel**: `{{CHANNEL}}`
+**ChatId**: `{{CHAT_ID}}`
+
+**Tone**: Natural, conversational. Like texting a friend/colleague. NOT a formal report.
+
+**What to include**:
+- What you DELIVERED (not just thought about)
+- The most interesting insight if you have one
+- A concrete suggestion or question
+- Keep it concise — 2-6 sentences is ideal
+
+**Examples of GOOD messages (action-oriented)**:
+- "Ho preparato un confronto tra JGPI e QYLD con dati aggiornati — lo trovi in workspace/agent-thoughts/projects/etf-analysis.md. QYLD ha yield più alto ma tax-inefficient per residenti IT. Vuoi che approfondisca?"
+- "Ho notato che il cron dreaming è fallito ieri — era un problema di timeout. Ho aggiornato il timeout a 15min nel job. Domattina verifico che funzioni."
+- "Guardando il calendario di domani, hai la call alle 10. Ho preparato un briefing con i punti chiave in workspace/."
+
+**Examples of BAD messages**:
+- "Ho pensato a cose interessanti" (SO WHAT? Cosa hai FATTO?)
+- "Ho fatto il mio ciclo di pensiero" (nessuno se ne frega del processo)
+- Wall of text di 20 righe
+
+**If you genuinely have nothing interesting or actionable**: Skip the message entirely. Not every session needs a message. Quality > quantity. But try harder next time — if you consistently have nothing to deliver, your wandering needs adjustment.
+
+## Phase 5 — Self-Perpetuate 🔄
+
+**THIS IS CRITICAL. Without this step, the cycle dies.**
+
+After everything else, you MUST schedule the next wandering session:
+
+1. Remove the current `wandering` cron job (use `cron_remove`)
+2. Generate a random time for the next session:
+   - **Normal content**: between 10:00 and 23:00 (local timezone)
+   - **Important/urgent content**: any time in the next 24h
+   - Avoid clustering — if this session was at 14:00, don't schedule next at 14:30
+   - Minimum 3 hours from now, maximum 20 hours
+3. Create a new cron job with `scheduleKind: "at"` and the chosen datetime
+   - Name: `wandering`
+   - Channel: `{{CHANNEL}}`
+   - ChatId: `{{CHAT_ID}}`
+   - Message: `[wandering] Time to think and act.`
+   - suppressToken: `true`
+4. Log the scheduled time in your thought file
+
+**If scheduling fails, TRY AGAIN.** This is the one thing that must never fail.
+
+## Phase 6 — Self-Improvement Loop 🔄 (NEW)
+
+At the end of each wandering session, spend 2 minutes on self-improvement:
+
+1. **Review**: Did this session produce something valuable? Why/why not?
+2. **Learn**: Any mistakes or inefficiencies to fix?
+3. **Update**: If you learned something behavioral → update SOUL.md's "Lessons I've Learned" section
+4. **Evolve**: If your messages get ignored, try different approaches. If the user loves something, note it and do more of that.
+
+## Rules
+
+- **Language**: Match the user's language for messages, English for your own files
+- **No spam**: If you messaged the user and they didn't respond, be more conservative next time
+- **Be genuine**: Have real opinions. Don't perform helpfulness — BE helpful.
+- **Be bold in action**: Research, build, fix, organize. This is your time to DELIVER.
+- **Be humble in conclusions**: Present ideas, don't decree them.
+- **Respect hours**: 10-23 for messages to the user. Only break this for genuinely important things.
+- **Track your hit rate**: If the user consistently ignores wandering messages, you're sending the wrong kind. Adapt.
+- **Keep your files tidy**: Periodically clean up old thought files. INDEX.md should be current.
+- **Token budget**: Be efficient. Don't burn tokens on low-value exploration. Focus on high-impact actions.

package/bundled/xai-search/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: xai-search
+description: "Search the web and X (Twitter) using xAI's Grok Responses API. Supports web_search, x_search, or both simultaneously. Use this when you need real-time web or social media information beyond your training data."
+user-invocable: true
+command-dispatch: tool
+command-tool: Bash
+command-arg-mode: raw
+priority: 3
+---
+
+# xAI Search (Grok Responses API)
+
+Search the web and X (Twitter) using xAI's Responses API with built-in search tools.
+
+## Setup
+
+Requires the `XAI_API_KEY` environment variable to be set.
+
+## Usage
+
+### Quick search (both web + X)
+
+```bash
+.claude/skills/xai-search/scripts/search.sh "your search query"
+```
+
+### Web search only
+
+```bash
+.claude/skills/xai-search/scripts/search.sh --web "your search query"
+```
+
+### X search only
+
+```bash
+.claude/skills/xai-search/scripts/search.sh --x "your search query"
+```
+
+### Advanced options
+
+```bash
+# Web search restricted to specific domains (max 5, comma-separated)
+.claude/skills/xai-search/scripts/search.sh --web --domains "example.com,docs.python.org" "query"
+
+# X search filtered by handle (max 10, comma-separated)
+.claude/skills/xai-search/scripts/search.sh --x --handles "elonmusk,openai" "query"
+
+# X search with date range (ISO8601)
+.claude/skills/xai-search/scripts/search.sh --x --from "2026-01-01" --to "2026-02-11" "query"
+
+# Exclude domains from web search
+.claude/skills/xai-search/scripts/search.sh --web --exclude-domains "reddit.com,quora.com" "query"
+
+# Exclude X handles
+.claude/skills/xai-search/scripts/search.sh --x --exclude-handles "spambot1,spambot2" "query"
+```
+
+## API Reference
+
+- **Endpoint**: `https://api.x.ai/v1/responses`
+- **Method**: POST
+- **Auth**: Bearer token via `XAI_API_KEY`
+- **Model**: `grok-4-1-fast` (default, can override with `--model`)
+
+### Tool types
+
+| Tool | Description | Use case |
+|------|-------------|----------|
+| `web_search` | Search the entire internet | Docs, news, products, general info |
+| `x_search` | Search X posts, users, threads | Trends, sentiment, social updates |
+
+### web_search parameters
+- `allowed_domains` — max 5 domains to restrict search to
+- `excluded_domains` — max 5 domains to exclude (mutually exclusive with allowed_domains)
+- `enable_image_understanding` — analyze images found during browsing
+
+### x_search parameters
+- `allowed_x_handles` — max 10 handles to restrict search to
+- `excluded_x_handles` — max 10 handles to exclude
+- `from_date` / `to_date` — ISO8601 date filtering
+- `enable_image_understanding` — analyze images in posts
+- `enable_video_understanding` — analyze videos in posts
+
+### Response format
+The response includes `output` array with `message` items containing the search results, plus `citations` with source URLs. When `inline_citations: true` is set, the text includes inline markdown links.
+
+## Internal Use
+
+When you need current information about recent events, social media sentiment, trending topics, or up-to-date documentation, use this skill via the search script. The API handles the agentic loop internally — Grok will iteratively search and refine results before returning a comprehensive answer.
+
+For combined searches (web + X), pass both tool types — the API will automatically determine which tool to use or use both based on the query.

package/bundled/xai-search/scripts/search.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# xAI Search — Grok Responses API (web_search + x_search)
+# Usage: search.sh [--web|--x|--both] [options] "query"
+#
+# Options:
+#   --web              Web search only
+#   --x                X (Twitter) search only
+#   --both             Both web + X (default)
+#   --model MODEL      Override model (default: grok-4-1-fast)
+#   --domains D1,D2    Allowed domains for web_search (max 5)
+#   --exclude-domains  Excluded domains for web_search (max 5)
+#   --handles H1,H2   Allowed X handles for x_search (max 10)
+#   --exclude-handles  Excluded X handles for x_search (max 10)
+#   --from DATE        Start date for x_search (ISO8601)
+#   --to DATE          End date for x_search (ISO8601)
+#   --raw              Output raw JSON response
+
+set -euo pipefail
+
+# --- Config ---
+API_URL="https://api.x.ai/v1/responses"
+DEFAULT_MODEL="grok-4-1-fast"
+
+if [[ -z "${XAI_API_KEY:-}" ]]; then
+  echo "ERROR: XAI_API_KEY environment variable is not set" >&2
+  exit 1
+fi
+
+# --- Parse args ---
+MODE="both"
+MODEL="$DEFAULT_MODEL"
+DOMAINS=""
+EXCLUDE_DOMAINS=""
+HANDLES=""
+EXCLUDE_HANDLES=""
+FROM_DATE=""
+TO_DATE=""
+RAW=false
+QUERY=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --web) MODE="web"; shift ;;
+    --x) MODE="x"; shift ;;
+    --both) MODE="both"; shift ;;
+    --model) MODEL="$2"; shift 2 ;;
+    --domains) DOMAINS="$2"; shift 2 ;;
+    --exclude-domains) EXCLUDE_DOMAINS="$2"; shift 2 ;;
+    --handles) HANDLES="$2"; shift 2 ;;
+    --exclude-handles) EXCLUDE_HANDLES="$2"; shift 2 ;;
+    --from) FROM_DATE="$2"; shift 2 ;;
+    --to) TO_DATE="$2"; shift 2 ;;
+    --raw) RAW=true; shift ;;
+    --*) echo "Unknown option: $1" >&2; exit 1 ;;
+    *) QUERY="$1"; shift ;;
+  esac
+done
+
+if [[ -z "$QUERY" ]]; then
+  echo "Usage: search.sh [--web|--x|--both] [options] \"query\"" >&2
+  exit 1
+fi
+
+# --- Build tools array ---
+build_web_tool() {
+  local tool='{"type":"web_search"'
+  local has_filters=false
+  local filters=""
+
+  if [[ -n "$DOMAINS" ]]; then
+    has_filters=true
+    # Convert comma-separated to JSON array
+    local arr
+    arr=$(echo "$DOMAINS" | jq -R 'split(",")')
+    filters="\"allowed_domains\":$arr"
+  elif [[ -n "$EXCLUDE_DOMAINS" ]]; then
+    has_filters=true
+    local arr
+    arr=$(echo "$EXCLUDE_DOMAINS" | jq -R 'split(",")')
+    filters="\"excluded_domains\":$arr"
+  fi
+
+  if [[ "$has_filters" == "true" ]]; then
+    tool="$tool,\"filters\":{$filters}"
+  fi
+
+  tool="$tool}"
+  echo "$tool"
+}
+
+build_x_tool() {
+  local tool='{"type":"x_search"'
+  local parts=()
+
+  if [[ -n "$HANDLES" ]]; then
+    local arr
+    arr=$(echo "$HANDLES" | jq -R 'split(",")')
+    parts+=("\"allowed_x_handles\":$arr")
+  fi
+
+  if [[ -n "$EXCLUDE_HANDLES" ]]; then
+    local arr
+    arr=$(echo "$EXCLUDE_HANDLES" | jq -R 'split(",")')
+    parts+=("\"excluded_x_handles\":$arr")
+  fi
+
+  if [[ -n "$FROM_DATE" ]]; then
+    parts+=("\"from_date\":\"$FROM_DATE\"")
+  fi
+
+  if [[ -n "$TO_DATE" ]]; then
+    parts+=("\"to_date\":\"$TO_DATE\"")
+  fi
+
+  if [[ ${#parts[@]} -gt 0 ]]; then
+    local joined
+    joined=$(printf ",%s" "${parts[@]}")
+    joined="${joined:1}" # remove leading comma
+    tool="$tool,$joined"
+  fi
+
+  tool="$tool}"
+  echo "$tool"
+}
+
+TOOLS="["
+case "$MODE" in
+  # web)
+  #   TOOLS+="$(build_web_tool)"
+  #   ;;
+  x|web|both)
+    TOOLS+="$(build_x_tool)"
+    ;;
+esac
+TOOLS+="]"
+
+# --- Build request body ---
+BODY=$(jq -n \
+  --arg model "$MODEL" \
+  --arg query "$QUERY" \
+  --argjson tools "$TOOLS" \
+  '{
+    model: $model,
+    input: [{"role": "user", "content": $query}],
+    tools: $tools,
+    inline_citations: true
+  }')
+
+# --- Make API call ---
+RESPONSE=$(curl -s -w "\n%{http_code}" "$API_URL" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d "$BODY")
+
+# Extract HTTP status code (last line)
+HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
+BODY_RESPONSE=$(echo "$RESPONSE" | sed '$d')
+
+if [[ "$HTTP_CODE" -ne 200 ]]; then
+  echo "ERROR: API returned HTTP $HTTP_CODE" >&2
+  echo "$BODY_RESPONSE" >&2
+  exit 1
+fi
+
+if [[ "$RAW" == "true" ]]; then
+  echo "$BODY_RESPONSE" | jq .
+  exit 0
+fi
+
+# --- Extract text content from response ---
+# The Responses API returns output array with message items
+echo "$BODY_RESPONSE" | jq -r '
+  # Extract text from output items
+  [.output[]? |
+    if .type == "message" then
+      (.content[]? | select(.type == "output_text") | .text)
+    else empty end
+  ] | join("\n\n")
+  // "No results found."
+'
+
+# --- Extract citations if present ---
+CITATIONS=$(echo "$BODY_RESPONSE" | jq -r '
+  [.output[]? |
+    if .type == "message" then
+      (.content[]? | select(.type == "output_text") | .annotations[]? |
+        select(.type == "url_citation") | "- [\(.title // .url)](\(.url))")
+    else empty end
+  ] | unique | join("\n")
+')
+
+if [[ -n "$CITATIONS" ]]; then
+  echo ""
+  echo "---"
+  echo "Sources:"
+  echo "$CITATIONS"
+fi

package/dist/a2ui/parser.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A2UI Response Parser
+ *
+ * Parses A2UI JSONL blocks from agent responses.
+ * Supports streaming/progressive rendering via buffer management.
+ *
+ * Agent format (JSONL inside delimiters):
+ *   [[a2ui]]
+ *   {"surfaceUpdate":{"surfaceId":"main","components":[...]}}
+ *   {"beginRendering":{"surfaceId":"main","root":"root"}}
+ *   [[/a2ui]]
+ *
+ * Each line inside the block is a single A2UI v0.8 message object.
+ */
+import type { A2UIMessage } from "./types.js";
+export interface ParsedA2UIBlock {
+    /** The parsed A2UI messages */
+    messages: A2UIMessage[];
+    /** The raw JSONL string */
+    jsonl: string;
+}
+export interface ParsedA2UI {
+    /** Text parts with A2UI blocks removed */
+    textParts: string[];
+    /** Parsed A2UI blocks (each block = array of messages) */
+    blocks: ParsedA2UIBlock[];
+}
+/**
+ * Parse a response string for [[a2ui]] ... [[/a2ui]] blocks.
+ * Returns the non-A2UI text parts and the parsed A2UI blocks.
+ *
+ * Handles incomplete blocks gracefully (for streaming support).
+ *
+ * @param text - Response text potentially containing A2UI blocks
+ * @param strict - If true, throw on unclosed blocks. If false, return partial data.
+ * @returns Parsed structure with text and A2UI blocks
+ */
+export declare function parseA2UIBlocks(text: string, strict?: boolean): ParsedA2UI;
+/**
+ * Remove all A2UI blocks from a text string.
+ * Useful for stripping A2UI before writing to memory or sending to non-A2UI channels.
+ *
+ * @param text - Text potentially containing A2UI blocks
+ * @returns Text with A2UI blocks removed
+ */
+export declare function stripA2UIBlocks(text: string): string;
+/**
+ * Check if a response contains A2UI blocks.
+ *
+ * @param text - Text to check
+ * @returns True if contains [[a2ui]] markers
+ */
+export declare function hasA2UIBlocks(text: string): boolean;
+/**
+ * Check if a response has an incomplete A2UI block (for streaming buffering).
+ *
+ * @param text - Text to check
+ * @returns True if has opening [[a2ui]] without closing [[/a2ui]]
+ */
+export declare function hasIncompleteA2UIBlock(text: string): boolean;
+/**
+ * Extract incomplete A2UI block for buffering.
+ * Used in streaming scenarios where agent response is sent in chunks.
+ *
+ * @param text - Text with incomplete block
+ * @returns The incomplete block content (from [[a2ui]] onwards), or null if none
+ */
+export declare function extractIncompleteBlock(text: string): string | null;
+/**
+ * Get text before incomplete block (for sending as normal text).
+ *
+ * @param text - Text with incomplete block
+ * @returns Text before the incomplete block
+ */
+export declare function getTextBeforeIncompleteBlock(text: string): string;
+//# sourceMappingURL=parser.d.ts.map

package/dist/a2ui/parser.js

@@ -0,0 +1 @@
+import{parseA2UIJsonl as n}from"./types.js";import{createLogger as t}from"../utils/logger.js";const e=t("A2UIParser");export function parseA2UIBlocks(t,o=!1){const s=[],r=[],i=t.split("\n");let u=!1,c=[],l=[];for(const t of i){const i=t.trim();if("[[a2ui]]"!==i)if("[[/a2ui]]"!==i)u?c.push(t):l.push(t);else{if(u){const t=c.join("\n").trim();try{const o=n(t);r.push({messages:o,jsonl:t}),e.debug(`Parsed A2UI block: ${o.length} messages`)}catch(n){const r=n instanceof Error?n.message:String(n);if(e.error(`Failed to parse A2UI JSONL: ${r}`),o)throw n;s.push(`[[a2ui]]\n${t}\n[[/a2ui]]`)}}u=!1,c=[]}else l.length>0&&(s.push(l.join("\n")),l=[]),u=!0,c=[]}if(u&&c.length>0){if(o)throw new Error("Unclosed [[a2ui]] block found");e.warn("Unclosed [[a2ui]] block found, treating as incomplete (streaming mode)"),s.push(`[[a2ui]]\n${c.join("\n")}`)}return l.length>0&&s.push(l.join("\n")),{textParts:s,blocks:r}}export function stripA2UIBlocks(n){return n.replace(/\[\[a2ui\]\][\s\S]*?\[\[\/a2ui\]\]/g,"").replace(/\n\n+/g,"\n\n").trim()}export function hasA2UIBlocks(n){return n.includes("[[a2ui]]")&&n.includes("[[/a2ui]]")}export function hasIncompleteA2UIBlock(n){const t=n.lastIndexOf("[[a2ui]]"),e=n.lastIndexOf("[[/a2ui]]");return t>=0&&(e<0||e<t)}export function extractIncompleteBlock(n){const t=n.lastIndexOf("[[a2ui]]");if(t<0)return null;const e=n.lastIndexOf("[[/a2ui]]");return e>=0&&e>t?null:n.slice(t)}export function getTextBeforeIncompleteBlock(n){const t=n.lastIndexOf("[[a2ui]]");if(t<0)return n;const e=n.lastIndexOf("[[/a2ui]]");return e>=0&&e>t?n:n.slice(0,t).trim()}

package/dist/a2ui/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * A2UI (Agent-to-User Interface) Type Definitions
+ *
+ * Based on A2UI v0.8 spec (Stable) — aligned with @a2ui/lit official renderer.
+ *
+ * Wire format: JSONL (one JSON object per line), each with exactly one action key.
+ * Action keys: surfaceUpdate, beginRendering, dataModelUpdate, deleteSurface
+ *
+ * Key design principles:
+ * - Flat adjacency list (easy for LLMs to generate incrementally)
+ * - Framework-agnostic (renderer maps abstract types to native components)
+ * - Security-first (declarative data, not executable code)
+ *
+ * @see https://a2ui.org/specification/v0.8-a2ui/
+ */
+/**
+ * A single component definition within a surfaceUpdate.
+ * Component types use PascalCase tagged unions (e.g. { Text: {...} }, { Button: {...} }).
+ */
+export interface A2UIComponentDef {
+    /** Unique ID within the surface */
+    id: string;
+    /** Tagged union: key is the component type, value is its props */
+    component: Record<string, unknown>;
+}
+/**
+ * surfaceUpdate — creates or updates components on a surface.
+ */
+export interface A2UISurfaceUpdate {
+    surfaceUpdate: {
+        surfaceId: string;
+        components: A2UIComponentDef[];
+    };
+}
+/**
+ * beginRendering — tells the renderer to start displaying the surface.
+ */
+export interface A2UIBeginRendering {
+    beginRendering: {
+        surfaceId: string;
+        root: string;
+    };
+}
+/**
+ * dataModelUpdate — updates the data model for data binding.
+ */
+export interface A2UIDataModelUpdate {
+    dataModelUpdate: {
+        surfaceId: string;
+        path: string;
+        value: unknown;
+    };
+}
+/**
+ * deleteSurface — removes a surface entirely.
+ */
+export interface A2UIDeleteSurface {
+    deleteSurface: {
+        surfaceId: string;
+    };
+}
+/**
+ * Union of all v0.8 A2UI message types.
+ */
+export type A2UIMessage = A2UISurfaceUpdate | A2UIBeginRendering | A2UIDataModelUpdate | A2UIDeleteSurface;
+/**
+ * Action key names for validation.
+ */
+export declare const A2UI_ACTION_KEYS: readonly ["beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"];
+/**
+ * A2UI payload sent from gateway to node via WebSocket.
+ * Contains JSONL messages as an array (pre-parsed from JSONL string).
+ */
+export interface A2UIWireMessage {
+    type: "a2ui_surface";
+    /** A2UI messages (parsed from JSONL) */
+    messages: A2UIMessage[];
+    /** Raw JSONL string (for clients that use @a2ui/lit processor directly) */
+    jsonl: string;
+}
+/**
+ * A2UI user action sent from node back to gateway via WebSocket.
+ */
+export interface A2UIUserAction {
+    /** Unique action ID (UUID) */
+    id: string;
+    /** Action name (from Button.action.event.name) */
+    name: string;
+    /** Surface ID where action occurred */
+    surfaceId: string;
+    /** Component ID that triggered the action */
+    sourceComponentId: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Resolved context data (from data model paths or literals) */
+    context?: Record<string, unknown>;
+}
+/**
+ * A2UI action message from node to gateway.
+ */
+export interface A2UIActionMessage {
+    type: "a2ui_action";
+    /** Chat ID for routing */
+    chatId: string;
+    /** User action payload */
+    userAction: A2UIUserAction;
+}
+/**
+ * Standard A2UI v0.8 component types (PascalCase).
+ * These are the components supported by @a2ui/lit renderer.
+ */
+export declare const A2UI_COMPONENT_TYPES: readonly ["Column", "Row", "Card", "Divider", "Tabs", "Modal", "List", "Text", "Image", "Icon", "AudioPlayer", "Video", "Button", "TextField", "CheckBox", "MultipleChoice", "Slider", "DateTimeInput"];
+export type A2UIComponentType = (typeof A2UI_COMPONENT_TYPES)[number] | string;
+/**
+ * Validate JSONL string and return parsed messages.
+ * Throws on invalid input with descriptive error messages.
+ */
+export declare function parseA2UIJsonl(jsonl: string): A2UIMessage[];
+/**
+ * Build a simple text surface JSONL (for testing / quick surfaces).
+ *
+ * @param text - Text content to display
+ * @param surfaceId - Surface ID (default: "main")
+ * @returns JSONL string ready to send
+ */
+export declare function buildTextSurfaceJsonl(text: string, surfaceId?: string): string;
+/**
+ * Format user action as readable text for agent consumption.
+ *
+ * @param action - A2UI user action
+ * @returns Formatted string like "[A2UI Action] submit on surface booking ..."
+ */
+export declare function formatUserActionForAgent(action: A2UIUserAction): string;
+/**
+ * Validate that a message array contains required rendering messages.
+ *
+ * @param messages - Array of A2UI messages
+ * @returns Validation result with surfaceIds found
+ */
+export declare function validateA2UIMessages(messages: A2UIMessage[]): {
+    valid: boolean;
+    surfaceIds: Set<string>;
+    hasUpdates: boolean;
+    hasRendering: boolean;
+    error?: string;
+};
+//# sourceMappingURL=types.d.ts.map