# 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.
- `plugin-lifecycle.request`: request a server-bound install, enable, disable, upgrade, rollback, retire, or dependency-check operation through Platform capacity and compatibility gates.
- `ai.invoke`: request platform-mediated AI assistance.
- `theme.tokens`: read safe platform theme tokens.
- `game-client-bridge`: query declared bridge snapshots, and queue or cancel only manifest-declared typed commands through Platform.

## 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 manifest-declared purpose, prompt, and scoped context refs. Use `parseAIInvocationResponse` to consume recommendations, optional `configExecution` job metadata, and safe errors. For config purposes Platform validates the current config and dispatches the bounded `config.write` job immediately; plugin code must not choose or receive provider API keys, provider base URLs, bearer tokens, or direct transport details.

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.

SQLite reads use manifest-declared `gameClientBridge.queryTemplates`. Plugin pages send only a declared template key plus typed inputs; Platform verifies the page contract, permission, SQLite transport/target, timeout, and row limit before dispatch. Query declarations and browser envelopes never contain SQL text, DSNs, credentials, sockets, or host paths.

Run distribution, dependency, and log backfill requests use `createRunDistributionRequest`, `createDependencyActionRequest`, and `createLogBackfillRequest`. These envelopes carry only operation names, logical profile keys, target platforms, artifact IDs, approved dependency plan digests, cursors, and idempotency keys. Raw run keys, component sessions, secret refs, host paths, PIDs, sockets, credentials, and direct Run endpoint details are never plugin bridge fields.

Game-client plugin pages receive a host-provided `GameClientBridgePageClient`. The SDK defines status, command, result, snapshot, approval, and manifest declaration types but never creates its own HTTP client. Queue requests carry only a declared command type, logical profile key, bounded typed payload, expiry, priority, and idempotency key. A command may declare a protected `sql`, `rcon`, or management-program request: the plugin supplies only its one bounded text field and logical transport/target keys; Platform authorizes, approves, queues, and forwards it to Run without inspecting or redacting plugin-owned request/result text. A management program is not host OS shell access. Transport envelope fields intentionally have no component session, component key, installation fence, Run endpoint, direct socket, or storage credential access; plugin-owned payload/result fields pass through unchanged inside those envelopes.

Production plugin lifecycle requests use `createProductionPluginLifecycleRequest`. Envelopes contain only plugin/server scope, enumerated operation, optional target version, confirmation, and idempotency key. Platform rechecks the manifest `productionLifecycle` declaration, dependency policy, disruptive approval, endpoint capacity, compatibility, and prior idempotency inputs before dispatch.

## 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.