@agent-native/core 0.59.0 → 0.60.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/a2a/index.d.ts +2 -0
- package/dist/a2a/index.d.ts.map +1 -1
- package/dist/a2a/index.js +1 -0
- package/dist/a2a/index.js.map +1 -1
- package/dist/a2a/invoke.d.ts +63 -0
- package/dist/a2a/invoke.d.ts.map +1 -0
- package/dist/a2a/invoke.js +157 -0
- package/dist/a2a/invoke.js.map +1 -0
- package/dist/agent/run-store.d.ts +15 -0
- package/dist/agent/run-store.d.ts.map +1 -1
- package/dist/agent/run-store.js +28 -0
- package/dist/agent/run-store.js.map +1 -1
- package/dist/chat-threads/store.d.ts +21 -0
- package/dist/chat-threads/store.d.ts.map +1 -1
- package/dist/chat-threads/store.js +128 -0
- package/dist/chat-threads/store.js.map +1 -1
- package/dist/cli/agent.d.ts +23 -0
- package/dist/cli/agent.d.ts.map +1 -0
- package/dist/cli/agent.js +300 -0
- package/dist/cli/agent.js.map +1 -0
- package/dist/cli/agents.d.ts +14 -0
- package/dist/cli/agents.d.ts.map +1 -0
- package/dist/cli/agents.js +95 -0
- package/dist/cli/agents.js.map +1 -0
- package/dist/cli/code-agent-executor.d.ts.map +1 -1
- package/dist/cli/code-agent-executor.js +264 -2
- package/dist/cli/code-agent-executor.js.map +1 -1
- package/dist/cli/create.d.ts +3 -2
- package/dist/cli/create.d.ts.map +1 -1
- package/dist/cli/create.js +154 -83
- package/dist/cli/create.js.map +1 -1
- package/dist/cli/index.js +50 -2
- package/dist/cli/index.js.map +1 -1
- package/dist/cli/invoke.d.ts +26 -0
- package/dist/cli/invoke.d.ts.map +1 -0
- package/dist/cli/invoke.js +227 -0
- package/dist/cli/invoke.js.map +1 -0
- package/dist/cli/templates-meta.d.ts +1 -1
- package/dist/cli/templates-meta.d.ts.map +1 -1
- package/dist/cli/templates-meta.js +9 -8
- package/dist/cli/templates-meta.js.map +1 -1
- package/dist/cli/workspacify.d.ts +1 -1
- package/dist/cli/workspacify.d.ts.map +1 -1
- package/dist/cli/workspacify.js +6 -6
- package/dist/cli/workspacify.js.map +1 -1
- package/dist/client/AgentPanel.js +1 -1
- package/dist/client/AgentPanel.js.map +1 -1
- package/dist/client/AssistantChat.d.ts.map +1 -1
- package/dist/client/AssistantChat.js +8 -2
- package/dist/client/AssistantChat.js.map +1 -1
- package/dist/client/NewWorkspaceAppFlow.d.ts.map +1 -1
- package/dist/client/NewWorkspaceAppFlow.js +5 -4
- package/dist/client/NewWorkspaceAppFlow.js.map +1 -1
- package/dist/client/agent-chat-adapter.d.ts.map +1 -1
- package/dist/client/agent-chat-adapter.js +65 -12
- package/dist/client/agent-chat-adapter.js.map +1 -1
- package/dist/client/blocks/library/diagram.d.ts.map +1 -1
- package/dist/client/blocks/library/diagram.js +23 -17
- package/dist/client/blocks/library/diagram.js.map +1 -1
- package/dist/client/blocks/types.d.ts +2 -0
- package/dist/client/blocks/types.d.ts.map +1 -1
- package/dist/client/blocks/types.js.map +1 -1
- package/dist/client/chat/index.d.ts +1 -1
- package/dist/client/chat/index.d.ts.map +1 -1
- package/dist/client/chat/index.js.map +1 -1
- package/dist/client/extensions/ExtensionViewer.js +1 -1
- package/dist/client/extensions/ExtensionViewer.js.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/notifications/NotificationsBell.d.ts +3 -1
- package/dist/client/notifications/NotificationsBell.d.ts.map +1 -1
- package/dist/client/notifications/NotificationsBell.js +7 -3
- package/dist/client/notifications/NotificationsBell.js.map +1 -1
- package/dist/client/use-chat-threads.d.ts +13 -0
- package/dist/client/use-chat-threads.d.ts.map +1 -1
- package/dist/client/use-chat-threads.js +41 -0
- package/dist/client/use-chat-threads.js.map +1 -1
- package/dist/integrations/plugin.d.ts.map +1 -1
- package/dist/integrations/plugin.js +2 -2
- package/dist/integrations/plugin.js.map +1 -1
- package/dist/onboarding/default-steps.d.ts.map +1 -1
- package/dist/onboarding/default-steps.js +102 -0
- package/dist/onboarding/default-steps.js.map +1 -1
- package/dist/org/auto-join-domain.d.ts +11 -3
- package/dist/org/auto-join-domain.d.ts.map +1 -1
- package/dist/org/auto-join-domain.js +7 -6
- package/dist/org/auto-join-domain.js.map +1 -1
- package/dist/org/context.d.ts.map +1 -1
- package/dist/org/context.js +68 -32
- package/dist/org/context.js.map +1 -1
- package/dist/org/migrations.d.ts.map +1 -1
- package/dist/org/migrations.js +6 -0
- package/dist/org/migrations.js.map +1 -1
- package/dist/provider-api/actions/github-repo-files.d.ts +84 -0
- package/dist/provider-api/actions/github-repo-files.d.ts.map +1 -0
- package/dist/provider-api/actions/github-repo-files.js +213 -0
- package/dist/provider-api/actions/github-repo-files.js.map +1 -0
- package/dist/provider-api/github-repo.d.ts +11 -0
- package/dist/provider-api/github-repo.d.ts.map +1 -0
- package/dist/provider-api/github-repo.js +553 -0
- package/dist/provider-api/github-repo.js.map +1 -0
- package/dist/provider-api/index.d.ts +184 -11
- package/dist/provider-api/index.d.ts.map +1 -1
- package/dist/provider-api/index.js +519 -0
- package/dist/provider-api/index.js.map +1 -1
- package/dist/scripts/docs/search.d.ts.map +1 -1
- package/dist/scripts/docs/search.js +38 -13
- package/dist/scripts/docs/search.js.map +1 -1
- package/dist/secrets/register-framework-secrets.d.ts.map +1 -1
- package/dist/secrets/register-framework-secrets.js +11 -0
- package/dist/secrets/register-framework-secrets.js.map +1 -1
- package/dist/server/agent-chat-plugin.d.ts +32 -0
- package/dist/server/agent-chat-plugin.d.ts.map +1 -1
- package/dist/server/agent-chat-plugin.js +297 -2
- package/dist/server/agent-chat-plugin.js.map +1 -1
- package/dist/server/auth-marketing.d.ts.map +1 -1
- package/dist/server/auth-marketing.js +17 -7
- package/dist/server/auth-marketing.js.map +1 -1
- package/dist/server/auth.d.ts.map +1 -1
- package/dist/server/auth.js +6 -0
- package/dist/server/auth.js.map +1 -1
- package/dist/server/core-routes-plugin.d.ts.map +1 -1
- package/dist/server/core-routes-plugin.js +18 -98
- package/dist/server/core-routes-plugin.js.map +1 -1
- package/dist/styles/blocks.css +30 -8
- package/dist/styles/rich-markdown-editor.css +10 -4
- package/dist/templates/{starter-shell-sync.spec.ts → chat-shell-sync.spec.ts} +21 -21
- package/dist/templates/default/.agents/skills/actions/SKILL.md +5 -5
- package/dist/templates/default/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/dist/templates/default/AGENTS.md +22 -1
- package/dist/templates/default/actions/hello.ts +1 -1
- package/dist/templates/default/actions/navigate.ts +1 -1
- package/dist/templates/default/actions/view-screen.ts +1 -1
- package/dist/templates/headless/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/dist/templates/headless/.env.example +4 -0
- package/dist/templates/headless/.prettierrc +5 -0
- package/dist/templates/headless/AGENTS.md +58 -0
- package/dist/templates/headless/DEVELOPING.md +22 -0
- package/dist/templates/headless/_gitignore +36 -0
- package/dist/templates/headless/actions/hello.ts +14 -0
- package/dist/templates/headless/actions/run.ts +3 -0
- package/dist/templates/headless/package.json +22 -0
- package/dist/templates/headless/tsconfig.json +7 -0
- package/dist/templates/ui-primitives-sync.spec.ts +2 -2
- package/dist/templates/workspace-core/.agents/skills/actions/SKILL.md +5 -5
- package/dist/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/dist/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md +9 -0
- package/dist/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md +93 -0
- package/dist/templates/workspace-core/.agents/skills/context-awareness/SKILL.md +11 -1
- package/dist/templates/workspace-core/.agents/skills/secrets/SKILL.md +1 -1
- package/dist/templates/workspace-core/AGENTS.md +20 -3
- package/dist/templates/workspace-core/src/server/index.ts +1 -1
- package/dist/templates/workspace-root/AGENTS.md +25 -5
- package/dist/templates/workspace-root/README.md +7 -7
- package/dist/triggers/dispatcher.d.ts +2 -3
- package/dist/triggers/dispatcher.d.ts.map +1 -1
- package/dist/triggers/dispatcher.js +2 -3
- package/dist/triggers/dispatcher.js.map +1 -1
- package/dist/triggers/routes.d.ts +38 -0
- package/dist/triggers/routes.d.ts.map +1 -0
- package/dist/triggers/routes.js +202 -0
- package/dist/triggers/routes.js.map +1 -0
- package/dist/vite/client.d.ts +2 -1
- package/dist/vite/client.d.ts.map +1 -1
- package/dist/vite/client.js +121 -2
- package/dist/vite/client.js.map +1 -1
- package/docs/AGENTS.md +57 -0
- package/docs/SKILL.md +40 -0
- package/docs/content/a2a-protocol.md +1 -1
- package/docs/content/actions.md +48 -8
- package/docs/content/agent-surfaces.md +76 -14
- package/docs/content/cli-adapters.md +1 -1
- package/docs/content/cloneable-saas.md +5 -4
- package/docs/content/code-agents-ui.md +1 -1
- package/docs/content/components.md +1 -1
- package/docs/content/context-awareness.md +15 -3
- package/docs/content/creating-templates.md +15 -7
- package/docs/content/drop-in-agent.md +1 -1
- package/docs/content/faq.md +6 -4
- package/docs/content/getting-started.md +63 -73
- package/docs/content/key-concepts.md +24 -24
- package/docs/content/native-chat-ui.md +4 -4
- package/docs/content/pure-agent-apps.md +34 -10
- package/docs/content/security.md +1 -1
- package/docs/content/server.md +1 -1
- package/docs/content/template-chat.md +85 -0
- package/docs/content/template-dispatch.md +1 -1
- package/docs/content/tracking.md +1 -1
- package/docs/content/what-is-agent-native.md +7 -6
- package/package.json +10 -1
- package/src/templates/{starter-shell-sync.spec.ts → chat-shell-sync.spec.ts} +21 -21
- package/src/templates/default/.agents/skills/actions/SKILL.md +5 -5
- package/src/templates/default/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/src/templates/default/AGENTS.md +22 -1
- package/src/templates/default/actions/hello.ts +1 -1
- package/src/templates/default/actions/navigate.ts +1 -1
- package/src/templates/default/actions/view-screen.ts +1 -1
- package/src/templates/headless/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/src/templates/headless/.env.example +4 -0
- package/src/templates/headless/.prettierrc +5 -0
- package/src/templates/headless/AGENTS.md +58 -0
- package/src/templates/headless/DEVELOPING.md +22 -0
- package/src/templates/headless/_gitignore +36 -0
- package/src/templates/headless/actions/hello.ts +14 -0
- package/src/templates/headless/actions/run.ts +3 -0
- package/src/templates/headless/package.json +22 -0
- package/src/templates/headless/tsconfig.json +7 -0
- package/src/templates/ui-primitives-sync.spec.ts +2 -2
- package/src/templates/workspace-core/.agents/skills/actions/SKILL.md +5 -5
- package/src/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md +63 -0
- package/src/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md +9 -0
- package/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md +93 -0
- package/src/templates/workspace-core/.agents/skills/context-awareness/SKILL.md +11 -1
- package/src/templates/workspace-core/.agents/skills/secrets/SKILL.md +1 -1
- package/src/templates/workspace-core/AGENTS.md +20 -3
- package/src/templates/workspace-core/src/server/index.ts +1 -1
- package/src/templates/workspace-root/AGENTS.md +25 -5
- package/src/templates/workspace-root/README.md +7 -7
- package/docs/content/template-starter.md +0 -78
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "{{APP_NAME}}",
|
|
3
|
+
"private": true,
|
|
4
|
+
"type": "module",
|
|
5
|
+
"scripts": {
|
|
6
|
+
"action": "agent-native action",
|
|
7
|
+
"agent": "agent-native agent",
|
|
8
|
+
"script": "agent-native script",
|
|
9
|
+
"typecheck": "tsc --noEmit"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@agent-native/core": "latest",
|
|
13
|
+
"postgres": "^3.4.9",
|
|
14
|
+
"zod": "^4.4.3"
|
|
15
|
+
},
|
|
16
|
+
"devDependencies": {
|
|
17
|
+
"@types/node": "^24.2.1",
|
|
18
|
+
"prettier": "^3.6.2",
|
|
19
|
+
"tsx": "^4.20.3",
|
|
20
|
+
"typescript": "^6.0.3"
|
|
21
|
+
}
|
|
22
|
+
}
|
|
@@ -70,8 +70,8 @@ const ALLOW_LIST: Array<[string, string, string]> = [
|
|
|
70
70
|
// chart.tsx — analytics adds the useChartTooltipFlip hook (which only exists
|
|
71
71
|
// in the analytics template's hooks/ dir) and uses `[_, config]` destructuring.
|
|
72
72
|
// forms/mail have a shared variant without that hook and with `[, config]`.
|
|
73
|
-
// The canonical 8-template version (calendar/clips/design/macros/plan/
|
|
74
|
-
//
|
|
73
|
+
// The canonical 8-template version (calendar/chat/clips/design/macros/plan/
|
|
74
|
+
// slides/videos) has neither analytics-specific hook nor forms/mail style.
|
|
75
75
|
[
|
|
76
76
|
"chart.tsx",
|
|
77
77
|
"analytics",
|
|
@@ -49,7 +49,7 @@ Use `defineAction` with a Zod schema (required for new actions):
|
|
|
49
49
|
```ts
|
|
50
50
|
// actions/list-meals.ts
|
|
51
51
|
import { z } from "zod";
|
|
52
|
-
import { defineAction } from "@agent-native/core";
|
|
52
|
+
import { defineAction } from "@agent-native/core/action";
|
|
53
53
|
import { getDb } from "../server/db/index.js";
|
|
54
54
|
import { meals } from "../server/db/schema.js";
|
|
55
55
|
|
|
@@ -352,7 +352,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
|
|
|
352
352
|
credentials belong in the encrypted secrets/credential/OAuth stores, never as
|
|
353
353
|
hardcoded literals or shared env fallbacks.
|
|
354
354
|
- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
|
|
355
|
-
- **Import from `@agent-native/core`**
|
|
355
|
+
- **Import action primitives from `@agent-native/core/action`** and CLI helpers such as `parseArgs()` from `@agent-native/core` — do not redefine framework utilities locally.
|
|
356
356
|
- **Do not re-export actions as REST.** The mounted `/_agent-native/actions/:name` endpoint is the REST surface; duplicating it under `/api/*` creates drift and hides the operation from agents.
|
|
357
357
|
|
|
358
358
|
## Common Patterns
|
|
@@ -361,7 +361,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
|
|
|
361
361
|
|
|
362
362
|
```ts
|
|
363
363
|
import { z } from "zod";
|
|
364
|
-
import { defineAction } from "@agent-native/core";
|
|
364
|
+
import { defineAction } from "@agent-native/core/action";
|
|
365
365
|
|
|
366
366
|
export default defineAction({
|
|
367
367
|
description: "List calendar events",
|
|
@@ -380,7 +380,7 @@ export default defineAction({
|
|
|
380
380
|
|
|
381
381
|
```ts
|
|
382
382
|
import { z } from "zod";
|
|
383
|
-
import { defineAction } from "@agent-native/core";
|
|
383
|
+
import { defineAction } from "@agent-native/core/action";
|
|
384
384
|
|
|
385
385
|
export default defineAction({
|
|
386
386
|
description: "Log a meal",
|
|
@@ -400,7 +400,7 @@ export default defineAction({
|
|
|
400
400
|
|
|
401
401
|
```ts
|
|
402
402
|
import { z } from "zod";
|
|
403
|
-
import { defineAction } from "@agent-native/core";
|
|
403
|
+
import { defineAction } from "@agent-native/core/action";
|
|
404
404
|
|
|
405
405
|
export default defineAction({
|
|
406
406
|
description: "Navigate the UI to a view",
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agent-native-docs
|
|
3
|
+
description: >-
|
|
4
|
+
How to find version-matched Agent Native framework docs bundled in
|
|
5
|
+
node_modules. Use before implementing or answering questions about
|
|
6
|
+
@agent-native/core APIs, generated apps, workspaces, or advanced features.
|
|
7
|
+
metadata:
|
|
8
|
+
internal: true
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Agent Native Docs Lookup
|
|
12
|
+
|
|
13
|
+
## Rule
|
|
14
|
+
|
|
15
|
+
Before implementing or explaining non-trivial Agent Native behavior, read the
|
|
16
|
+
version-matched docs installed with `@agent-native/core`.
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
Generated apps and workspaces may be on a different framework version than the
|
|
21
|
+
public docs or model memory. The installed package is the source that matches
|
|
22
|
+
the app in front of you.
|
|
23
|
+
|
|
24
|
+
## How
|
|
25
|
+
|
|
26
|
+
From a generated app directory:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pnpm action docs-search --query "<feature>"
|
|
30
|
+
pnpm action docs-search --slug <slug>
|
|
31
|
+
pnpm action docs-search --list
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The headless `pnpm agent` loop and built-in app agent also expose a read-only
|
|
35
|
+
`docs-search` tool with the same `query`, `slug`, and `list` options.
|
|
36
|
+
|
|
37
|
+
If the action runner is unavailable, search the package docs directly:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
|
|
44
|
+
under `node_modules/@agent-native/core/docs/content/`.
|
|
45
|
+
|
|
46
|
+
## Useful Slugs
|
|
47
|
+
|
|
48
|
+
| Need | Slugs |
|
|
49
|
+
| --- | --- |
|
|
50
|
+
| Actions and typed client calls | `actions`, `client` |
|
|
51
|
+
| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
|
|
52
|
+
| UI state visible to the agent | `context-awareness` |
|
|
53
|
+
| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
|
|
54
|
+
| Automations and schedules | `automations`, `recurring-jobs` |
|
|
55
|
+
| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
|
|
56
|
+
| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
|
|
57
|
+
|
|
58
|
+
## Don't
|
|
59
|
+
|
|
60
|
+
- Do not rely on memory for framework APIs when package docs are present.
|
|
61
|
+
- Do not add custom REST wrappers for app data before reading `actions`.
|
|
62
|
+
- Do not add inline LLM calls before reading `using-your-agent` and
|
|
63
|
+
`agent-surfaces`.
|
|
@@ -66,6 +66,15 @@ export default function Settings() {
|
|
|
66
66
|
|
|
67
67
|
If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
|
|
68
68
|
|
|
69
|
+
## Chat-First Routes
|
|
70
|
+
|
|
71
|
+
If `/` is a full-page chat such as `AgentChatHome`, keep the app shell mounted
|
|
72
|
+
around it when possible so `AgentSidebar` URL sync and route warmup stay active.
|
|
73
|
+
If the chat route intentionally lives outside the shell, add a tiny app-owned
|
|
74
|
+
prewarm for the routes agents commonly open from that chat. In local dev,
|
|
75
|
+
React Router can update the address bar before a cold Vite route chunk commits,
|
|
76
|
+
which makes navigation look broken even when the URL is correct.
|
|
77
|
+
|
|
69
78
|
## Adding a New Route
|
|
70
79
|
|
|
71
80
|
- **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: composable-mini-apps
|
|
3
|
+
description: >-
|
|
4
|
+
Build many focused workspace apps that compose through agent discovery and
|
|
5
|
+
A2A. Use when designing headless mini-apps or cross-app workflows.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Composable Mini-Apps
|
|
9
|
+
|
|
10
|
+
## Rule
|
|
11
|
+
|
|
12
|
+
Prefer many one-job apps in a workspace over one oversized app. A headless app
|
|
13
|
+
can own a provider, dataset, workflow, or specialist action surface without a
|
|
14
|
+
full UI; the main agent composes those apps through discovery and A2A.
|
|
15
|
+
|
|
16
|
+
## Shape
|
|
17
|
+
|
|
18
|
+
- Give each mini-app one clear job, a concise `package.json` description, and
|
|
19
|
+
action names that describe the job it owns.
|
|
20
|
+
- Keep provider credentials and upstream API details in the app that owns that
|
|
21
|
+
provider or workflow. Other apps should delegate to it instead of copying its
|
|
22
|
+
integration code.
|
|
23
|
+
- Use a tiny status/config screen only when users need to inspect state. A
|
|
24
|
+
pure headless app is fine when its job is invoked by agents, automations, or
|
|
25
|
+
sibling apps.
|
|
26
|
+
- If two workflows only share a helper, put the helper in `packages/shared`;
|
|
27
|
+
keep the workflow actions in separate apps.
|
|
28
|
+
|
|
29
|
+
## Discovery And Invocation
|
|
30
|
+
|
|
31
|
+
The main agent should discover available siblings before assuming capability:
|
|
32
|
+
|
|
33
|
+
- Runtime agents receive an `<available-apps>` block built from
|
|
34
|
+
`discoverAgents()`. Workspace siblings are layered in by
|
|
35
|
+
`discoverWorkspaceAgents()`.
|
|
36
|
+
- UI shells, headless surfaces, and scripts can read the same registry through
|
|
37
|
+
`GET /_agent-native/agents?selfAppId=<app-id>`.
|
|
38
|
+
- Code or CLI callers should use the first-class A2A invocation path
|
|
39
|
+
(`invokeAgent()` / `agent-native invoke`) when they need to call an app by
|
|
40
|
+
id, name, or URL.
|
|
41
|
+
- In the agent loop, use `call-agent` with the sibling app id when another app
|
|
42
|
+
owns the work or data. Never call the current app through `call-agent`; use
|
|
43
|
+
local actions instead.
|
|
44
|
+
|
|
45
|
+
Send narrow prompts to siblings: name the exact question, relevant ids, date
|
|
46
|
+
ranges, and expected output shape. Preserve returned ids and URLs verbatim.
|
|
47
|
+
|
|
48
|
+
## Provider APIs
|
|
49
|
+
|
|
50
|
+
Provider-specific actions are shortcuts, not limits. When the upstream API can
|
|
51
|
+
answer the question better than a first-class shortcut, call
|
|
52
|
+
`provider-api-catalog` and `provider-api-docs` as needed, then
|
|
53
|
+
`provider-api-request` against the real provider endpoint. For broad joins,
|
|
54
|
+
searches, or absence claims, stage the bounded corpus with `stageAs` and reduce
|
|
55
|
+
it with `query-staged-dataset` or code.
|
|
56
|
+
|
|
57
|
+
When composing apps, make the provider-owning mini-app do those
|
|
58
|
+
`provider-api-request` calls. The orchestrator should delegate a bounded job;
|
|
59
|
+
it should not reimplement every provider endpoint locally.
|
|
60
|
+
|
|
61
|
+
## Example
|
|
62
|
+
|
|
63
|
+
For a sales-intelligence workspace, split the job into small apps:
|
|
64
|
+
|
|
65
|
+
| App | Owns | Calls |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
|
|
68
|
+
| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
|
|
69
|
+
| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
|
|
70
|
+
| `deal-brief` | Orchestration and final brief | `invokeAgent()` or `call-agent` to the three apps |
|
|
71
|
+
|
|
72
|
+
Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
|
|
73
|
+
deals, asks `gong-evidence` for recent transcript evidence about those deals,
|
|
74
|
+
asks `knowledge-base` for relevant playbook guidance, then synthesizes the
|
|
75
|
+
answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
|
|
76
|
+
not a single app that clones every provider integration.
|
|
77
|
+
|
|
78
|
+
## Don't
|
|
79
|
+
|
|
80
|
+
- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
|
|
81
|
+
app just to reuse its data. Delegate or link to the existing app.
|
|
82
|
+
- Do not hide a multi-provider workflow inside a giant "misc tools" app.
|
|
83
|
+
- Do not add one-off provider endpoints when `provider-api-request` can express
|
|
84
|
+
the upstream API safely.
|
|
85
|
+
- Do not create wrapper routes that only re-export another app's action or A2A
|
|
86
|
+
result.
|
|
87
|
+
|
|
88
|
+
## Related Skills
|
|
89
|
+
|
|
90
|
+
- **a2a-protocol** - How apps expose and call A2A endpoints.
|
|
91
|
+
- **actions** - How each mini-app exposes its own operation surface.
|
|
92
|
+
- **external-agents** - How external MCP hosts route through workspace apps.
|
|
93
|
+
- **storing-data** - How app-owned data stays SQL-backed and portable.
|
|
@@ -125,6 +125,15 @@ await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
|
|
|
125
125
|
**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
|
|
126
126
|
dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
|
|
127
127
|
|
|
128
|
+
When a destination has a real URL, let the `navigate` command carry that local
|
|
129
|
+
`path` (plus semantic fields when useful) and have the UI prefer `path` before
|
|
130
|
+
falling back to semantic routing. Keep app navigation single-channel: do not
|
|
131
|
+
also write `__set_url__` for the same navigation. `__set_url__` belongs to the
|
|
132
|
+
framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
|
|
133
|
+
changes. If a command can arrive while a chat stream is rendering, prefer
|
|
134
|
+
`navigate(path, { replace: true, flushSync: true })` over a view-transition
|
|
135
|
+
wrapper so the URL and visible route commit together.
|
|
136
|
+
|
|
128
137
|
## Jitter Prevention
|
|
129
138
|
|
|
130
139
|
When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
|
|
@@ -171,7 +180,7 @@ The mail template demonstrates these patterns working together:
|
|
|
171
180
|
- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
|
|
172
181
|
- Update `view-screen` when adding new features — it should return data for every view
|
|
173
182
|
- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
|
|
174
|
-
- Use the one-shot `navigate` command pattern for
|
|
183
|
+
- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
|
|
175
184
|
- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
|
|
176
185
|
|
|
177
186
|
## Don't
|
|
@@ -179,6 +188,7 @@ The mail template demonstrates these patterns working together:
|
|
|
179
188
|
- Don't assume the user is on a specific page — always check navigation state
|
|
180
189
|
- Don't hardcode navigation paths in scripts — read the current state and branch
|
|
181
190
|
- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
|
|
191
|
+
- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
|
|
182
192
|
- Don't ignore the `<current-screen>` block — it tells you where the user is
|
|
183
193
|
- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
|
|
184
194
|
- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
|
|
@@ -111,7 +111,7 @@ row is written — status is derived from `hasOAuthTokens("google")`.
|
|
|
111
111
|
|
|
112
112
|
```ts
|
|
113
113
|
import { z } from "zod";
|
|
114
|
-
import { defineAction } from "@agent-native/core";
|
|
114
|
+
import { defineAction } from "@agent-native/core/action";
|
|
115
115
|
import { readAppSecret } from "@agent-native/core/secrets";
|
|
116
116
|
import { getRequestUserEmail } from "@agent-native/core/server";
|
|
117
117
|
|
|
@@ -4,6 +4,23 @@ These instructions apply to every app in the {{APP_TITLE}} workspace. Keep
|
|
|
4
4
|
only rules that should be shared across all apps here. App-specific behavior
|
|
5
5
|
belongs in that app's own `AGENTS.md` or `.agents/skills/` directory.
|
|
6
6
|
|
|
7
|
+
## Framework Docs Lookup
|
|
8
|
+
|
|
9
|
+
Version-matched Agent Native docs ship with `@agent-native/core` in
|
|
10
|
+
`node_modules/@agent-native/core/docs`.
|
|
11
|
+
|
|
12
|
+
- From an app directory, use `pnpm action docs-search --query "<topic>"`,
|
|
13
|
+
`pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
|
|
14
|
+
- If the action runner is unavailable, read
|
|
15
|
+
`node_modules/@agent-native/core/docs/AGENTS.md` and search
|
|
16
|
+
`node_modules/@agent-native/core/docs/content/` directly with `rg`.
|
|
17
|
+
- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
|
|
18
|
+
`a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
|
|
19
|
+
`external-agents`, `mcp-protocol`, `sharing`, and `security`.
|
|
20
|
+
|
|
21
|
+
Use package docs for framework APIs, and use this `AGENTS.md` plus
|
|
22
|
+
`.agents/skills/` for workspace-specific conventions.
|
|
23
|
+
|
|
7
24
|
## Shared Context
|
|
8
25
|
|
|
9
26
|
Add company, product, compliance, or support-context notes that every app
|
|
@@ -55,7 +72,7 @@ become a separate workspace app under `apps/<app-name>`, mounted at
|
|
|
55
72
|
`/<app-name>`.
|
|
56
73
|
|
|
57
74
|
Do not implement a new app by adding a route, page, component, or file to
|
|
58
|
-
`apps/
|
|
75
|
+
`apps/chat` or another existing app unless the user explicitly asks to modify
|
|
59
76
|
that existing app.
|
|
60
77
|
|
|
61
78
|
Dispatch vault access is workspace-wide by default: every saved vault key is
|
|
@@ -101,8 +118,8 @@ branch creation; Builder should still scaffold the separate workspace app. The
|
|
|
101
118
|
workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories
|
|
102
119
|
automatically.
|
|
103
120
|
|
|
104
|
-
When using the
|
|
121
|
+
When using the chat template, treat it as scaffolding only. The finished app
|
|
105
122
|
must be branded as the requested app, with its own home screen, navigation,
|
|
106
123
|
package metadata, manifest, and domain workflow. Do not leave visible
|
|
107
|
-
`Starter`, `Blank app`, `Start building`, or `New app` UI in a
|
|
124
|
+
`Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived
|
|
108
125
|
app.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// Export workspace-wide server plugin overrides here when you need them.
|
|
2
|
-
//
|
|
2
|
+
// Chat-derived apps inherit these exports, so provide explicit framework defaults
|
|
3
3
|
// to keep generated workspaces warning-free until a workspace customizes them.
|
|
4
4
|
import {
|
|
5
5
|
createAgentChatPlugin,
|
|
@@ -6,6 +6,22 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
|
|
|
6
6
|
The root `.agents/skills` path points at the shared package's skills so local
|
|
7
7
|
coding agents can discover the same workspace-wide guidance from the root.
|
|
8
8
|
|
|
9
|
+
## Framework Docs Lookup
|
|
10
|
+
|
|
11
|
+
Version-matched Agent Native docs ship with `@agent-native/core` in
|
|
12
|
+
`node_modules/@agent-native/core/docs`.
|
|
13
|
+
|
|
14
|
+
- From an app directory, use `pnpm action docs-search --query "<topic>"`,
|
|
15
|
+
`pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
|
|
16
|
+
- From the workspace root, read `node_modules/@agent-native/core/docs/AGENTS.md`
|
|
17
|
+
and search `node_modules/@agent-native/core/docs/content/` directly with `rg`.
|
|
18
|
+
- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
|
|
19
|
+
`a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
|
|
20
|
+
`external-agents`, `mcp-protocol`, `sharing`, and `security`.
|
|
21
|
+
|
|
22
|
+
Use package docs for framework APIs, and use `packages/shared/AGENTS.md` plus
|
|
23
|
+
`packages/shared/.agents/skills/` for workspace-specific conventions.
|
|
24
|
+
|
|
9
25
|
## Core Agent Rule
|
|
10
26
|
|
|
11
27
|
- All AI/LLM behavior goes through the app's agent chat. UI and server code
|
|
@@ -61,11 +77,15 @@ coding agents can discover the same workspace-wide guidance from the root.
|
|
|
61
77
|
`/<app-id>`.
|
|
62
78
|
- When a user explicitly asks for a new app or workspace app, create the
|
|
63
79
|
separate workspace app.
|
|
80
|
+
- For composable workflows, prefer many one-job headless or small-UI apps that
|
|
81
|
+
discover and call sibling apps over A2A. Read
|
|
82
|
+
`packages/shared/.agents/skills/composable-mini-apps/SKILL.md` before
|
|
83
|
+
designing cross-app orchestration.
|
|
64
84
|
- Dispatch vault access is workspace-wide by default: every saved vault key is
|
|
65
85
|
available to every workspace app. Only create or request per-app vault grants
|
|
66
86
|
when Dispatch's vault access setting is switched to manual mode.
|
|
67
87
|
- Do not satisfy a new-app request by adding a route, page, component, or file
|
|
68
|
-
to `apps/
|
|
88
|
+
to `apps/chat` or another existing app unless the user explicitly asks to
|
|
69
89
|
modify that existing app.
|
|
70
90
|
- Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as
|
|
71
91
|
existing hosted/connected neighbors available through links and A2A/default
|
|
@@ -121,14 +141,14 @@ coding agents can discover the same workspace-wide guidance from the root.
|
|
|
121
141
|
- In local development, scaffold the app from the workspace root with
|
|
122
142
|
`pnpm exec agent-native create <app-id> --template=<template>`. In production
|
|
123
143
|
Dispatch posts the request to Builder branch creation; the Builder branch
|
|
124
|
-
should still create the separate workspace app, not patch
|
|
144
|
+
should still create the separate workspace app, not patch chat. The local
|
|
125
145
|
workspace gateway detects new app directories automatically and starts each
|
|
126
146
|
app server lazily on first visit.
|
|
127
|
-
- When using the
|
|
147
|
+
- When using the chat template, treat it as scaffolding only. The finished
|
|
128
148
|
app must be branded as the requested app, with its own home screen,
|
|
129
149
|
navigation, package metadata, manifest, and domain workflow. Do not leave
|
|
130
|
-
visible `Starter`, `Blank app`, `Start building`, or `New app` UI in
|
|
131
|
-
|
|
150
|
+
visible `Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in
|
|
151
|
+
a chat-derived app.
|
|
132
152
|
|
|
133
153
|
## Workspace Identity
|
|
134
154
|
|
|
@@ -68,10 +68,10 @@ pnpm dev # starts the workspace gateway; opens Dispatch when prese
|
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
The dev gateway serves Dispatch at `/dispatch` when you keep the recommended
|
|
71
|
-
Dispatch app selected, and every app at its own path such as `/
|
|
71
|
+
Dispatch app selected, and every app at its own path such as `/chat`. It
|
|
72
72
|
watches `apps/`, so newly-created apps are detected without restarting
|
|
73
73
|
`pnpm dev`. App servers start lazily the first time you visit their path. App
|
|
74
|
-
links should stay relative, such as `/
|
|
74
|
+
links should stay relative, such as `/chat` or `/<app-id>`; do not hardcode
|
|
75
75
|
localhost or dev ports because the active gateway origin owns the port.
|
|
76
76
|
|
|
77
77
|
Dispatch vault keys are workspace-wide by default: every saved vault key is
|
|
@@ -100,18 +100,18 @@ authenticated org routes whenever possible.
|
|
|
100
100
|
## Adding a new app
|
|
101
101
|
|
|
102
102
|
```bash
|
|
103
|
-
pnpm exec agent-native create crm --template=
|
|
103
|
+
pnpm exec agent-native create crm --template=chat
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
The CLI detects the workspace root and scaffolds a minimal app that already
|
|
106
|
+
The CLI detects the workspace root and scaffolds a minimal chat app that already
|
|
107
107
|
depends on `@{{APP_NAME}}/shared`. Edit only the routes you care about;
|
|
108
108
|
auth, org switching, skills, and instructions come from the shared package.
|
|
109
|
-
|
|
109
|
+
Chat is only the source scaffold: the finished app should use its own name,
|
|
110
110
|
home screen, navigation, package metadata, and manifest rather than leaving
|
|
111
|
-
|
|
111
|
+
chat or new-app UI in place.
|
|
112
112
|
If the request starts from Dispatch in production, Dispatch sends it to Builder
|
|
113
113
|
branch creation; that branch should still add a new `apps/<app-id>` workspace
|
|
114
|
-
app rather than adding files to `apps/
|
|
114
|
+
app rather than adding files to `apps/chat`.
|
|
115
115
|
Dispatch discovers ready apps from `apps/<app-id>/package.json`; there is no
|
|
116
116
|
separate workspace app registry to edit. React Router apps must preserve
|
|
117
117
|
`APP_BASE_PATH` / `VITE_APP_BASE_PATH` in `app/entry.client.tsx` via
|
|
@@ -7,11 +7,11 @@
|
|
|
7
7
|
*/
|
|
8
8
|
import { type ActionEntry } from "../agent/production-agent.js";
|
|
9
9
|
import type { TriggerFrontmatter } from "./types.js";
|
|
10
|
-
declare function parseTriggerFrontmatter(content: string): {
|
|
10
|
+
export declare function parseTriggerFrontmatter(content: string): {
|
|
11
11
|
meta: TriggerFrontmatter;
|
|
12
12
|
body: string;
|
|
13
13
|
};
|
|
14
|
-
declare function buildTriggerContent(meta: TriggerFrontmatter, body: string): string;
|
|
14
|
+
export declare function buildTriggerContent(meta: TriggerFrontmatter, body: string): string;
|
|
15
15
|
export interface TriggerDispatcherDeps {
|
|
16
16
|
getActions: () => Record<string, ActionEntry>;
|
|
17
17
|
getSystemPrompt: (owner: string) => Promise<string>;
|
|
@@ -30,5 +30,4 @@ export declare function initTriggerDispatcher(deps: TriggerDispatcherDeps): Prom
|
|
|
30
30
|
* Call after creating/updating triggers.
|
|
31
31
|
*/
|
|
32
32
|
export declare function refreshEventSubscriptions(): Promise<void>;
|
|
33
|
-
export { parseTriggerFrontmatter, buildTriggerContent };
|
|
34
33
|
//# sourceMappingURL=dispatcher.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/triggers/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,
|
|
1
|
+
{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/triggers/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKrD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IACxD,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd,CAsFA;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,MAAM,GACX,MAAM,CAsBR;AAID,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC9C,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgBD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgC/D"}
|
|
@@ -14,7 +14,7 @@ import { createThread } from "../chat-threads/store.js";
|
|
|
14
14
|
import { evaluateCondition } from "./condition-evaluator.js";
|
|
15
15
|
// Re-use the job frontmatter parser — triggers extend the same format.
|
|
16
16
|
const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
|
|
17
|
-
function parseTriggerFrontmatter(content) {
|
|
17
|
+
export function parseTriggerFrontmatter(content) {
|
|
18
18
|
const match = content.match(FRONTMATTER_RE);
|
|
19
19
|
if (!match) {
|
|
20
20
|
return {
|
|
@@ -95,7 +95,7 @@ function parseTriggerFrontmatter(content) {
|
|
|
95
95
|
}
|
|
96
96
|
return { meta, body };
|
|
97
97
|
}
|
|
98
|
-
function buildTriggerContent(meta, body) {
|
|
98
|
+
export function buildTriggerContent(meta, body) {
|
|
99
99
|
const lines = ["---"];
|
|
100
100
|
lines.push(`schedule: "${meta.schedule}"`);
|
|
101
101
|
lines.push(`enabled: ${meta.enabled}`);
|
|
@@ -382,5 +382,4 @@ ${body}`;
|
|
|
382
382
|
}
|
|
383
383
|
});
|
|
384
384
|
}
|
|
385
|
-
export { parseTriggerFrontmatter, buildTriggerContent };
|
|
386
385
|
//# sourceMappingURL=dispatcher.js.map
|