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