# Local Bridge and Qoder Cloud Runtime Design

Date: 2026-07-17

## Goal

Extend the existing runtime registry so Skill creation, evaluation, production runs, and API invocation can use either:

1. An online local CLI exposed through an outbound-only bridge.
2. Qoder Cloud Agent configured with only a PAT, Environment ID, and Agent ID.
3. The existing AgentRun runtime as a final fallback.

The existing Node backend direct local CLI execution remains available.

## User Experience

### Local bridge

The runtime settings page presents a guided connection card:

1. Generate a one-time pairing link.
2. Copy an install command.
3. Copy a connect command or open the pairing link.
4. See the host status change to online and its detected CLIs light up.

The host can be paused or revoked. Logged-in platform users can submit work to an online host but cannot view its credential.

### Qoder Cloud Agent

Selecting Qoder Cloud Agent shows only three required fields:

- PAT
- Environment ID
- Agent ID

The API base URL, session lifecycle, event endpoints, retry behavior, and streaming translation are built in. After a PAT is entered, the UI attempts to list available Agents and Environments for selection and retains manual ID entry as a fallback.

Saving or testing the runtime validates the PAT and confirms that the Agent and Environment exist and are accessible.

## Architecture

### Runtime priority

Runtime resolution is purpose-aware and follows this order unless a purpose-specific Agent explicitly selects a runtime:

1. Enabled online local runtime supporting the purpose.
2. Enabled and ready Qoder Cloud Agent.
3. Enabled and ready AgentRun.

An explicitly selected runtime is used when ready. If it is temporarily unavailable and fallback is enabled, the resolver continues through the priority list. Resolution returns both the chosen runtime and fallback reason so the UI and audit logs can explain the choice.

### Local bridge transport

The local bridge uses outbound HTTPS long polling rather than an inbound tunnel or a mandatory WebSocket service. This works behind NAT, does not expose a local port, and can run on the Cloudflare Lite deployment.

New persisted entities:

- `runtime_bridge_pairings`: short-lived one-time pairing codes.
- `runtime_bridge_hosts`: registered hosts, hashed host credentials, capabilities, status, and heartbeat.
- `runtime_bridge_jobs`: queued, claimed, running, completed, failed, canceled, or expired jobs.
- `runtime_bridge_events`: ordered progress and result events.

The local CLI exchanges a pairing code for a host credential, detects supported commands, sends heartbeats, claims one job at a time, executes it in an isolated temporary workspace, uploads normalized events and artifacts, and removes the workspace after completion.

The connector endpoints authenticate with a dedicated bearer credential. Platform task submission continues to use the existing user identity. Pairing codes expire quickly and are single-use; host credentials are only shown to the connector and are stored hashed on the server.

### Qoder Cloud transport

Qoder Cloud uses its REST API directly:

1. Create a Session with the configured Agent ID and Environment ID.
2. Send a `user.message` event containing the composed platform prompt.
3. Consume Session SSE events.
4. Translate status, text, tool, error, and completion events into the existing Skill run event contract.
5. Preserve the Qoder Session ID for a continued conversation when applicable.

The PAT is encrypted or protected using the same secret-storage boundary as existing runtime credentials and is never returned to the browser. UI responses expose only a masked preview and readiness flags.

## Execution Data Flow

For create, evaluate, or run requests, the backend composes the existing system Skill prompt, runtime Agent prompt, Skill package context, and user messages before selecting a runtime.

For a bridge runtime, the backend queues a normalized job. The bridge receives the payload, materializes package files in a temporary directory, invokes the selected local CLI adapter, and posts normalized events. The browser receives the same event types used by current runs.

For Qoder Cloud, the backend creates and drives a Qoder Session and translates its events directly. Cloud artifacts are surfaced when the API supplies downloadable file metadata; text-only runs remain fully supported.

## Error Handling and Fallback

- A host is considered offline when its heartbeat expires.
- Claimed jobs have a lease and can be returned to the queue when the lease expires.
- Pairing, host, and job credentials are rate-limited and audited.
- Qoder 401 and 403 responses mark configuration as invalid and require administrator action.
- Qoder 404 responses identify the missing Agent or Environment.
- Qoder 409 responses are retried only when the Session is temporarily busy.
- Qoder 429 and 5xx responses use bounded exponential backoff.
- Runtime unavailability before execution can trigger the configured fallback chain.
- A task that has already produced side effects does not automatically replay on another runtime.
- Users receive a clear selected-runtime label and a concise fallback or failure reason.

## Testing

Unit and contract tests cover:

- Runtime readiness and priority resolution.
- Secret masking and Qoder configuration validation.
- Qoder Session request construction and SSE event translation.
- Pairing expiry and one-time exchange.
- Host authentication, heartbeat, capability detection, job leasing, and completion.
- Local CLI adapter argument construction and event normalization.
- Cloudflare Lite and Node route parity.

End-to-end verification starts the local frontend, backend, and bridge, then runs one real local CLI task through the platform. Qoder is verified against a deterministic local mock server when live credentials are unavailable; with PAT, Environment ID, and Agent ID present, the same check runs against the real Qoder Cloud service.

## Scope Boundaries

The first release does not expose arbitrary inbound host ports, allow anonymous runtime use, synchronize an entire user filesystem, or automatically create Qoder Agents and Environments. It connects existing local CLIs and existing Qoder Cloud resources with the minimum configuration surface.
