36 lines
2.0 KiB
Markdown
36 lines
2.0 KiB
Markdown
# 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.
|