Core concepts
Use this glossary to identify the contract you need. Follow its link for a working example; you do not need to read every guide before starting.
Extension
Section titled “Extension”The installable unit: a directory with extension.json. Its directory name is
its id; name in the manifest is the display label. A tool pack, a skill pack,
a page, and an application use the same package and lifecycle.
An extension can contain UI (ui/index.tsx), Node code (main/activate.ts),
a headless entry (server), and declarative agents, skills, or MCP servers.
Create only the parts you use. Extension anatomy.
Manifest
Section titled “Manifest”extension.json declares contributions, permissions, entry points, and
activation events. Only name and a numeric MAJOR.MINOR.PATCH version are
required to load. compat.pluginApi is the compatibility range the loader
enforces.
The root and some contribution objects discard unknown fields; strict objects such as pages reject them. Do not assume a successfully parsed manifest means every key had an effect. Manifest reference.
App, and window ownership
Section titled “App, and window ownership”An app is an extension with a page whose presentation is app. On Desktop
that page opens in its own window. A docked page uses the main shell. In the
Cloud web workspace, eligible pages appear as panels; app does not create a
native window there. Pages and windows.
Contributions
Section titled “Contributions”Declarations that make your extension reachable: pages, slot views, commands,
agents, skills, settings, services, MCP servers, agent runtimes, and IPC
namespaces. A declaration does not replace an implementation: commands need
handlers, and tools are registered in code with ctx.api.tools.register.
A session.dock view joins the workbench. The shell owns layout and view
instances; your component receives session and workspace authority, visibility,
and its selected resource tab. Slot views.
Permissions and capabilities
Section titled “Permissions and capabilities”Some permissions withhold an API namespace (cron, process, auth.identity),
while others are primarily install-time disclosures (network, filesystem).
database is a legacy no-op retained so published 1.x manifests still parse;
the extension API has no hosted document store. ai also gates an ACP runtime’s
modelAccess: "host" credential.
Capabilities are a separate list for webview navigation, scripts, interception, and header rewriting. Extensions execute trusted JavaScript; these declarations are not a sandbox. Permissions.
The plugin API
Section titled “The plugin API”Node code receives ctx.api in activate(ctx). UI code imports pluginAPI
from @wamp/plugin-api. They have different members and signatures. Both can
use typed data, AI, and extension-owned tools; processes, cron, and service
registration belong to the Node half.
Use pluginAPI.ipc.invoke and subscribe to reach your Node half from either
Desktop or the Cloud web host. API guide ·
Signature reference.
Typed data
Section titled “Typed data”data.defineSchema(schema) opens an extension-owned SQLite store on the engine
machine. Both halves share the schema; collection calls are asynchronous.
Use q.gte, q.in, and the other query builders for comparisons. Plain objects
such as { gte: value } are not predicates.
For records that have to leave the machine, use your own backend. The extension API does not expose a remote document store. Typed data.
Named functions with JSON-Schema inputs. Names contain letters, numbers,
underscores, or hyphens; use a prefix such as notes_search. Registration does
not add a namespace for you.
Agent tools: lists are intended equipment, not a security boundary. Session
filters can narrow the model’s tool list using exact names or a trailing *.
Enforce sensitive operations at the tool’s own boundary.
Contributing tools.
Agents and skills
Section titled “Agents and skills”An agent definition combines a prompt, model selection, tools, and limits in
agents/<id>.md. A runtime contributes an external process speaking ACP.
Choose the definition to configure WAMP’s loop; choose a runtime to run a
different harness.
A skill is a portable directory containing SKILL.md plus optional resources.
The model sees routable skill descriptions and loads bodies when needed.
Extension skills have publisher-qualified identities; a short name is usable
only when it is unambiguous. Agents and skills.
An engine run records one execution and its outcome, usage, and child runs.
An extension has no multi-turn session primitive of its own: pluginAPI.ai
is one-shot (the extension keeps its own history and resends it), and
pluginAPI.agents.delegate runs a configured agent — with its own tool
loop — to completion in one call. The plugin API.
Cloud’s HTTP Session, Turn, and Run resources are a separate integration contract. Use the Cloud documentation when calling that API.
Products
Section titled “Products”product.json configures a branded Desktop build: name, app id, icons, bundled
extensions, update feed, and optional root page. Every branded Desktop uses
WAMP sign-in; identity is not a product-file option. Your extension artifact
stays the same. Branded product.
Where to go next
Section titled “Where to go next”Quickstart gets a page running. Choosing a path separates extensions, branded builds, and HTTP integrations.