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