@agent-native/core 0.6.1 → 0.7.2

package/dist/vite/client.js

@@ -4,6 +4,7 @@ import { createRequire } from "module";
 import { nitro as nitroVitePlugin } from "nitro/vite";
 import { actionTypesPlugin } from "./action-types-plugin.js";
 import { agentsBundlePlugin } from "./agents-bundle-plugin.js";
+import { findWorkspaceRoot } from "../scripts/utils.js";
 import { fileURLToPath } from "url";
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -294,6 +295,50 @@ function rolldownInputFix() {
  * in-process scripts (which use localFetch → http://localhost:${PORT}/api/...)
  * hit the right address even when Vite auto-increments the port.
  */
+/**
+ * Replace caller-specified packages with an empty proxy stub during SSR
+ * builds. For apps whose heavy browser-only deps would otherwise bloat the
+ * edge worker past CF Pages' 25 MiB Functions limit.
+ *
+ * The template lists the packages in its `defineConfig({ ssrStubs })` call —
+ * the framework never hardcodes package names.
+ */
+function ssrStubPlugin(packages) {
+    if (!packages.length)
+        return null;
+    const stubbed = new Set(packages);
+    const STUB_ID = "\0agent-native-ssr-stub";
+    return {
+        name: "agent-native-ssr-stub-heavy-libs",
+        enforce: "pre",
+        resolveId(id, _importer, opts) {
+            if (!opts?.ssr)
+                return null;
+            // Match the bare package name or any subpath
+            const pkg = id
+                .split("/")
+                .slice(0, id.startsWith("@") ? 2 : 1)
+                .join("/");
+            if (stubbed.has(pkg))
+                return STUB_ID;
+            return null;
+        },
+        load(id) {
+            if (id !== STUB_ID)
+                return null;
+            // Proxy that answers any property access with itself — lets dead
+            // import/re-export chains parse without blowing up, and still throws
+            // if code actually tries to call any of it on the server.
+            return ("const handler = { get(_, p) { " +
+                "if (p === Symbol.toPrimitive) return () => ''; " +
+                "if (p === 'then') return undefined; " +
+                "return new Proxy(() => {}, handler); " +
+                "} };" +
+                "const stub = new Proxy(() => {}, handler);" +
+                "export default stub;");
+        },
+    };
+}
 function portExposer() {
     return {
         name: "agent-native-port-exposer",
@@ -308,6 +353,47 @@ function portExposer() {
         },
     };
 }
+/**
+ * Silence benign `read ECONNRESET` noise from Vite's dev middleware.
+ * Fires when a browser closes/reloads/navigates mid-request — the peer has
+ * already gone away, there's nothing to fix, and Vite's error middleware
+ * spams the terminal with "Internal server error: read ECONNRESET". Our H3
+ * server layer already swallows this (create-server.ts onError); this plugin
+ * does the same for Vite's own connect pipeline.
+ */
+function silenceConnectionResets() {
+    const isBenign = (err) => {
+        const e = err;
+        const code = e?.code || e?.cause?.code;
+        return (code === "ECONNRESET" ||
+            code === "ECONNABORTED" ||
+            code === "EPIPE" ||
+            e?.message === "aborted");
+    };
+    return {
+        name: "agent-native-silence-connection-resets",
+        apply: "serve",
+        configureServer(server) {
+            // Swallow socket-level resets so Node doesn't surface them as uncaught.
+            server.httpServer?.on("connection", (socket) => {
+                socket.on("error", (err) => {
+                    if (!isBenign(err))
+                        throw err;
+                });
+            });
+            // Drop Vite's "Internal server error: read ECONNRESET" log lines.
+            const origError = server.config.logger.error.bind(server.config.logger);
+            server.config.logger.error = (msg, opts) => {
+                const text = typeof msg === "string" ? msg : String(msg ?? "");
+                if ((opts?.error && isBenign(opts.error)) ||
+                    /Internal server error:\s*(read ECONNRESET|aborted|EPIPE)/i.test(text)) {
+                    return;
+                }
+                origError(msg, opts);
+            };
+        },
+    };
+}
 /**
  * Create the client Vite config with sensible agent-native defaults.
  * Supports two modes:
@@ -333,9 +419,32 @@ export function defineConfig(options = {}) {
         }
     }
     const cwd = process.cwd();
+    // Workspace env fallback. If this app is inside a workspace, tell Vite to
+    // also look for .env files at the workspace root. Per-app .env still wins
+    // (Vite's loadEnv merges in precedence order — app dir is loaded after).
+    const workspaceRoot = findWorkspaceRoot(cwd);
+    const envDir = workspaceRoot && workspaceRoot !== cwd ? workspaceRoot : cwd;
+    // Preload workspace-root .env into process.env so Nitro server code sees
+    // shared keys during dev (Nitro reads process.env, not vite's envDir).
+    if (workspaceRoot && workspaceRoot !== cwd) {
+        try {
+            const dotenv = require("dotenv");
+            dotenv.config({
+                path: path.join(workspaceRoot, ".env"),
+                override: false,
+            });
+        }
+        catch { }
+    }
     // Build the React transform plugin (only for legacy SPA mode)
     const reactPluginInstance = reactTransformPlugin?.();
+    // APP_BASE_PATH lets this app be mounted under a prefix (e.g. "/mail") as
+    // part of a unified workspace deploy. Defaults to "/" for standalone apps.
+    const appBasePath = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "/";
+    const base = appBasePath.endsWith("/") ? appBasePath : `${appBasePath}/`;
     return {
+        envDir,
+        base,
         server: {
             host: "::",
             port: options.port ?? 8080,
@@ -362,11 +471,19 @@ export function defineConfig(options = {}) {
             noExternal: /^(?!node:)/,
         },
         plugins: [
+            // Stub packages from `options.ssrStubs` in the SSR bundle so they
+            // don't bloat the edge worker. Opt-in per template — the framework
+            // hardcodes nothing.
+            ...(() => {
+                const p = ssrStubPlugin(options.ssrStubs ?? []);
+                return p ? [p] : [];
+            })(),
             actionTypesPlugin(),
             agentsBundlePlugin(),
             autoReloadOnOptimizeDep(),
             baseRedirectGuard(),
             portExposer(),
+            silenceConnectionResets(),
             rolldownInputFix(),
             // Nitro Vite plugin for dev-mode API route serving and HMR.
             // Disabled during build — React Router's build handles production.
@@ -394,6 +511,19 @@ export function defineConfig(options = {}) {
                 : {}),
         },
         resolve: {
+            // Dedupe React and Radix — without this, a second copy of React can get
+            // loaded from `packages/core`'s own node_modules (via pnpm symlinks),
+            // which breaks hooks-based libraries like Radix Select with "Invalid
+            // hook call" / "Cannot read properties of null (reading 'useMemo')".
+            dedupe: [
+                "react",
+                "react-dom",
+                "react-dom/client",
+                "@radix-ui/react-select",
+                "@radix-ui/react-popover",
+                "@radix-ui/react-tooltip",
+                "@radix-ui/react-dialog",
+            ],
             alias: [
                 // In monorepo dev: resolve @agent-native/core to source for HMR.
                 // Uses regex with $ anchor for exact matching to prevent

package/dist/vite/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/vite/client.ts"],"names":[],"mappings":"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"}

package/docs/content/a2a-protocol.md

@@ -0,0 +1,223 @@
+---
+title: "A2A Protocol"
+description: "Agent-to-agent communication via JSON-RPC: discovery, messaging, streaming, and task management."
+---
+
+# A2A Protocol
+
+Agent-to-agent communication over HTTP. Agents discover each other, send messages, and receive structured results.
+
+## Overview {#overview}
+
+A2A (agent-to-agent) is a JSON-RPC protocol for inter-agent communication. A mail agent can ask an analytics agent to run a query. A calendar agent can search issues in a project management agent. Each agent exposes its capabilities via an agent card and accepts work via a standard JSON-RPC endpoint.
+
+Key concepts:
+
+- **Agent card** — public metadata at `/.well-known/agent-card.json` describing skills and capabilities
+- **JSON-RPC** — all communication goes through `POST /a2a` with standard JSON-RPC 2.0
+- **Tasks** — each message creates a task with a lifecycle (submitted, working, completed, failed, canceled)
+- **Bearer auth** — optional API key authentication via environment variable
+
+## Server setup {#server-setup}
+
+Call `mountA2A()` in a server plugin to expose the A2A endpoints:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro.h3App, {
+    name: "Analytics Agent",
+    description: "Runs analytics queries and returns chart data",
+    skills: [
+      {
+        id: "run-query",
+        name: "Run Query",
+        description: "Execute a SQL query against the analytics database",
+        tags: ["analytics", "sql"],
+        examples: ["Show me signups by source this month"],
+      },
+    ],
+    apiKeyEnv: "A2A_API_KEY", // env var name for bearer token
+    streaming: true, // enable message/stream
+  });
+});
+```
+
+This mounts two endpoints: `GET /.well-known/agent-card.json` (public, no auth) and `POST /a2a` (authenticated JSON-RPC).
+
+## Agent card {#agent-card}
+
+The agent card is auto-generated from your config and served at `/.well-known/agent-card.json`. Other agents fetch it to discover your agent's skills.
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Runs analytics queries and returns chart data",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": true
+  },
+  "skills": [
+    {
+      "id": "run-query",
+      "name": "Run Query",
+      "description": "Execute a SQL query against the analytics database",
+      "tags": ["analytics", "sql"],
+      "examples": ["Show me signups by source this month"]
+    }
+  ],
+  "securitySchemes": {
+    "apiKey": { "type": "http", "scheme": "bearer" }
+  },
+  "security": [{ "apiKey": [] }]
+}
+```
+
+## JSON-RPC methods {#json-rpc-methods}
+
+All methods are called via `POST /a2a` with JSON-RPC 2.0 format:
+
+| Method           | Description                               | Key params            |
+| ---------------- | ----------------------------------------- | --------------------- |
+| `message/send`   | Send a message, get a completed task back | `message, contextId?` |
+| `message/stream` | Send a message, receive SSE task updates  | `message, contextId?` |
+| `tasks/get`      | Fetch a task by ID                        | `id`                  |
+| `tasks/cancel`   | Cancel a running task                     | `id`                  |
+
+Messages contain typed parts:
+
+```json
+{
+  "role": "user",
+  "parts": [
+    { "type": "text", "text": "Show signups by source" },
+    { "type": "data", "data": { "dateRange": "last-30d" } },
+    {
+      "type": "file",
+      "file": { "name": "report.csv", "mimeType": "text/csv", "bytes": "..." }
+    }
+  ]
+}
+```
+
+## Client {#client}
+
+The `A2AClient` class handles discovery, messaging, and streaming:
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient("https://analytics.example.com", "my-api-key");
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+console.log(card.skills);
+
+// Send a message and get a completed task
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "Show signups by source this month" }],
+});
+console.log(task.status.state); // "completed"
+console.log(task.status.message); // agent's response
+
+// Stream responses for long-running work
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Generate a full quarterly report" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## Convenience helper {#convenience-helper}
+
+For simple text-in/text-out calls, use `callAgent()`:
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// One-shot: send text, get text back
+const response = await callAgent(
+  "https://analytics.example.com",
+  "How many signups last week?",
+  { apiKey: process.env.ANALYTICS_API_KEY },
+);
+console.log(response); // "There were 1,247 signups last week..."
+```
+
+## Task lifecycle {#task-lifecycle}
+
+Each message creates a task that moves through these states:
+
+`submitted` → `working` → `completed` | `failed` | `canceled`
+
+| State            | Meaning                                        |
+| ---------------- | ---------------------------------------------- |
+| `submitted`      | Task created, queued for processing            |
+| `working`        | Handler is processing the message              |
+| `completed`      | Handler finished successfully                  |
+| `failed`         | Handler threw an error                         |
+| `canceled`       | Task was canceled via tasks/cancel             |
+| `input-required` | Handler needs more information from the caller |
+
+Tasks persist in the `a2a_tasks` SQL table and can be retrieved later via `tasks/get`.
+
+## Security {#security}
+
+Set `apiKeyEnv` in your config to the name of an environment variable containing the expected bearer token:
+
+```ts
+// Config
+mountA2A(app, {
+  // ...
+  apiKeyEnv: "A2A_API_KEY", // reads process.env.A2A_API_KEY
+});
+
+// Client calls with the matching key
+const client = new A2AClient(url, process.env.A2A_API_KEY);
+```
+
+The agent card endpoint is always public (no auth) so other agents can discover capabilities. The `/a2a` JSON-RPC endpoint requires a valid bearer token when `apiKeyEnv` is set. In dev mode (no env var configured), auth is skipped.
+
+## Agent mentions {#agent-mentions}
+
+You can `@`-mention agents directly in the chat composer. Connected agents use A2A: when you mention a connected agent, the server makes an A2A call to that agent and weaves the response into your conversation context.
+
+Custom workspace agents are different: they run locally inside the current app/runtime rather than over A2A.
+
+See [Agent Mentions](/docs/agent-mentions) for details on how mentions work, how to add agents, and how to create custom mention providers.
+
+## Messaging integrations {#messaging-integrations}
+
+Agents can also be reached from external messaging platforms like Slack, Telegram, and WhatsApp. Users send messages on those platforms and the agent responds in the same thread, using the same tools and actions as the web chat.
+
+See [Integrations](/docs/integrations) for setup details on each platform.
+
+## Example: cross-agent query {#example}
+
+A mail agent needs analytics data. The analytics agent exposes a "run-query" skill via A2A:
+
+```ts
+// In the mail agent's actions/get-analytics.ts
+import { callAgent } from "@agent-native/core/a2a";
+
+export default async function (args: string[]) {
+  const response = await callAgent(
+    "https://analytics.example.com",
+    "How many emails were sent last week by category?",
+    { apiKey: process.env.ANALYTICS_API_KEY },
+  );
+
+  console.log(response);
+  // The mail agent can now use this data in its response
+}
+```
+
+The analytics agent receives the message, runs the query via its handler, and returns the result. The mail agent's script gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.

package/docs/content/actions.md

@@ -0,0 +1,129 @@
+---
+title: "Actions"
+description: "Action dispatcher, parseArgs, standard actions, and utility functions for agent-callable operations."
+---
+
+# Actions
+
+`@agent-native/core` provides an action dispatcher and utilities for building agent-callable actions.
+
+## Action Dispatcher {#action-dispatcher}
+
+The action system lets you create actions that agents can invoke via `pnpm action <name>`. Each action is a TypeScript file that exports a default async function.
+
+```ts
+// actions/run.ts — dispatcher (one-time setup)
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+```ts
+// actions/hello.ts — example action
+import { parseArgs } from "@agent-native/core";
+
+export default async function hello(args: string[]) {
+  const { name } = parseArgs(args);
+  console.log(`Hello, ${name ?? "world"}!`);
+}
+```
+
+```bash
+# Run it
+pnpm action hello --name Steve
+```
+
+## parseArgs(args) {#parseargs}
+
+Parse CLI arguments in `--key value` or `--key=value` format:
+
+```ts
+import { parseArgs } from "@agent-native/core";
+
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
+```
+
+## Standard actions {#standard-actions}
+
+Every template should include these two actions for [context awareness](/docs/context-awareness):
+
+### view-screen {#view-screen}
+
+Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent should always call this before acting.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  if (navigation?.view === "inbox") {
+    const res = await fetch(
+      "http://localhost:3000/api/emails?label=" + navigation.label,
+    );
+    screen.emailList = await res.json();
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+```bash
+pnpm action view-screen
+```
+
+### navigate {#navigate}
+
+Writes a one-shot navigation command to application-state. The UI reads it, navigates, and deletes the entry.
+
+```ts
+// actions/navigate.ts
+import { parseArgs } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+
+export default async function main(args: string[]) {
+  const parsed = parseArgs(args);
+  await writeAppState("navigate", parsed);
+  console.log("Navigate command written:", parsed);
+}
+```
+
+```bash
+pnpm action navigate --view inbox --threadId thread-123
+```
+
+## Shared Agent Chat {#shared-agent-chat}
+
+`@agent-native/core` provides an isomorphic chat bridge that works in both browser and Node.js:
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+// Auto-submit a message
+agentChat.submit("Generate a report for Q4");
+
+// Prefill without submitting
+agentChat.prefill("Draft an email to...", contextData);
+
+// Full control
+agentChat.send({
+  message: "Process this data",
+  context: JSON.stringify(data),
+  submit: true,
+});
+```
+
+In the browser, messages are sent via `window.postMessage()`. In Node.js (actions), they use the `BUILDER_PARENT_MESSAGE:` stdout format that the Electron host translates to postMessage.
+
+## Utility Functions {#utility-functions}
+
+| Function                | Returns   | Description                                        |
+| ----------------------- | --------- | -------------------------------------------------- |
+| `loadEnv(path?)`        | `void`    | Load .env from project root (or custom path)       |
+| `camelCaseArgs(args)`   | `Record`  | Convert kebab-case keys to camelCase               |
+| `isValidPath(p)`        | `boolean` | Validate relative path (no traversal, no absolute) |
+| `isValidProjectPath(p)` | `boolean` | Validate project slug (e.g. "my-project")          |
+| `ensureDir(dir)`        | `void`    | mkdir -p helper                                    |
+| `fail(message)`         | `never`   | Print error to stderr and exit(1)                  |