Extension SDK

An Extension is code that runs in its own background process. Cowork loads its entry file and calls activate(api) once. Everything the Extension can do goes through that api object, and through the ctx objects Cowork hands to what it registers. This chapter lists every module and function.

Release status

Functions marked Not yet released are in Cowork's source but not in a released version yet.

Modules

Module	Functions	Needs
Entry and Registration	activate(api) · api.registerConnector · api.registerService · api.log	—
Connector	start(ctx) · stop() · send(reply) · ctx.emit · ctx.log	— (in 0.1.41: listed in connectors)
Background Tasks	run(ctx) · ctx.status · ctx.log · ctx.readJson · ctx.writeJson · ctx.env · ctx.dataDir · ctx.signal	capability service
Site Requests	ctx.site.request · ctx.site.session	service + sites
Service Conversations	ctx.agent.handoff	service + agent
Browser	ctx.browser.adoptTab · releaseTab · evaluate · inject · uninject · captureAudio · stopAudio · onEvent	capability browser (audio for sound)

package.json

This example uses service and sites, which are not released yet; on 0.1.41 it is refused.

{
  "name": "janeapp-operator",
  "version": "0.1.0",
  "pi": { "extensions": ["./index.mjs"] },
  "dozin": {
    "capabilities": ["service"],
    "sites": [{ "host": "welladjustedhk.janeapp.com", "methods": ["GET"], "pathPrefixes": ["/admin/api/v2/"], "minIntervalMs": 1000 }]
  }
}

Field	Description
name	Lowercase letters, digits and hyphens; equals the folder name
version	The version shown in Settings › Extensions. Required in 0.1.41; from the next version it defaults to 0.0.0
pi.extensions	Exactly one entry file. Required in 0.1.41. Not yet released: may be left out, then main is used, else the first of index.mjs, index.js, index.ts
dozin.connectors	IDs of the Connectors it registers. When listed, only these ids can register. In 0.1.41 a Connector can register only if its id is listed here
dozin.capabilities	browser, audio (needs browser), platform-gate-v1, and service Not yet released
dozin.origins	With browser: 1 to 20 exact websites (https://example.com) it may use. Required with browser in 0.1.41; from the next version it may be left out, and then any http(s) site is allowed, still only in tabs the person hands over
dozin.platforms	darwin-arm64, darwin-x64, win32-x64; needs exactly one platform-gate-v1 in capabilities
dozin.secrets Not yet released	With service: up to 8 values the person fills in, { env, label }; env matches ^[A-Z][A-Z0-9_]{0,63}$
dozin.sites Not yet released	With service: up to 8 sites for ctx.site, { host, methods, pathPrefixes, minIntervalMs }
dozin.agent Not yet released	With service: { brief, model?, tools?, secret? } for service conversations

The type name is DozinAPI in both Cowork and Dozin, so one Extension installs unchanged in either.

Rules that apply to every module

• Nothing runs until a person approves the exact files in Settings › Extensions. Changing one file means approving again.
• A package has at most 200 files and 5 MB; dependencies are not installed.
• An Extension cannot read cookies, tokens or other extensions' data.

Related

• Extension What an Extension is and how it goes live
• Mini App SDK What the Mini App of the same package can call
• Extensions settings Install, approve and switch on