# Extension compatibility

What the hosted runtime runs, accepts without effect, refuses, or doesn't make available.

Compatibility has three separate checks: the package's exports and types, the build and profile admission, and the actual runtime wiring. Passing one does not prove the other two.

## Typed surface

The guides use `ExtensionAPI`, `defineTool`, TypeBox schemas, and the `before_agent_start`, `tool_call` and `tool_result` hooks. Model selection uses `{ provider, id }`; tool selection returns `void`.

## Hosted only

Declarative custom providers, session-writing actions, bounded `exec`, provider hooks and compaction work in hosted deployments. Their presence in the package types does not make them part of `salambo dev`, which refuses them by name instead of approximating them. See [local execution](/docs/agent-development/local-validation).

## Accepted without effect

Command, shortcut and renderer registration, and noninteractive UI calls (except `notify` and `setStatus`, listed below as not available), are accepted without producing a terminal interface. Flag defaults and the empty command catalogue are kept for compatibility.

## Refused

`before_provider_headers` is refused at deploy. CommonJS extension entry points, native add-ons, blocked install scripts and imports that `@salambo-ai/agent` does not export can fail the build.

## Not available on Salambo

| Capability                  | On Salambo                                                                                                                                         |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_info_changed` hook | Not available on Salambo. The deploy's build refuses it, naming the file and line.                                                                 |
| `ctx.ui.notify()`           | Not available on Salambo. During a Turn the call fails the tool with `ctx.ui.notify isn't available on Salambo.`, and the Turn still completes.    |
| `ctx.ui.setStatus()`        | Not available on Salambo. During a Turn the call fails the tool with `ctx.ui.setStatus isn't available on Salambo.`, and the Turn still completes. |

The build also refuses the `ctx.ui.notify()` and `ctx.ui.setStatus()` calls it can see in the source, naming the file and line; a call it cannot see, such as one through a variable, fails during the Turn as above, and the extension can catch the error. If a `session_info_changed` registration reaches a Turn anyway, it fails the extension's start (`extension_registration_failed`, naming the extension) with `session_info_changed isn't available on Salambo.`

The runtime context also carries bounded integration metadata, `external` and `inputOrigins`, that the `ExtensionContext` type does not declare. They are null or empty for ordinary input. TypeScript code that reads them needs its own type; see [external event context](/docs/integrations/external-context).

## Older hook names

Register `model_select` and `thinking_level_select`. The older update names are not part of the typed surface.

See the [extension API](/docs/reference/extensions/extension-api), the [migration guide](/docs/guides/coming-from-pi) and [credits](/docs/credits).