Skip to content
OpenWaggle

Extension manifest reference

Every field, limit, capability, and rule of an OpenWaggle extension's openwaggle.extension.json manifest and SDK.

This page lists the fields of openwaggle.extension.json, what OpenWaggle checks before an extension runs, and the SDK capabilities an extension may call. To build your first extension, see Build an extension. The generated @openwaggle/extension-sdk API reference lists every exported type.

Manifest fields

FieldTypeRequiredDefaultWhat it does
$schemaURLNoThe manifest’s JSON Schema, for editor completion. OpenWaggle ignores it
manifestVersion1YesManifest format version
idstringYesPackage id, the same as the package folder’s name. See Limits
namestringYesDisplay name
versionsemver stringYesPackage version, raised with each update
descriptionstringNoShort description
sdk.openwagglesemver rangeYesVersions of OpenWaggle’s extension API the package works with, such as ">=0.1.0 <0.2.0". This isn’t the @openwaggle/extension-sdk npm version
sourceFilespathsYesEvery source file in the package
builtArtifactspathsYesEvery built file OpenWaggle loads, local build outputs included
install.sourceprebuilt or local-buildNoprebuiltWhether the package ships built files or builds on the user’s machine
build.commandstringWith local-buildCommand that builds the package, run in the package folder
build.outputspathsNobuiltArtifactsFiles the build writes
docs.topicslistNoDocs the package ships. See Docs topics
network.originslist of originsNoExternal origins the package may reach, each an exact HTTPS origin with no path, such as https://api.github.com
capabilitieslistNoSDK capabilities, methods, and scopes. See Capabilities
contributionsobjectNoContributions by family. See Contribution families
pi.resourceRootspathsNoFolders of Pi resources (skills, extensions, prompts, themes) the package adds, loaded ahead of .pi
trusted.mainpathNoTrusted local code that runs in the main process
trusted.rendererpathWith trusted-renderer contributionsPrivileged renderer code, which every contribution with runtime: "trusted-renderer" needs
runtimeRequirementslistNoPrograms the package needs. See Runtime requirements

Paths are relative to the package folder.

Check a manifest

The manifest’s JSON Schema is at https://openwaggle.ai/schemas/openwaggle-extension-manifest-v1.schema.json. It checks field types, lengths, allowed values and string formats such as ids, versions, paths and origins. It differs from OpenWaggle’s own check in three ways:

  • It allows keys the manifest format doesn’t declare. OpenWaggle ignores them.
  • It accepts a few network origins that OpenWaggle refuses, ones the URL parser would rewrite, such as a port above 65535 or a port with a leading zero.
  • It doesn’t check rules that span fields, such as a declared capability for each contribution’s methods or trusted.renderer for a trusted-renderer contribution.

validateExtensionManifest from @openwaggle/extension-sdk/validation runs every check OpenWaggle runs on the manifest’s contents when it loads the package. It never throws, and returns one of:

ResultFields
Validsuccess: true, and value, the manifest
Invalidsuccess: false, and issues, a list of { path, message }

path is the field’s dotted path, with list items by index, such as contributions.sidePanels.0.icon. It is (root) for a problem with the whole manifest. OpenWaggle’s diagnostics use the same paths.

Runtime requirements

Each entry in runtimeRequirements names one program the package needs. OpenWaggle checks for it and shows an error on the package card when it is missing. It never installs a missing program.

FieldRequiredWhat it does
idYesRequirement id inside the package
labelYesName shown in the error, at most 120 characters
binaryOne of binary or commandA program name, such as git, looked up on PATH. A name, not a path
commandOne of binary or commandA file inside the package, relative to the package folder
kindNobinary or command, matching the field you set

Limits

ValueLimit
Package id96 lowercase letters, digits, ., _, and -, starting with a letter or digit
Contribution id128 characters. Lowercase letters, digits, ., _, /, and -
name, title, label, badge, category120 characters
description, row value, state message2,000 characters
A relative path260 characters
A network origin300 characters, https only, with no path, query, fragment or trailing slash
A runtime requirement binary120 characters
build.command500 characters
Build time10 minutes
Build log keptThe last 4,000 characters
Storage key160 characters
Side panel SVG icon32 KiB

Package folders

ScopeFolder
Project<project>/.openwaggle/extensions/<extension-id>/
Globalextensions/<extension-id>/ in the app data folder

The package files can be committed with a project. Trust, enablement, permission grants, build approvals, project opt-outs, lifecycle records, and extension storage stay on the user’s machine.

Contribution families

FamilyWhere it appearsHas an entry module
settingsSectionsSettings > Extensions, under Extension settingsYes
sidePanelsThe right sidebar, opened from the Panel rail or All panelsYes
dialogsA modal OpenWaggle drawsYes
routesA route container inside OpenWaggleYes
transcriptRenderersThe chat transcript, for Pi session recordsYes
toolRenderersThe card of a Pi tool call and its resultYes
customMessageRenderersPi custom message recordsYes
interactionRenderersA pending Pi questionYes
statusWidgetsA small status displayYes
commandsThe slash command menu and launchers next to the composerNo
slashCommandsThe slash command menu and launchers next to the composerNo
sessionSummarySectionsThe floating Session Summary. OpenWaggle draws the rowsNo

Contribution fields

Contributions with an entry module take these fields:

FieldValuesWhat it does
idstringContribution id, unique within the package
titlestringTitle OpenWaggle shows
runtimefederated-module or trusted-rendererHow the module loads. Both mount in the sandboxed extension frame and get the same SDK
executionhost-renderer or frameWhere it runs. A trusted-renderer contribution must use host-renderer
entrypathThe module that exports mount(context)
target.projectPaths, target.sessionIdslistsLimits the contribution to these projects or sessions
matches.toolNameslistPi tool names a renderer draws
matches.customMessageNameslistPi custom message types a renderer draws
matches.interactionKindslistStandard question kinds, or a custom question’s customType
capabilitycapability idThe capability the contribution calls
method, methodsmethod idsThe methods of that capability it calls
iconLucide name or { "svg": "<path>" }Side panels only. See Side panel icons

commands and slashCommands take id, title, an optional category, target, capability, and method or methods, with no entry.

A package that registers contributions at run time must declare the openwaggle.runtime capability with register-contribution, unregister-contribution, or both, and must list each family it registers in contributions, even as an empty array.

Side panel icons

FormExampleRules
Lucide name"ticket", "git-pull-request"A kebab-case Lucide name, checked against the Lucide version OpenWaggle ships
SVG file{ "svg": "assets/panel-icon.svg" }A path relative to the package folder, ending in .svg, at most 260 characters

An SVG path may not start with / or \, name a drive, have an empty, . or .. segment, have leading or trailing whitespace, or hold a NUL byte.

OpenWaggle reads an SVG icon once for each installed version of the package content and keeps only its shapes, painted in the rail’s colors:

  • It rejects a file with <script> or <foreignObject> elements, characters XML does not allow, or no shapes left after cleaning.
  • It drops <style> elements, style and class attributes, event handlers, external href references, embedded images, and attribute values that name any resource other than a url(#id) inside the file.
  • The file counts toward the package’s content hash.
  • A side panel registered at run time may use a Lucide name, or an SVG file that a side panel in the manifest already declares. Any other SVG file fails, as does an icon that does not match the schema.
  • A missing or unusable icon shows a letter tile with the first letter of the title, and a panel-icon-invalid warning under the contribution registry diagnostics in Settings > Extensions.

Session Summary sections

FieldValuesDefaultWhat it does
idstringSection id
titlestringSection title
placementcontext, coordination, detailsdetailsWhere the section goes. See below
targetprojectPaths, sessionIdsLimits the section to these projects or sessions
disclosure.defaultExpandedbooleanWhether the section starts expanded
disclosure.collapsiblebooleanWhether it can collapse
disclosure.autoCollapseAfterMs1,000 to 300,000Collapses the section after this many milliseconds
state.statusready, loading, live, failureThe section’s state. See below
state.messagestringA message, required for failure and optional for loading and live
rowslistThe rows, below

placement decides where the section goes. context comes after Environment, Actions, Scheduled, workspace setup, and pull or merge request details, before Hive. coordination comes after Hive, before Outputs and Sources. details comes last, after Sources.

OpenWaggle hides an empty ready section. A loading, live or failure section stays visible without rows.

Row fieldValuesWhat it does
idstringRow id
labelstringRow label
valuestringText value
badgestringBadge text
countwhole number, 0 or moreA count
resourceIdresource idOpens a resource published with openWaggle.resources. Cannot go with action
action.familycommands, sidePanels, dialogsFamily of the target contribution, in the same package
action.contributionIdcontribution idThe target contribution. A command also needs a capability and method

OpenWaggle rejects a section whose action target is missing, has the wrong family, is not eligible, or is out of scope, and reports a contribution diagnostic. See Add to the Session Summary for how sections behave.

Capabilities

A capability declaration has an id, the methods the package may call, and the scopes it may call them in: app, project, session, or branch. Calls outside the declaration fail.

CapabilityMethodsSDK calls
openwaggle.host.contextget-scopehostContext.getScope(scope)
openwaggle.storageget, set, delete, liststorage.packageState.global, storage.packageState.project, storage.packageConfig.global, storage.packageConfig.project, each with get, set, delete, and list
openwaggle.stateget-state, read-stateopenWaggle.state.get, readCurrentProject, readCurrentSession, readCurrentBranch, readRecentProjects, readModelPreferences
openwaggle.actionsselect-projectopenWaggle.actions.selectProject(scope, projectPath)
openwaggle.settingsget-settings, update-settings, get-setting, update-settingopenWaggle.settings.get, update, getModelPreferences, updateModelPreferences, getProjectDisplayName, setProjectDisplayName
openwaggle.docsdiscover-docs, resolve-docs-topicopenWaggle.docs.discover(scope, input), openWaggle.docs.resolveTopic(scope, input)
openwaggle.runtimeregister-contribution, unregister-contributionruntime.registerContribution(scope, registration), runtime.unregisterContribution(scope, unregistration)
openwaggle.resourceslist-resources, publish-resourceopenWaggle.resources.list(scope, { limit, cursor }), openWaggle.resources.publish(scope, resource), in session scope

Notes on some calls:

  • The state selectors are current-project, current-session, current-branch, recent-projects, and model-preferences. The settings keys are model-preferences and project-display-name.
  • Model preferences report Pi’s global default thinking level as thinkingLevel. An update cannot set it, because the thinking level belongs to each session and only the user changes it.
  • Runtime registrations use the manifest’s schemas. They cannot add capabilities, methods, or scopes, and cannot replace or remove a manifest contribution. Project and session registrations stay in the scope that made them. Registering the same family, id, and scope again replaces the earlier one. Branch scope fails.
  • resources.publish accepts image and link resources with credential-free HTTPS locators, in the source or output role. Publishing the same key, kind, role, and locator again changes nothing. resources.list takes a limit from 1 to 100 and returns value.resources (display details only), value.total (the exact session total), and value.nextCursor. Both reach only the mounted contribution’s project and session.

Failure codes

A rejected call returns one of these codes:

CodeMeaning
invalid-inputThe call’s input is malformed
invalid-payloadThe payload does not match the schema
unknown-extensionNo such extension
disabled-extensionThe extension is not enabled
unknown-contributionNo such contribution
undeclared-capabilityThe manifest does not declare the capability
undeclared-methodThe manifest does not declare the method
undeclared-scopeThe manifest does not declare the scope
out-of-scopeThe call names a project or session outside the contribution’s scope
unsupported-capabilityThis OpenWaggle does not have the capability
unsupported-methodThis OpenWaggle does not have the method
transport-failedThe call did not reach OpenWaggle

Mount context

FieldWhat it holds
context.rootThe element the contribution adds its content to
context.extensionThe package’s id, name, and version
context.contributionThe contribution’s id, title, and family
context.surfaceThe surface’s family, execution, and payload. The payload carries the surface’s data, such as the transcript record, tool event, or pending question
context.packagePathThe package folder
context.sessionId, context.projectPathsThe session and projects the contribution is mounted for
context.sdkThe SDK calls above, plus sdk.surface.sendAction, sdk.surface.respondInteraction, and sdk.surface.syntax.highlight
context.themeTheme tokens with CSS-variable-shaped values for color, typography, spacing, radius, focus, and shadow
context.modulesThe shared author modules for the installed SDK version

mount(context) may return a cleanup function, which OpenWaggle calls when it unmounts the contribution.

Interaction kinds

KindOpenWaggle’s fallback
confirmA confirmation, recorded in the transcript
selectA choice, recorded in the transcript
inputA short text field, recorded in the transcript
editorA multiline editor, recorded in the transcript
notifyA notification or status, recorded in the transcript when relevant
customNone. A renderer whose matches.interactionKinds names the customType draws it. Without one, OpenWaggle shows an unsupported-question fallback with a reject button

A renderer answers with sdk.surface.respondInteraction(response). A standard kind’s answer must match its public schema, such as { "kind": "confirm", "accepted": true }. A custom kind’s answer is passed back as its result. OpenWaggle checks every answer against the pending question before returning it to Pi.

Event data

Renderers receive OpenWaggle’s public event data, never Pi package types or OpenWaggle internals. It keeps these Pi details:

  • tool name
  • custom message type
  • tool call id
  • interaction id
  • input parameters
  • partial and final result state
  • structured details
  • error state
  • session and project

Readiness checks

A contribution is in the contribution registry, and can appear, only when all of these hold:

  • The manifest matches the schema.
  • Every referenced file exists.
  • The SDK range is compatible with the installed OpenWaggle.
  • The content hash matches the trusted record.
  • A required local build was approved and succeeded.
  • The extension is trusted.
  • The extension is enabled.
  • The extension was reloaded after its last trust, enable, build, or update change.
  • The current project has not opted out.

It is mounted once the iframe has loaded the module and mount(context) has resolved.

Permissions

The trust review shows each of these:

PermissionDeclared byWhat it allows
Trusted visual modulesfederated-module entriesRun in OpenWaggle’s contribution containers after trust, enabling, and reload
Trusted renderertrusted.rendererReviewed as privileged. trusted-renderer entries still mount in the sandboxed extension frame
Trusted local main codetrusted.mainCode that runs in the main process. Needs explicit trust
Network accessnetwork.originsExternal origins the package may reach. Origins not declared are not approved
Build scriptinstall.source: "local-build" and build.commandRuns local code at build time. Approved separately from trust
Runtime requirementsruntimeRequirementsPrograms the package needs. A missing one blocks trust or use until it is installed
SDK capabilitiescapabilitiesThe capabilities, methods, and scopes above
Session resourcesopenwaggle.resourcesListing and publishing credential-free HTTPS links and images in session scope. Never exposes stored bytes or private locators

Trust records the package’s content hash. Editing the manifest, source files, built files, or build plan changes the hash, and the change becomes an update the user must approve.

How OpenWaggle enforces them in version 1:

  • Frame-mounted visual contributions run in a sandboxed iframe, with a CSP that limits network connect-src to network.origins.
  • Trusted main-process code gets only the public SDK. While the module activates and cleans up, and in the callbacks it registers, OpenWaggle guards direct fetch, node:http, node:https, electron.net, raw node:net, raw node:tls, UDP sockets, direct DNS lookups, node:http2, WebSocket, child processes, cluster forks, and worker threads, however the module imports them. It allows only the exact HTTPS origins in network.origins. The guard does not follow redirects, and a target it cannot resolve fails. It rejects custom fetch agents, dispatchers and proxies, custom Node HTTP agents, connection factories, and DNS lookup functions, Unix socket paths, raw sockets, and ways out of the process or isolate.
  • The guard runs in the same process as the extension, so it is not a sandbox. Trust a package only if you trust its code. Code can still reach the network through native code (a native addon). It can also change a shared object so that OpenWaggle’s own code makes a request later. The guard does not stop the module from listening for incoming connections.
  • Trusted renderer code mounts in a frame. Importing it straight into the app’s renderer is not supported, so it uses the SDK and mount context like any other contribution.

Docs topics

Each entry in docs.topics has:

FieldRequiredWhat it does
idYesTopic id inside the package
titleYesTopic title
pathYesThe Markdown file, relative to the package folder
descriptionNoShort description
aliasesNoOther names readers search for
keywordsNoSearch keywords

Docs lookup

openWaggle.docs.discover and openWaggle.docs.resolveTopic return a topic’s details, not its content. The openwaggle_docs tool’s list and search actions return the same details, and its read action returns the topic’s Markdown. A first-party topic looks like this:

{
  topic: 'openwaggle:extending/openwaggle-extensions',
  source: 'openwaggle',
  group: 'OpenWaggle Docs',
  title: 'Build an extension',
  path: '/path/to/openwaggle/docs/extending/openwaggle-extensions.md',
  bundlePath: 'topics/openwaggle/extending/openwaggle-extensions.md',
  sourcePath: 'website/src/content/docs/extending/openwaggle-extensions.md',
  aliases: ['tool renderers', 'transcript cards'],
  keywords: ['ctx.ui.confirm', 'Pi tools', 'custom interaction'],
  contentHash: 'sha256...'
}

First-party topics are a fixed, typed set, so generated indexes and SDK calls can be checked. An extension topic sits in the extension’s namespace, carries where it came from, and cannot replace an OpenWaggle or Pi topic:

{
  topic: 'extension:openwaggle-github-issues-overview/configuration',
  localTopic: 'configuration',
  provenance: {
    extensionId: 'openwaggle-github-issues-overview',
    trust: 'trusted',
    lifecycle: 'enabled'
  }
}

The docs index lists extension topics whatever their trust or lifecycle state. The openwaggle_docs tool includes only the docs of extensions the session’s runs load, and reads a file only while it is still inside the package and matches the hash recorded at discovery.

What needs an OpenWaggle update

You can ship these without an OpenWaggle update:

  • New or changed contributions in existing families.
  • New or updated federated-module entries that still export mount(context).
  • Assets, CSS, package docs, and built files declared in the manifest.
  • Pi tools, custom messages, resource folders, and runtime behavior that Pi supports and the package declares.
  • More use of SDK capabilities, methods, and scopes the installed SDK already has.
  • Package storage keys and package configuration.
  • UI code that uses the existing optional SDK, theme, and UI helpers and still mounts through mount(context).
  • Added or removed network origins, local build commands, or runtime requirements, after the user approves them.

These need an OpenWaggle update:

  • A new contribution family, or a new surface or container in the app.
  • A visual runtime other than federated-module.
  • An execution placement other than the supported ones.
  • A new SDK capability, method, scope, data shape, action, or settings schema.
  • A new shared SDK, theme, or UI helper that OpenWaggle must supply instead of the extension bundling it.
  • A new fallback renderer for a standard question kind.
  • A new Pi question type that OpenWaggle must understand in the desktop app.
  • Changes to how trust works, which folders OpenWaggle searches for packages, how the content hash is calculated, network approval, CSP or protocol behavior, or build approval.
  • A change to how the packaged app is distributed, such as shipping a first-party extension, or changing how the installed OpenWaggle and Pi docs are generated.

If the installed app reports sdk.openwaggle as incompatible, changing the extension’s code cannot fix it. Target the installed SDK range, or update OpenWaggle.