46 lines
3.4 KiB
Markdown
46 lines
3.4 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.
|
|
- `remote.access.request`: request plugin-declared FTP, rsync, or run-mediated remote operations through platform jobs.
|
|
- `run.distribution.request`: request platform-mediated run package generation, download, key reset, or self-update orchestration.
|
|
- `dependencies.request`: request typed dependency checks or approved install plans declared by the plugin runtime profile.
|
|
- `logs.backfill.request`: request historical log backfill for a declared log source.
|
|
- `client-manager.request`: request generation, download, or key reset for a plugin-declared companion client manager.
|
|
- `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.
|
|
|
|
Remote access requests use `createRemoteAccessRequest` with a plugin-declared `remote.*` capability, logical target key, optional scoped `input://` or `artifact://` ref, and idempotency key. The SDK never accepts FTP passwords, rsync endpoints, database DSNs, RCON passwords, run sockets, or raw host paths in these envelopes.
|
|
|
|
Run distribution, dependency, log backfill, and client-manager requests use `createRunDistributionRequest`, `createDependencyActionRequest`, `createLogBackfillRequest`, and `createClientManagerRequest`. These helpers carry operation names, logical profile keys, target OS/architecture, artifact IDs, cursors, and idempotency keys only; raw run keys and client-manager keys are written only into generated packages by platform services.
|
|
|
|
## 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.
|
|
- FTP, rsync, database, or RCON credentials.
|