@agent-native/core 0.7.12 → 0.7.14

package/src/templates/default/.agents/skills/progress/SKILL.md

@@ -22,25 +22,27 @@ Separate concern from `notifications`:
 
 Common pattern: on completion, emit a `notify()` so the user sees the outcome when they're not actively watching the tray.
 
-## Available Tools
+## Tool
 
-| Tool | Purpose |
+All progress operations go through a single `manage-progress` tool with an `action` parameter:
+
+| Action | Purpose |
 |---|---|
-| `start-run` | Mark the start of a long task. Returns a runId. |
-| `update-run-progress` | Update percent and/or current step. Call frequently. |
-| `complete-run` | Mark terminal status: `succeeded`, `failed`, `cancelled`. |
-| `list-runs` | List recent runs (all or `--active=true`). |
+| `start` | Mark the start of a long task. Returns a runId. |
+| `update` | Update percent and/or current step. Call frequently. |
+| `complete` | Mark terminal status: `succeeded`, `failed`, `cancelled`. |
+| `list` | List recent runs (all or `--active=true`). |
 
 ## Canonical Flow
 
 ```
-start-run --title "Triage 128 unread emails" --step "Fetching inbox"
+manage-progress --action=start --title "Triage 128 unread emails" --step "Fetching inbox"
   → runId=abc
 
-update-run-progress --runId=abc --percent=25 --step="Classifying 32/128"
-update-run-progress --runId=abc --percent=75 --step="Drafting replies 97/128"
+manage-progress --action=update --runId=abc --percent=25 --step="Classifying 32/128"
+manage-progress --action=update --runId=abc --percent=75 --step="Drafting replies 97/128"
 
-complete-run --runId=abc --status=succeeded
+manage-progress --action=complete --runId=abc --status=succeeded
 notify --severity=info --title="Triage done" --body="12 archived, 6 drafts ready to review"
 ```
 
@@ -48,9 +50,9 @@ notify --severity=info --title="Triage done" --body="12 archived, 6 drafts ready
 
 - **Start a run for anything > ~5 seconds.** Users want feedback; a spinner with no context feels frozen.
 - **Update at natural checkpoints**, not every iteration. Every 5–10% is enough for most UIs.
-- **Always call `complete-run`** at the end — including the error path. An orphaned `running` row is worse than no row.
+- **Always call `manage-progress --action=complete`** at the end — including the error path. An orphaned `running` row is worse than no row.
 - **Pair with `notify`** on completion. The tray tells users what's *running*; notifications tell them what *finished*.
-- **Use `metadataJson`** on `start-run` to pass a link back to the produced artifact (thread id, document path), so the UI can deep-link from the runs tray.
+- **Use `metadataJson`** on `manage-progress --action=start` to pass a link back to the produced artifact (thread id, document path), so the UI can deep-link from the runs tray.
 
 ## Runs API
 

package/src/templates/default/app/root.tsx

@@ -5,8 +5,10 @@ import {
   Scripts,
   ScrollRestoration,
   isRouteErrorResponse,
+  Link,
+  useRouteError,
 } from "react-router";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import {
   QueryClient,
   QueryClientProvider,
@@ -16,6 +18,13 @@ import { ThemeProvider } from "next-themes";
 import { useDbSync } from "@agent-native/core";
 import { ClientOnly, DefaultSpinner } from "@agent-native/core/client";
 import { Toaster } from "sonner";
+import { configureTracking } from "@agent-native/core/client";
+configureTracking({
+  getDefaultProps: (_name, properties) => ({
+    ...properties,
+    app: "{{APP_NAME}}",
+  }),
+});
 import "./global.css";
 
 export function Layout({ children }: { children: React.ReactNode }) {
@@ -74,17 +83,41 @@ export default function Root() {
   );
 }
 
-export function ErrorBoundary({ error }: { error: unknown }) {
-  let message = "Oops!";
+function useApplyThemeClass() {
+  useEffect(() => {
+    const root = document.documentElement;
+    if (root.classList.contains("dark") || root.classList.contains("light"))
+      return;
+    try {
+      const stored = localStorage.getItem("theme");
+      if (stored === "dark") {
+        root.classList.add("dark");
+      } else if (stored === "light") {
+        root.classList.add("light");
+      } else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+        root.classList.add("dark");
+      }
+    } catch {}
+  }, []);
+}
+
+export function ErrorBoundary() {
+  useApplyThemeClass();
+  const error = useRouteError();
+  let status: number | null = null;
+  let title = "Something went wrong";
   let details = "An unexpected error occurred.";
   let stack: string | undefined;
 
   if (isRouteErrorResponse(error)) {
-    message = error.status === 404 ? "404" : "Error";
-    details =
-      error.status === 404
-        ? "The requested page could not be found."
-        : error.statusText || details;
+    status = error.status;
+    if (error.status === 404) {
+      title = "Page not found";
+      details = "This page doesn't exist. It may have been moved or deleted.";
+    } else {
+      title = `${error.status} Error`;
+      details = error.statusText || details;
+    }
   } else if (
     typeof process !== "undefined" &&
     process.env.NODE_ENV !== "production" &&
@@ -95,12 +128,23 @@ export function ErrorBoundary({ error }: { error: unknown }) {
   }
 
   return (
-    <main className="flex items-center justify-center min-h-screen p-4">
-      <div className="text-center">
-        <h1 className="text-4xl font-bold mb-2">{message}</h1>
-        <p className="text-muted-foreground">{details}</p>
+    <main className="flex items-center justify-center min-h-screen p-4 bg-background text-foreground">
+      <div className="flex flex-col items-center text-center max-w-md">
+        {status && (
+          <span className="text-7xl font-bold tracking-tight text-muted-foreground/40">
+            {status}
+          </span>
+        )}
+        <h1 className="mt-3 text-2xl font-semibold">{title}</h1>
+        <p className="mt-2 text-muted-foreground text-sm">{details}</p>
+        <Link
+          to="/"
+          className="mt-6 inline-flex items-center gap-1.5 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm hover:bg-primary/90 cursor-pointer"
+        >
+          Go home
+        </Link>
         {stack && (
-          <pre className="mt-4 text-left text-xs overflow-auto max-w-lg mx-auto p-4 bg-muted rounded">
+          <pre className="mt-6 w-full text-left text-xs overflow-auto p-4 bg-muted rounded">
             <code>{stack}</code>
           </pre>
         )}

package/src/templates/default/react-router.config.ts

@@ -3,4 +3,7 @@ import type { Config } from "@react-router/dev/config";
 export default {
   appDirectory: "app",
   ssr: true,
+  future: {
+    v8_viteEnvironmentApi: true,
+  },
 } satisfies Config;

package/docs/content/integrations.md

@@ -1,198 +0,0 @@
----
-title: "Integrations"
-description: "Connect your agent to Slack, Telegram, WhatsApp, and other messaging platforms."
----
-
-# Integrations
-
-Connect your agent to messaging platforms so you can chat with it from Slack, Telegram, WhatsApp, and more. Same agent, same tools, same thread history.
-
-## Overview {#overview}
-
-Messaging integrations let users talk to their agent from the platforms they already use. Instead of opening the web UI, you send a message in Slack or Telegram and the agent responds right there. It has access to the same actions, the same database, and the same conversation history as the web chat.
-
-Each integration works through webhooks. The messaging platform sends incoming messages to your app, the agent processes them, and the response is posted back. No polling, no long-lived connections — just standard HTTP webhooks.
-
-## How it works {#how-it-works}
-
-The flow for every platform follows the same pattern:
-
-1. A user sends a message on the external platform (Slack, Telegram, etc.)
-2. The platform delivers the message to your app via a webhook at `/_agent-native/integrations/<platform>/webhook`
-3. The integrations plugin validates the request, extracts the message text and thread context, and maps it to an internal conversation thread
-4. The agent processes the message in the background using the same pipeline as the web chat — same system prompt, same actions, same tools
-5. The response is posted back to the external platform in the same thread
-
-`User (Slack/Telegram/WhatsApp)` → `Webhook` → `Agent Processing` → `Response posted back`
-
-## Setup {#setup}
-
-The integrations plugin auto-mounts when no custom version exists in your template. To customize it, create a plugin file:
-
-```ts
-// server/plugins/integrations.ts
-import { createIntegrationsPlugin } from "@agent-native/core/server";
-import { scriptRegistry } from "../../agent.config";
-
-export default createIntegrationsPlugin({
-  actions: scriptRegistry,
-  systemPrompt: "You are a helpful assistant...",
-});
-```
-
-The plugin registers webhook routes for each enabled platform under `/_agent-native/integrations/`. Which platforms are active depends on which environment variables are configured.
-
-## Slack {#slack}
-
-### 1. Create a Slack app
-
-Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app. Under **OAuth & Permissions**, add the following bot token scopes:
-
-- `chat:write` — send messages
-- `app_mentions:read` — receive @-mentions (optional)
-
-### 2. Enable Event Subscriptions
-
-Under **Event Subscriptions**, set the Request URL to:
-
-```text
-https://your-app.example.com/_agent-native/integrations/slack/webhook
-```
-
-Subscribe to the `message.im` bot event (and optionally `app_mention` for channel mentions).
-
-### 3. Set environment variables
-
-```bash
-SLACK_BOT_TOKEN=xoxb-your-bot-token
-SLACK_SIGNING_SECRET=your-signing-secret
-```
-
-The bot token is found under **OAuth & Permissions** after installing the app to your workspace. The signing secret is under **Basic Information**.
-
-## Telegram {#telegram}
-
-### 1. Create a bot
-
-Message [@BotFather](https://t.me/BotFather) on Telegram and use the `/newbot` command. You will receive a bot token.
-
-### 2. Set environment variables
-
-```bash
-TELEGRAM_BOT_TOKEN=your-bot-token
-```
-
-### 3. Register the webhook
-
-After deploying your app, call the setup endpoint to register the webhook with Telegram:
-
-```text
-// The integrations plugin exposes a setup endpoint
-POST /_agent-native/integrations/telegram/setup
-
-// This calls Telegram's setWebhook API pointing to:
-// https://your-app.example.com/_agent-native/integrations/telegram/webhook
-```
-
-You can also register the webhook manually using the Telegram Bot API if you prefer.
-
-## WhatsApp {#whatsapp}
-
-### 1. Set up the WhatsApp Cloud API
-
-Go to the [Meta Developer Portal](https://developers.facebook.com/), create an app, and enable the WhatsApp product. Configure a phone number for your business.
-
-### 2. Set environment variables
-
-```bash
-WHATSAPP_ACCESS_TOKEN=your-access-token
-WHATSAPP_VERIFY_TOKEN=your-verify-token
-WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
-```
-
-The verify token is a string you choose — Meta uses it during webhook verification. The access token and phone number ID come from the Meta Developer Portal.
-
-### 3. Configure the webhook
-
-In the Meta Developer Portal, set the webhook URL to:
-
-```text
-https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
-```
-
-Subscribe to the `messages` webhook field.
-
-## Configuration {#configuration}
-
-Integrations can be managed from the settings UI in the sidebar. Each platform shows its connection status and webhook URL. You can enable/disable individual integrations without removing environment variables.
-
-The webhook URLs follow a consistent pattern:
-
-```text
-/_agent-native/integrations/<platform>/webhook
-
-# Examples:
-/_agent-native/integrations/slack/webhook
-/_agent-native/integrations/telegram/webhook
-/_agent-native/integrations/whatsapp/webhook
-```
-
-## Thread continuity {#thread-continuity}
-
-Conversations from external platforms are mapped to internal threads. Each Slack DM, Telegram chat, or WhatsApp conversation becomes a persistent thread in the agent-native database. This means:
-
-- The agent retains context across messages in the same external conversation
-- External conversations appear in the web UI alongside web-originated threads, tagged with their source platform
-- You can continue a conversation that started in Slack from the web UI, or vice versa
-
-## Custom adapters {#custom-adapters}
-
-To add support for a new messaging platform, implement the `PlatformAdapter` interface:
-
-```ts
-import type { PlatformAdapter } from "@agent-native/core/server";
-
-const myAdapter: PlatformAdapter = {
-  platform: "discord",
-
-  // Verify the incoming webhook request is authentic
-  verifyRequest(request: Request): Promise<boolean> {
-    // Validate signature headers
-  },
-
-  // Extract the message text and thread context from the webhook payload
-  parseMessage(body: unknown): Promise<{
-    text: string;
-    threadId: string;
-    senderId: string;
-    metadata?: Record<string, unknown>;
-  }> {
-    // Parse platform-specific payload
-  },
-
-  // Send the agent's response back to the platform
-  sendResponse(threadId: string, text: string): Promise<void> {
-    // Call the platform's API to post the message
-  },
-};
-```
-
-Register your adapter in the integrations plugin config:
-
-```ts
-export default createIntegrationsPlugin({
-  actions: scriptRegistry,
-  systemPrompt: "You are a helpful assistant...",
-  adapters: [myAdapter],
-});
-```
-
-## Security {#security}
-
-Every incoming webhook is verified before processing:
-
-- **Slack** — HMAC-SHA256 signature verification using `SLACK_SIGNING_SECRET`. The `X-Slack-Signature` header is checked against the request body.
-- **Telegram** — requests are validated by checking the secret token set during webhook registration via the Telegram Bot API.
-- **WhatsApp** — Meta's webhook verification challenge (using `WHATSAPP_VERIFY_TOKEN`) and payload signature validation.
-
-All platform credentials (tokens, secrets) are stored as environment variables and never persisted in the database or source code. Use the settings UI or your deployment platform's env var management to configure them.