privateer-agent 0.2.1 → 0.3.0

package/src/permissions/{uiGate.ts → modeGate.ts}

@@ -1,9 +1,14 @@
 import { dirname } from "node:path";
-import type { PermissionMode } from "../config/schema.ts";
+import type { PermissionMode } from "../config/permissionMode.ts";
 import type { PermissionGate, PermissionRequest, PermissionDecision } from "./gate.ts";
 import { decideAuto } from "./mode.ts";
 import { isDangerousCommand } from "./danger.ts";
 
+// Ported verbatim from tree-cli/src/permissions/uiGate.ts (renamed modeGate;
+// only import paths changed). The mode/allowlist/remote policy engine — the moat.
+// In the Pi rewrite the extension (../ext/permissionGate.ts) builds one of these
+// per tool_call, with `ask` bound to that call's ctx.ui (local) or the relay (remote).
+
 // What the interactive prompt can return. "always" means allow now and remember:
 // for bash, add the command to the session allowlist; for edits, switch to acceptEdits.
 export type AskOutcome = "allow" | "deny" | "always";
@@ -15,8 +20,7 @@ export interface ModeGateDeps {
   allowlist: string[]; // session-scoped, mutated in place on "always"
   denylist?: string[]; // dangerous-command patterns that always require a prompt
   // Out-of-cwd directories approved this session ("always" on an outside prompt),
-  // mutated in place. Shared with the tool context so approved locations stop
-  // re-prompting. The same array instance must be handed to the tools.
+  // mutated in place. Shared with the tool scope so approved locations stop re-prompting.
   allowedOutsideRoots?: string[];
   ask: Asker;
   // True while the active turn was injected by a remote controller (the app, via
@@ -25,6 +29,11 @@ export interface ModeGateDeps {
   // an unattended terminal can't silently run a remote party's bash or edits.
   // Hard denies (e.g. plan mode) are still honored without bothering the phone.
   getRemote?: () => boolean;
+  // True while the controller has toggled no-quarter (unattended) mode: remote
+  // turns auto-approve like bypass mode so the agent runs to completion without
+  // pinging the phone. Dangerous shell and alwaysAsk-destructive actions rank
+  // above bypass in decideAuto, so those still relay for an explicit Allow/Deny.
+  getNoQuarter?: () => boolean;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -43,6 +52,12 @@ export class ModeGate implements PermissionGate {
     // remembered — we don't let a remote operator mutate local allowlist/mode.
     if (this.deps.getRemote?.()) {
       if (auto === "deny") return "deny";
+      // No-quarter: re-evaluate as if in bypass mode. Dangerous/destructive
+      // actions still come back "ask" (they sit above bypass) and fall through
+      // to the relayed prompt; everything else runs unattended.
+      if (this.deps.getNoQuarter?.() && decideAuto(req, "bypass", this.deps.allowlist, denylist) === "allow") {
+        return "allow";
+      }
       return (await this.deps.ask(req)) === "deny" ? "deny" : "allow";
     }
 

package/src/providers/account.ts

@@ -0,0 +1,170 @@
+// The `privateer` account provider — run inference billed to the user's Privateer
+// subscription instead of a BYO key. This is the one provider the plan flags as a
+// genuine code-blocker (Appendix A): it can't be a static key — it uses a rotating,
+// 401-refreshing child session against the account channel (`${server}/api/agent/v1`).
+//
+// We register it via Pi's OAuth path (ProviderConfigInput.oauth). Pi drives the
+// credential lifecycle: it calls getApiKey(cred) per request and refreshToken(cred)
+// when Date.now() >= cred.expires. We map a per-terminal child session onto that
+// shape (see auth/privateer.ts spawn/refreshAccountCredentials). Because the machine
+// login already exists (~/.privateer/credentials.json), login() just spawns a child;
+// only a first-ever machine login runs the device-code flow.
+
+import {
+  serverBaseUrl,
+  hasCredentials,
+  runDeviceLogin,
+  authedFetch,
+  spawnAccountCredentials,
+  refreshAccountCredentials,
+} from "../auth/privateer.ts";
+import { interpretReport, teePosture, type PrivacyTier } from "pi-privacy";
+
+// Seed/fallback catalog: registered synchronously so the account provider has real
+// models the instant it loads (before the live /api/models fetch resolves) — in
+// particular the signed-in default, near/zai-org/GLM-5.1-FP8, resolves at startup
+// without a "model not found" warning. The first entry is that default: a NEAR
+// confidential-compute (TEE, attestable) model — the strongest privacy tier. Also the
+// fallback list if the live listing can't be reached.
+const DEFAULT_MODELS = [
+  "near/zai-org/GLM-5.1-FP8",
+  "anthropic/claude-sonnet-4.6",
+  "openai/gpt-5.5",
+  "deepseek/deepseek-v4-flash",
+];
+
+function seedModel(id: string) {
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"] as ("text" | "image")[],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+  };
+}
+
+// Fetch the account channel's enabled model catalog. `GET /api/models` is the server's
+// public list of billable models (`{ models: [{ modelId }] }`) — the same set the app
+// shows. (The `/api/agent/v1` base only implements chat/completions, no /models route.)
+// Falls back to DEFAULT_MODELS on any failure.
+export async function fetchAccountModels(): Promise<string[]> {
+  try {
+    const res = await fetch(`${serverBaseUrl()}/api/models`);
+    if (!res.ok) return DEFAULT_MODELS;
+    const data = (await res.json()) as { models?: { modelId?: string }[] };
+    const ids = (data.models ?? []).map((m) => m.modelId).filter((x): x is string => !!x);
+    return ids.length ? ids : DEFAULT_MODELS;
+  } catch {
+    return DEFAULT_MODELS;
+  }
+}
+
+// The Pi OAuth provider (Omit<OAuthProviderInterface, "id"> — Pi supplies the id from
+// the provider name). login/refreshToken/getApiKey are the whole contract.
+export const privateerOAuthProvider = {
+  name: "Privateer account",
+  usesCallbackServer: false,
+  async login(cb: { onDeviceCode?: (info: unknown) => void }) {
+    if (!hasCredentials()) {
+      await runDeviceLogin({
+        onCode: (code) =>
+          cb.onDeviceCode?.({
+            userCode: code.user_code,
+            verificationUri: code.verification_uri_complete ?? code.verification_uri ?? "",
+            intervalSeconds: code.interval,
+            expiresInSeconds: code.expires_in,
+          }),
+      });
+    }
+    return spawnAccountCredentials();
+  },
+  async refreshToken(creds: { refresh: string }) {
+    try {
+      return await refreshAccountCredentials(creds.refresh);
+    } catch {
+      // child token expired/reused → spawn a fresh one from the parent login.
+      return spawnAccountCredentials();
+    }
+  },
+  getApiKey(creds: { access: string }): string {
+    return creds.access;
+  },
+};
+
+// Which privacy channel an account model routes through: NEAR confidential-compute
+// (TEE, attestable) for `near/`-prefixed ids, else a server-side ZDR channel.
+// Ported from tree-cli resolve.ts.
+export function privateerChannel(modelId: string): "tee" | "zdr" {
+  return modelId.startsWith("near/") ? "tee" : "zdr";
+}
+
+export interface AccountPosture {
+  tier: PrivacyTier;
+  teePosture?: "green" | "yellow" | "red";
+  error?: string;
+}
+
+// Posture for an account-channel model. For NEAR models the attestation is fetched
+// through the SERVER proxy (the account's NEAR key stays server-side): the server
+// mints the nonce AND returns the report, so the CLIENT contributes no freshness and
+// can't bind the report to the live TLS key. That is a trust-the-server posture, not
+// client-verified — materially weaker than the direct nearai path (which supplies its
+// own randomNonce). So we must NOT promote it to `tee-verified`: that tier reads as
+// cryptographically proven and, critically, disables pi-privacy's PII gate. We cap a
+// green server posture at `tee-unverified` (honest yellow — the PII gate stays on) and
+// still surface the raw teePosture for display. ZDR-channel models route to
+// zero-retention endpoints server-side, which we can't observe here — a policy claim.
+export async function accountPosture(modelId: string): Promise<AccountPosture> {
+  if (privateerChannel(modelId) === "zdr") {
+    return { tier: "zdr-policy" };
+  }
+  try {
+    const res = await authedFetch(
+      `${serverBaseUrl()}/api/models/near/attestation?model=${encodeURIComponent(modelId)}`,
+    );
+    if (!res.ok) return { tier: "tee-unverified", error: `HTTP ${res.status}` };
+    const data = (await res.json()) as { nonce?: string; report?: unknown };
+    const att = interpretReport(modelId, data.nonce ?? "", data.report ?? {});
+    const tp = teePosture(att);
+    // Cap at client-unverifiable: server-proxied green never earns `tee-verified`.
+    const tier: PrivacyTier = tp === "red" ? "standard" : "tee-unverified";
+    return { tier, teePosture: tp };
+  } catch (e) {
+    return { tier: "tee-unverified", error: (e as Error).message };
+  }
+}
+
+// Extension factory: registers the account provider when a machine login exists. No
+// login → nothing registered (BYO-key only).
+//
+// Registration is SYNCHRONOUS (seeded with the fallback), then refined once the live
+// catalog is fetched. This matters: Pi flushes provider registrations made during the
+// synchronous extension-init pass before it binds extensions, so the `privateer`
+// provider (and its OAuth login path) exist immediately — before the model picker can
+// open. If we instead awaited the network fetch first, the registration could land
+// after the picker built its list, and privateer models would be missing until reopen.
+// registerProvider replaces the provider's models on the second call, and the picker's
+// refresh() re-applies registered providers, so the full list appears once fetched.
+export function makeAccountProvider() {
+  return (pi: {
+    registerProvider?: (name: string, config: unknown) => void;
+  }): void => {
+    if (!hasCredentials() || typeof pi.registerProvider !== "function") return;
+    const register = (ids: string[]): void =>
+      pi.registerProvider!("privateer", {
+        name: "Privateer account",
+        baseUrl: `${serverBaseUrl()}/api/agent/v1`,
+        api: "openai-completions",
+        oauth: privateerOAuthProvider,
+        models: ids.map(seedModel),
+      });
+    register(DEFAULT_MODELS); // immediate: provider exists this tick
+    void fetchAccountModels()
+      .then((ids) => ids.length && register(ids)) // refine to the live catalog
+      .catch(() => {
+        /* keep the fallback model */
+      });
+  };
+}

package/src/providers/catalog.ts

@@ -1,66 +1,78 @@
-import { KNOWN_PROVIDERS, type ProviderName } from "../config/schema.ts";
-import { providerRequiresKey } from "./registry.ts";
+// The provider landscape — the single map of how each of privateer's 21 providers
+// becomes reachable under Pi. Written after verifying (2026-07-07) that:
+//   - pi-ai ships STATIC model catalogs for its 14 built-in providers, so they're
+//     selectable once a key is present — privateer emits NO models.json entry for them;
+//   - the `pi-privacy` extension registers the 5 privacy providers (tinfoil, nearai,
+//     venice, ollama, custom) at load — privateer emits NO entry for them either;
+//   - so the ONLY provider this generator must emit is `qwen` (config-only,
+//     non-privacy, no built-in catalog), and `privateer` (the account OAuth channel)
+//     is handled in code, not config (Phase 4).
+//
+// The plan (Appendix A) assumed we'd generate the whole models.json; Pi's built-in
+// catalogs + pi-privacy made most of that redundant. This map keeps the accounting
+// explicit so nothing silently falls through.
 
-// Human-facing metadata for each provider, used by the onboarding flow: a display
-// label, where to get an API key, and the model to default to when the provider is
-// chosen first. Keeps the registry (wiring) separate from presentation.
-export interface ProviderMeta {
-  name: ProviderName;
-  label: string;
-  requiresKey: boolean;
-  defaultModel: string; // "provider:model" picked when this provider is selected first
-  keyHint: string; // where to obtain a key, or a note for keyless providers
-  baseURLDefault?: string; // shown as the placeholder for keyless/local providers
+export type ProviderSource =
+  | "pi-builtin" // pi-ai ships the provider + its model catalog (needs only a key)
+  | "pi-privacy" // registered by the pi-privacy extension at load
+  | "generate" // privateer must emit a models.json entry (config-only, no built-in)
+  | "account"; // the privateer account channel — OAuth in code, not config
+
+export type ProviderApi = "openai-completions" | "openai-responses" | "anthropic-messages";
+
+export interface ProviderEntry {
+  id: string;
+  source: ProviderSource;
+  // For `generate` providers: the config a models.json entry needs.
+  baseUrl?: string;
+  api?: ProviderApi;
+  keyEnv?: string; // env template ${...}; Pi resolves it (or auth.json wins)
+  compat?: Record<string, unknown>;
+  seedModels?: string[]; // provisional ids until live listing refines them
+  // Optional nuance override for a built-in (api/compat differs from pi-ai default).
+  // Not emitted yet — overriding a built-in can drop its model catalog; revisit once
+  // Pi's override-merge semantics are confirmed. Documented here so it's not lost.
+  overrideNote?: string;
 }
 
-export const PROVIDER_META: Record<ProviderName, ProviderMeta> = {
-  anthropic: {
-    name: "anthropic",
-    label: "Anthropic",
-    requiresKey: providerRequiresKey("anthropic"),
-    defaultModel: "anthropic:claude-opus-4-8",
-    keyHint: "console.anthropic.com/settings/keys",
-  },
-  openai: {
-    name: "openai",
-    label: "OpenAI",
-    requiresKey: providerRequiresKey("openai"),
-    defaultModel: "openai:gpt-4o",
-    keyHint: "platform.openai.com/api-keys",
-  },
-  openrouter: {
-    name: "openrouter",
-    label: "OpenRouter",
-    requiresKey: providerRequiresKey("openrouter"),
-    defaultModel: "openrouter:anthropic/claude-opus-4.8",
-    keyHint: "openrouter.ai/keys",
-  },
-  ollama: {
-    name: "ollama",
-    label: "Ollama (local)",
-    requiresKey: providerRequiresKey("ollama"),
-    defaultModel: "ollama:llama3.1",
-    keyHint: "runs locally — no key needed",
-    baseURLDefault: "http://localhost:11434/api",
+// Ordered like KNOWN_PROVIDERS (tree-cli schema.ts) for a stable picker order.
+export const PROVIDERS: ProviderEntry[] = [
+  { id: "openrouter", source: "pi-builtin", overrideNote: "ZDR routing handled by pi-privacy" },
+  { id: "anthropic", source: "pi-builtin" },
+  { id: "openai", source: "pi-builtin", overrideNote: "0.2 used chat-completions, not responses" },
+  { id: "google", source: "pi-builtin" },
+  { id: "xai", source: "pi-builtin" },
+  { id: "groq", source: "pi-builtin" },
+  { id: "mistral", source: "pi-builtin" },
+  { id: "zai", source: "pi-builtin", overrideNote: "0.2 baseUrl …/api/paas/v4; compat.thinkingFormat zai" },
+  { id: "moonshot", source: "pi-builtin" },
+  { id: "cerebras", source: "pi-builtin" },
+  { id: "fireworks", source: "pi-builtin" },
+  { id: "together", source: "pi-builtin", overrideNote: "compat.thinkingFormat together" },
+  { id: "deepseek", source: "pi-builtin", overrideNote: "compat.thinkingFormat deepseek" },
+  { id: "minimax", source: "pi-builtin", overrideNote: "0.2 used …/v1 openai-compat, not anthropic-messages" },
+  {
+    id: "qwen",
+    source: "generate",
+    baseUrl: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    api: "openai-completions",
+    keyEnv: "${DASHSCOPE_API_KEY}",
+    compat: { thinkingFormat: "qwen" },
+    seedModels: ["qwen3-max", "qwen3-coder-plus", "qwen-max-latest"],
   },
-  nearai: {
-    name: "nearai",
-    label: "NEAR AI (private TEE inference)",
-    requiresKey: providerRequiresKey("nearai"),
-    defaultModel: "nearai:zai-org/GLM-5.1-FP8",
-    keyHint: "cloud.near.ai → API Keys",
-  },
-  privateer: {
-    name: "privateer",
-    // Default to a NEAR confidential-compute (TEE) model: it's the strongest
-    // privacy guarantee, runs through the same billed agent endpoint, and was
-    // verified to pass agent tool_calls. Switch to any listed model with /model.
-    label: "Privateer account (billed to your subscription)",
-    requiresKey: providerRequiresKey("privateer"),
-    defaultModel: "privateer:near/deepseek-ai/DeepSeek-V4-Flash",
-    keyHint: "sign in with /login — no API key needed",
-  },
-};
+  { id: "ollama", source: "pi-privacy" },
+  { id: "nearai", source: "pi-privacy" },
+  { id: "tinfoil", source: "pi-privacy" },
+  { id: "venice", source: "pi-privacy" },
+  { id: "custom", source: "pi-privacy" },
+  { id: "privateer", source: "account" },
+];
 
-// Provider metadata in display order.
-export const PROVIDER_LIST: ProviderMeta[] = KNOWN_PROVIDERS.map((n) => PROVIDER_META[n]);
+export const PROVIDER_BY_ID: Record<string, ProviderEntry> = Object.fromEntries(
+  PROVIDERS.map((p) => [p.id, p]),
+);
+
+// Providers this generator is responsible for emitting into models.json.
+export function providersToGenerate(): ProviderEntry[] {
+  return PROVIDERS.filter((p) => p.source === "generate");
+}

package/src/providers/genModelsJson.ts

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { agentDir } from "../config/paths.ts";
+import { providersToGenerate, type ProviderEntry } from "./catalog.ts";
+
+// Emit models.json entries for the config-only providers Pi doesn't ship and
+// pi-privacy doesn't register (today: just `qwen`). Built-ins come from pi-ai's
+// static catalogs; privacy providers from the pi-privacy extension; the privateer
+// account channel from code. See catalog.ts for the full accounting.
+//
+// Model metadata defaults follow the migration plan Appendix A.4 (used until a live
+// listing refines them): contextWindow 128000, maxTokens 16384, zero cost, text-only.
+
+export interface ModelsJsonModel {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ("text" | "image")[];
+  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  contextWindow: number;
+  maxTokens: number;
+  compat?: Record<string, unknown>;
+}
+
+export interface ModelsJsonProvider {
+  name: string;
+  baseUrl: string;
+  api: string;
+  apiKey?: string;
+  authHeader?: boolean;
+  compat?: Record<string, unknown>;
+  models: ModelsJsonModel[];
+}
+
+export interface ModelsJson {
+  providers: Record<string, ModelsJsonProvider>;
+}
+
+function seedModel(id: string, compat?: Record<string, unknown>): ModelsJsonModel {
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 16384,
+    ...(compat ? { compat } : {}),
+  };
+}
+
+function providerConfig(p: ProviderEntry): ModelsJsonProvider {
+  return {
+    name: p.id,
+    baseUrl: p.baseUrl!,
+    api: p.api ?? "openai-completions",
+    // Env-template key (Pi resolves ${...}; auth.json takes precedence when present).
+    // Never a literal key — and never emitted for the account/venice providers.
+    ...(p.keyEnv ? { apiKey: p.keyEnv, authHeader: true } : {}),
+    ...(p.compat ? { compat: p.compat } : {}),
+    models: (p.seedModels ?? []).map((id) => seedModel(id, p.compat)),
+  };
+}
+
+// Build the models.json object for all `generate`-sourced providers.
+export function generateModelsJson(providers: ProviderEntry[] = providersToGenerate()): ModelsJson {
+  const out: ModelsJson = { providers: {} };
+  for (const p of providers) {
+    if (p.source !== "generate" || !p.baseUrl) continue;
+    out.providers[p.id] = providerConfig(p);
+  }
+  return out;
+}
+
+// Merge generated providers into an existing models.json WITHOUT clobbering
+// user-added or extension-registered providers. Generated ids are refreshed; every
+// other provider in the file is preserved. Writes to $PRIVATEER_HOME/agent/models.json
+// by default. Returns the merged object.
+export function writeModelsJson(
+  generated: ModelsJson = generateModelsJson(),
+  path: string = join(agentDir(), "models.json"),
+): ModelsJson {
+  let existing: ModelsJson = { providers: {} };
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object" && parsed.providers) existing = parsed;
+    } catch {
+      // Unreadable/corrupt file → treat as empty rather than throwing; we only add
+      // our generated providers and never drop the user's.
+    }
+  }
+  const merged: ModelsJson = { providers: { ...existing.providers, ...generated.providers } };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  return merged;
+}

package/src/remote/relayClient.ts

@@ -61,6 +61,10 @@ export interface RelayCallbacks {
   onTerminate?: () => void;
   // The app answered a relayed approval request.
   onApprovalResponse: (id: string, decision: "allow" | "deny") => void;
+  // The app toggled no-quarter (unattended) mode: remote turns auto-approve like
+  // bypass mode instead of relaying every action, so the agent runs to completion.
+  // Dangerous/destructive actions still relay — they sit above bypass locally too.
+  onNoQuarter?: (on: boolean) => void;
   // A controller attached — push a transcript snapshot so it can catch up.
   onControllerAttached: () => void;
   // A file finished transferring from the app (reassembled from chunks). Held to
@@ -250,6 +254,7 @@ export class RelayClient {
       size?: number;
       seq?: number;
       data?: string;
+      on?: boolean;
     };
     try {
       frame = JSON.parse(data.toString());
@@ -273,6 +278,9 @@ export class RelayClient {
       case "approval_response":
         if (frame.id) this.cb.onApprovalResponse(frame.id, frame.decision === "deny" ? "deny" : "allow");
         break;
+      case "no_quarter":
+        this.cb.onNoQuarter?.(frame.on === true);
+        break;
       case "controller_attached":
         this.cb.onControllerAttached();
         break;
@@ -407,6 +415,13 @@ export class RelayClient {
     return { ok: true };
   }
 
+  // Echo the no-quarter (unattended auto-approve) state up to the controller so
+  // its toggle reflects what this terminal is actually doing. Sent on every
+  // change (ack) and on controller attach (a re-attaching app resyncs).
+  sendNoQuarter(on: boolean): void {
+    this.rawSend({ type: "no_quarter", on });
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",

package/src/remote/remoteBridge.ts

@@ -0,0 +1,152 @@
+// The wiring between the relay and the rest of the agent — NEW code for the Pi
+// rewrite. It connects three things that were built to meet here:
+//   - the Phase-1 adapter's EngineEvents  → up to the app (relay.sendEvent)
+//   - the Phase-2 gate's remote branch    → each tool relayed to the app for
+//     allow/deny via `remoteAsk` + `getRemote` (the slots makePermissionGate stubbed)
+//   - the app's prompts/interrupts        → down into the turn loop (cfg callbacks)
+//
+// The RelayClient itself is KEEP (verbatim 0.2); this bridge is the only new part,
+// so it's what the tests exercise (against a fake relay). Fail-closed throughout:
+// no controller, a disconnect, or an aborted turn all resolve a pending approval
+// to "deny".
+
+import { randomUUID } from "node:crypto";
+import type { EngineEvent } from "../engine/events.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+import type { AskOutcome } from "../permissions/modeGate.ts";
+import type { RelayCallbacks } from "./relayClient.ts";
+
+// The outbound surface the bridge needs; RelayClient implements all of it.
+export interface RelayLike {
+  requestApproval(id: string, req: PermissionRequest): void;
+  sendEvent(ev: EngineEvent): void;
+  isConnected(): boolean;
+  sendNoQuarter(on: boolean): void;
+  sendFile(file: { name: string; mediaType: string; base64: string; size: number }): Promise<{ ok: boolean; reason?: string }>;
+}
+
+export interface RemoteAttachment {
+  name: string;
+  mediaType: string;
+  base64: string;
+}
+
+export interface RemoteBridgeConfig {
+  // A prompt arrived from the app — drive the turn loop (tagged remote). Any files
+  // the app sent ahead of the prompt ride along.
+  onPrompt: (text: string, attachments: RemoteAttachment[]) => void;
+  onInterrupt?: () => void;
+  onTerminate?: () => void;
+  // A controller (re)attached — the owner should push a transcript snapshot.
+  onControllerAttached?: () => void;
+  onStatus?: (text: string) => void;
+  // A file finished transferring down from the app. The owner registers it (e.g. into
+  // an AttachmentStore) so the save_attachment tool can persist it.
+  onAttachment?: (file: RemoteAttachment) => void;
+}
+
+export class RemoteBridge {
+  private relay?: RelayLike;
+  private remote = false;
+  private noQuarter = false;
+  private readonly pending = new Map<string, (d: AskOutcome) => void>();
+  private pendingAttachments: RemoteAttachment[] = [];
+
+  constructor(private readonly cfg: RemoteBridgeConfig) {}
+
+  // Wire the outbound relay once it's constructed (RelayClient needs `callbacks`
+  // at construction, so the relay is attached right after).
+  attachRelay(relay: RelayLike): void {
+    this.relay = relay;
+  }
+
+  // Hand this to `new RelayClient(bridge.callbacks)`. Typed Required so every hook
+  // (including the ones RelayCallbacks marks optional) is defined — the bridge wires
+  // them all.
+  readonly callbacks: Required<RelayCallbacks> = {
+    onPrompt: (text) => {
+      this.remote = true; // a remote turn is now in flight → gate relays each action
+      const attachments = this.pendingAttachments;
+      this.pendingAttachments = [];
+      this.cfg.onPrompt(text, attachments);
+    },
+    onInterrupt: () => this.cfg.onInterrupt?.(),
+    onTerminate: () => this.cfg.onTerminate?.(),
+    onApprovalResponse: (id, decision) => {
+      const resolve = this.pending.get(id);
+      if (resolve) resolve(decision);
+    },
+    onNoQuarter: (on) => {
+      this.noQuarter = on;
+      this.relay?.sendNoQuarter(on); // echo the ack back so the app's toggle syncs
+    },
+    onControllerAttached: () => this.cfg.onControllerAttached?.(),
+    onAttachment: (file) => {
+      this.pendingAttachments.push(file);
+      this.cfg.onAttachment?.(file);
+    },
+    onStatus: (text) => this.cfg.onStatus?.(text),
+    onDisconnected: () => {
+      this.remote = false;
+      // Any approval waiting on a now-gone controller fails closed.
+      this.rejectAllPending();
+    },
+  };
+
+  // ── gate hooks (passed into the GateController) ─────────────────────────────
+
+  getRemote = (): boolean => this.remote;
+  getNoQuarter = (): boolean => this.noQuarter;
+
+  // The gate's remote approver: relay the request to the app and await its
+  // allow/deny. Fail closed if no controller, on abort, or on disconnect. (The gate
+  // also wraps this in its own timeout, so a silent app can't wedge the turn.)
+  remoteAsk = (req: PermissionRequest, signal?: AbortSignal): Promise<AskOutcome> => {
+    if (!this.relay || !this.relay.isConnected()) return Promise.resolve("deny");
+    const id = randomUUID();
+    return new Promise<AskOutcome>((resolve) => {
+      const onAbort = () => settle("deny");
+      const settle = (d: AskOutcome) => {
+        this.pending.delete(id);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(d);
+      };
+      this.pending.set(id, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      this.relay!.requestApproval(id, req);
+    });
+  };
+
+  // ── turn lifecycle + event forwarding ───────────────────────────────────────
+
+  // Mark the end of a turn so the next (possibly local) turn isn't treated as
+  // remote. Call after each driven turn completes.
+  settleTurn(): void {
+    this.remote = false;
+  }
+
+  // Forward an EngineEvent up to the app. Safe to call for every event of every
+  // turn (local included) — the relay only sends when a socket is open.
+  forwardEvent(ev: EngineEvent): void {
+    this.relay?.sendEvent(ev);
+  }
+
+  // Is a controller actually reachable right now? (Relay socket open.)
+  isConnected(): boolean {
+    return !!this.relay?.isConnected();
+  }
+
+  // Stream a file up to the connected app (the send_file_to_client tool).
+  async sendFile(file: { name: string; mediaType: string; base64: string; size: number }): Promise<{ ok: boolean; reason?: string }> {
+    if (!this.relay) return { ok: false, reason: "remote access is not enabled" };
+    return this.relay.sendFile(file);
+  }
+
+  private rejectAllPending(): void {
+    for (const resolve of this.pending.values()) resolve("deny");
+    this.pending.clear();
+  }
+}