Browse documentation
The pi object
Reference for the API passed to a hosted Salambo extension.
View MarkdownEvery hosted extension exports a default function receiving pi:
import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
export default function extension(pi: ExtensionAPI) {
// Register tools and lifecycle handlers here.
}Depot compiles the module without executing it. The default factory executes once when the sandbox extension host starts. Keep factory registration deterministic. 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 lifecycle handler. They are not available while the factory is registering the extension.
Methods
| Method | Purpose |
|---|---|
registerTool(tool) | Register a model-callable sandbox tool |
on(event, handler) | Subscribe to a hosted lifecycle event |
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 |
getActiveTools(), getAllTools(), setActiveTools() | Read or change the hosted tool selection |
setModel(selection) | Select an allowed model |
getThinkingLevel() and setThinkingLevel() | Read or change the hosted thinking level |
registerProvider() and unregisterProvider() | Manage a declarative, session-scoped provider configuration |
events | Communicate between extensions in the same hosted session |
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.
The runtime handler context exposes bounded session, model, tool, usage, prompt, cancellation, and external-event state. It does not expose worker memory, persistence clients, or sealed provider credentials. See external event context and the generated compatibility profile for exact fields.
TypeScript and JavaScript
Use .ts with a type-only import from @earendil-works/pi-coding-agent@0.83, or deploy an ESM .js or .mjs entrypoint. Depot transpiles TypeScript and preserves source maps. It does not replace your project TypeScript check.