Extensions

Extensions add capabilities to an ECP (Execution Control Protocol) environment: model providers, formats, memory, secrets, and more.

Catalog and bind

Extension packages should call catalogExtension(def) at module load so string ids resolve:

import "@executioncontrolprotocol/format-toon"
import { extension } from "@executioncontrolprotocol/node"

extension("@executioncontrolprotocol/format-toon").with({})

Prefer npm package name === extension id (for example @executioncontrolprotocol/format-toon). ensureBoundExtensionsRegistered() runs automatically before encode, decode, describe, and run when using the core environment path — you typically do not need a separate register step for cataloged packages.

Definitions vs invocations

Layer	API
Define	`defineExtension(ns, name).withCapabilities([...]).build()`
Catalog	`catalogExtension(def)` on package load
Bind	`extension("@scope/name").with({…})` in an environment
Invoke	`step("@scope/name.capability", "Label").with({…})`

Custom extension

Capability bodies are inline TypeScript handlers via .withHandler(...):

import {
  defineExtension,
  capabilityFor,
  catalogExtension,
} from "@executioncontrolprotocol/core"
import { z } from "zod"

export const myExtension = defineExtension("@vendor", "my-ext")
  .withConfig({ apiKey: z.string().optional() })
  .withCapabilities([
    capabilityFor("@vendor/my-ext", "do-thing")
      .withInput(z.object({ value: z.string() }))
      .withOutput(z.object({ result: z.string() }))
      .withHandler(async (input) => ({ result: input.value })),
  ])
  .build()

catalogExtension(myExtension)

Bind with extension("@vendor/my-ext").with({}), then invoke with step("@vendor/my-ext.do-thing", "Label").with({ value: "hi" }).

Package boundaries

Extensions depend on @executioncontrolprotocol/types and @executioncontrolprotocol/core (plus focused third-party libs). They must not import:

@executioncontrolprotocol/node
@executioncontrolprotocol/browser
@executioncontrolprotocol/cli
@executioncontrolprotocol/mcp

Hosts wrap core; extensions stay portable.

Browser vs Node package graphs

Capability execution (local | host | mixed) is not a bundler export name. Those names describe where a step runs after dispatch. If the Node implementation imports native modules or Node-only SDKs (sharp, @azure/storage-blob, node:fs), ship a standard exports condition so web bundlers never see that graph:

".": {
  "types": "./dist/index.d.ts",
  "browser": "./dist/index.browser.js",
  "node": "./dist/index.js",
  "import": "./dist/index.js"
}

browser and node are bundler/Node conditions (Vite, webpack, Rollup, Node). Apps import the package root only:

import "@executioncontrolprotocol/image-sharp"

Do not import index.browser by path. Vite selects exports["."].browser automatically.

Execution	Browser graph
`host`	Catalog (ids, schemas, execution). Handlers may throw; dispatch hops to `ecp up`.
`mixed`	Catalog plus tab-safe handlers (for example Azure PUT). No native SDK.
`local`	Full handlers that are safe in the tab (formats, Chrome AI, HTTP+secrets).

Media refs (images and binaries)

Workflows pass portable ImageRef values (buffer | file | url | artifact), not raw bytes. Extensions resolve and write through core:

import { resolveFile, writeMediaArtifact } from "@executioncontrolprotocol/core"

const { bytes, mediaType } = await resolveFile(input.image, ctx)
// …domain processing (Sharp, upload, generate)…
return { image: await writeMediaArtifact(outBytes, { mediaType, prefix: "artifacts/images" }, ctx) }

file.path may be a Node path or an ecp://browser/<id> locator in ctx.blobs. Do not reimplement fs/fetch/artifact maps inside the extension.

First-party and vendor

Protocol/platform extensions live in the ECP monorepo (formats, providers such as Ollama and Chrome AI, memory, secrets, …). Vendor integrations (fal, Slack, image-sharp, Adobe, …) ship from the sibling extensions repository. In-repo testing stub:

import "@executioncontrolprotocol/core/testing"
extension("@executioncontrolprotocol/test").with({})

Getting started

Learn

Build

Alternatives

AI tools

Reference

Extensions

Extensions

Catalog and bind

Definitions vs invocations

Custom extension

Package boundaries

Browser vs Node package graphs

Media refs (images and binaries)

First-party and vendor

Next steps

​Extensions

​Catalog and bind

​Definitions vs invocations

​Custom extension

​Package boundaries

​Browser vs Node package graphs

​Media refs (images and binaries)

​First-party and vendor

​Next steps

Extensions

Catalog and bind

Definitions vs invocations

Custom extension

Package boundaries

Browser vs Node package graphs

Media refs (images and binaries)

First-party and vendor

Next steps