2.0 KiB
Plugin Bridge Contract
Plugins use the platform bridge for every privileged action.
Allowed Bridge Areas
server.instances: read current server instance context.jobs.dispatch: request platform-authorized run jobs.logs.query: query historical logs by server, stream, time range, cursor, or analysis window.artifacts.open: request platform-mediated artifact download references.files.request: request scoped file list/read/patch/replace operations through platform jobs.ai.invoke: request platform-mediated AI assistance.theme.tokens: read safe platform theme tokens.
Execution Envelopes
Plugin pages build execution requests with createBridgeExecutionRequest and hand them to the host-provided bridge transport. The SDK never owns fetch, platform authorization headers, run sockets, or provider credentials.
Execution responses use requestId, plugin/page/server scope, action, status, optional result refs, and optional safe errors. Use parseBridgeExecutionResponse before reading results so plugin code handles denied, deferred, and failed states uniformly.
AI requests use createAIInvocationRequest with an explicit purpose, prompt, scoped context refs, and optional current config. Use parseAIInvocationResponse to consume recommendations and safe errors. Plugin code must not include provider API keys, provider base URLs, bearer tokens, or direct transport details in AI request payloads.
Artifact open requests use createArtifactOpenRequest with an artifact ID that belongs to the current server/job scope. Use parseArtifactReference to consume the bridge result. Parsed references contain platform-owned download URLs, filename, content type, size, checksum, expiry, range support, and chunk size; they do not contain bytes or raw storage adapter locations.
Forbidden Data
The bridge must not expose:
- raw run credentials.
- raw host paths.
- AI provider API keys.
- platform auth storage.
- storage backend endpoints.
- unrestricted artifact storage credentials.
- direct storage URLs or presigned backend URLs.