@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.
- package/dist/a2a/artifact-response.d.ts.map +1 -1
- package/dist/a2a/artifact-response.js +109 -5
- package/dist/a2a/artifact-response.js.map +1 -1
- package/dist/a2a/server.d.ts.map +1 -1
- package/dist/a2a/server.js +11 -0
- package/dist/a2a/server.js.map +1 -1
- package/dist/cli/templates-meta.d.ts.map +1 -1
- package/dist/cli/templates-meta.js +1 -0
- package/dist/cli/templates-meta.js.map +1 -1
- package/dist/client/settings/VoiceTranscriptionSection.d.ts.map +1 -1
- package/dist/client/settings/VoiceTranscriptionSection.js +54 -13
- package/dist/client/settings/VoiceTranscriptionSection.js.map +1 -1
- package/dist/deploy/workspace-deploy.js +32 -3
- package/dist/deploy/workspace-deploy.js.map +1 -1
- package/dist/integrations/plugin.d.ts.map +1 -1
- package/dist/integrations/plugin.js +2 -1
- package/dist/integrations/plugin.js.map +1 -1
- package/dist/integrations/webhook-handler.d.ts.map +1 -1
- package/dist/integrations/webhook-handler.js +10 -0
- package/dist/integrations/webhook-handler.js.map +1 -1
- package/dist/onboarding/plugin.d.ts.map +1 -1
- package/dist/onboarding/plugin.js +2 -1
- package/dist/onboarding/plugin.js.map +1 -1
- package/dist/org/plugin.d.ts.map +1 -1
- package/dist/org/plugin.js +2 -1
- package/dist/org/plugin.js.map +1 -1
- package/dist/scripts/call-agent.js +2 -2
- package/dist/scripts/call-agent.js.map +1 -1
- package/dist/server/action-routes.d.ts.map +1 -1
- package/dist/server/action-routes.js +5 -11
- package/dist/server/action-routes.js.map +1 -1
- package/dist/server/agent-chat-plugin.d.ts.map +1 -1
- package/dist/server/agent-chat-plugin.js +2 -1
- package/dist/server/agent-chat-plugin.js.map +1 -1
- package/dist/server/auth-plugin.d.ts.map +1 -1
- package/dist/server/auth-plugin.js +2 -1
- package/dist/server/auth-plugin.js.map +1 -1
- package/dist/server/auth.d.ts.map +1 -1
- package/dist/server/auth.js +7 -12
- 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 +9 -29
- package/dist/server/core-routes-plugin.js.map +1 -1
- package/dist/server/cors-origins.d.ts +10 -0
- package/dist/server/cors-origins.d.ts.map +1 -0
- package/dist/server/cors-origins.js +34 -0
- package/dist/server/cors-origins.js.map +1 -0
- package/dist/server/create-server.d.ts.map +1 -1
- package/dist/server/create-server.js +10 -29
- package/dist/server/create-server.js.map +1 -1
- package/dist/server/framework-request-handler.d.ts +11 -0
- package/dist/server/framework-request-handler.d.ts.map +1 -1
- package/dist/server/framework-request-handler.js +24 -1
- package/dist/server/framework-request-handler.js.map +1 -1
- package/dist/server/resources-plugin.d.ts.map +1 -1
- package/dist/server/resources-plugin.js +2 -1
- package/dist/server/resources-plugin.js.map +1 -1
- package/dist/terminal/terminal-plugin.d.ts.map +1 -1
- package/dist/terminal/terminal-plugin.js +2 -1
- package/dist/terminal/terminal-plugin.js.map +1 -1
- package/docs/content/a2a-protocol.md +93 -14
- package/docs/content/agent-mentions.md +2 -2
- package/docs/content/agent-teams.md +2 -2
- package/docs/content/client.md +1 -1
- package/docs/content/cloneable-saas.md +13 -13
- package/docs/content/creating-templates.md +253 -211
- package/docs/content/dispatch.md +94 -0
- package/docs/content/faq.md +2 -2
- package/docs/content/frames.md +1 -1
- package/docs/content/getting-started.md +9 -1
- package/docs/content/key-concepts.md +17 -1
- package/docs/content/messaging.md +56 -19
- package/docs/content/multi-app-workspace.md +10 -2
- package/docs/content/notifications.md +1 -1
- package/docs/content/observability.md +184 -0
- package/docs/content/onboarding.md +7 -2
- package/docs/content/server.md +117 -133
- package/docs/content/skills-guide.md +3 -3
- package/docs/content/template-analytics.md +8 -6
- package/docs/content/template-design.md +25 -27
- package/docs/content/template-dispatch.md +3 -1
- package/docs/content/template-forms.md +26 -21
- package/docs/content/template-mail.md +4 -0
- package/docs/content/template-video.md +4 -4
- package/docs/content/tools.md +95 -1
- package/docs/content/tracking.md +1 -1
- package/docs/content/what-is-agent-native.md +4 -2
- package/docs/content/workspace-management.md +5 -5
- package/docs/content/workspace.md +39 -30
- 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`, `
|
|
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
|
-
- `
|
|
155
|
-
- `generate-animated-component.ts` — generate a new
|
|
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
|
|
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
|
|
package/docs/content/tools.md
CHANGED
|
@@ -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:
|
package/docs/content/tracking.md
CHANGED
|
@@ -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
|
|
3
|
-
description: "Branching
|
|
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
|
|
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
|
|
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
|
-
|
|
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` +
|
|
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
|
|
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
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
|
|
|
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
|
-
- **
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
|
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
|
|
154
|
-
|
|
|
155
|
-
| `AGENTS.md`
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
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
|
|
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
|
|
288
|
-
|
|
|
289
|
-
| @ tagging
|
|
290
|
-
| / slash commands
|
|
291
|
-
| Agent file access
|
|
292
|
-
| Workspace panel
|
|
293
|
-
| AGENTS.md /
|
|
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
|
|