reborn-extension-surfaces

---
name: reborn-extension-surfaces
description: Use when adding or changing a Reborn integration — a new extension, a channel surface, model-callable tools, or a shared auth provider — or when deciding whether something is "a channel", "an extension", or "a tool". Maps the unified extension model (NEA-25) to the exact manifest sections, crates, seams, and tests.
---

# Reborn Extension Surfaces

The top-level product object is always an **extension**. A channel is not a
sibling product type: it is one **capability surface** an extension's manifest
declares, exactly like tools and auth. Runtime (`wasm` / `mcp` /
`first_party`) is implementation only and never taxonomy. The retired
vocabulary (connectable channels, `slack_bot`, `slack_personal`, extension
`kind` strings) is pinned at zero by
`crates/app/ironclaw_architecture_tests/tests/reborn_retired_taxonomy.rs` — if your
change trips that gate, you are re-introducing a deleted model.

**Schema is `reborn.extension_manifest.v3`** — v2 plus explicit `[channel]`
and `[auth.*]` sections. The design is law: `docs/internal/reborn/extension-runtime/`
(`overview.md` §3 the manifest, §4 the adapters, §5 the flows, §6 lifecycle).
The worked example for *every* section below is the live Slack manifest —
read it first: `crates/extensions/packages/slack/manifest.toml`.

## The model in one diagram

```text
extension  (one manifest.toml, one installed identity, e.g. `slack`)
  [[tools]]              → tool surfaces (model-callable), each with [[tools.credentials]]
  [channel]             → channel surface (AT MOST ONE per extension; inbound/outbound)
  [auth.<vendor>]       → auth surface: one recipe per vendor (oauth2_code | api_key)
  [mcp]                 → hosted-MCP extension: discovered tools INSTEAD of [runtime]+[[tools]]
  [runtime] first_party|wasm|mcp   → how the adapter LOADS (implementation only, never taxonomy)
```

- `ExtensionId` (`slack`, `github`, `gmail`) — product/installed identity.
- `VendorId` (`slack`, `github`, `google`) — credential authority; several
  extensions may share one (gmail + google-drive + calendar + … share
  `google`). The manifest field is `vendor = "..."`. It is **not** the
  extension id. (Renamed from `ProviderId`/`RuntimeCredentialAccountProviderId`
  in this train — overview §2; stored id strings are unchanged.)
- `CapabilitySurfaceKind` (`crates/contracts/ironclaw_extension_contracts/src/surface.rs`) — `tool`,
  `channel`, `auth` (+ reserved `trigger`, `file`).
- Surfaces are **derived** from the resolved manifest — never store a parallel
  taxonomy. The manifest compiles **once** per install into a typed
  `ResolvedExtensionManifest` (+ `manifest_digest`); all production projection
  reads the resolved record, never re-parsed TOML (overview §3.3).

Adapters implement **behavior only** (overview §4): they never report ids,
schemas, effects, scopes, routes, or credentials — the resolved manifest is the
sole authority. Trait homes:
`ToolAdapter` — `crates/contracts/ironclaw_extension_contracts/src/tool_adapter.rs`;
`ChannelIngress`/`ChannelDelivery` — `crates/contracts/ironclaw_extension_contracts/src/channel_adapter.rs`;
`ReplySink` — `crates/contracts/ironclaw_extension_contracts/src/reply.rs`;
`ExtensionEntrypoint`/`ExtensionBindings` —
`crates/extensions/ironclaw_extension_host/src/entrypoint.rs`. Auth has **no** adapter
trait — it is one host engine driving manifest recipes (overview §4.3).

## Where a bundled package lives

Every first-party integration is a self-contained package:
`crates/extensions/packages/<id>/` (manifest + schemas +
prompts + any WASM) beside one module
`crates/extensions/ironclaw_extension_support/src/packages/<id>.rs` (embeds via
`include_str!`/`include_bytes!`, onboarding copy, trust effects). A collector
concatenates them; add a line to `PACKAGES` in `.../src/packages/mod.rs`.
Composition and the CLI consume these as **opaque bundles** and never name a
package (overview §3). Do NOT register assets in composition — the old
`available_extensions.rs::*_assets()` home (now `crates/extensions/ironclaw_extension_host/src/available_extensions.rs`) is being dissolved.
Re-verify the module list: `grep -n 'ID,' crates/extensions/ironclaw_extension_support/src/packages/mod.rs`.

## Adding a tool surface

1. Declare each capability as a `[[tools]]` entry (id, description, effects,
   default_permission, visibility, `input_schema_ref`, optional
   `prompt_doc_ref`) with a `[[tools.credentials]]` block naming its `vendor`,
   `audience`, and `injection`. Copy the plain schema-declaring shape from
   `crates/extensions/packages/github/manifest.toml`; for `standard_op`-bound
   messaging tools the exemplar is
   `crates/extensions/packages/slack/manifest.toml`, whose tools are all
   standard-op-bound (count entries with `grep -c '^\[\[tools\]\]'
   <manifest>` rather than trusting a written number).
2. Schemas and prompt docs are **package assets** (`schemas/…`, `prompts/…`)
   embedded by the package module — not composition.
3. Model-visible tool wording is product surface: if a tool acts *as the user*
   (delegated authority), its description and prompt doc must say so — and must
   say the tool is for side effects inside a job, never for delivering the final
   answer (the host delivers final replies on the outbound channel surface —
   overview §5.4). Exemplar: `crates/extensions/packages/slack/prompts/slack/send_message.md`.
4. A **messaging-shaped** tool (send/read/react over a conversation) binds
   `standard_op = "<op_name>"` instead of declaring its own schemas — a
   closed, host-owned vocabulary with host-canonical input/output schemas.
   See `docs/internal/reborn/extension-runtime/standard-operations.md` for the full
   vocabulary and binding rules.

## Adding a channel surface

1. Add a `[channel]` section (**at most one per extension**) with `id`,
   `display_name`, `inbound`/`outbound` bools, and **required**
   `conversation_model` (`continuous` | `isolated`, overview §3). Then its
   subsections, all worked in `crates/extensions/packages/slack/manifest.toml`:
   `[channel.ingress]` (route_suffix, method, body limit),
   `[channel.ingress.verification]` (declarative recipe the *host* executes —
   `hmac_sha256` segment list or `shared_secret_header`; signing secrets never
   reach the adapter), `[channel.connection]` (connection strategy),
   `[[channel.egress]]` (host allowlist + credential handle), and
   `[channel.presentation]`. Operator/deployment setup fields are a separate
   top-level `[admin_configuration]` section (there is no `[channel.config]`);
   the host renders the generic form from it.
2. Direction is the `inbound`/`outbound` bools, which project to
   `channel { inbound, outbound }` on the extensions wire. A run's own final
   reply is never an agent decision — it rides the runtime-owned delivery
   coordinator automatically (lane 1, overview §5.4). The agent DOES get one
   generic, host-built-in tool for reaching any other target explicitly,
   `builtin.outbound_deliver` (lane 2) — it is not a per-channel tool an
   extension declares.
3. Behavior lives in the extension's channel adapter: `ChannelIngress::receive`
   (parse → normalized outcome), `ChannelDelivery::deliver` (render+send a
   discrete message), and — for a declared `[channel.reply]` — one
   `ReplySink::reconcile` (`crates/contracts/ironclaw_extension_contracts/src/reply.rs`)
   that converges the vendor's presentation onto the run's reply document
   (`transport = "stream"` hears every revision, `"message"` the terminal
   one; the host publishes, the sink renders; verify with
   `rg -n "impl ReplySink for" crates/extensions/packages`) — see each trait
   doc for the method contract. Vendor-side webhook wiring is manifest data,
   not adapter code: the `[channel.ingress.registration]` /
   `[channel.ingress.deregistration]` recipes the host executes (worked
   example: `rg -n "channel.ingress.registration" crates/extensions/packages/telegram/manifest.toml`).
   Additional activation-time vendor calls (e.g. registering a native command
   menu) are `[[channel.ingress.activation_calls]]` /
   `[[channel.ingress.deactivation_calls]]` recipes — never per-vendor host
   code (worked example: Telegram's `setMyCommands` in the same manifest).
   The binary
   supplies the adapter to composition through the
   `RebornHostBindings::with_channel_extension_bindings` seam
   (`crates/app/ironclaw_composition/src/input.rs`, `ChannelExtensionBinding`);
   composition iterates it by `extension_id` and never names a concrete crate.
4. Conversation/actor binding is **data, not per-channel code**: the
   `conversation_model` value + the identity resolver drive it. Contract:
   `docs/internal/reborn/contracts/conversation-binding.md`. The actor→user resolver is
   `ProviderIdentityActorResolver`
   (`crates/extensions/ironclaw_extension_host/src/provider_identity.rs`, re-exported by
   composition),
   parameterized by (vendor, adapter id, actor kind) — not a per-channel
   resolver (the retired-taxonomy gate hunts the old pattern).
5. Connect affordance is **derived** (overview §6.4): installation state +
   `[admin_configuration]` completeness + the auth account state. The WebUI channels
   tab renders every channel surface with the same generic components — there is
   no channel registry to update (frontend helpers:
   `crates/product/ironclaw_webui/frontend/src/pages/extensions/lib/extensions-schema.ts`,
   `hasChannelSurface`). Editing `[channel.connection]` while `Active` runs an
   automatic deactivate → reactivate cycle; there is no separate reconfigure
   state or channel-setup activation gate.

## Adding / sharing an auth provider

1. Add one `[auth.<vendor>]` recipe per vendor the extension needs — the
   section key **is** the vendor id. `method = "oauth2_code"` (endpoints,
   `scope_param`, PKCE, `client_credentials` handles, `[auth.<vendor>].token_response`
   + `[auth.<vendor>].identity` JSON-pointer maps) or `method = "api_key"` (form
   `fields` + optional `validation` probe). Worked example: `[auth.slack]` in
   `crates/extensions/packages/slack/manifest.toml`; the full recipe vocabulary is overview §4.3 +
   implementation.md §7. There is **no auth adapter trait and no extension code
   in an auth flow** — the host engine (`crates/domains/ironclaw_auth`) runs each method
   once over the recipe data.
2. Share a `vendor` across extensions when the credential authority is the same
   (`google` across gmail/drive/calendar/docs/sheets/slides). Recipes for one
   vendor must be identical except `scopes`/`display_name`, or activation fails
   with a conflict; scopes union across active extensions (overview §3.2).
3. Renaming any persisted identity (vendor id, extension id) requires a one-time
   forward data migration, never a runtime alias. There is currently **no
   in-tree migration exemplar**: the retired-identity boot migration this skill
   used to cite was deleted 2026-08-04 by owner ruling, and its identifiers
   (`RETIRED_SLACK_USER_EXTENSION_ID`, `remove_retired_internal_installation`)
   are now on the banned list in
   `crates/app/ironclaw_architecture_tests/tests/reborn_retired_taxonomy.rs` — do not
   reintroduce them. The behavioral pin is
   `restore_special_cases_no_extension_id_and_leaves_every_uncatalogued_row_intact`
   (`crates/extensions/ironclaw_extension_host/tests/lifecycle_restore_contract.rs`):
   boot restore must leave uncatalogued rows intact, never delete or re-key
   them.

## Hosted-MCP extensions

An extension whose tools are discovered from a server declares one `[mcp]`
section (server, namespace, max_tools, effects, `[[mcp.credentials]]`) **instead
of** `[runtime]` (and normally instead of `[[tools]]` + `[channel]`), plus its
`[auth.<vendor>]` recipe. A hosted-MCP package MAY additionally pin static
`[[tools]]` entries beside `[mcp]` — guaranteed model-visible from first boot
and on the bundled-manifest fallback; a successful `tools/list` discovery
replaces the static set with the server's live catalog (worked example:
`nearai.web_search` in `crates/extensions/packages/nearai-mcp/manifest.toml`).
The MCP loader owns discovery; past activation a discovered tool is an ordinary
tool surface (overview §3.1). Worked example:
`crates/extensions/packages/notion-mcp/manifest.toml`.

## Testing surfaces

- Manifest projection (v3): `crates/extensions/ironclaw_extension_registry/tests/manifest_v3_contract.rs`;
  channel ingestion through the real contract:
  `crates/extensions/ironclaw_extension_registry/tests/product_adapter_manifest_ingestion.rs`
  (drives `parse_product_adapter_manifest_record` in
  `crates/extensions/ironclaw_extension_registry/src/host_api/product_adapter.rs`). Extend
  these rather than adding parallel suites.
- Adapter behavior: the exported conformance suites — channel in
  `crates/contracts/ironclaw_extension_contracts/src/test_support/conformance.rs`
  (`run_channel_adapter_conformance`, consumed by
  `crates/extensions/packages/{slack,telegram}/tests/channel_conformance.rs`),
  standard-messaging schema conformance in
  `crates/contracts/ironclaw_host_api/src/test_support/messaging_conformance.rs`, and auth
  in `crates/domains/ironclaw_auth/src/test_support/conformance.rs`. Run by every
  applicable extension crate + the `acme`
  fixture (`tests/fixtures/extensions/acme-messenger/`). Real extensions add one
  end-to-end integration proof each (`tests/integration/`).
- Frontend: `pnpm --dir crates/product/ironclaw_webui/frontend test`.
- Always finish with `cargo test -p ironclaw_architecture_tests` — the specificity,
  dependency-direction, and retired-taxonomy gates are the machine reviewers.
  Generic code naming your extension trips
  `reborn_extension_specificity.rs`: put the name in the package/CLI, not
  generic crates.

## Sibling skills

`reborn-feature` (wiring a feature through the layers) ·
`ironclaw-reborn-architecture-review` (boundaries) ·
`ironclaw-reborn-testing` (tiers).

More agent context in nearai/ironclaw

28 other files this repository gives its agents.