@agent-native/core 0.14.8 → 0.15.1

package/src/templates/workspace-core/.agents/skills/extension-points/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: extension-points
+description: >-
+  How extensions render as widgets inside other apps via named UI slots — the
+  framework's VS-Code-style extension system. Use when a user asks to add a
+  custom widget to an app surface (e.g. "add a sticky-note widget to my mail
+  contact sidebar"), when wiring an ExtensionSlot in a template, or when
+  marking an extension as installable into a slot.
+---
+
+# Extension Points
+
+> **Terminology note.** "Extensions" in this doc are the framework's
+> sandboxed Alpine.js mini-app primitive (see the `extensions` skill).
+> They are NOT LLM "tools" (function calls). The slot-system tables are
+> still physically named `tool_slots` and `tool_slot_installs` for
+> back-compat — see the table at the bottom of this doc and the
+> "Database & API names" section in the `extensions` skill.
+
+## Mental model
+
+**Slots** are named React-shaped holes in apps. **Extensions** are widgets
+that opt into filling those holes. The framework matches them up by string
+ID.
+
+Three primitives:
+
+| Primitive            | What it is                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| **Slot**             | `<ExtensionSlot id="..." context={...} />` dropped into an app's JSX                            |
+| **Slot target**      | A row saying "extension X can render in slot Y" — `tool_slots` table (Drizzle: `extensionSlots`) |
+| **Slot install**     | A row saying "user U wants extension X in slot Y" — `tool_slot_installs` (Drizzle: `extensionSlotInstalls`) |
+
+When `<ExtensionSlot>` renders, it queries the user's installs and mounts
+one `<EmbeddedTool>` (a small auto-sized iframe) per install, pushing the
+slot's context into each via postMessage. (The component is still exported
+as `EmbeddedTool` for back-compat.)
+
+## Slot ID convention
+
+`<app>.<area>.<position>` — three dot-separated lowercase-kebab segments.
+
+- `mail.contact-sidebar.bottom`
+- `mail.thread-toolbar.actions`
+- `clips.right-panel.tabs`
+- `calendar.event-detail.bottom`
+
+Stable strings. Renaming a slot is a data migration — same as renaming a
+route.
+
+## How to author an extension that fills a slot
+
+1. **Create the extension** with `create-extension`. The HTML can read
+   `window.slotContext` to get the host's context (the contact email,
+   recording id, etc.) and subscribe to changes via
+   `window.onSlotContext(fn)`.
+
+   ```html
+   <div
+     x-data="{ contact: null }"
+     x-init="contact = window.slotContext; window.onSlotContext(c => contact = c)"
+   >
+     <template x-if="contact">
+       <div class="rounded-lg border p-4 m-4">
+         <p class="text-sm">
+           Notes for <span x-text="contact.contactEmail"></span>
+         </p>
+       </div>
+     </template>
+   </div>
+   ```
+
+2. **Declare the slot target** with `add-extension-slot-target`:
+
+   ```
+   add-extension-slot-target { extensionId: "<id>", slotId: "mail.contact-sidebar.bottom" }
+   ```
+
+3. **Install it** for the current user with `install-extension`:
+
+   ```
+   install-extension { extensionId: "<id>", slotId: "mail.contact-sidebar.bottom" }
+   ```
+
+The slot will pick up the install on its next render (≤2s via polling sync,
+immediate after the action's UI invalidation).
+
+## How to declare a slot in your app
+
+Drop `<ExtensionSlot>` wherever you want to allow extensions:
+
+```tsx
+import { ExtensionSlot } from "@agent-native/core/client/extensions";
+
+// inside your component
+<ExtensionSlot
+  id="mail.contact-sidebar.bottom"
+  context={{ contactEmail: contact.email, contactName: contact.name }}
+  showEmptyAffordance
+/>;
+```
+
+> The legacy import path `@agent-native/core/client/tools` continues to
+> re-export the same component for back-compat with existing templates.
+
+Props:
+
+- `id` — slot identifier. Must match what extensions target.
+- `context` — object pushed to each embedded extension as `slotContext`. Re-pushed
+  whenever this prop changes.
+- `showEmptyAffordance` — when true, shows a "+ Add widget" button in the
+  empty state. Default: false (slot renders nothing when empty).
+- `className` / `toolClassName` — optional styling hooks. (The `toolClassName`
+  prop name is kept for back-compat; it styles the embedded extension's
+  iframe wrapper.)
+
+The host doesn't register slots in advance — `<ExtensionSlot>` is the
+declaration. If an extension targets a slot ID that no app has placed, it
+just won't render anywhere (the install record is harmless).
+
+## Context contract
+
+Each slot publishes whatever shape it wants via the `context` prop. There's
+no schema enforcement in v1 — extensions should null-check fields and fail
+gracefully if a field they expect is missing.
+
+Document the context shape next to your `<ExtensionSlot>` so extension
+authors know what to read. Convention: include the document in the slot
+ID's prefix section so the agent can find it (`mail.contact-sidebar.*`
+slots all publish `{ contactEmail, contactName }`).
+
+## Agent actions
+
+| Action                       | What it does                                                            |
+| ---------------------------- | ----------------------------------------------------------------------- |
+| `add-extension-slot-target`  | Mark an extension as installable into a slot (extension author opts in) |
+| `install-extension`          | Install an extension into a slot for the current user                   |
+| `uninstall-extension`        | Remove an extension from a slot for the current user                    |
+| `list-extensions-for-slot`   | List installable extensions for a given slot ID                         |
+| `list-extension-slots`       | List slot targets an extension declares                                 |
+
+Typical flow when a user asks "add a CRM widget below my contacts":
+
+1. `list-extensions-for-slot { slotId: "mail.contact-sidebar.bottom" }` —
+   see what's already installable
+2. If a fitting extension exists: `install-extension`
+3. Otherwise: `create-extension` → `add-extension-slot-target` →
+   `install-extension`
+
+## Lifecycle
+
+**Mount** — host calls the slot installs API, renders an `<iframe>` per
+install. The iframe URL includes `?slot=<slotId>` so the runtime knows it's
+embedded (enables auto-resize, suppresses anything that only makes sense
+full-page).
+
+**Context push** — host posts `agent-native-slot-context` immediately on
+iframe load, and again on every prop change. The extension reads the
+current value synchronously via `window.slotContext` and subscribes via
+`window.onSlotContext(fn)` for live updates.
+
+**Auto-resize** — when in slot mode, the iframe runtime measures its
+content height and posts `agent-native-tool-resize` (postMessage type kept
+for back-compat) to the host. The `<EmbeddedTool>` sets the iframe height
+accordingly. Use `ResizeObserver` to follow content changes.
+
+**Extension API** — embedded extensions have the full helper set:
+`appAction`, `appFetch`, `dbQuery`, `dbExec`, `extensionFetch`,
+`extensionData` (with `toolFetch` / `toolData` legacy aliases). Same auth
+context as full-page extensions.
+
+**Unmount** — uninstall deletes the install row. Polling sync invalidates
+the `slot-installs` query and the host re-renders without the iframe.
+
+## Permissions
+
+- Installing requires viewer access to the extension. A user can only
+  install extensions they have access to.
+- Declaring slot targets requires editor access to the extension.
+- Slot installs are per-user — installing a widget only affects the
+  installing user's view. There's no org-wide "default install" in v1.
+- Slots themselves are ungated. Any app code can drop an `<ExtensionSlot>`
+  in any user's view; the slot's contents come from that user's installs.
+
+## What this is NOT
+
+- **Not a way to render arbitrary React in slots.** Slots only render
+  Alpine.js iframe extensions. Same security/auth/sandbox as
+  `/extensions/:id`.
+- **Not cross-extension messaging.** Two extensions in the same slot can't
+  read each other's `extensionData`. Use actions or app SQL if widgets need
+  to coordinate.
+- **Not a slot manifest.** Slot targets live in the `tool_slots` table
+  (Drizzle export `extensionSlots`), not in the extension's HTML content.
+  The agent can re-target an extension without rewriting it.
+- **Not for arbitrary code modification.** If a user wants to change how
+  the app itself behaves (not add a sandboxed widget), use the
+  `self-modifying-code` skill instead.
+
+## Cross-references
+
+- `extensions` skill — authoring Alpine.js mini-apps (the substrate for widgets)
+- `sharing` skill — how access flows from extension sharing to slot installs
+- `context-awareness` skill — how extensions read what the user is looking at
+- `actions` skill — how `install-extension` etc. are auto-mounted