An extension is a JavaScript module loaded by Salambo’s authenticated extension host inside the sandbox. It can register tools and subscribe to supported lifecycle events without executing customer code in the trusted worker.

​
1. Create the module

Create agent/extensions/support.mjs: 
export default function supportExtension(pi) {
  pi.registerTool({
    name: 'format_case_reference',
    label: 'Format case reference',
    description: 'Format a customer support case identifier.',
    parameters: {
      type: 'object',
      properties: {
        caseId: {
          type: 'string',
          description: 'The customer support case identifier.',
        },
      },
      required: ['caseId'],
      additionalProperties: false,
    },
    async execute(_toolCallId, { caseId }) {
      return {
        content: [
          {
            type: 'text',
            text: `CASE-${caseId.trim().toUpperCase()}`,
          },
        ],
      };
    },
  });
}
The default export receives the hosted pi API. Registration runs during manifest discovery and again when the sandbox extension host starts.

​
2. Declare the entrypoint

Add the relative path to salambo.yaml: 
extensions:
  - path: agent/extensions/support.mjs
    mode: auto
Paths must remain inside the project. Absolute paths and parent traversal are rejected. Use auto by default. Use eager only when the extension must load as soon as the sandbox runtime starts.

​
3. Activate the tool

If agent/settings.json contains an explicit tool list, include the new name: 
{
  "tools": ["read", "write", "format_case_reference"]
}
If the list is omitted, discovered extension tools are active by default.

​
4. Validate discovery

salambo manifest --path . --json
Inspect the compiled extension entry for:
  • the normalized entrypoint;
  • the tool name and description;
  • the JSON parameter schema;
  • the extension execution identifier.
manifest imports the module with a discovery API. It validates registrations but does not execute the real tool or lifecycle flow.

​
5. Deploy and execute it

salambo deploy
salambo smoke "Use format_case_reference for case 42 and return only the result."
Inspect the run’s Activity and Diagnostics views to confirm the extension tool call and result.

​
Important boundary

Use .mjs examples unless your own build step emits runnable JavaScript. Salambo does not currently publish a TypeScript extension SDK, so the documentation does not assume one. Next, learn the complete custom tool contract and then react to lifecycle events.