docs(agent): streamline guidance and skills

Keep always-on instructions concise and route specialized work through focused skills. Split large skills into progressive references and add dedicated change, desktop, sync, and performance guidance.
2026-07-14 00:45:44 +03:00
parent b36afbf5ee
commit 68f1c1efe3
20 changed files with 1257 additions and 1371 deletions
@@ -0,0 +1,46 @@
+# Browser Assets And URL Authentication
+
+## Choose By Request Owner
+
+| Request shape | Correct path |
+|---|---|
+| UI can fetch a small authenticated asset | `runtimeFetch`, read `blob()`, render an object URL |
+| Browser must own a URL (`iframe`, download/open link, large/raw image, rewritten subresource) | `getRuntimeUrlResolver().authenticatedAsset(...)` |
+| SSE | `getRuntimeUrlResolver().sse(...)` and owning transport |
+| WebSocket | `getRuntimeUrlResolver().websocket(...)` plus `openRuntimeWebSocket` where required |
+
+Do not prebuild a browser URL and then immediately call `runtimeFetch` with it. Ordinary HTTP callers pass route paths to `runtimeFetch`; browser/realtime consumers use resolver URLs.
+
+## Object URLs
+
+- Key caches by runtime identity, entity ID, update/version, and render options.
+- Bound caches by count and bytes when values can be large.
+- Revoke evicted object URLs with `URL.revokeObjectURL`.
+- Render a deterministic fallback while loading or after display-only failure.
+
+## URL Tokens
+
+Browser-owned URLs cannot attach the normal `Authorization` header. Use short-lived scoped `oc_url_token` minted through runtime auth helpers.
+
+- Never manually append `oc_url_token`.
+- Never place a long-lived client bearer token in a URL.
+- Treat `oc_client_token` query use as legacy stripping/rejection only.
+- Add browser-readable GET or realtime paths to the narrow allowlist in `packages/web/server/lib/ui-auth/ui-auth.js`.
+- Add allowlist tests; never allow arbitrary `/api/*` URL-token access.
+
+## Preview Iframes And Rewritten Resources
+
+- Use preview proxy helpers so preview and URL tokens propagate to rewritten resources and redirects.
+- Strip legacy client-token query parameters before forwarding upstream.
+- Do not use `postMessage('*')`; target the known preview origin.
+- Preserve CSP where possible. If injecting a bridge, prefer a per-response nonce and remove only directives that block framing or the bridge.
+- Re-resolve browser URLs after runtime switches; do not retain URLs minted for an old runtime.
+
+## Security Tests
+
+Prefer focused coverage in:
+
+- `packages/ui/src/lib/runtime-url.test.ts`
+- `packages/ui/src/lib/runtime-auth.test.ts`
+- `packages/web/server/lib/ui-auth/ui-auth.test.js`
+- `packages/web/server/lib/preview/proxy-runtime.test.js`
@@ -0,0 +1,49 @@
+# Runtime Implementation Map
+
+## Shared UI
+
+- `packages/ui/src/lib/opencode/client.ts`: OpenCode v2 SDK wrapper, current-directory handling, runtime-aware SDK client.
+- `packages/ui/src/lib/runtime-fetch.ts`: runtime HTTP URL resolution and auth while preserving SDK `Request` fidelity.
+- `packages/ui/src/lib/runtime-url.ts`: browser/realtime URL construction.
+- `packages/ui/src/lib/runtime-auth.ts`: bearer state and short-lived URL-token minting.
+- `packages/ui/src/lib/api/types.ts`: shared `RuntimeAPIs` contract.
+- `packages/ui/src/contexts/RuntimeAPIProvider.tsx`: React provider and runtime API wrappers.
+- `packages/ui/src/hooks/useRuntimeAPIs.ts`: React consumption path.
+
+## Web And Server
+
+- `packages/web/src/runtimeConfig.ts`: initializes runtime URL/auth and web APIs.
+- `packages/web/src/api/index.ts`: composes web `RuntimeAPIs`.
+- `packages/web/server/lib/opencode/core-routes.js`: installs OpenChamber route families.
+- `packages/web/server/lib/opencode/feature-routes-runtime.js`: explicit feature route registration.
+- `packages/web/server/lib/opencode/proxy.js`: generic OpenCode proxy fallback.
+- `packages/web/server/lib/ui-auth/ui-auth.js`: session and URL-token route gates.
+
+Explicit OpenChamber routes must register before the generic `/api/*` OpenCode proxy.
+
+## VS Code
+
+- `packages/vscode/webview/main.tsx`: webview fetch routing and local-route handling.
+- `packages/vscode/webview/api/index.ts`: webview `RuntimeAPIs` composition.
+- `packages/vscode/webview/api/bridge.ts`: request, session-message, and SSE bridge helpers.
+- `packages/vscode/webview/requestBodyTransport.ts`: byte-preserving request-body extraction.
+- `packages/vscode/src/bridge-proxy-runtime.ts`: extension-host OpenCode forwarding.
+- `packages/vscode/src/bridge-*-runtime.ts`: owning native/local handlers.
+
+## Runtime Switching
+
+`packages/ui/src/lib/runtime-switch.ts` updates endpoint/auth state and emits the runtime-change event. App roots reconnect SDK clients and reset runtime-scoped stores/transports.
+
+Review every cache keyed only by session ID, directory, URL, or entity ID. Add runtime identity when local and remote runtimes can collide.
+
+## Tests To Prefer
+
+- HTTP/request fidelity: `packages/ui/src/lib/runtime-fetch.test.ts`
+- URL/auth: `packages/ui/src/lib/runtime-url.test.ts`, `runtime-auth.test.ts`
+- Server auth: `packages/web/server/lib/ui-auth/ui-auth.test.js`
+- Generic proxy: `packages/web/server/opencode-proxy.test.js`
+- Preview proxy: `packages/web/server/lib/preview/proxy-runtime.test.js`
+- VS Code bridge: `packages/vscode/webview/api/bridge.test.ts`
+- VS Code proxy: `packages/vscode/src/bridge-proxy-runtime.test.js`
+
+Also run focused tests beside new runtime implementations and validation required by each affected workspace.
@@ -0,0 +1,38 @@
+# Runtime API And Parity
+
+## Extending `RuntimeAPIs`
+
+1. Add or extend the shared interface in `packages/ui/src/lib/api/types.ts`.
+2. Implement web behavior under `packages/web/src/api/*` and compose it in `packages/web/src/api/index.ts`.
+3. Implement VS Code webview behavior under `packages/vscode/webview/api/*`.
+4. Add extension-host bridge handlers when filesystem, git, settings, or manager access is required.
+5. Keep Electron shared through the web runtime unless behavior is inherently native.
+6. Register APIs through app entrypoints and consume via `RuntimeAPIProvider` hooks.
+
+React components use `useRuntimeAPIs()` or `useRuntimeAPI()`. Non-React modules use `getRegisteredRuntimeAPIs()` only when hooks are impossible. Do not introduce direct reads of `window.__OPENCHAMBER_RUNTIME_APIS__` in feature code.
+
+## VS Code Route Decisions
+
+| Route type | VS Code behavior |
+|---|---|
+| OpenChamber local route | Handle in the webview and bridge to extension host when needed |
+| Official OpenCode route | Forward through the generic OpenCode proxy |
+| SSE | Use the dedicated SSE bridge, never generic proxy |
+| Session message POST | Use the dedicated session-message path |
+| Unsupported native feature | Return stable explicit unsupported behavior, normally 501 JSON |
+
+Register explicit OpenChamber handling before generic proxy fallback. Silent empty fallback is not parity.
+
+## Electron Boundary
+
+Electron normally reuses the web runtime/server implementation. Keep privileged shell behavior behind main/preload IPC and local-page gates.
+
+- API base and shell identity may be broadly available for routing.
+- Client tokens, home paths, filesystem/shell access, and privileged IPC remain local-page gated.
+- Do not trust arbitrary loopback, `file://`, or `about:blank` origins as packaged UI.
+- Remote pages and preview iframes must not gain local host privileges.
+- Deep links that import hosts, store credentials, or switch runtimes require explicit in-app confirmation before mutation.
+
+## Shared Contract Rule
+
+For every shared capability, decide web, Electron, VS Code, hosted-mobile, and Capacitor behavior explicitly. A stable unsupported response is acceptable; accidental fallthrough is not.