@johpaz/hive-sdk 0.1.4 → 0.1.6

package/packages/core/src/scheduler/index.ts

@@ -1,12 +1,14 @@
 /**
- * Hive Scheduler Module
- * 
- * Croner-based scheduling system for Hive.
- * Supports recurring and one-shot cron jobs with SQLite persistence.
+ * Scheduler — cron con Croner sobre HiveDB.
+ *
+ * Soporta jobs recurrentes y de una sola vez. La persistencia pasó de SQLite a
+ * las colecciones `cronJobs` / `taskRuns` de HiveDB en 0.1.5.
  */
 
-export { CronScheduler } from "./CronScheduler";
-export { executeScheduledTask, createTaskHandler, notifyTaskCompletion, setSchedulerForCleanup } from "./integration";
+export { CronScheduler } from "./CronScheduler.ts";
+// `executeScheduledTask` dejó de ser público: la ejecución entra por
+// `createTaskHandler()`, que es lo que el scheduler engancha.
+export { createTaskHandler, notifyTaskCompletion, setSchedulerForCleanup } from "./integration.ts";
 export type {
   CronJob,
   TaskRun,
@@ -19,4 +21,4 @@ export type {
   TaskStatus,
   TaskRunStatus,
   CronerOptions,
-} from "./types";
+} from "./types.ts";

package/packages/core/src/scheduler/integration.ts

@@ -7,18 +7,20 @@
 
 import type { CronJob, CronJobExecutionResult } from "./types";
 import { logger } from "../utils/logger";
-import { getDb } from "../storage/SQLiteStorage";
-import { buildAgentLoop } from "../agent/AgentRunner";
+import { buildAgentLoop } from "../agent/agent-loop";
 import { resolveAgentId } from "../storage/onboarding";
 import { sendToUserChannel } from "../gateway/channel-notify";
-import { addMessage } from "../agent/ConversationStore";
+import { getNarration } from "../events/tool-narration.ts";
+import { addMessage } from "../agent/conversation-store";
 import { resolveBestChannel } from "../tools/cron/index";
+import { col } from "../storage/hive";
+import type { UserDoc, CronJobDoc } from "../storage/collections";
 
 const log = logger.child("SchedulerIntegration");
 
-let _scheduler: { runCleanup(): void } | null = null;
+let _scheduler: { runCleanup(): Promise<void> } | null = null;
 
-export function setSchedulerForCleanup(scheduler: { runCleanup(): void }): void {
+export function setSchedulerForCleanup(scheduler: { runCleanup(): Promise<void> }): void {
   _scheduler = scheduler;
 }
 
@@ -32,7 +34,7 @@ export function setSchedulerForCleanup(scheduler: { runCleanup(): void }): void
  * 4. Executes the tool if tool_name is specified
  * 5. Returns the agent response
  */
-export async function executeScheduledTask(job: CronJob): Promise<CronJobExecutionResult> {
+async function executeScheduledTask(job: CronJob): Promise<CronJobExecutionResult> {
   log.info(`[execute] Processing job "${job.name}" (${job.id})`);
 
   try {
@@ -52,7 +54,7 @@ export async function executeScheduledTask(job: CronJob): Promise<CronJobExecuti
 
     if (payload._internal === true && (payload as any).action === "cleanup") {
       if (_scheduler) {
-        _scheduler.runCleanup();
+        await _scheduler.runCleanup();
       } else {
         log.warn("[execute] Cleanup job fired but scheduler instance not available");
       }
@@ -71,18 +73,19 @@ export async function executeScheduledTask(job: CronJob): Promise<CronJobExecuti
     };
 
     let targetAgentId: string | null = job.agent_id || null;
-    
+
     if (!targetAgentId) {
-      targetAgentId = resolveAgentId(null);
+      targetAgentId = await resolveAgentId(null);
       log.debug(`[execute] No agent specified, routing to Coordinator: ${targetAgentId}`);
     }
 
-    const db = getDb();
-    const user = db.query("SELECT id, timezone, language FROM users LIMIT 1").get() as {
-      id: string;
-      timezone: string;
-      language: string | null;
-    } | undefined;
+    const usersCol = await col<UserDoc>("users");
+    const userEntry = (await usersCol.scan({ limit: 1 }))[0];
+    const user = userEntry ? {
+      id: userEntry.doc.id,
+      timezone: userEntry.doc.timezone || "UTC",
+      language: userEntry.doc.language,
+    } : undefined;
 
     const userTimezone = user?.timezone || "UTC";
     const userLanguage = user?.language || "en";
@@ -124,7 +127,24 @@ ${prompt || `Execute tool: ${job.tool_name}`}`;
 
       const agentChannel = (job.channel && job.channel !== "system")
         ? job.channel
-        : resolveBestChannel(user?.id || "");
+        : await resolveBestChannel(user?.id || "");
+
+      // Narrate progress to the user's channel as the task runs, same as a
+      // live chat turn (server.ts onStep) — without this, scheduled tasks
+      // execute silently and only the final completion message is sent.
+      const onStep = async (step: { type: string; message?: string; toolName?: string }) => {
+        if (!agentChannel) return;
+        try {
+          if (step.type === "tool_call" && step.toolName) {
+            await sendToUserChannel(agentChannel, user?.id || "", getNarration(step.toolName));
+          } else if (step.type === "text" && step.message) {
+            const trimmed = step.message.trim();
+            if (trimmed) await sendToUserChannel(agentChannel, user?.id || "", trimmed);
+          }
+        } catch (err) {
+          log.warn(`[execute] Narration send failed: ${(err as Error).message}`);
+        }
+      };
 
       const messages = [{ role: "user", content: contextPrompt }];
       const stream = agentLoop.stream({ messages }, {
@@ -136,6 +156,7 @@ ${prompt || `Execute tool: ${job.tool_name}`}`;
           system_prompt: undefined,
           raw_user_message: contextPrompt,
         },
+        onStep,
       });
 
       let response = "";
@@ -194,22 +215,21 @@ export async function notifyTaskCompletion(
   response?: string,
   error?: string
 ): Promise<void> {
-  const db = getDb();
-
-  const task = db.query(
-    "SELECT channel, agent_id FROM cron_jobs WHERE id = ?"
-  ).get(taskId) as { channel: string; agent_id: string | null } | undefined;
+  const cronJobsCol = await col<CronJobDoc>("cronJobs");
+  const taskEntry = await cronJobsCol.get(taskId);
 
-  if (!task) {
+  if (!taskEntry) {
     log.warn(`[notify] Job "${taskId}" not found`);
     return;
   }
+  const task = taskEntry.doc;
 
-  const userRow = db.query("SELECT id FROM users LIMIT 1").get() as { id: string } | undefined;
-  const userId = userRow?.id || "";
+  const usersCol = await col<UserDoc>("users");
+  const userEntry = (await usersCol.scan({ limit: 1 }))[0];
+  const userId = userEntry?.id || "";
 
   const explicitChannel = task.channel && task.channel !== "system" ? task.channel : undefined;
-  const notifyChannel = resolveBestChannel(userId, explicitChannel) || "webchat";
+  const notifyChannel = (await resolveBestChannel(userId, explicitChannel)) || "webchat";
   log.info(`[notifyTaskCompletion] task.channel=${task.channel} explicit=${explicitChannel} resolved=${notifyChannel}`);
 
   const status = success ? "✅" : "❌";
@@ -220,7 +240,7 @@ export async function notifyTaskCompletion(
   log.info(`[notify] Sending notification to ${notifyChannel}: "${message.slice(0, 50)}..."`);
 
   try {
-    addMessage(userId, "assistant", message, { channel: notifyChannel });
+    await addMessage(userId, "assistant", message, { channel: notifyChannel });
   } catch (e) {
     log.warn(`[notify] Failed to persist notification to DB: ${(e as Error).message}`);
   }

package/packages/core/src/scheduler/scheduler.test.ts

@@ -1,19 +1,15 @@
-import { describe, expect, it, beforeAll, afterAll } from "bun:test";
-import { CronScheduler } from "./CronScheduler.ts";
-import { getTestDb, setupTestDb, teardownTestDb } from "../../../../test/setup-db.ts";
+process.env.HIVE_DB_PATH = ":memory:";
 
-describe("CronScheduler", () => {
-  beforeAll(() => {
-    setupTestDb();
-  });
+import { describe, expect, it } from "bun:test";
+import { CronScheduler } from "./CronScheduler.ts";
 
-  afterAll(() => {
-    teardownTestDb();
-  });
+// `new CronScheduler(db, handler)` pasó a `new CronScheduler(handler)`: los jobs
+// viven en la colección `cronJobs` de HiveDB y el scheduler la abre solo, así
+// que ya no recibe un handle de base.
 
-  it("creates a scheduler instance with db and handler", () => {
-    const db = getTestDb();
-    const scheduler = new CronScheduler(db, async () => ({ success: true }));
+describe("CronScheduler", () => {
+  it("creates a scheduler instance with a handler", () => {
+    const scheduler = new CronScheduler(async () => ({ success: true }));
     expect(scheduler).toBeDefined();
   });
 });

package/packages/core/src/scheduler/types.ts

@@ -5,7 +5,6 @@
  * All names use "CronJob" terminology (formerly ScheduledTask).
  */
 
-import type { Database } from "bun:sqlite";
 import type { Cron } from "croner";
 
 /**
@@ -24,7 +23,7 @@ export type TaskStatus = "active" | "paused" | "completed" | "failed" | "cancell
 export type TaskRunStatus = "running" | "success" | "failed" | "timeout";
 
 /**
- * CronJob as stored in SQLite (cron_jobs table)
+ * CronJob as stored in the `cronJobs` HiveDB collection
  */
 export interface CronJob {
   id: string;
@@ -48,6 +47,8 @@ export interface CronJob {
   run_count: number;
   error_count: number;
   last_error: string | null;
+  misfire_policy?: "skip" | "fire_once";
+  misfire_grace_min?: number;
   created_at: string;
   updated_at: string;
   last_run_at: string | null;
@@ -90,6 +91,8 @@ export interface CreateCronJobInput {
   max_runs?: number | null;
   protect?: boolean;
   interval_sec?: number | null;
+  misfire_policy?: "skip" | "fire_once";
+  misfire_grace_min?: number;
 }
 
 /**
@@ -113,6 +116,8 @@ export interface UpdateCronJobInput {
   protect?: boolean;
   interval_sec?: number | null;
   status?: TaskStatus;
+  misfire_policy?: "skip" | "fire_once";
+  misfire_grace_min?: number;
 }
 
 /**

package/packages/core/src/security/Pairing.ts

@@ -1,5 +1,5 @@
 import crypto from "crypto";
-import { eventBus } from "../swarm/EventBus.ts";
+import { eventBus } from "../events/event-bus.ts";
 import { logger } from "../utils/logger.ts";
 
 export interface PairingCode {

package/packages/core/src/skills/bundled/a2ui/a2ui_dashboard/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: a2ui_dashboard
+description: "Create real-time interactive dashboards using A2UI v0.9 protocol with dynamic data binding and live updates"
+version: 1.0.0
+author: Hive Team
+icon: "📊"
+category: a2ui
+permissions:
+  - a2ui_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "dashboard A2UI"
+  - "panel de control A2UI"
+  - "A2UI dashboard"
+  - "mostrar métricas A2UI"
+  - "A2UI metrics"
+  - "dashboard interactivo A2UI"
+  - "interactive dashboard"
+  - "A2UI dashboard en tiempo real"
+  - "real-time dashboard A2UI"
+  - "mostrar datos A2UI"
+  - "visualizar datos con A2UI"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface for the dashboard. Set theme with primaryColor matching project branding."
+    params:
+      surfaceId: "Descriptive ID (e.g. 'project_dashboard', 'metrics_dashboard')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#10B981', agentDisplayName: 'Dashboard' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Build dashboard layout using Row, Column, Card, and Text components. Use weight for proportional sizing."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions for dashboard layout"
+    output: dashboard_layout
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Populate dashboard with initial data using JSON Pointer paths. All dynamic values should use path bindings."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/"
+      value: "Full data model object with all metric values"
+    output: data_populated
+
+  - step: 4
+    action: a2ui_update_data_model
+    instruction: "Update specific data model paths to refresh dashboard metrics in real-time."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/metrics/completionRate"
+      value: "Updated value"
+    output: metrics_updated
+
+  - step: 5
+    action: a2ui_delete_surface
+    instruction: "Delete the dashboard surface when no longer needed."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use Row with weight for side-by-side metrics (e.g. weight: 1 vs weight: 3)"
+  - "Use Card to group related metrics together"
+  - "Use Text with usageHint: 'h2' for section titles, 'h1' for dashboard title"
+  - "Use Text with usageHint: 'caption' for labels"
+  - "Use data binding { path: '/metrics/name' } for all dynamic values"
+  - "Update metrics with a2ui_update_data_model using specific JSON Pointer paths"
+  - "Use a2ui_update_data_model with path: '/' to replace entire data model if needed"
+  - "Delete surfaces with a2ui_delete_surface when dashboard is no longer needed"
+  - "Use A2UI for both static and live dashboards"
+
+output_format:
+  structure: a2ui_dashboard
+  sections:
+    - "surface_creation"
+    - "dashboard_layout"
+    - "data_model"
+    - "live_updates"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "mostrá el dashboard del proyecto"
+    expected_behavior: "a2ui_create_surface(surfaceId:'project_dash', theme:{primaryColor:'#10B981'}) → a2ui_update_components with Row[Column[Card[metrics]],Column[tasks]] → a2ui_update_data_model(path:'/', value:{metrics:{...}})"
+
+  - user_input: "actualizá las métricas del dashboard"
+    expected_behavior: "a2ui_update_data_model(surfaceId:'project_dash', path:'/metrics/completionRate', value:75)"
+
+  - user_input: "show a real-time dashboard with server metrics"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Cards for each metric → a2ui_update_data_model → periodic updates with a2ui_update_data_model"
+---
+
+# A2UI Dashboard Skill
+
+## Cuándo se Activa
+
+Para crear dashboards interactivos en tiempo real usando A2UI v0.9. Usar cuando se necesita:
+- Métricas que se actualizan dinámicamente
+- Dashboards con data binding
+- Paneles con Cards, Rows, Columns
+- Visualización de datos que cambia en tiempo real
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía componentes | Para layout del dashboard |
+| `a2ui_update_data_model` | Actualiza datos | Para métricas dinámicas |
+| `a2ui_delete_surface` | Elimina la superficie | Al cerrar dashboard |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // datos iniciales
+4. [actualizar métricas con a2ui_update_data_model según necesidad]
+5. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Patrón de Dashboard Típico
+
+```json
+[
+  {"id": "root", "component": "Column", "children": ["title", "metrics_row", "tasks_list"]},
+  {"id": "title", "component": "Text", "text": "Dashboard de Proyecto", "variant": "h1"},
+
+  {"id": "metrics_row", "component": "Row", "children": ["card1", "card2", "card3"]},
+  {"id": "card1", "component": "Card", "child": "card1_content", "weight": 1},
+  {"id": "card1_content", "component": "Column", "children": ["card1_label", "card1_value"]},
+  {"id": "card1_label", "component": "Text", "text": "Completado", "variant": "caption"},
+  {"id": "card1_value", "component": "Text", "text": {"path": "/metrics/completionRate"}, "variant": "h2"},
+
+  {"id": "tasks_list", "component": "List", "children": {"path": "/tasks", "componentId": "task_template"}},
+  {"id": "task_template", "component": "Card", "child": "task_content"},
+  {"id": "task_content", "component": "Column", "children": ["task_name", "task_status"]},
+  {"id": "task_name", "component": "Text", "text": {"path": "/name"}},
+  {"id": "task_status", "component": "Text", "text": {"path": "/status"}, "variant": "caption"}
+]
+```
+
+## Actualización en Tiempo Real
+
+Para actualizar métricas específicas sin reenviar componentes:
+```json
+a2ui_update_data_model(surfaceId: "dash", path: "/metrics/completionRate", value: 85)
+a2ui_update_data_model(surfaceId: "dash", path: "/metrics/totalTasks", value: 24)
+```
+
+Para reemplazar todo el data model:
+```json
+a2ui_update_data_model(surfaceId: "dash", path: "/", value: {metrics: {completionRate: 90, totalTasks: 25}, tasks: [...]})
+```
+
+## Mejores Prácticas
+
+- Usar `weight` en Row/Column para proporciones (weight:1 vs weight:3 = 25% vs 75%)
+- Agrupar métricas en Cards para separación visual
+- Usar `usageHint: "caption"` para labels, `"h1"/"h2"` para valores
+- Bind todos los valores dinámicos con `{ path: "/..." }`
+- Actualizar métricas con `a2ui_update_data_model` path específico
+- Eliminar surfaces al terminar para evitar memory leaks

package/packages/core/src/skills/bundled/a2ui/a2ui_form/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: a2ui_form
+description: "Create rich interactive forms using A2UI v0.9 protocol with validation, data binding, and multi-step flows"
+version: 1.0.0
+author: Hive Team
+icon: "📝"
+category: a2ui
+permissions:
+  - a2ui_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "crear formulario A2UI"
+  - "create A2UI form"
+  - "formulario interactivo A2UI"
+  - "A2UI form"
+  - "pedir datos con A2UI"
+  - "collect data A2UI"
+  - "formulario con validación"
+  - "form with validation"
+  - "formulario multi-paso"
+  - "multi-step form A2UI"
+  - "form dinámico A2UI"
+  - "dynamic form A2UI"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface with a unique surfaceId and catalog. Set theme with primaryColor and agentDisplayName."
+    params:
+      surfaceId: "Unique identifier (e.g. 'contact_form', 'signup_form')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#3B82F6', agentDisplayName: 'Asistente' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Send the form layout as a flat list of A2UI components. Must include a 'root' component. Use Column/Row for layout, TextField for inputs, Button for submit."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions"
+    output: components_sent
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Populate initial form values using JSON Pointer paths (e.g. '/form/name'). Sets default values and enables two-way binding."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/form"
+      value: "{ name: '', email: '' }"
+    output: data_populated
+
+  - step: 4
+    action: a2ui_delete_surface
+    instruction: "Delete the A2UI surface when the form is completed or no longer needed."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use data binding with { path: '/form/field' } for TextField values to enable two-way binding"
+  - "Add checks (validation) to TextField: [{ call: 'required', args: { value: { path: '/form/email' } }, message: 'Email is required' }]"
+  - "Button actions use event format: { event: { name: 'submit_form', context: { email: { path: '/form/email' } } } }"
+  - "Use Column for vertical layouts, Row for horizontal layouts"
+  - "Set weight on Row/Column children for proportional sizing (e.g. weight: 1 vs weight: 3)"
+  - "Delete surfaces with a2ui_delete_surface when no longer needed to prevent memory leaks"
+  - "Use A2UI forms for every structured data-entry flow"
+
+output_format:
+  structure: a2ui_form
+  sections:
+    - "surface_creation"
+    - "component_layout"
+    - "data_model"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "creá un formulario de contacto"
+    expected_behavior: "a2ui_create_surface(surfaceId:'contact_form', theme:{primaryColor:'#3B82F6',agentDisplayName:'Asistente'}) → a2ui_update_components(surfaceId:'contact_form', components:[root,Column,hdr,name_fld,email_fld,msg_fld,submit_btn]) → a2ui_update_data_model(surfaceId:'contact_form', path:'/form', value:{name:'',email:'',message:''})"
+
+  - user_input: "I need a signup form with email validation"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with TextField({value:{path:'/form/email'}, checks:[{call:'required',...},{call:'email',...}]}) → a2ui_update_data_model"
+
+  - user_input: "creá un formulario multi-paso"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Tabs+Column per step → a2ui_update_data_model for all fields"
+---
+
+# A2UI Form Skill
+
+## Cuándo se Activa
+
+Para crear formularios interactivos ricos usando el protocolo A2UI v0.9. Usar cuando se necesita:
+- Validación de campos (required, email, regex)
+- Data binding dinámico
+- Formularios multi-paso
+- Choice pickers, sliders, checkboxes
+- Formularios con acciones personalizadas
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía componentes | Después de crear surface |
+| `a2ui_update_data_model` | Actualiza datos | Para valores iniciales o dinámicos |
+| `a2ui_delete_surface` | Elimina la superficie | Al terminar |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // opcional, para datos iniciales
+4. [esperar acción del usuario]
+5. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Componentes Disponibles
+
+| Componente | Descripción | Props clave |
+|------------|-------------|-------------|
+| `Column` | Layout vertical | `children`, `distribution`, `alignment` |
+| `Row` | Layout horizontal | `children`, `distribution`, `alignment` |
+| `Text` | Texto | `text`, `usageHint` (h1-h5, body, caption, code) |
+| `Button` | Botón | `child`, `variant`, `action` |
+| `TextField` | Campo de texto | `label`, `value`, `variant` (shortText/longText/number/obscured), `validationRegexp`, `checks`, `action` |
+| `CheckBox` | Checkbox | `label`, `value` |
+| `ChoicePicker` | Selector múltiple | `options`, `value` (DynamicStringList), `variant` (mutuallyExclusive/multipleSelection), `displayStyle`, `filterable`, `action` |
+| `Slider` | Slider numérico | `value`, `minValue`, `maxValue` |
+| `DateTimeInput` | Fecha/hora | `value`, `enableDate`, `enableTime` |
+| `Card` | Tarjeta | `child` |
+| `Divider` | Separador | `axis` |
+| `Image` | Imagen | `url`, `fit` |
+| `Tabs` | Pestañas | `tabItems` |
+
+## Data Binding
+
+- Literal: `"texto directo"` o número
+- Path: `{ "path": "/form/name" }` — se resuelve contra el data model
+- Function call: `{ "call": "formatDate", "args": {...} }`
+
+## Cuándo disparan acciones los inputs
+
+| Componente | Cuándo dispara | Formato de action |
+|------------|---------------|-------------------|
+| `Button` | Al hacer click | `{name: "...", context: {...}}` o `{event: {name: "...", context: {...}}}` |
+| `TextField` | Al perder foco (blur) o presionar Enter (en shortText) | `{name: "...", context: {...}}` |
+| `ChoicePicker` | Inmediatamente al seleccionar/deseleccionar | `{name: "...", context: {...}}` |
+| `Slider` | Al soltar el slider (onValueCommit) | `{name: "...", context: {...}}` |
+| `CheckBox` | Al cambiar estado | — (solo two-way binding) |
+| `DateTimeInput` | Al cambiar valor | — (solo two-way binding) |
+
+**Nota**: Tanto `{name: "...", context: {...}}` (directo) como `{event: {name: "...", context: {...}}}` (con wrapper) son formatos válidos.
+
+**Nota**: Para ChoicePicker usa siempre `selections: {path: "..."}` (no `value`) para two-way binding.
+
+## Validación (checks)
+
+```json
+"checks": [
+  { "call": "required", "args": { "value": { "path": "/form/email" } }, "message": "Email is required" },
+  { "call": "email", "args": { "value": { "path": "/form/email" } }, "message": "Invalid email" },
+  { "call": "regex", "args": { "value": { "path": "/form/phone" }, "pattern": "^\\d{10}$" }, "message": "10 digits required" }
+]
+```
+
+## Ejemplo: Formulario de Contacto
+
+```json
+// 1. Create surface
+a2ui_create_surface(surfaceId: "contact_form", catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json", theme: {primaryColor: "#3B82F6", agentDisplayName: "Asistente"})
+
+// 2. Send components
+a2ui_update_components(surfaceId: "contact_form", components: [
+  {"id": "root", "component": "Column", "children": ["header","name_field","email_field","msg_field","submit_btn"]},
+  {id: "header", component: "Text", text: "Contacto", variant: "h2"},
+  {id: "name_field", component: "TextField", label: "Nombre", value: {path: "/form/name"}, variant: "shortText"},
+  {id: "email_field", component: "TextField", label: "Email", value: {path: "/form/email"}, variant: "shortText", validationRegexp: "^[^@]+@[^@]+\\.[^@]+$", checks: [{call: "required", args: {value: {path: "/form/email"}}, message: "Email obligatorio"}, {call: "email", args: {value: {path: "/form/email"}}, message: "Email inválido"}]},
+  {id: "msg_field", component: "TextField", label: "Mensaje", value: {path: "/form/message"}, variant: "longText"},
+  {id: "submit_label", component: "Text", text: "Enviar"},
+  {id: "submit_btn", component: "Button", child: "submit_label", variant: "primary", action: {event: {name: "submit_contact", context: {name: {path: "/form/name"}, email: {path: "/form/email"}, message: {path: "/form/message"}}}}
+])
+
+// 3. Initialize data model
+a2ui_update_data_model(surfaceId: "contact_form", path: "/form", value: {name: "", email: "", message: ""})
+```
+
+## Mejores Prácticas
+
+- Siempre incluir un componente `root` con id="root"
+- Usar `{ path: "/..." }` para data binding en TextField values
+- Agregar `checks` para validación de campos obligatorios
+- Usar `variant: "primary"` para botones principales
+- Eliminar surfaces con `a2ui_delete_surface` al terminar
+- Usar formularios A2UI para toda captura estructurada de datos