Browse documentation

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.

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)`	Register a model-callable sandbox tool
`on(event, handler)`	Subscribe to a supported lifecycle event
`getActiveTools()`, `getAllTools()`	Read the hosted tool selection
`setActiveTools(names)`	Select the active tools
`setModel(selection)`	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.

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.

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 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:

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.

PreviousComing from Pi

Up nextExtension compatibility