@agent-native/core 0.152.1 → 0.153.1

package/src/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -1,340 +0,0 @@
-# Extension API Reference
-
-This is the exhaustive reference for the helpers and globals injected into
-every extension iframe, plus the back-compat naming table. For the model +
-when-to-use overview, see `../SKILL.md`. For worked HTML examples, see
-`examples.md`.
-
-## Accessing app data
-
-Extensions can call the host app's actions and API endpoints directly. The
-iframe shares the session cookie, so authentication is automatic.
-
-### `appAction(name, params)` — Call app actions
-
-Call any action defined in the app's `actions/` directory. Actions are
-auto-mounted at `/_agent-native/actions/:name`.
-
-```html
-<div
-  x-data="{ emails: [], loading: true }"
-  x-init="
-  appAction('list-emails', { view: 'inbox', limit: 10 })
-    .then(d => { emails = d.emails || d; loading = false })
-    .catch(e => { console.error(e); loading = false })
-"
->
-  <h2 class="text-lg font-semibold mb-4">My Inbox</h2>
-  <template x-for="email in emails" :key="email.id">
-    <div class="rounded-lg border p-3 mb-2">
-      <p class="font-medium text-sm" x-text="email.subject"></p>
-      <p
-        class="text-xs text-muted-foreground"
-        x-text="email.from?.name || email.from?.email"
-      ></p>
-    </div>
-  </template>
-</div>
-```
-
-### Connected MCP and provider APIs
-
-The host injects connector helpers that reuse the current user's or
-organization's server-side grants. OAuth tokens, refresh tokens, client
-secrets, and remote server URLs stay in the parent/runtime and are never
-serialized into the iframe.
-
-```javascript
-const tools = await agentNative.mcp.listTools();
-const linearTools = await agentNative.mcp.listTools("org_linear");
-const result = await agentNative.mcp.callTool("org_linear", "list_issues", {
-  project: "<PROJECT_ID>",
-});
-```
-
-For regular provider connectors, use the shared provider API actions when the
-template exposes them:
-
-```javascript
-const catalog = await agentNative.providerApi.catalog({ provider: "github" });
-const docs = await agentNative.providerApi.docs({ provider: "github" });
-```
-
-These helpers are also available as
-`agentNative.connectors.mcp` and `agentNative.connectors.providerApi`. They
-are action-backed, so the host enforces authentication, app grants, provider
-allow-lists, audit behavior, and any local-file `permissions.appActions`
-declarations. Extensions can discover provider APIs and use connected MCP tools,
-but they cannot issue arbitrary provider requests. Use a purpose-built app action
-for a bounded operation instead.
-
-### `appFetch(path, options)` — Call allowed framework endpoints
-
-General-purpose fetch to allowed framework endpoints (for example,
-`/_agent-native/application-state/navigation`). Automatically adds credentials
-and JSON content type. Template `/api/*` routes are intentionally blocked by
-the extension bridge; use `appAction(name, params)` for app data instead.
-
-```javascript
-// Read application state
-const nav = await appFetch("/_agent-native/application-state/navigation");
-
-// Call a framework route
-const nav = await appFetch("/_agent-native/application-state/navigation");
-```
-
-### `dbQuery(sql)` — Read from the app's database
-
-Run a read-only SELECT query against the app's SQL database. Results are
-auto-scoped to the current user/org.
-
-```html
-<div
-  x-data="{ rows: [] }"
-  x-init="
-  dbQuery('SELECT id, name FROM tools ORDER BY created_at DESC LIMIT 10')
-    .then(d => rows = d.rows || d)
-"
->
-  <template x-for="row in rows" :key="row.id">
-    <div class="border-b p-2 text-sm" x-text="row.name"></div>
-  </template>
-</div>
-```
-
-> The physical SQL table is still named `tools` (and `tool_data`,
-> `tool_shares`) for back-compat. The Drizzle exports are `extensions`,
-> `extensionData`, and `extensionShares` — use those when you query via the
-> ORM. When writing raw SQL inside an extension (as above), use the
-> physical names.
-
-### `dbExec(sql)` — Write to the app's database
-
-Run an INSERT, UPDATE, or DELETE statement. Writes are auto-scoped to the
-current user/org, and `owner_email` / `org_id` are auto-injected on INSERT.
-
-```javascript
-// Insert a new record
-await dbExec(
-  "INSERT INTO notes (id, title, body) VALUES ('abc', 'My Note', 'Hello world')",
-);
-
-// Update an existing record
-await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
-```
-
-### All helpers summary
-
-| Helper                                           | Use for                                                  | Example                                                                                                          |
-| ------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `appAction(name, params)`                        | Call app actions (CRUD, queries)                         | `appAction('list-emails', { view: 'inbox' })`                                                                    |
-| `appFetch(path, options)`                        | Call allowed framework endpoints                         | `appFetch('/_agent-native/application-state/navigation')`                                                        |
-| `dbQuery(sql)`                                   | Read from the app's SQL database                         | `dbQuery('SELECT * FROM notes LIMIT 10')`                                                                        |
-| `dbExec(sql)`                                    | Write to the app's SQL database                          | `dbExec("INSERT INTO notes ...")`                                                                                |
-| `extensionFetch(url, options)`                   | Call external APIs via proxy (alias `toolFetch`)         | `extensionFetch('https://api.github.com/user', { headers: { 'Authorization': 'Bearer ${keys.GITHUB_TOKEN}' } })` |
-| `extensionData.set(collection, id, data, opts?)` | Save an item to extension storage (alias `toolData.set`) | `extensionData.set('todos', 'todo-1', { title: 'Buy milk' })`                                                    |
-| `extensionData.list(collection, opts?)`          | List items in a collection                               | `extensionData.list('todos', { scope: 'all' })`                                                                  |
-| `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
-| `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
-| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state     | `agentNative.ui.output({ threshold })`                                                                           |
-| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })`                                           |
-
-## Persisting Custom Data
-
-Extensions have a built-in key-value store via `extensionData` (legacy alias:
-`toolData`). Each extension gets its own isolated storage, organized into
-collections. Every method accepts an optional `{ scope }` option:
-
-- `'user'` (default) — private to the current user
-- `'org'` — visible to everyone in the user's org
-- `'all'` (list/get only) — returns both user and org items
-
-```javascript
-// Save a private item (default scope: 'user')
-await extensionData.set("todos", "todo-1", { title: "Buy milk", done: false });
-
-// Save an org-shared item
-await extensionData.set(
-  "todos",
-  "team-todo-1",
-  { title: "Ship v2", done: false },
-  { scope: "org" },
-);
-
-// List user items (default)
-const myTodos = await extensionData.list("todos");
-
-// List org items
-const orgTodos = await extensionData.list("todos", { scope: "org" });
-
-// List both user + org items
-const allTodos = await extensionData.list("todos", { scope: "all" });
-// Returns: [{ id, toolId, collection, data (JSON string), ownerEmail, scope, orgId, createdAt, updatedAt }]
-// (the row column is still named `toolId` for back-compat — it's the extension id)
-
-// Parse the JSON data
-const parsed = allTodos.map((t) => ({
-  ...JSON.parse(t.data),
-  id: t.id,
-  scope: t.scope,
-}));
-
-// Get/delete with scope
-const item = await extensionData.get("todos", "team-todo-1", { scope: "org" });
-await extensionData.remove("todos", "team-todo-1", { scope: "org" });
-```
-
-Data is scoped per-extension. User-scoped items are private per-user;
-org-scoped items are shared across the org. Any org member can read,
-update, or delete org-scoped items when the caller has editor/admin/owner
-access to the extension. Viewer access is read-only. **Prefer
-`extensionData` over raw `dbExec` for extension-specific persistence** — it
-handles table creation, scoping, and upserts automatically.
-
-### Authenticated extension data routes
-
-`extensionData` uses the same authenticated HTTP routes that external
-logged-in clients may call directly:
-
-| Method | Path                                                              | Access             |
-| ------ | ----------------------------------------------------------------- | ------------------ |
-| GET    | `/_agent-native/extensions/data/:extensionId/:collection`         | viewer or above    |
-| POST   | `/_agent-native/extensions/data/:extensionId/:collection`         | editor/admin/owner |
-| DELETE | `/_agent-native/extensions/data/:extensionId/:collection/:itemId` | editor/admin/owner |
-
-Reads accept `?scope=user`, `?scope=org`, `?scope=all`, and `?limit=100`.
-Writes accept `{ id, data, scope }` where `scope` is `user` or `org`. These
-routes use the caller's app session and extension sharing role; they are not a
-public API-key or anonymous ingestion surface. If a template needs
-server-to-server access, add a template-specific action or route with explicit
-scoped keys and rate limits.
-
-## Using `extensionFetch()` for API calls
-
-`extensionFetch()` (legacy alias `toolFetch()`) is a drop-in replacement for
-`fetch()` that proxies requests through the server. The server injects
-secret values before the request leaves.
-
-```javascript
-// Basic GET
-const res = await extensionFetch("https://api.example.com/data");
-const data = await res.json();
-
-// With secret injection
-const res = await extensionFetch("https://api.openai.com/v1/models", {
-  headers: {
-    Authorization: "Bearer ${keys.OPENAI_API_KEY}",
-  },
-});
-
-// POST with body
-const res = await extensionFetch("https://api.example.com/items", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ name: "New Item" }),
-});
-```
-
-**Important:** Use single quotes around strings containing `${keys.NAME}`
-to prevent JavaScript template literal evaluation. The substitution
-happens server-side, not in the browser.
-
-## Tailwind classes
-
-Extensions inherit the main app's Tailwind v4 theme. Use the same utility
-classes:
-
-- **Colors:** `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `text-muted-foreground`, `border-border`, `bg-accent`, `bg-destructive`
-- **Layout:** `flex`, `grid`, `space-y-2`, `gap-4`, `p-4`, `m-2`
-- **Typography:** `text-sm`, `text-lg`, `font-medium`, `font-bold`
-- **Borders:** `border`, `rounded-lg`, `rounded-md`, `rounded-sm`
-- **Dark mode:** automatic via `.dark` class on the html element
-
-## Managing secrets
-
-Extensions reference secrets via `${keys.NAME}` inside `extensionFetch()`
-calls. Create secrets via:
-
-```
-POST /_agent-native/secrets/adhoc
-{ "name": "GITHUB_TOKEN", "value": "<TOKEN_VALUE_FROM_USER_SETTINGS>", "description": "GitHub PAT", "urlAllowlist": ["https://api.github.com"] }
-```
-
-Or the user can add them in the settings UI. If an extension needs an API
-key that isn't configured yet, tell the user what key is needed and where
-to get it. Never invent PAT-shaped values or store keys in extension HTML,
-`extensionData`, or examples.
-
-See the `secrets` skill for the full secrets API.
-
-## Sharing
-
-Use the framework sharing actions:
-
-```bash
-# Make an extension visible to the org
-pnpm action set-resource-visibility --resourceType=tool --resourceId=EXTENSION_ID --visibility=org
-
-# Share with a specific user
-pnpm action share-resource --resourceType=tool --resourceId=EXTENSION_ID --principalType=user --principalId=user@example.com --role=editor
-
-# List current shares
-pnpm action list-resource-shares --resourceType=tool --resourceId=EXTENSION_ID
-```
-
-> The `resourceType` value is still `tool` for back-compat with the
-> `tool_shares` table. The variable name `EXTENSION_ID` is the canonical
-> name for the value going into the call.
-
-See the `sharing` skill for visibility levels and roles.
-
-## Navigation
-
-```bash
-# Navigate to the extensions list
-pnpm action navigate --view=extensions
-
-# Navigate to a specific extension
-pnpm action navigate --view=extensions --extensionId=EXTENSION_ID
-
-# Or directly:
-set-url-path({ "pathname": "/extensions/EXTENSION_ID" })
-```
-
-## Routes
-
-| Method | Path                                                     | Purpose                                       |
-| ------ | -------------------------------------------------------- | --------------------------------------------- |
-| GET    | `/_agent-native/extensions`                              | List extensions (filtered by ownership/share) |
-| POST   | `/_agent-native/extensions`                              | Create an extension                           |
-| GET    | `/_agent-native/extensions/:id`                          | Get an extension                              |
-| PUT    | `/_agent-native/extensions/:id`                          | Update (supports `patches` for diffing)       |
-| DELETE | `/_agent-native/extensions/:id`                          | Delete an extension                           |
-| GET    | `/_agent-native/extensions/:id/render`                   | Render HTML for iframe                        |
-| POST   | `/_agent-native/extensions/proxy`                        | Authenticated proxy with secret injection     |
-| GET    | `/_agent-native/extensions/data/:id/:collection`         | List authenticated extension data             |
-| POST   | `/_agent-native/extensions/data/:id/:collection`         | Upsert authenticated extension data           |
-| DELETE | `/_agent-native/extensions/data/:id/:collection/:itemId` | Delete authenticated extension data           |
-
-## Database & API names — back-compat reference
-
-The rename from "tools" to "extensions" is mostly user-facing. Several
-under-the-hood names are kept to avoid breaking existing data and code:
-
-| Surface                           | Stays as             | Rationale                                                   |
-| --------------------------------- | -------------------- | ----------------------------------------------------------- |
-| SQL table for extensions          | `tools`              | Renaming a table = drop+create; data must not move          |
-| SQL table for per-ext data        | `tool_data`          | Same                                                        |
-| SQL table for ext shares          | `tool_shares`        | Same                                                        |
-| SQL table for ext history         | `tool_history`       | Same DB naming family                                       |
-| Drizzle schema export             | `extensions`         | Code-side rename — no data migration needed                 |
-| Drizzle schema export             | `extensionData`      | Same                                                        |
-| Drizzle schema export             | `extensionShares`    | Same                                                        |
-| Iframe global (legacy alias)      | `toolFetch`          | Kept so older extension bodies keep working                 |
-| Iframe global (legacy alias)      | `toolData`           | Same                                                        |
-| Iframe global (canonical)         | `extensionFetch`     | Use this in new extensions                                  |
-| Iframe global (canonical)         | `extensionData`      | Same                                                        |
-| `data-tool-layout` HTML attribute | unchanged            | Runtime contract; not worth churning                        |
-| `resourceType` for sharing        | `tool`               | Matches `tool_shares` table                                 |
-| Slot-system table                 | `tool_slots`         | Drizzle export is `extensionSlots` (see `extension-points`) |
-| Slot-installs table               | `tool_slot_installs` | Drizzle export is `extensionSlotInstalls`                   |

package/src/templates/workspace-core/.agents/skills/extensions/references/examples.md

@@ -1,259 +0,0 @@
-# Extension Examples
-
-Worked HTML examples for extensions. For the model + when-to-use overview, see
-`../SKILL.md`. For the full helper/global API tables, see `api.md`.
-
-## API Status Dashboard
-
-Checks the health of multiple endpoints and shows green/red status:
-
-```html
-<div
-  class="p-6"
-  x-data="{
-  endpoints: [
-    { name: 'API', url: 'https://api.example.com/health' },
-    { name: 'Auth', url: 'https://auth.example.com/health' },
-    { name: 'CDN', url: 'https://cdn.example.com/health' }
-  ],
-  results: [],
-  loading: true
-}"
-  x-init="
-  Promise.all(endpoints.map(ep =>
-    extensionFetch(ep.url).then(r => ({ ...ep, ok: r.ok })).catch(() => ({ ...ep, ok: false }))
-  )).then(r => { results = r; loading = false })
-"
->
-  <h2 class="text-lg font-bold mb-4">Service Status</h2>
-  <template x-if="loading"
-    ><p class="text-muted-foreground">Checking...</p></template
-  >
-  <div class="space-y-2">
-    <template x-for="r in results" :key="r.name">
-      <div class="flex items-center justify-between rounded-lg border p-3">
-        <span class="font-medium" x-text="r.name"></span>
-        <span
-          x-bind:class="r.ok ? 'text-green-600' : 'text-red-600'"
-          x-text="r.ok ? 'Healthy' : 'Down'"
-        ></span>
-      </div>
-    </template>
-  </div>
-</div>
-```
-
-## Weather Widget
-
-Fetches current weather for a city:
-
-```html
-<div
-  class="p-6"
-  x-data="{ city: 'San Francisco', weather: null, loading: false }"
-  x-init="
-  loading = true;
-  extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}')
-    .then(r => r.json()).then(d => { weather = d; loading = false })
-"
->
-  <div class="space-y-4">
-    <div class="flex gap-2">
-      <input
-        type="text"
-        x-model="city"
-        class="flex-1 rounded-md border bg-background px-3 py-2 text-sm"
-        placeholder="City name"
-      />
-      <button
-        x-on:click="loading = true; extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}').then(r => r.json()).then(d => { weather = d; loading = false })"
-        class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer"
-      >
-        Search
-      </button>
-    </div>
-    <template x-if="loading"
-      ><p class="text-muted-foreground">Loading...</p></template
-    >
-    <template x-if="weather && !loading">
-      <div class="rounded-lg border p-4">
-        <p
-          class="text-2xl font-bold"
-          x-text="weather.current.temp_f + '°F'"
-        ></p>
-        <p
-          class="text-muted-foreground"
-          x-text="weather.current.condition.text"
-        ></p>
-        <p
-          class="text-sm text-muted-foreground"
-          x-text="weather.location.name + ', ' + weather.location.region"
-        ></p>
-      </div>
-    </template>
-  </div>
-</div>
-```
-
-## Todo List (using extensionData)
-
-Full CRUD app using the built-in `extensionData` store — no SQL, no schema
-files, no actions. Data is automatically scoped per-extension and per-user:
-
-```html
-<div
-  class="p-6"
-  x-data="{
-  todos: [],
-  newTodo: '',
-  loading: true,
-  async init() {
-    const items = await extensionData.list('todos');
-    this.todos = items.map(i => ({ id: i.id, ...JSON.parse(i.data) }));
-    this.loading = false;
-  },
-  async addTodo() {
-    if (!this.newTodo.trim()) return;
-    const id = crypto.randomUUID();
-    const data = { title: this.newTodo.trim(), completed: false };
-    await extensionData.set('todos', id, data);
-    this.todos.unshift({ id, ...data });
-    this.newTodo = '';
-  },
-  async toggle(todo) {
-    todo.completed = !todo.completed;
-    await extensionData.set('todos', todo.id, { title: todo.title, completed: todo.completed });
-  },
-  async remove(id) {
-    await extensionData.remove('todos', id);
-    this.todos = this.todos.filter(t => t.id !== id);
-  }
-}"
->
-  <h2 class="text-lg font-semibold mb-4">Todo List</h2>
-  <div class="flex gap-2 mb-4">
-    <input
-      x-model="newTodo"
-      type="text"
-      placeholder="What needs to be done?"
-      class="flex-1 rounded-md border border-input bg-background px-3 py-2 text-sm"
-      @keydown.enter="addTodo()"
-    />
-    <button
-      @click="addTodo()"
-      class="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground cursor-pointer hover:bg-primary/90"
-    >
-      Add
-    </button>
-  </div>
-  <div x-show="loading" class="text-sm text-muted-foreground">Loading...</div>
-  <div class="space-y-2">
-    <template x-for="todo in todos" :key="todo.id">
-      <div class="flex items-center gap-3 rounded-md border p-3">
-        <button
-          @click="toggle(todo)"
-          class="cursor-pointer"
-          :class="todo.completed ? 'text-green-500' : 'text-muted-foreground'"
-        >
-          <svg
-            xmlns="http://www.w3.org/2000/svg"
-            width="18"
-            height="18"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-          >
-            <template x-if="todo.completed">
-              <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14M22 4 12 14.01l-3-3" />
-            </template>
-            <template x-if="!todo.completed">
-              <circle cx="12" cy="12" r="10" />
-            </template>
-          </svg>
-        </button>
-        <span
-          class="flex-1 text-sm"
-          :class="todo.completed && 'line-through text-muted-foreground'"
-          x-text="todo.title"
-        ></span>
-        <button
-          @click="remove(todo.id)"
-          class="text-muted-foreground hover:text-destructive cursor-pointer text-xs"
-        >
-          Remove
-        </button>
-      </div>
-    </template>
-  </div>
-  <p
-    x-show="!loading && todos.length === 0"
-    class="text-sm text-muted-foreground text-center py-8"
-  >
-    No todos yet. Add one above!
-  </p>
-</div>
-```
-
-## Quick Notes
-
-Persistent notes using localStorage -- no API key needed:
-
-```html
-<div
-  class="p-6"
-  x-data="{
-  notes: JSON.parse(localStorage.getItem('quick-notes') || '[]'),
-  draft: '',
-  save() {
-    if (!this.draft.trim()) return;
-    this.notes.unshift({ id: Date.now(), text: this.draft, date: new Date().toLocaleDateString() });
-    this.draft = '';
-    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
-  },
-  remove(id) {
-    this.notes = this.notes.filter(n => n.id !== id);
-    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
-  }
-}"
->
-  <div class="space-y-4">
-    <div class="flex gap-2">
-      <input
-        type="text"
-        x-model="draft"
-        x-on:keydown.enter="save()"
-        class="flex-1 rounded-md border bg-background px-3 py-2 text-sm"
-        placeholder="Add a note..."
-      />
-      <button
-        x-on:click="save()"
-        class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer"
-      >
-        Add
-      </button>
-    </div>
-    <div class="space-y-2">
-      <template x-for="note in notes" :key="note.id">
-        <div class="flex items-start justify-between rounded-lg border p-3">
-          <div>
-            <p class="text-sm" x-text="note.text"></p>
-            <p class="text-xs text-muted-foreground" x-text="note.date"></p>
-          </div>
-          <button
-            x-on:click="remove(note.id)"
-            class="text-muted-foreground hover:text-destructive text-sm cursor-pointer"
-          >
-            Remove
-          </button>
-        </div>
-      </template>
-      <template x-if="notes.length === 0">
-        <p class="text-sm text-muted-foreground">No notes yet.</p>
-      </template>
-    </div>
-  </div>
-</div>
-```