Extend the SDK or add a capability

A new privileged operation should be bounded, reusable, and justified by an actual plugin need. Existing capabilities should be preferred when they can express the feature.

Specify the operation

Define the user action, capability, serializable input/output, validation rules, resource limits, cancellation behavior, and ownership lifetime. Identify whether it needs a trusted host interaction.

Avoid APIs that accept arbitrary JavaScript, expose credentials, return host DOM objects, or grant general transport for a narrow task.

Implement across boundaries

Update the public PluginAPI and supporting types, shared contracts/schemas, sandbox client mapping, host capability checks, and the responsible generic service. Add main-process validation when data crosses that boundary.

Do not add a plugin-specific method or third-party hostname to core. Plugins own feature UI, selectors, and URL construction.

Verify denial as well as success

Test absent grants, malformed input, wrong-instance handles, expired context, cancellation, shutdown, resource exhaustion, and late results. Add a public-SDK example and update the manifest/capability documentation.

Run contract generation, schema/runtime tests, architecture checks, SDK example typechecks, and the external-plugin fixture. A new API should work from a separately packaged plugin without private imports.

An actual breaking API change needs its own compatibility and migration decision; this beta documentation change does not alter the SDK.