@agent-native/core 0.7.51 → 0.7.53

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.
Files changed (90) hide show
  1. package/dist/a2a/artifact-response.d.ts.map +1 -1
  2. package/dist/a2a/artifact-response.js +109 -5
  3. package/dist/a2a/artifact-response.js.map +1 -1
  4. package/dist/a2a/server.d.ts.map +1 -1
  5. package/dist/a2a/server.js +11 -0
  6. package/dist/a2a/server.js.map +1 -1
  7. package/dist/cli/templates-meta.d.ts.map +1 -1
  8. package/dist/cli/templates-meta.js +1 -0
  9. package/dist/cli/templates-meta.js.map +1 -1
  10. package/dist/client/settings/VoiceTranscriptionSection.d.ts.map +1 -1
  11. package/dist/client/settings/VoiceTranscriptionSection.js +54 -13
  12. package/dist/client/settings/VoiceTranscriptionSection.js.map +1 -1
  13. package/dist/deploy/workspace-deploy.js +32 -3
  14. package/dist/deploy/workspace-deploy.js.map +1 -1
  15. package/dist/integrations/plugin.d.ts.map +1 -1
  16. package/dist/integrations/plugin.js +2 -1
  17. package/dist/integrations/plugin.js.map +1 -1
  18. package/dist/integrations/webhook-handler.d.ts.map +1 -1
  19. package/dist/integrations/webhook-handler.js +10 -0
  20. package/dist/integrations/webhook-handler.js.map +1 -1
  21. package/dist/onboarding/plugin.d.ts.map +1 -1
  22. package/dist/onboarding/plugin.js +2 -1
  23. package/dist/onboarding/plugin.js.map +1 -1
  24. package/dist/org/plugin.d.ts.map +1 -1
  25. package/dist/org/plugin.js +2 -1
  26. package/dist/org/plugin.js.map +1 -1
  27. package/dist/scripts/call-agent.js +2 -2
  28. package/dist/scripts/call-agent.js.map +1 -1
  29. package/dist/server/action-routes.d.ts.map +1 -1
  30. package/dist/server/action-routes.js +5 -11
  31. package/dist/server/action-routes.js.map +1 -1
  32. package/dist/server/agent-chat-plugin.d.ts.map +1 -1
  33. package/dist/server/agent-chat-plugin.js +2 -1
  34. package/dist/server/agent-chat-plugin.js.map +1 -1
  35. package/dist/server/auth-plugin.d.ts.map +1 -1
  36. package/dist/server/auth-plugin.js +2 -1
  37. package/dist/server/auth-plugin.js.map +1 -1
  38. package/dist/server/auth.d.ts.map +1 -1
  39. package/dist/server/auth.js +7 -12
  40. package/dist/server/auth.js.map +1 -1
  41. package/dist/server/core-routes-plugin.d.ts.map +1 -1
  42. package/dist/server/core-routes-plugin.js +9 -29
  43. package/dist/server/core-routes-plugin.js.map +1 -1
  44. package/dist/server/cors-origins.d.ts +10 -0
  45. package/dist/server/cors-origins.d.ts.map +1 -0
  46. package/dist/server/cors-origins.js +34 -0
  47. package/dist/server/cors-origins.js.map +1 -0
  48. package/dist/server/create-server.d.ts.map +1 -1
  49. package/dist/server/create-server.js +10 -29
  50. package/dist/server/create-server.js.map +1 -1
  51. package/dist/server/framework-request-handler.d.ts +11 -0
  52. package/dist/server/framework-request-handler.d.ts.map +1 -1
  53. package/dist/server/framework-request-handler.js +24 -1
  54. package/dist/server/framework-request-handler.js.map +1 -1
  55. package/dist/server/resources-plugin.d.ts.map +1 -1
  56. package/dist/server/resources-plugin.js +2 -1
  57. package/dist/server/resources-plugin.js.map +1 -1
  58. package/dist/terminal/terminal-plugin.d.ts.map +1 -1
  59. package/dist/terminal/terminal-plugin.js +2 -1
  60. package/dist/terminal/terminal-plugin.js.map +1 -1
  61. package/docs/content/a2a-protocol.md +93 -14
  62. package/docs/content/agent-mentions.md +2 -2
  63. package/docs/content/agent-teams.md +2 -2
  64. package/docs/content/client.md +1 -1
  65. package/docs/content/cloneable-saas.md +13 -13
  66. package/docs/content/creating-templates.md +253 -211
  67. package/docs/content/dispatch.md +94 -0
  68. package/docs/content/faq.md +2 -2
  69. package/docs/content/frames.md +1 -1
  70. package/docs/content/getting-started.md +9 -1
  71. package/docs/content/key-concepts.md +17 -1
  72. package/docs/content/messaging.md +56 -19
  73. package/docs/content/multi-app-workspace.md +10 -2
  74. package/docs/content/notifications.md +1 -1
  75. package/docs/content/observability.md +184 -0
  76. package/docs/content/onboarding.md +7 -2
  77. package/docs/content/server.md +117 -133
  78. package/docs/content/skills-guide.md +3 -3
  79. package/docs/content/template-analytics.md +8 -6
  80. package/docs/content/template-design.md +25 -27
  81. package/docs/content/template-dispatch.md +3 -1
  82. package/docs/content/template-forms.md +26 -21
  83. package/docs/content/template-mail.md +4 -0
  84. package/docs/content/template-video.md +4 -4
  85. package/docs/content/tools.md +95 -1
  86. package/docs/content/tracking.md +1 -1
  87. package/docs/content/what-is-agent-native.md +4 -2
  88. package/docs/content/workspace-management.md +5 -5
  89. package/docs/content/workspace.md +39 -30
  90. package/package.json +1 -1
@@ -14,6 +14,7 @@ When you open the app, you'll see your inbox on the left, the open thread in the
14
14
  - **Read and triage email** with keyboard shortcuts (`J`/`K` to move, `E` to archive, `R` to reply, `C` to compose).
15
15
  - **Connect multiple Gmail accounts** — personal and work in one inbox.
16
16
  - **Ask the agent to do anything you can do.** "Summarize my unread emails." "Draft a reply that politely declines." "Archive all Netlify bot emails older than a week."
17
+ - **Queue drafts for review.** Teammates and Slack users can ask the agent to prepare an email for an org member; the owner reviews, edits, and sends it from Mail.
17
18
  - **Auto-triage with rules.** Set up automation rules in plain English ("from a newsletter") with actions (label, archive, mark read, star, trash).
18
19
  - **Track opens and clicks** on the emails you send.
19
20
  - **Search across every connected inbox** with one query.
@@ -96,6 +97,8 @@ agent-native add-app
96
97
 
97
98
  **Multiple compose drafts.** The compose panel supports multiple draft tabs at once. Each draft is stored as an `application_state` entry at `compose-{id}` and syncs live between the agent and the UI. The agent can create a new draft with `manage-draft --action=create`, edit your in-progress draft with `--action=update`, or close tabs with `--action=delete`. Drafts use markdown in the body field; the TipTap editor renders it as rich text and converts to HTML on send.
98
99
 
100
+ **Queued draft review.** Drafts requested by teammates or Slack are durable SQL rows in `queued_email_drafts`. The agent uses `queue-email-draft` to assign a draft to an org member, returns a review URL such as `/draft-queue/<id>`, and waits for the owner to review or explicitly send. The queue supports listing assigned drafts, editing them, opening one in the compose panel, dismissing it, and sending one or all reviewed drafts.
101
+
99
102
  **AI triage via automations.** Mail supports automation rules that run against new inbox email using AI. A rule has a natural-language condition (for example, `"from a newsletter"` or `"subject contains invoice"`) and a list of actions (`label`, `archive`, `mark_read`, `star`, `trash`). Manage them via `pnpm action manage-automations --action=create|list|update|delete|enable|disable`, or through the Settings page. Rules fire automatically and can be triggered manually with `pnpm action trigger-automations`.
100
103
 
101
104
  **Send tracking.** Sent messages get open-pixel and link-click tracking injected automatically. Settings live under `mail-settings.tracking` with `tracking.opens` and `tracking.clicks` (both default `true`). Only links in the new portion of a reply or forward are rewritten — quoted content is left alone. Pull stats for any sent message with `pnpm action get-tracking --id=<message-id>`, or from `GET /api/emails/:id/tracking`. Open and click events are stored in the `email_tracking` and `email_link_tracking` tables.
@@ -132,6 +135,7 @@ When a Google account is connected, email lives in Gmail — the app is a view o
132
135
  | `getSetting("labels")` | System and user labels, with unread counts |
133
136
  | `getSetting("mail-settings")` | User profile, tracking preferences, signature, aliases |
134
137
  | `getSetting("aliases")` | Email aliases |
138
+ | `queued_email_drafts` table | Teammate-requested drafts awaiting owner review/send |
135
139
  | `email_tracking` table | Open-pixel events for sent messages |
136
140
  | `email_link_tracking` table | Link-click events for sent messages |
137
141
  | `application_state` table | `navigation`, `navigate`, `compose-{id}` entries (ephemeral) |
@@ -124,7 +124,7 @@ User edits (track values, parameter values, prop overrides, composition settings
124
124
 
125
125
  The agent always knows which composition you have open. Navigation state (`{ view, compositionId }`) is written to the framework's `application_state` table, and the `view-screen` action returns it plus a hint pointing at `app/remotion/registry.ts`. You don't have to tell the agent which composition you're on — ask it to act on "this one" and it will.
126
126
 
127
- Under the hood the agent calls actions like `navigate`, `create-composition`, `generate-animated-component`, and edits `app/remotion/registry.ts` and `app/remotion/compositions/*.tsx` directly. Every change shows up in the timeline.
127
+ Under the hood the agent calls actions like `navigate`, `save-composition`, and `generate-animated-component`. SQL-backed composition records are created or updated through `save-composition`; code-backed Remotion components still live in `app/remotion/compositions/*.tsx` and are registered in `app/remotion/registry.ts`.
128
128
 
129
129
  ### Data model
130
130
 
@@ -151,10 +151,10 @@ The template folder is `templates/videos/` (the user-facing slug is `video`, but
151
151
 
152
152
  - `view-screen.ts` — returns current navigation state for the agent.
153
153
  - `navigate.ts` — navigate to a composition (`--compositionId <id>`) or the home view (`--view home`).
154
- - `create-composition.ts` — scaffold a new composition with the standard camera and cursor tracks.
155
- - `generate-animated-component.ts` — generate a new animated component file with boilerplate.
154
+ - `save-composition.ts` — create or update a SQL-backed composition record.
155
+ - `generate-animated-component.ts` — generate a new Remotion component file with boilerplate.
156
156
  - `validate-compositions.ts` — check all registered compositions for structural problems.
157
- - `list-compositions.ts`, `get-composition.ts`, `update-composition.ts`, `delete-composition.ts`, `save-composition.ts`CRUD over the SQL table.
157
+ - `list-compositions.ts`, `get-composition.ts`, `update-composition.ts`, `delete-composition.ts` — read, update, and delete SQL-backed composition records.
158
158
 
159
159
  **Routes** — `templates/videos/app/routes/`
160
160
 
@@ -26,6 +26,26 @@ Tools are different:
26
26
 
27
27
  Use app code for features that are core to the product. Use tools for everything else — one-off utilities, personal dashboards, quick integrations, monitors, and things you want to spin up in seconds.
28
28
 
29
+ ## When to build a tool vs. a template feature {#when-to-build}
30
+
31
+ A quick decision rubric:
32
+
33
+ **Build a tool when:**
34
+
35
+ - It's for one user or one team, not the whole product.
36
+ - It's a quick utility, dashboard, or widget you want now, not next sprint.
37
+ - No new database schema is needed (or per-tool key-value storage is enough).
38
+ - You want to ship it inside a single chat turn, no deploy.
39
+
40
+ **Add a template feature when:**
41
+
42
+ - Every user of the template should get it.
43
+ - It needs new SQL tables, migrations, or shared schema changes.
44
+ - The UI is complex enough to warrant React components, routes, and proper testing.
45
+ - It's part of the product surface — something you'd advertise on a landing page.
46
+
47
+ When in doubt, start as a tool. Promoting a tool to a template feature later is straightforward; rolling back a half-shipped product feature is not.
48
+
29
49
  ## Creating a tool {#creating}
30
50
 
31
51
  ### From the sidebar
@@ -58,16 +78,56 @@ Tools render with modest canvas padding by default so simple widgets and dashboa
58
78
 
59
79
  ## Persistent storage {#persistent-storage}
60
80
 
61
- Every tool has access to a built-in key-value store. Data is automatically scoped per tool and per user — your data stays yours.
81
+ Every tool has access to a built-in key-value store via the `toolData` helper. Data is automatically scoped per tool and per user — your data stays yours.
62
82
 
63
83
  When you ask the agent to "add persistence" or "remember state" in a tool, it uses this built-in storage. No database tables to create, no migrations to run.
64
84
 
85
+ ### Scopes
86
+
87
+ All `toolData` methods accept an optional `{ scope }` option:
88
+
89
+ - `'user'` (default) — private to the current user.
90
+ - `'org'` — shared across the user's organization.
91
+ - `'all'` — list/get only; returns both user-scoped and org-scoped items.
92
+
93
+ ```html
94
+ <script>
95
+ // Private to me
96
+ await toolData.set('notes', 'note-1', { title: 'My Note' });
97
+
98
+ // Shared with my org
99
+ await toolData.set('notes', 'team-note', { title: 'Team Note' }, { scope: 'org' });
100
+
101
+ // List my notes (default)
102
+ const mine = await toolData.list('notes');
103
+
104
+ // List both mine and the org's
105
+ const everything = await toolData.list('notes', { scope: 'all' });
106
+ </script>
107
+ ```
108
+
65
109
  ## API keys and secrets {#secrets}
66
110
 
67
111
  When a tool needs an API key (for GitHub, OpenAI, a weather service, etc.), the agent will tell you what's needed and where to get it. You add the key through the Settings UI in the agent sidebar.
68
112
 
69
113
  Keys are encrypted and stored securely. Each key is restricted to specific domains — a GitHub token can only be sent to `api.github.com`, never anywhere else.
70
114
 
115
+ ### Secrets in tools {#secrets-in-tools}
116
+
117
+ Tools reference secrets in `toolFetch()` calls using the `${keys.NAME}` template pattern. The proxy substitutes the encrypted value server-side; the actual key never reaches the browser.
118
+
119
+ ```html
120
+ <script>
121
+ const res = await toolFetch('https://api.github.com/user', {
122
+ headers: {
123
+ Authorization: 'Bearer ${keys.GITHUB_TOKEN}',
124
+ },
125
+ });
126
+ </script>
127
+ ```
128
+
129
+ When a tool needs a one-off key, the agent can register an ad-hoc secret via `POST /_agent-native/secrets/adhoc` with a `urlAllowlist` that pins which domains the secret may be sent to. A request to any other host is rejected before the proxy fires. Combined with SSRF and private-network protections, this means a leaked tool can't exfiltrate secrets to an attacker-controlled URL.
130
+
71
131
  ## Sharing {#sharing}
72
132
 
73
133
  Tools are **private by default** — only you can see and use a tool you create.
@@ -79,6 +139,8 @@ You can share tools with your team:
79
139
 
80
140
  Shared tools have their own URLs, so you can link to them directly.
81
141
 
142
+ Under the hood, tools use the same ownable-resource model as the rest of the framework — `ownableColumns()` on the `tools` table and a standard `createSharesTable()` for grants. That means tools plug into the same share dialog, access checks, and audit surfaces as documents, decks, dashboards, and any other shareable resource. See [Security](/docs/security) for the full access model.
143
+
82
144
  ## Security {#security}
83
145
 
84
146
  Tools run in a secure sandbox:
@@ -89,6 +151,38 @@ Tools run in a secure sandbox:
89
151
  - **Private network protection** — tools can't reach internal/private network addresses.
90
152
  - **Authentication required** — only logged-in users can use tools.
91
153
 
154
+ ## Tool API reference {#api-reference}
155
+
156
+ Every tool runs inside a sandboxed iframe with the following helpers injected on `window`. They are the complete surface area — anything else a tool needs has to go through one of these.
157
+
158
+ | Helper | Purpose | Example |
159
+ | ------------------------------------------- | ---------------------- | --------------------------------------------- |
160
+ | `toolData.set(collection, id, data, opts?)` | Persist data per-tool | `toolData.set('notes', id, { text: '...' })` |
161
+ | `toolData.list(collection, opts?)` | List persisted items | `toolData.list('notes', { scope: 'all' })` |
162
+ | `toolData.get(collection, id, opts?)` | Get a single item | `toolData.get('notes', 'note-1')` |
163
+ | `toolData.remove(collection, id, opts?)` | Delete persisted item | `toolData.remove('notes', 'note-1')` |
164
+ | `appAction(name, params)` | Call any app action | `appAction('list-emails', { view: 'inbox' })` |
165
+ | `dbQuery(sql, args)` | Read from SQL | `dbQuery('SELECT * FROM tools')` |
166
+ | `dbExec(sql, args)` | Write to SQL | `dbExec('INSERT INTO ...')` |
167
+ | `appFetch(path, options)` | Call any app endpoint | `appFetch('/api/settings')` |
168
+ | `toolFetch(url, options)` | External API via proxy | `toolFetch('https://api.github.com/...')` |
169
+
170
+ `appAction` is the preferred way to trigger app behavior — it routes through the same actions the agent and the frontend use, so authorization and access scoping happen automatically. Drop down to `dbQuery`/`dbExec` only when there's no action that fits.
171
+
172
+ ### Routes {#routes}
173
+
174
+ The framework mounts the following endpoints under `/_agent-native/tools/`. Tools themselves rarely call these directly — they're useful when integrating tools with external scripts or custom UI.
175
+
176
+ | Method | Path | Purpose |
177
+ | ------ | --------------------------------- | -------------------------------------------- |
178
+ | GET | `/_agent-native/tools` | List tools (filtered by ownership + sharing) |
179
+ | POST | `/_agent-native/tools` | Create a tool |
180
+ | GET | `/_agent-native/tools/:id` | Get a single tool |
181
+ | PUT | `/_agent-native/tools/:id` | Update (supports `patches` for diffing) |
182
+ | DELETE | `/_agent-native/tools/:id` | Delete a tool |
183
+ | GET | `/_agent-native/tools/:id/render` | Render the iframe HTML |
184
+ | POST | `/_agent-native/tools/proxy` | Authenticated proxy with secret injection |
185
+
92
186
  ## Examples {#examples}
93
187
 
94
188
  Here are some things people build as tools:
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Analytics Tracking"
2
+ title: "Tracking & Analytics"
3
3
  description: "Server-side analytics with pluggable providers — PostHog, Mixpanel, Amplitude, or custom webhook"
4
4
  ---
5
5
 
@@ -120,7 +120,7 @@ The vision: fewer handoffs, one person doing the work of a small team.
120
120
 
121
121
  ## Fork and customize {#fork-and-customize}
122
122
 
123
- Agent-native apps follow a fork-and-customize model. You start from a **cloneable SaaS** template — Mail, Calendar, Analytics, Slides, Clips, Forms, Dispatch — and make it yours:
123
+ Agent-native apps follow a fork-and-customize model. You start from a **cloneable SaaS** template — Mail, Calendar, Analytics, Slides, Clips, Design, Forms, Dispatch — and make it yours:
124
124
 
125
125
  1. Pick a template on [agent-native.com/templates](/templates)
126
126
  2. Use it immediately as a hosted app (e.g. mail.agent-native.com)
@@ -177,5 +177,7 @@ One action, four surfaces: the agent calls it as a tool, the UI calls it as a ty
177
177
  - [**Getting Started**](/docs) — pick a template and run it
178
178
  - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
179
179
  - [**Cloneable SaaS**](/docs/cloneable-saas) — templates as complete products you own
180
- - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP)
180
+ - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP) backed by SQL, not files
181
+ - [**Dispatch**](/docs/dispatch) — the workspace control plane: secrets vault, Slack/email inbox, cross-app delegation
182
+ - [**Tools**](/docs/tools) — sandboxed mini-apps the agent creates instantly without code changes
181
183
  - [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` into any React app
@@ -1,13 +1,13 @@
1
1
  ---
2
- title: "Workspace Management"
3
- description: "Branching strategies, code ownership, PR review, and governance practices for agent-native workspaces."
2
+ title: "Workspace Governance"
3
+ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime governance alongside git-level governance."
4
4
  ---
5
5
 
6
- # Workspace Management
6
+ # Workspace Governance
7
7
 
8
8
  This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the dispatch control plane fits into your governance model.
9
9
 
10
- For workspace setup, shared auth, and deployment, see [Multi-App Workspace](/docs/multi-app-workspace).
10
+ For workspace setup, shared auth, and deployment, see [Multi-App Workspaces](/docs/multi-app-workspace).
11
11
 
12
12
  ## Branching
13
13
 
@@ -179,7 +179,7 @@ When reviewing PRs in this environment:
179
179
 
180
180
  ## Dispatch as Governance
181
181
 
182
- The dispatch app is the workspace's runtime control plane. It complements git-level governance with runtime governance:
182
+ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It complements git-level governance with runtime governance:
183
183
 
184
184
  | Concern | Git / GitHub | Dispatch |
185
185
  | ------------------------------- | ----------------------------- | ------------------------------------------ |
@@ -5,7 +5,9 @@ description: "Claude-Code-level customization per user — skills, memory, instr
5
5
 
6
6
  # Workspace
7
7
 
8
- Every agent-native app ships with a **workspace**: the customization layer that makes the agent yours. It contains team instructions (`AGENTS.md`), per-user memory (`learnings.md`), skills the agent pulls in on demand, custom sub-agents, scheduled jobs, and connected MCP servers — everything you'd expect from a Claude Code / Codex setup.
8
+ > **See also:** Deploying multiple apps as one workspace? See [Multi-App Workspaces](/docs/multi-app-workspace). Governance, branching, and CODEOWNERS? See [Workspace Governance](/docs/workspace-management).
9
+
10
+ Every agent-native app ships with a **workspace**: the customization layer that makes the agent yours. It contains team instructions (`AGENTS.md`), shared learnings (`LEARNINGS.md`), personal structured memory (`memory/MEMORY.md`), skills the agent pulls in on demand, custom sub-agents, scheduled jobs, and connected MCP servers — everything you'd expect from a Claude Code / Codex setup.
9
11
 
10
12
  The twist: **it's SQL rows, not filesystem files.** Each user gets their own workspace stored in the database. There's no dev-box to spin up, no container per user, no files to mount. A multi-tenant SaaS can give every user a fully-customizable agent for essentially free, because all of it is rows — personal memory, personal MCP servers, personal skills, personal sub-agents — and the shared codebase hosts all of them at once.
11
13
 
@@ -15,7 +17,7 @@ The twist: **it's SQL rows, not filesystem files.** Each user gets their own wor
15
17
  | One codebase per developer | One codebase, many users |
16
18
  | Needs a dev-box or container | Runs on any serverless/edge host |
17
19
  | Customization at `~/.claude/` | Customization per-user, scoped `u:<email>:…` |
18
- | Per-project `CLAUDE.md` / skills | Per-app `AGENTS.md` + per-user `learnings.md` |
20
+ | Per-project `CLAUDE.md` / skills | Per-app `AGENTS.md` + workspace memory resources |
19
21
  | MCP config in a JSON file | MCP config in JSON _or_ the settings UI, per scope |
20
22
 
21
23
  Same capabilities. Different economics. See [Cloneable SaaS](/docs/cloneable-saas) for why this matters for SaaS.
@@ -30,19 +32,20 @@ The **Workspace** tab in the agent sidebar is where you and the agent share pers
30
32
  - Create files with the `+` menu. Upload with the upload button. Edit inline (visual or code view).
31
33
  - **Personal** is just you. **Shared** is your team/org.
32
34
  - The agent can read, write, and rename any of these files as part of a conversation.
33
- - Special files the agent always reads: `AGENTS.md` (team rules) and `learnings.md` (per-user memory the agent auto-updates when you correct it).
35
+ - Special files the agent preloads: shared `AGENTS.md`, shared `LEARNINGS.md`, and personal structured memory at `memory/MEMORY.md`.
34
36
 
35
37
  ## What goes in here? {#what-goes-in-here}
36
38
 
37
- | File / path | What it's for |
38
- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
39
- | `AGENTS.md` (Shared) | Team instructions the agent reads every turn — tone, rules, domain context, skill references. |
40
- | `learnings.md` (Personal) | **Agent memory.** Per-user file the agent auto-writes to on corrections/preferences and auto-reads every turn. |
41
- | `skills/<name>.md` | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands). |
42
- | `agents/<name>.md` | **Custom agents** reusable sub-agent profiles the agent can delegate to (invoked with `@` mentions). |
43
- | `remote-agents/<name>.json` | A2A manifests for connected remote agents edited via a form, not raw JSON. |
44
- | `jobs/<name>.md` | Scheduled tasks that run on a cron (see the recurring-jobs docs). |
45
- | Anything else | Notes, prompts, config, dataset snippets any text file. |
39
+ | File / path | What it's for |
40
+ | --------------------------- | ------------------------------------------------------------------------------------------------------ |
41
+ | `AGENTS.md` (Shared) | Team instructions the agent reads every turn — tone, rules, domain context, skill references. |
42
+ | `LEARNINGS.md` (Shared) | Shared corrections, conventions, and durable project memory the agent preloads. |
43
+ | `memory/MEMORY.md` | Personal structured memory the chat preloads for the current user. |
44
+ | `skills/<name>.md` | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands). |
45
+ | `agents/<name>.md` | **Custom agents** reusable sub-agent profiles the agent can delegate to (invoked with `@` mentions). |
46
+ | `remote-agents/<name>.json` | A2A manifests for connected remote agents — edited via a form, not raw JSON. |
47
+ | `jobs/<name>.md` | Scheduled tasks that run on a cron (see the recurring-jobs docs). |
48
+ | Anything else | Notes, prompts, config, dataset snippets — any text file. |
46
49
 
47
50
  ## Overview {#overview}
48
51
 
@@ -93,7 +96,7 @@ Change how the agent behaves, in 60 seconds.
93
96
  - **Skills** (`+` → **Skill**) — focused how-to files invoked in chat with `/skill-name`.
94
97
  - **Agents** (`+` → **Agent**) — reusable sub-agent personas invoked with `@agent-name`.
95
98
  - **Scheduled Tasks** (`+` → **Scheduled Task**) — prompts that run on a cron.
96
- - **learnings.md** — your Personal file the agent auto-updates whenever you correct it.
99
+ - **Memory** — shared `LEARNINGS.md` and personal `memory/MEMORY.md` keep durable context available across conversations.
97
100
 
98
101
  ## How the Agent Uses Resources {#how-the-agent-uses-resources}
99
102
 
@@ -124,11 +127,16 @@ Be concise. Lead with the answer.
124
127
  | data-analysis | `skills/data-analysis.md` | BigQuery and data workflows |
125
128
  ```
126
129
 
127
- ### learnings.md — agent memory {#learnings-md}
130
+ ### Memory {#memory}
131
+
132
+ The workspace has two current memory surfaces:
133
+
134
+ - `LEARNINGS.md` in **Shared** scope for project-wide conventions, corrections, and durable team knowledge.
135
+ - `memory/MEMORY.md` in **Personal** scope for structured memory about the current user.
128
136
 
129
- `learnings.md` is the agent's long-term memory about _you_. It's a **Personal-scope** resource (one per user) that the agent auto-reads at the start of every conversation and auto-writes to whenever it picks up something worth remembering.
137
+ The resource system also seeds a personal `LEARNINGS.md` for compatibility with older workspaces, but the chat preload path is shared `LEARNINGS.md` plus personal `memory/MEMORY.md`.
130
138
 
131
- **What gets saved.** When you correct the agent ("no, always use X instead of Y"), share a preference ("I prefer concise answers"), or reveal context ("my team calls this 'the dispatch layer'"), the agent appends the learning to `learnings.md` so it doesn't repeat the mistake or have to re-ask next time. This behavior lives in the framework system prompt (the `capture-learnings` skill spells out the rules for when and how).
139
+ **What gets saved.** When you correct the agent ("no, always use X instead of Y"), share a preference ("I prefer concise answers"), or reveal context ("my team calls this 'the dispatch layer'"), the agent can capture that learning so it doesn't repeat the mistake or have to re-ask next time. Project-wide learnings belong in shared `LEARNINGS.md`; user-specific memory belongs under `memory/`. This behavior lives in the framework system prompt and the `capture-learnings` skill spells out the rules for when and how.
132
140
 
133
141
  **What it looks like.**
134
142
 
@@ -150,13 +158,14 @@ Be concise. Lead with the answer.
150
158
 
151
159
  **Where it fits.**
152
160
 
153
- | Surface | Scope | Written by | Read when |
154
- | -------------- | -------- | ------------------------- | ---------------------------- |
155
- | `AGENTS.md` | Shared | Humans / agent on request | Every turn |
156
- | `learnings.md` | Personal | Agent, automatically | Every turn |
157
- | `skills/…` | Shared | Humans / agent on request | On demand (`/slash` command) |
161
+ | Surface | Scope | Written by | Read when |
162
+ | ------------------ | -------- | ------------------------- | ---------------------------- |
163
+ | `AGENTS.md` | Shared | Humans / agent on request | Every turn |
164
+ | `LEARNINGS.md` | Shared | Humans / agent on request | Every turn |
165
+ | `memory/MEMORY.md` | Personal | Agent / humans | Every turn |
166
+ | `skills/…` | Shared | Humans / agent on request | On demand (`/slash` command) |
158
167
 
159
- Users can edit `learnings.md` directly in the Workspace tab — it's a regular resource. Delete lines the agent got wrong or promote them into `AGENTS.md` if they apply to the whole team.
168
+ Users can edit these memory files directly in the Workspace tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.
160
169
 
161
170
  ## Skills {#skills}
162
171
 
@@ -220,7 +229,7 @@ Recommended conventions:
220
229
  There are two agent types in Workspace:
221
230
 
222
231
  - **Custom agents** — local profiles in `agents/*.md`, executed inside the current app/runtime
223
- - **Connected agents** — remote A2A peers described by manifests in `agents/*.json`
232
+ - **Connected agents** — remote A2A peers described by manifests in `remote-agents/*.json` (legacy `agents/*.json` manifests are still recognized)
224
233
 
225
234
  Use custom agents for delegation within one app. Use connected agents when you need to call another app over A2A.
226
235
 
@@ -284,13 +293,13 @@ If no skills are configured, the dropdown shows a hint with a link to these docs
284
293
 
285
294
  The resource system works identically in both modes. The difference is what additional sources are available for `@` tagging and `/` commands:
286
295
 
287
- | Feature | Dev Mode | Production |
288
- | ------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
289
- | @ tagging | Codebase files + workspace resources + custom agents + connected agents | Workspace resources + custom agents + connected agents |
290
- | / slash commands | .agents/skills/ + resource skills | Resource skills only |
291
- | Agent file access | Filesystem + resources | Resources only |
292
- | Workspace panel | Full access | Full access |
293
- | AGENTS.md / learnings.md | Available | Available |
296
+ | Feature | Dev Mode | Production |
297
+ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------ |
298
+ | @ tagging | Codebase files + workspace resources + custom agents + connected agents | Workspace resources + custom agents + connected agents |
299
+ | / slash commands | .agents/skills/ + resource skills | Resource skills only |
300
+ | Agent file access | Filesystem + resources | Resources only |
301
+ | Workspace panel | Full access | Full access |
302
+ | AGENTS.md / memory | Available | Available |
294
303
 
295
304
  ## Resource API {#resource-api}
296
305
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-native/core",
3
- "version": "0.7.51",
3
+ "version": "0.7.53",
4
4
  "type": "module",
5
5
  "description": "Framework for agent-native application development — where AI agents and UI share state via files",
6
6
  "license": "MIT",