browser/plugins/sdk/bridge-contract.md

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/key reset or a typed status, deploy, start, stop, restart, update, rollback, session-revoke, retry, or uninstall operation for a plugin-declared companion client manager.
• 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 companion health and 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, reviewable diffId metadata, and safe errors. Plugin code must not choose or receive provider API keys, provider base URLs, bearer tokens, or direct transport details. Config writes require a separate Platform operator approval.

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, log backfill, and client-manager requests use createRunDistributionRequest, createDependencyActionRequest, createLogBackfillRequest, and createClientManagerRequest. Client-manager lifecycle envelopes carry only operation names, logical profile/installation IDs, target OS/architecture, artifact IDs, expected deployment generations, and idempotency keys. parseClientManagerLifecycleStatus whitelists safe state, version, health, job, artifact, and action fields. Raw run/client-manager keys, component sessions, secret refs, host paths, PIDs, sockets, credentials, and direct Run endpoint details are never plugin bridge fields.

Client-manager lifecycle requests remain Platform-mediated. A plugin declaration does not grant access by itself: Platform rechecks the installed plugin, server owner/administrator scope, runtime binding, assigned Run endpoint capabilities, current distribution target/revision/key generation, and durable installation state before dispatching a typed job.

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, redacts, queues, and forwards it to Run. A management program is not host OS shell access. Browser-facing types intentionally have no component session, component key, installation fence, host path, DSN, Run endpoint, socket, or storage credential fields.

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.

Client Manager lifecycle bridge

The bridge may request typed deploy, start, stop, restart, status, update, rollback, revoke, retry, or uninstall intents when Platform action gating says they are available. Results are safe logical projections with real job phase/progress and redacted recovery guidance. The bridge is not a transport for Run sessions, component keys, artifact bytes, machine paths, process IDs, sockets, or credentials; component registration and heartbeat remain component-to-Platform contracts outside the plugin page.