@agent-native/core 0.7.7 → 0.7.11

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

@@ -0,0 +1,95 @@
+---
+name: notifications
+description: >-
+  In-app notifications primitive with pluggable server-side channels. Use when
+  the agent needs to surface progress, alerts, or completions to the user —
+  both in-app (bell + toast) and out-of-band (webhook, Slack, custom).
+---
+
+# Notifications
+
+`notify()` is the framework's "tell the user something" primitive. Every call persists a row to the inbox (drives the bell UI) and fans out to any registered server-side channels. Channels follow the same pluggable-provider pattern as `tracking` — register at startup, `notify()` fans out, errors are isolated.
+
+Use for: *agent progress milestones, automation triggers firing, background job completions, critical errors*. Don't use for chat replies — those go through the conversation.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `notify` | Send a notification (severity + title + optional body/metadata/channels) |
+| `list-notifications` | Show recent notifications for the current user |
+
+## Sending
+
+```
+notify --severity info --title "Booking confirmed" --body "Jane at 3pm"
+```
+
+| Severity | When |
+|---|---|
+| `info` | FYI / progress / confirmation |
+| `warning` | Something to look at soon |
+| `critical` | Needs immediate attention |
+
+Optional: `--metadataJson '{"threadId":"abc"}'`, `--channels inbox,webhook` (omit to run all registered).
+
+## Delivery
+
+`notify()` always inserts into the `notifications` table (unless `channels` explicitly excludes `inbox`), then fans out to every registered channel in parallel (best-effort; a failing channel doesn't block others). Finally it emits `notification.sent` on the event bus so automations can chain — e.g. *"when a critical notification fires, also page on-call."*
+
+## Built-in Channels
+
+| Channel | How | Requires |
+|---|---|---|
+| `inbox` | INSERT → drives bell UI | (always on) |
+| `webhook` | POST JSON to `NOTIFICATIONS_WEBHOOK_URL` (+ optional `NOTIFICATIONS_WEBHOOK_AUTH`); both support `${keys.NAME}` + URL allowlists from the ad-hoc-keys system | env var set |
+
+The webhook channel resolves `${keys.NAME}` server-side — the raw value never enters the agent context.
+
+## Registering a Custom Channel
+
+```ts
+// server/plugins/notifications-slack.ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+export default () => {
+  registerNotificationChannel({
+    name: "slack-ops",
+    async deliver(input, meta) {
+      await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ text: `*${input.severity}* — ${input.title}`, owner: meta.owner }),
+      });
+    },
+  });
+};
+```
+
+Names are unique — re-registering replaces. `deliver()` must be best-effort; a thrown error is logged and ignored. Do NOT call `notify()` from inside a channel (recursion).
+
+## HTTP API
+
+Mounted at `/_agent-native/notifications/*` by `core-routes-plugin`, all session-scoped:
+
+- `GET    /notifications?unread=true&limit=50&before=<iso>`
+- `GET    /notifications/count`
+- `POST   /notifications/:id/read`
+- `POST   /notifications/read-all`
+- `DELETE /notifications/:id`
+
+## UI
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+<NotificationsBell browserNotifications />
+```
+
+Bell icon + unread badge + lazy-loaded dropdown. Pass `browserNotifications` to also fire system `new Notification(...)` popups for items that arrive after mount (dedups by id, renders an "Enable" prompt until permission is granted, silently no-ops on denied / unsupported). Styled with shadcn tokens — adapts to the host theme.
+
+## Related
+
+- `automations` — event-triggered bodies can call `notify`.
+- `secrets` — `${keys.NAME}` substitution + URL allowlists powering the webhook channel.
+- `tracking` — analytics; separate concern, don't route through notifications.

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

@@ -0,0 +1,97 @@
+---
+name: progress
+description: >-
+  Report live progress from long-running agent tasks. Use when a task takes
+  more than a few seconds, so the user can watch status in the runs tray
+  instead of staring at a spinner.
+---
+
+# Progress
+
+## Overview
+
+`progress_runs` is the framework's "what is the agent doing right now" primitive. The agent starts a run at the top of a long task, updates it as work proceeds, and completes it with a terminal status. The UI renders active runs in a header-bar widget with a percent bar, current step, and spinner/check/X — live visibility into work that would otherwise be opaque.
+
+Separate concern from `notifications`:
+
+| | Notifications | Progress |
+|---|---|---|
+| Shape | One-shot event — "X happened" | Continuous state — "X is 45% done" |
+| UI surface | Bell + toast | Runs tray with percent bar |
+| Lifecycle | Dismissable (read/unread) | Running → terminal (succeeded/failed/cancelled) |
+
+Common pattern: on completion, emit a `notify()` so the user sees the outcome when they're not actively watching the tray.
+
+## Available Tools
+
+| Tool | 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`). |
+
+## Canonical Flow
+
+```
+start-run --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"
+
+complete-run --runId=abc --status=succeeded
+notify --severity=info --title="Triage done" --body="12 archived, 6 drafts ready to review"
+```
+
+## Best Practices
+
+- **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.
+- **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.
+
+## Runs API
+
+Mounted at `/_agent-native/runs/*` by `core-routes-plugin`. **Read-only** over HTTP — writes flow through the agent tools:
+
+| Method | Route |
+|---|---|
+| `GET`    | `/_agent-native/runs?active=true&limit=50` |
+| `GET`    | `/_agent-native/runs/:id` |
+| `DELETE` | `/_agent-native/runs/:id` |
+
+## UI Surface
+
+Ships as `<RunsTray />` at `@agent-native/core/client/progress`:
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+Inline header widget — mount next to the notifications bell. Shows a spinner icon + count badge when runs are active; click opens a dropdown with a live percent bar per run. Hides the trigger entirely when no active runs. Polls `active=true` every `pollMs` (default 3s).
+
+## Event Bus Integration
+
+Two events emit on the bus so automations can react:
+
+- `run.progress.started` — `{ runId, title, step? }`
+- `run.progress.updated` — `{ runId, percent, step, status }`
+
+Example automation: *"when a run takes longer than 5 minutes, notify me."*
+
+## Related Skills
+
+- `notifications` — fire one when a run finishes so the user sees the outcome.
+- `automations` — subscribe to `run.progress.updated` to build watchdogs on slow runs.
+- `delegate-to-agent` — if you're delegating a long task, start a run on the delegator side so the caller has visibility.

package/src/templates/default/AGENTS.md

@@ -84,16 +84,18 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                   |
-| --------------------- | -------------------------------------------------------------- |
-| `storing-data`        | Before storing or reading any app state                        |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                       |
-| `actions`             | Before creating or modifying actions                           |
-| `real-time-sync`      | Before wiring up real-time UI sync                             |
-| `self-modifying-code` | Before editing source, components, or styles                   |
-| `capture-learnings`   | Before recording user preferences or corrections               |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine  |
+| Skill                 | When to read                                                    |
+| --------------------- | --------------------------------------------------------------- |
+| `storing-data`        | Before storing or reading any app state                         |
+| `delegate-to-agent`   | Before adding LLM calls or AI delegation                        |
+| `actions`             | Before creating or modifying actions                            |
+| `real-time-sync`      | Before wiring up real-time UI sync                              |
+| `self-modifying-code` | Before editing source, components, or styles                    |
+| `capture-learnings`   | Before recording user preferences or corrections                |
+| `frontend-design`     | Before building or restyling any UI component, page, or layout  |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine   |
+| `notifications`       | Before surfacing alerts/progress to the user or adding channels |
+| `progress`            | Before running any task that takes more than a few seconds      |
 
 ## When Adding Features
 

package/src/templates/default/package.json

@@ -22,23 +22,23 @@
     "@react-router/dev": "^7.13.1",
     "@react-router/fs-routes": "^7.13.1",
     "@tailwindcss/vite": "^4.1.18",
-    "@tanstack/react-query": "^5.84.2",
+    "@tanstack/react-query": "^5.99.2",
     "@types/node": "^24.2.1",
-    "@types/react": "^18.3.23",
-    "@types/react-dom": "^18.3.7",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "lucide-react": "^0.539.0",
+    "lucide-react": "^1.8.0",
     "next-themes": "^0.4.6",
     "prettier": "^3.6.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "react-router": "^7.13.1",
-    "sonner": "^1.7.4",
-    "tailwind-merge": "^2.6.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.20.3",
-    "typescript": "^5.9.2",
-    "vite": "^7.1.2"
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0"
   }
 }

package/src/templates/workspace-core/package.json

@@ -23,14 +23,14 @@
     "./styles/tokens.css": "./styles/tokens.css"
   },
   "dependencies": {
-    "@agent-native/core": "^0.6.0"
+    "@agent-native/core": "^0.7.10"
   },
   "devDependencies": {
-    "@types/react": "^18.3.23",
-    "react": "^18.3.1",
-    "typescript": "^5.9.2"
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "react": "^18.3.1"
+    "react": "^19.2.5"
   }
 }

package/src/templates/workspace-root/package.json

@@ -12,7 +12,7 @@
   },
   "devDependencies": {
     "prettier": "^3.6.2",
-    "typescript": "^5.9.2"
+    "typescript": "^6.0.3"
   },
   "packageManager": "pnpm@10.14.0"
 }

package/src/templates/workspace-root/tsconfig.base.json

@@ -15,7 +15,6 @@
     "skipLibCheck": true,
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "allowSyntheticDefaultImports": true,
-    "forceConsistentCasingInFileNames": true
+    "allowSyntheticDefaultImports": true
   }
 }

package/tsconfig.base.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "compilerOptions": {
+    "ignoreDeprecations": "6.0",
     "target": "ES2020",
     "useDefineForClassFields": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
@@ -15,7 +16,6 @@
     "jsx": "react-jsx",
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,
-    "forceConsistentCasingInFileNames": true,
 
     "strict": false,
     "noUnusedLocals": false,