@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/docs/content/cli-adapters.md

@@ -0,0 +1,244 @@
+---
+title: "CLI Adapters"
+description: "Connect any CLI tool to your agent-native app with a standard adapter interface for discovery and execution."
+---
+
+# CLI Adapters
+
+Give your agent structured access to any CLI tool — with discovery, execution, and consistent output handling.
+
+## Overview {#overview}
+
+Agents are great at running CLI commands. But without structure, every script reinvents how to invoke a CLI, check if it's installed, and parse its output.
+
+CLI adapters solve this with a small interface — similar to file sync adapters but for command-line tools. Each adapter wraps a single CLI (`gh`, `ffmpeg`, `stripe`, `aws`) and provides:
+
+- **Discovery** — the agent can list what CLIs are available and what they do
+- **Availability checks** — is the CLI installed?
+- **Consistent execution** — stdout, stderr, and exit code in a standard format
+
+## The interface {#the-interface}
+
+Every CLI adapter implements `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## ShellCliAdapter {#shell-adapter}
+
+For most CLIs, you don't need a custom class. `ShellCliAdapter` wraps any CLI binary with sensible defaults:
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+});
+
+const stripe = new ShellCliAdapter({
+  command: "stripe",
+  description: "Stripe CLI — manage payments, webhooks, and customers",
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+### Options {#shell-adapter-options}
+
+| Option        | Type   | Description                                         |
+| ------------- | ------ | --------------------------------------------------- |
+| `command`     | string | Binary name or path (required)                      |
+| `description` | string | What the CLI does — shown to the agent (required)   |
+| `name`        | string | Display name (defaults to `command`)                |
+| `env`         | Record | Extra environment variables merged with process.env |
+| `cwd`         | string | Working directory (defaults to process.cwd())       |
+| `timeoutMs`   | number | Execution timeout (default: 30000)                  |
+
+## Registry {#registry}
+
+The `CliRegistry` collects adapters so the agent can discover what's available at runtime:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "ffmpeg",
+    description: "Audio/video processing and transcoding",
+  }),
+);
+
+// List all registered CLIs
+cliRegistry.list();
+// → [{ name: "gh", ... }, { name: "ffmpeg", ... }]
+
+// List only installed CLIs
+await cliRegistry.listAvailable();
+// → [{ name: "gh", ... }]  (if ffmpeg isn't installed)
+
+// Get a full summary for agent discovery
+await cliRegistry.describe();
+// → [{ name: "gh", description: "...", available: true },
+//    { name: "ffmpeg", description: "...", available: false }]
+
+// Execute a command
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+console.log(result?.stdout);
+```
+
+## Custom adapters {#custom-adapter}
+
+When you need more than `ShellCliAdapter` provides — custom auth, output parsing, or pre/post processing — implement `CliAdapter` directly:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+import { execFile } from "node:child_process";
+
+export class DockerAdapter implements CliAdapter {
+  name = "docker";
+  description =
+    "Docker container management — build, run, and manage containers";
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      const result = await this.execute([
+        "info",
+        "--format",
+        "{{.ServerVersion}}",
+      ]);
+      return result.exitCode === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  async execute(args: string[]): Promise<CliResult> {
+    return new Promise((resolve) => {
+      execFile(
+        "docker",
+        args,
+        {
+          timeout: 60_000,
+          maxBuffer: 10 * 1024 * 1024,
+          encoding: "utf-8",
+        },
+        (error, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            exitCode: (error as any)?.code ?? 0,
+          });
+        },
+      );
+    });
+  }
+}
+```
+
+## Server route {#server-route}
+
+Expose the registry to the UI via an API route so actions and components can discover and invoke CLIs:
+
+```ts
+// server/index.ts
+import { createServer } from "@agent-native/core";
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const app = createServer();
+const cliRegistry = new CliRegistry();
+
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI",
+  }),
+);
+
+// Discovery endpoint — agent can query this
+app.get("/api/cli", async (_req, res) => {
+  const tools = await cliRegistry.describe();
+  res.json(tools);
+});
+
+// Execution endpoint
+app.post("/api/cli/:name", async (req, res) => {
+  const adapter = cliRegistry.get(req.params.name);
+  if (!adapter) return res.status(404).json({ error: "CLI not found" });
+
+  const { args } = req.body;
+  const result = await adapter.execute(args ?? []);
+  res.json(result);
+});
+```
+
+## Using from actions {#from-scripts}
+
+Actions can use CLI adapters directly for structured access:
+
+```ts
+// actions/list-prs.ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI",
+});
+
+export default async function listPrs() {
+  if (!(await gh.isAvailable())) {
+    console.error("GitHub CLI not installed. Run: brew install gh");
+    process.exit(1);
+  }
+
+  const result = await gh.execute([
+    "pr",
+    "list",
+    "--json",
+    "title,url,state",
+    "--limit",
+    "10",
+  ]);
+
+  if (result.exitCode !== 0) {
+    console.error(result.stderr);
+    process.exit(1);
+  }
+
+  const prs = JSON.parse(result.stdout);
+  const fs = await import("node:fs/promises");
+  await fs.writeFile("data/prs.json", JSON.stringify(prs, null, 2));
+  console.log(`Fetched ${prs.length} PRs`);
+}
+```
+
+Or skip the adapter entirely and call the CLI directly in a script — adapters are useful when you want discovery, availability checks, and consistent error handling, but they're not required. Use whichever approach fits.

package/docs/content/client.md

@@ -0,0 +1,175 @@
+---
+title: "Client"
+description: "React hooks and utilities for agent-native apps: sendToAgentChat, useDbSync, useAgentChatGenerating, and cn."
+---
+
+# Client
+
+`@agent-native/core` provides React hooks and utilities for the browser-side of agent-native apps.
+
+## File-Based Routing {#file-based-routing}
+
+Agent-native apps use **React Router v7** with file-based routing. Every file in `app/routes/` becomes a URL.
+
+### File → URL mapping
+
+| File                             | URL                                   |
+| -------------------------------- | ------------------------------------- |
+| `app/routes/_index.tsx`          | `/`                                   |
+| `app/routes/settings.tsx`        | `/settings`                           |
+| `app/routes/inbox/index.tsx`     | `/inbox`                              |
+| `app/routes/inbox/$threadId.tsx` | `/inbox/:threadId`                    |
+| `app/routes/inbox.$threadId.tsx` | `/inbox/:threadId` (flat alternative) |
+
+Prefix a segment with `$` for dynamic params. Prefix with `_` to make it a pathless layout route (doesn't add a URL segment). `_index.tsx` is the index route for its folder.
+
+### Adding a new page
+
+Create the file and export a default component:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+That's it — React Router picks it up automatically, no registration needed.
+
+### Dynamic params
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+### Navigation
+
+Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+---
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Send a message to the agent chat via postMessage. Used to delegate AI tasks from UI interactions.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option                | Type        | Description                                    |
+| --------------------- | ----------- | ---------------------------------------------- |
+| `message`             | `string`    | The visible prompt sent to the chat            |
+| `context`             | `string?`   | Hidden context appended (not shown in chat UI) |
+| `submit`              | `boolean?`  | true = auto-submit, false = prefill only       |
+| `projectSlug`         | `string?`   | Optional project slug for structured context   |
+| `preset`              | `string?`   | Optional preset name for downstream consumers  |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                 |
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+React hook that wraps sendToAgentChat with loading state tracking:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating` turns true when you call `send()` and automatically resets to false when the agent finishes generating.
+
+## useDbSync(options?) {#usedbsync}
+
+React hook (formerly `useFileWatcher`) that polls for database changes and invalidates react-query caches:
+
+```ts
+import { useDbSync } from "@agent-native/core";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    queryKeys: ["files", "projects", "versionHistory"],
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### Options {#usedbsync-options}
+
+| Option        | Type             | Description                                                       |
+| ------------- | ---------------- | ----------------------------------------------------------------- |
+| `queryClient` | `QueryClient?`   | React-query client for cache invalidation                         |
+| `queryKeys`   | `string[]?`      | Query key prefixes to invalidate. Default: `["file", "fileTree"]` |
+| `pollUrl`     | `string?`        | Poll endpoint URL. Default: `"/_agent-native/poll"`               |
+| `onEvent`     | `(data) => void` | Optional callback for each SSE event                              |
+
+## cn(...inputs) {#cn}
+
+Utility for merging class names (clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```

package/docs/content/context-awareness.md

@@ -0,0 +1,168 @@
+---
+title: "Context Awareness"
+description: "How the agent knows what the user is looking at: navigation state, view-screen, navigate commands, and jitter prevention."
+---
+
+# Context Awareness
+
+How the agent knows what the user is looking at — and how the agent can control what the user sees.
+
+## Overview {#overview}
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees.
+
+Three patterns solve this:
+
+1. **Navigation state** — the UI writes a `navigation` key to application-state on every route change
+2. **`view-screen`** — an action that reads navigation state, fetches contextual data, and returns a snapshot of what the user sees
+3. **`navigate`** — a one-shot command from the agent that tells the UI where to go
+
+## Navigation state {#navigation-state}
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+
+```json
+{
+  "view": "inbox",
+  "threadId": "thread-123",
+  "focusedEmailId": "msg-456",
+  "search": "budget",
+  "label": "important"
+}
+```
+
+What to include in navigation state:
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`)
+- Filter state — active search, label, or category filters
+- Any selection — focused item, selected text range, active tab
+
+The agent reads this before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// { view: "inbox", threadId: "thread-123", label: "important" }
+```
+
+## The view-screen action {#view-screen-action}
+
+Every template should have a `view-screen` action. It reads navigation state, fetches the relevant data, and returns a snapshot of what the user sees. This is the agent's eyes.
+
+```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 };
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const res = await fetch(
+      "http://localhost:3000/api/emails?label=" + navigation.label,
+    );
+    screen.emailList = await res.json();
+  }
+  if (navigation?.threadId) {
+    const res = await fetch(
+      "http://localhost:3000/api/threads/" + navigation.threadId,
+    );
+    screen.thread = await res.json();
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+The agent should always call `pnpm action view-screen` before acting. This is a hard convention across all templates. When adding new features, update `view-screen` to return data for the new view.
+
+## The navigate action {#navigate-action}
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+```ts
+// Agent side — write a navigate command
+import { writeAppState } from "@agent-native/core/application-state";
+
+await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
+```
+
+The UI polls for this command and navigates when it appears:
+
+```ts
+// UI side — poll for navigate commands
+const { data: navCommand } = useQuery({
+  queryKey: ["navigate-command"],
+  queryFn: async () => {
+    const res = await fetch("/_agent-native/application-state/navigate");
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (data) {
+      // Delete the one-shot command after reading
+      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
+      return data;
+    }
+    return null;
+  },
+  staleTime: 2_000,
+});
+
+useEffect(() => {
+  if (navCommand) {
+    router.navigate(buildPath(navCommand));
+  }
+}, [navCommand]);
+```
+
+The `navigation` key belongs to the UI — the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation (which then updates `navigation`).
+
+## useNavigationState hook {#use-navigation-state}
+
+The `use-navigation-state.ts` hook syncs routes to application-state on every navigation:
+
+```ts
+// app/hooks/use-navigation-state.ts
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+
+export function useNavigationState() {
+  const location = useLocation();
+
+  useEffect(() => {
+    const state = deriveNavigationState(location.pathname);
+    fetch("/_agent-native/application-state/navigation", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+}
+```
+
+The `deriveNavigationState()` function is template-specific — it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
+
+## Jitter prevention {#jitter-prevention}
+
+When the agent writes to application-state, the polling system might cause the UI to refetch data it just wrote. This creates jitter. The solution is source tagging:
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID, // ignore events from this tab's own writes
+});
+```
+
+How it works:
+
+- Agent writes are tagged with `requestSource: "agent"` (the action helpers do this automatically)
+- UI writes include the tab's unique ID via `X-Request-Source` header
+- The server stores the source on each event
+- When polling, the UI filters out events matching its own `ignoreSource` value — so it doesn't refetch data it just wrote
+- Events from agents, other tabs, and actions still come through normally