# The extension API

Reference for the API object passed to a hosted Salambo extension.

Every hosted extension exports a default factory that receives the extension API. The parameter name is yours; these pages use `agent`.

```ts
import type { ExtensionAPI } from '@salambo-ai/agent';

export default function extension(agent: ExtensionAPI) {
  agent.on('before_agent_start', () => {
    agent.setActiveTools(['read', 'bash']);
  });
}
```

Depot compiles the module without executing it. The factory executes once when the sandbox extension host starts. Keep registration deterministic, and perform network calls and mutable workspace work inside tools or lifecycle handlers. Read session-dependent values such as active tools or thinking level inside a tool or handler; they are not available while the factory registers.

## Methods

| Method                                                                 | Hosted purpose                                            |
| ---------------------------------------------------------------------- | --------------------------------------------------------- |
| [`registerTool(tool)`](/docs/reference/extensions/register-tool)       | Register a model-callable sandbox tool                    |
| [`on(event, handler)`](/docs/reference/extensions/on)                  | Subscribe to a supported lifecycle event                  |
| `getActiveTools()`, `getAllTools()`                                    | Read the hosted tool selection                            |
| [`setActiveTools(names)`](/docs/reference/extensions/set-active-tools) | Select the active tools                                   |
| [`setModel(selection)`](/docs/reference/extensions/set-model)          | Select an allowed model                                   |
| `getThinkingLevel()` and `setThinkingLevel()`                          | Read or change the thinking level                         |
| `registerProvider()` and `unregisterProvider()`                        | Declarative provider registration during initialization   |
| `sendMessage()` and `sendUserMessage()`                                | Persist a custom message or queue hosted user input       |
| `appendEntry()`, `setSessionName()`, `getSessionName()`                | Persist and read hosted session state                     |
| `exec()`                                                               | Run a bounded command through Salambo's sandbox authority |
| `events.on()`, `events.emit()`                                         | Communicate between extensions in the same hosted session |

`salambo dev` supports a smaller list; provider, session-writing and command-execution methods are refused there. See [local execution](/docs/agent-development/local-validation).

## Not available on Salambo

The `session_info_changed` hook, `ctx.ui.notify()` and `ctx.ui.setStatus()` are not available on Salambo. The deploy's build refuses the hook, and any `notify` or `setStatus` call it can see, naming the file and line; a call it can't see fails the tool during a Turn, and the Turn still completes. See the [compatibility reference](/docs/reference/extensions/compatibility).

## Context boundary

Tools and hook handlers run inside the sandbox extension host. They can use projected agent resources and the mutable agent workspace. They do not execute in trusted worker memory, and the types do not grant access to storage clients, sealed credentials or the full worker context.

The runtime context also carries bounded integration metadata (`external`, `inputOrigins`) that the current `ExtensionContext` type does not declare. For ordinary input these are null or empty. The examples in these pages use only the typed surface; see [external event context](/docs/integrations/external-context) for the integration fields.

## Package exports

`@salambo-ai/agent` exposes its root entry point only; do not import undocumented subpaths. Its runtime helpers are `defineTool`, `isToolCallEventType`, `formatSize`, `DEFAULT_MAX_LINES` and `DEFAULT_MAX_BYTES`. Install it with its `typebox` peer for types:

```bash
pnpm add -D @salambo-ai/agent typebox@1.3.27 typescript
```

Depot transpiles TypeScript and preserves source maps. It does not replace your project's TypeScript check. ESM `.js` and `.mjs` entry points are also accepted.

Which capabilities have hosted behavior, and which are accepted without effect, is listed in the [compatibility reference](/docs/reference/extensions/compatibility).