privateer-agent 0.3.6 → 0.4.1

package/src/remote/channelsControl.ts

@@ -0,0 +1,192 @@
+/**
+ * Channel management for the app — the sibling of routinesControl.ts, but for the
+ * messaging-channel config (Telegram/Slack/Discord/WhatsApp) rather than scheduled
+ * routines.
+ *
+ * Like routines, this is owned by the ALWAYS-ON daemon relay (daemon/index.ts),
+ * NOT the channels daemon (channels/run.ts) — which may be down, and which the app
+ * must be able to configure before it has ever run. So this control edits the
+ * `channels` block of ~/.privateer/config.json; the channels daemon adopts changes
+ * on its next RESTART, matching run.ts's deliberate "no in-chat toggle, restart is
+ * the fail-safe reset" posture. `running` is a best-effort read of the channels
+ * daemon's heartbeat (channels/status.ts), never a dependency.
+ *
+ * SECRETS: bot tokens are WRITE-ONLY from the app's perspective. list() NEVER
+ * returns a token value — it reports `configured`, `running`, and `secretsSet`
+ * (which secret fields are present, by name only). save() persists whatever secret
+ * VALUES it is handed in `draft.secrets`; the seal/open of those values in transit
+ * is the caller's job (Phase 3), so this module only ever deals in the plaintext
+ * config.json it already owns.
+ *
+ * Framework-agnostic: nothing here imports React or the relay. The caller owns the
+ * frame plumbing and the running-presence read.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { configPath } from "../config/paths.ts";
+
+// The platforms channels/run.ts knows how to start. Order is the app's display
+// order. Keep in sync with the `startChannel` calls in run.ts.
+export const CHANNEL_PLATFORMS = ["telegram", "slack", "discord", "whatsapp"] as const;
+export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+
+const POSTURES = ["readonly", "approve", "auto"] as const;
+export type ChannelPosture = (typeof POSTURES)[number];
+
+// The secret (never-echoed) fields per platform — the union of the token blocks
+// run.ts requires to START each platform. `secretsSet` reports presence of these.
+const SECRET_FIELDS: Record<ChannelPlatform, string[]> = {
+  telegram: ["botToken"],
+  slack: ["appToken", "botToken"],
+  discord: ["botToken"],
+  whatsapp: ["phoneNumberId", "accessToken", "verifyToken", "appSecret"],
+};
+
+// Non-secret projection of one platform's config, sent to the app. No token
+// values, ever — only which secret fields are already present (`secretsSet`).
+export interface RemoteChannel {
+  platform: ChannelPlatform;
+  configured: boolean; // a config block exists for this platform
+  running: boolean; // the channels daemon is currently serving it
+  adminCount: number;
+  memberCount: number;
+  posture: ChannelPosture;
+  tools: string[];
+  model?: string;
+  secretsSet: string[]; // e.g. ["botToken"] — names only, never values
+}
+
+// An app-submitted edit. Non-secret fields REPLACE when present; `secrets` maps a
+// secret field name → its (already-opened) value, and only present, non-empty
+// values overwrite — omitted means "keep the existing value".
+export interface ChannelDraft {
+  platform: ChannelPlatform;
+  admins?: string[];
+  members?: string[];
+  posture?: ChannelPosture;
+  tools?: string[];
+  model?: string;
+  secrets?: Record<string, string>;
+}
+
+export interface ChannelsControl {
+  // All four platforms, always — configured or not — so the app can show empty
+  // slots to set up. Order follows CHANNEL_PLATFORMS.
+  list(): RemoteChannel[];
+  // Create or edit a platform's config. Validates posture + fail-closes on a block
+  // with no admins/members (mirrors run.ts). Returns a one-line result.
+  save(draft: ChannelDraft): { ok: boolean; message?: string };
+  // Delete a platform's config entirely. ok:false when nothing was configured.
+  remove(platform: ChannelPlatform): { ok: boolean; message?: string };
+}
+
+function isPlatform(v: unknown): v is ChannelPlatform {
+  return typeof v === "string" && (CHANNEL_PLATFORMS as readonly string[]).includes(v);
+}
+
+function normalizePosture(v: unknown): ChannelPosture | undefined {
+  return typeof v === "string" && (POSTURES as readonly string[]).includes(v) ? (v as ChannelPosture) : undefined;
+}
+
+function cleanStrList(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  const out = v.map((x) => String(x ?? "").trim()).filter(Boolean);
+  return out.length > 0 ? out : [];
+}
+
+export function makeChannelsControl(opts: {
+  // Which platforms the channels daemon is serving right now (heartbeat read).
+  // Absent → everything reports not-running.
+  runningPlatforms?: () => Set<string>;
+}): ChannelsControl {
+  const running = opts.runningPlatforms ?? (() => new Set<string>());
+
+  function readCfg(): any {
+    try {
+      return JSON.parse(readFileSync(configPath(), "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  function toRemote(platform: ChannelPlatform, block: any, live: Set<string>): RemoteChannel {
+    const admins = block?.admins ?? block?.allowFrom ?? []; // legacy allowFrom == admins
+    return {
+      platform,
+      configured: !!block,
+      running: live.has(platform),
+      adminCount: Array.isArray(admins) ? admins.length : 0,
+      memberCount: Array.isArray(block?.members) ? block.members.length : 0,
+      posture: normalizePosture(block?.posture) ?? "approve",
+      tools: Array.isArray(block?.tools) ? block.tools.map(String) : [],
+      model: typeof block?.model === "string" ? block.model : undefined,
+      secretsSet: SECRET_FIELDS[platform].filter((f) => block?.[f]),
+    };
+  }
+
+  return {
+    list(): RemoteChannel[] {
+      const ch = readCfg().channels ?? {};
+      const live = running();
+      return CHANNEL_PLATFORMS.map((p) => toRemote(p, ch[p], live));
+    },
+
+    save(draft: ChannelDraft): { ok: boolean; message?: string } {
+      if (!isPlatform(draft?.platform)) return { ok: false, message: "Unknown platform." };
+      if (draft.posture !== undefined && !normalizePosture(draft.posture))
+        return { ok: false, message: "Invalid posture." };
+
+      const cfg = readCfg();
+      cfg.channels ??= {};
+      const block: any = { ...(cfg.channels[draft.platform] ?? {}) };
+
+      // Non-secret fields replace when provided. An explicit empty array clears.
+      const admins = cleanStrList(draft.admins);
+      if (admins !== undefined) block.admins = admins;
+      const members = cleanStrList(draft.members);
+      if (members !== undefined) block.members = members;
+      if (draft.posture !== undefined) block.posture = draft.posture;
+      const tools = cleanStrList(draft.tools);
+      if (tools !== undefined) block.tools = tools;
+      if (draft.model !== undefined) {
+        const m = String(draft.model).trim();
+        if (m) block.model = m;
+        else delete block.model;
+      }
+
+      // Secrets: a present, non-empty value overwrites; omitted keeps the existing.
+      for (const [k, v] of Object.entries(draft.secrets ?? {})) {
+        if (!SECRET_FIELDS[draft.platform].includes(k)) continue;
+        const val = String(v ?? "").trim();
+        if (val) block[k] = val;
+      }
+
+      // Fail-closed: never persist a block that can't authorize anyone (mirrors
+      // run.ts:261 — a channel with no admins/members is skipped anyway).
+      const hasAdmins = Array.isArray(block.admins) && block.admins.length > 0;
+      const hasMembers = Array.isArray(block.members) && block.members.length > 0;
+      if (!hasAdmins && !hasMembers)
+        return { ok: false, message: "Add at least one admin before saving." };
+
+      cfg.channels[draft.platform] = block;
+      try {
+        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+      } catch (e) {
+        return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Saved ${draft.platform}. Restart the channels daemon to apply.` };
+    },
+
+    remove(platform: ChannelPlatform): { ok: boolean; message?: string } {
+      if (!isPlatform(platform)) return { ok: false, message: "Unknown platform." };
+      const cfg = readCfg();
+      if (!cfg.channels?.[platform]) return { ok: false, message: "Not configured." };
+      delete cfg.channels[platform];
+      try {
+        writeFileSync(configPath(), JSON.stringify(cfg, null, 2));
+      } catch (e) {
+        return { ok: false, message: `Couldn't write config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Removed ${platform}. Restart the channels daemon to apply.` };
+    },
+  };
+}

package/src/remote/controlAuth.ts

@@ -0,0 +1,67 @@
+// Shared fail-closed gate for signed app->terminal control frames (H2).
+//
+// Every mutating control frame the app sends over the (untrusted) relay --
+// routines_save/delete/set_enabled/run, extensions_add/remove,
+// skills_create/delete/set_enabled, channels_remove -- is signed by the account and
+// MUST be verified before it takes effect, or a malicious server could forge it (a
+// forged routine yields a headless-bypass session = RCE; a forged extensions_add
+// installs an npm package = RCE; a forged skills_create injects an auto-invoked
+// skill). channels_save has its own bespoke verify (it also carries sealed secrets);
+// everything else routes through here.
+//
+// Both loci call this: the daemon (routines_*/channels_remove, termId = routineRelayId)
+// and each interactive terminal (extensions_*/skills_*, termId = the relay's id).
+//
+// Fail-closed: no pinned account key, a missing signature, a bad signature, or a stale
+// ts all reject the mutation. On success the per-terminal replay watermark advances.
+import { loadAccountSignKey, loadLastControlTs, saveLastControlTs } from "../crypto/accountTrust.ts";
+import { verifyControl } from "../crypto/accountVerify.ts";
+
+export interface ControlAuthResult {
+  ok: boolean;
+  message?: string;
+}
+
+/**
+ * Authorize a mutating control frame against the pinned account key + replay watermark.
+ * `termId` is THIS terminal's id (verification binds it, so a signature for another
+ * terminal won't match). Returns { ok:true } to proceed, or { ok:false, message } to
+ * refuse — the caller surfaces the message and does NOT perform the mutation.
+ *
+ * `opts.strict` (default false) governs the watermark comparison:
+ *   - non-strict: reject ts BELOW the watermark; ACCEPT at-or-above. Correct for
+ *     idempotent config mutations (routines/skills/extensions/channels save|delete),
+ *     where replaying the latest signed frame just re-applies the same state — harmless.
+ *   - strict: reject ts AT-or-below the watermark. Required for NON-idempotent, effectful
+ *     actions (task_submit/task_spawn — each RUNS a headless session), where a malicious
+ *     relay replaying the latest signed frame (same ts) would re-run the task / spawn
+ *     another session (inference-cost + resource abuse). Strict forces every accepted
+ *     effectful frame to carry a strictly-fresh ts, which the server cannot fabricate (it
+ *     can't sign) — so it can only replay old frames, all of which are now refused.
+ */
+export function authorizeControl(
+  termId: string,
+  action: string,
+  args: Record<string, unknown>,
+  sig?: string,
+  ts?: number,
+  opts?: { strict?: boolean },
+): ControlAuthResult {
+  const accountPub = loadAccountSignKey();
+  if (!accountPub) {
+    return { ok: false, message: "This terminal can't accept changes from the app yet — re-link it to establish trust." };
+  }
+  if (!sig || typeof ts !== "number") {
+    return { ok: false, message: "Refused an unsigned change from the app." };
+  }
+  if (!verifyControl(accountPub, { termId, ts, action, args }, sig)) {
+    return { ok: false, message: "Couldn't verify this change came from your account." };
+  }
+  const last = loadLastControlTs(termId);
+  const tooOld = opts?.strict ? ts <= last : ts < last;
+  if (tooOld) {
+    return { ok: false, message: "Ignored an out-of-date change from the app." };
+  }
+  saveLastControlTs(termId, ts);
+  return { ok: true };
+}

package/src/remote/extensionsControl.ts

@@ -0,0 +1,140 @@
+/**
+ * Extension management for linked terminals.
+ *
+ * A UI-agnostic wrapper over Pi's PackageManager so the app (over the relay) can
+ * see which Pi extensions THIS terminal has installed and add/remove them — the
+ * same way the model picker lets the app switch models. Both the dev REPL
+ * (src/cli/chat.ts) and the shipped TUI (extensions/privateer-gate.ts) build one
+ * of these and route the extensions_* relay frames through it.
+ *
+ * Only the user's OWN packages surface here. The Privateer moat (privateer-*,
+ * pi-privacy, rpiv-web-tools, …) is installed by bin/privateer-tui as shim .ts
+ * files in the agent dir's extensions/ folder — auto-discovered, NOT recorded in
+ * settings.json "packages". listConfiguredPackages() reads only "packages", so the
+ * moat is naturally excluded. We keep a RESERVED name guard as defence in depth in
+ * case a user ever hand-adds one of our package names.
+ *
+ * Framework-agnostic: nothing here imports React or the relay. The caller owns the
+ * frame plumbing and hands us a SettingsManager (the REPL reuses the session's;
+ * the TUI creates a fresh one — both read the same ~/.privateer/agent/settings.json).
+ */
+import { DefaultPackageManager } from "@earendil-works/pi-coding-agent";
+import type { ProgressEvent, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// One installed extension as surfaced to the app. NON-PII: a package source
+// (npm:/git: spec) plus its scope — no cwd, no absolute paths beyond what Pi
+// already resolved. `installed` reflects whether the package is downloaded on disk
+// yet (a freshly-added one persists to settings before its install completes).
+export interface InstalledExtension {
+  source: string;
+  scope: "user" | "project";
+  filtered: boolean;
+  installed: boolean;
+  installedPath?: string;
+}
+
+export interface ExtensionsControl {
+  // The user's own configured packages (moat excluded). Cheap — reads settings.
+  listInstalled(): InstalledExtension[];
+  // Persist + download an npm:/git:/path package to USER settings. Returns ok:false
+  // with Pi's own message on a bad spec or a failed npm/git fetch.
+  add(source: string): Promise<{ ok: boolean; message?: string }>;
+  // Remove from USER settings + prune the cache. ok:false when nothing matched.
+  remove(source: string): Promise<{ ok: boolean; message?: string }>;
+  // Progress callback for the current add/remove (install/clone/pull steps), so the
+  // caller can relay a busy indicator. Pass undefined to clear.
+  setProgress(cb: ((ev: ProgressEvent) => void) | undefined): void;
+}
+
+// Package names we never manage from the app: the Privateer moat + adopted packs
+// installed as shims by the launcher. A guard only — listConfiguredPackages()
+// already omits them since they aren't settings "packages".
+const RESERVED = new Set([
+  "privateer-brand",
+  "privateer-context",
+  "privateer-gate",
+  "privateer-account",
+  "privateer-posture",
+  "privateer-tools",
+  "privateer-privacy",
+  "pi-privacy",
+  "pi-web-access",
+  "rpiv-web-tools",
+  "@juicesharp/rpiv-web-tools",
+  "pi-mcp-adapter",
+  "pi-hypa",
+  "@hypabolic/pi-hypa",
+  "pi-subagents",
+]);
+
+// The bare package name inside a source spec, for the RESERVED check. Strips the
+// npm:/git: scheme and any @version / #ref suffix; leaves scoped names intact.
+function packageName(source: string): string {
+  let s = source.trim();
+  const scheme = s.indexOf(":");
+  if (scheme > 0 && /^(npm|git)$/i.test(s.slice(0, scheme))) s = s.slice(scheme + 1);
+  // Drop a trailing @version (but not the leading @ of a scope) and a git #ref.
+  s = s.replace(/#.*$/, "");
+  const at = s.lastIndexOf("@");
+  if (at > 0) s = s.slice(0, at);
+  return s;
+}
+
+export function makeExtensionsControl(opts: {
+  cwd: string;
+  agentDir: string;
+  settingsManager: SettingsManager;
+}): ExtensionsControl {
+  const pm = new DefaultPackageManager({
+    cwd: opts.cwd,
+    agentDir: opts.agentDir,
+    settingsManager: opts.settingsManager,
+  });
+
+  return {
+    listInstalled(): InstalledExtension[] {
+      let configured: Array<{ source: string; scope: string; filtered: boolean; installedPath?: string }> = [];
+      try {
+        configured = pm.listConfiguredPackages() as typeof configured;
+      } catch {
+        return [];
+      }
+      return configured
+        .filter((p) => !RESERVED.has(packageName(p.source)))
+        .map((p) => ({
+          source: p.source,
+          scope: p.scope === "project" ? "project" : "user",
+          filtered: !!p.filtered,
+          installed: !!p.installedPath,
+          installedPath: p.installedPath,
+        }));
+    },
+
+    async add(source: string): Promise<{ ok: boolean; message?: string }> {
+      const src = source.trim();
+      if (!src) return { ok: false, message: "No package specified." };
+      if (RESERVED.has(packageName(src))) return { ok: false, message: "That extension is managed by Privateer." };
+      try {
+        await pm.installAndPersist(src, { local: false });
+        return { ok: true };
+      } catch (e) {
+        return { ok: false, message: (e as Error).message };
+      }
+    },
+
+    async remove(source: string): Promise<{ ok: boolean; message?: string }> {
+      const src = source.trim();
+      if (!src) return { ok: false, message: "No package specified." };
+      try {
+        const removed = await pm.removeAndPersist(src, { local: false });
+        return removed ? { ok: true } : { ok: false, message: "Not installed." };
+      } catch (e) {
+        return { ok: false, message: (e as Error).message };
+      }
+    },
+
+    setProgress(cb: ((ev: ProgressEvent) => void) | undefined): void {
+      pm.setProgressCallback(cb);
+    },
+  };
+}

package/src/remote/liveTaskSession.ts

@@ -0,0 +1,218 @@
+// A live, app-drivable agent session spawned on demand by the daemon (task_spawn,
+// mode:"live"). Unlike a headless task (daemon/index.ts runTask → restricted tools +
+// bypass gate + outbox), this stands up a FULL interactive session behind its own relay
+// terminal so the app can attach and drive it in real time: stream tokens, approve each
+// tool, interrupt. It is the same wiring cli/chat.ts uses for `/remote-access`, factored
+// so the daemon can create one without a TTY.
+//
+// SAFETY: the gate runs in "default" mode, so on a driven turn every gated tool relays to
+// the app for allow/deny (bridge.remoteAsk) and fail-closes if the controller is gone —
+// full tools are safe precisely because a human is watching and approving. localAsk denies
+// (there is no terminal to prompt), and remote-unsafe tools (subagents) are blocked.
+import { randomUUID } from "node:crypto";
+import {
+  createAgentSessionServices,
+  createAgentSessionFromServices,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { agentDir } from "../config/paths.ts";
+import { agentVersion } from "../config/version.ts";
+import { createEngineEventAdapter } from "../bridge/engineAdapter.ts";
+import { makePermissionGate, isRemoteUnsafeTool, type GateController } from "../ext/permissionGate.ts";
+import { makePiPrivacyExtension } from "pi-privacy";
+import { makeAccountProvider } from "../providers/account.ts";
+import { RelayClient, type TaskSpec } from "./relayClient.ts";
+import { RemoteBridge } from "./remoteBridge.ts";
+import { spawnAccountCredentials, revokeAccountSession } from "../auth/privateer.ts";
+
+export interface LiveTaskHandle {
+  termId: string;
+  label: string;
+  stop: () => Promise<void>;
+}
+
+export interface LiveTaskDeps {
+  defaultModel: string;
+  parseSpec: (spec: string) => { provider: string; modelId: string };
+  log: (msg: string) => void;
+  onClosed: (termId: string) => void;
+}
+
+// How long to keep a spawned session alive with NO controller ever attaching, and the
+// hard ceiling on any one session's lifetime (a driven session left open is reaped so an
+// abandoned spawn can't run the account meter or hold resources forever).
+const ATTACH_GRACE_MS = 180_000; // 3 min to attach after spawn
+const MAX_LIFETIME_MS = 30 * 60_000; // 30 min absolute cap
+
+export async function createLiveTaskSession(spec: TaskSpec, deps: LiveTaskDeps): Promise<LiveTaskHandle> {
+  const cwd = spec.cwd && spec.cwd.trim() ? spec.cwd : process.cwd();
+  const modelSpec = spec.model && spec.model.trim() ? spec.model : deps.defaultModel;
+  const title = spec.title && spec.title.trim() ? spec.title.trim() : "";
+  const termId = `task-${randomUUID()}`;
+  const label = title ? `Task: ${title}`.slice(0, 60) : "Privateer Task";
+
+  let relay: RelayClient | undefined;
+  let session: any;
+  let turnActive = false;
+  let attached = false;
+  let initialPromptSent = false;
+  let stopped = false;
+  let spawnedAccount = false;
+  let servicesRef: { authStorage?: { remove?: (p: string) => void } } | null = null;
+
+  let attachTimer: ReturnType<typeof setTimeout> | undefined;
+  let lifeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    stopped = true;
+    if (attachTimer) clearTimeout(attachTimer);
+    if (lifeTimer) clearTimeout(lifeTimer);
+    try { relay?.stop(); } catch { /* already stopped */ }
+    // Revoke ONLY this session's account inference session so it doesn't linger in the
+    // app's Linked Devices; the daemon's own child session stays alive. Best-effort.
+    if (spawnedAccount) {
+      try { await revokeAccountSession(); } catch { /* server TTL is the fallback */ }
+      try { servicesRef?.authStorage?.remove?.("privateer"); } catch { /* nothing persisted */ }
+    }
+    deps.onClosed(termId);
+    deps.log(`live task ${termId} closed`);
+  };
+
+  const runTurn = async (text: string): Promise<void> => {
+    if (turnActive || stopped) return;
+    turnActive = true;
+    try {
+      await session.prompt(text);
+    } catch (e) {
+      deps.log(`live task ${termId} turn error: ${(e as Error).message}`);
+    } finally {
+      turnActive = false;
+      bridge.settleTurn();
+    }
+  };
+
+  const bridge = new RemoteBridge({
+    onPrompt: (text) => void runTurn(text),
+    onInterrupt: () => void session?.abort?.(),
+    // Slash commands from the app composer fall through to the turn loop (Pi executes
+    // extension/skill commands via prompt). No local dispatcher here — this is headless.
+    onCommand: (text) => void runTurn(text),
+    onControllerAttached: () => {
+      attached = true;
+      if (attachTimer) { clearTimeout(attachTimer); attachTimer = undefined; }
+      relay?.sendSnapshot([]);
+      relay?.sendContext({ model: modelSpec, version: agentVersion() });
+      relay?.sendCommands([]);
+      // Deliver the spawn's initial prompt exactly once, THROUGH the bridge's own prompt
+      // path so it counts as a driven turn (remote=true → tools relay to the app).
+      if (!initialPromptSent && spec.prompt && spec.prompt.trim()) {
+        initialPromptSent = true;
+        bridge.callbacks.onPrompt(spec.prompt);
+      }
+    },
+    onTerminate: () => void stop(),
+    onStatus: (t) => deps.log(`live task ${termId}: ${t}`),
+  });
+
+  const gate: GateController = {
+    getMode: () => "default",
+    setMode: () => {},
+    allowlist: [],
+    allowedOutsideRoots: [],
+    cwd,
+    confineToCwd: true,
+    // No terminal to ask — a LOCAL turn can't happen here, but fail closed if one ever
+    // reaches this path.
+    async localAsk() {
+      return "deny";
+    },
+    getRemote: bridge.getRemote,
+    getNoQuarter: bridge.getNoQuarter,
+    remoteAsk: bridge.remoteAsk,
+    blockedWhenRemote: isRemoteUnsafeTool,
+    onRemoteBlocked: (toolName) => bridge.sendNotice(`${toolName} is disabled while driving remotely — its prompts can't reach the app.`),
+  };
+
+  const services = await createAgentSessionServices({
+    cwd,
+    agentDir: agentDir(),
+    resourceLoaderOptions: {
+      extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+    },
+  });
+  servicesRef = services as any;
+
+  const { provider, modelId } = deps.parseSpec(modelSpec);
+  if (provider === "privateer") {
+    try {
+      const creds = await spawnAccountCredentials();
+      (services.authStorage as any).set("privateer", { type: "oauth", ...creds });
+      spawnedAccount = true;
+    } catch (e) {
+      deps.log(`live task ${termId} account channel unavailable: ${(e as Error).message}`);
+    }
+  }
+
+  // From here on any failure MUST tear down (stop() revokes the account child session we
+  // just spawned + closes the relay), or a throw would leak an orphaned account "device"
+  // until its token TTL. Everything post-account-spawn runs under one guard.
+  try {
+  const model = (services.modelRegistry as any).find(provider, modelId);
+  if (!model) {
+    throw new Error(`model ${provider}/${modelId} not found`);
+  }
+
+  ({ session } = await createAgentSessionFromServices({
+    services,
+    sessionManager: SessionManager.inMemory(cwd),
+    model,
+    // No `tools` restriction: a live session gets Pi's full toolset, made safe by the
+    // per-tool relay-to-app approval above.
+  } as any));
+
+  // Relay the extension mid-turn UI (select/confirm/input) to the app when driven, so an
+  // extension asking a question doesn't silently cancel. Mirrors cli/chat.ts's uiContext.
+  const driven = (): boolean => bridge.getRemote() && bridge.isConnected();
+  const uiContext = {
+    async select(t: string, options: string[], opts?: { signal?: AbortSignal }): Promise<string | undefined> {
+      if (!options.length) return undefined;
+      if (!driven()) return undefined;
+      const choice = await bridge.selectRemote({ title: t, options: options.map((o) => ({ value: o, label: o })) }, opts?.signal);
+      return choice ?? undefined;
+    },
+    async confirm(t: string, message: string, opts?: { signal?: AbortSignal }): Promise<boolean> {
+      if (!driven()) return false;
+      const choice = await bridge.selectRemote({ title: t || message, options: [{ value: "yes", label: "Yes" }, { value: "no", label: "No" }] }, opts?.signal);
+      return choice === "yes";
+    },
+    async input(t: string, placeholder?: string, opts?: { signal?: AbortSignal }): Promise<string | undefined> {
+      if (!driven()) return undefined;
+      const value = await bridge.inputRemote({ title: t, placeholder }, opts?.signal);
+      return value ?? undefined;
+    },
+    notify(message: string): void {
+      if (driven()) bridge.sendNotice(message);
+    },
+  };
+  await (session as any).bindExtensions({ uiContext });
+
+  const adapter = createEngineEventAdapter();
+  session.subscribe((ev: any) => {
+    for (const ee of adapter.toEngineEvents(ev)) bridge.forwardEvent(ee);
+  });
+
+  relay = new RelayClient(bridge.callbacks, { termId, label });
+  bridge.attachRelay(relay);
+  await relay.start();
+
+  // Reap if nobody ever attaches, and cap the absolute lifetime regardless.
+  attachTimer = setTimeout(() => { if (!attached) void stop(); }, ATTACH_GRACE_MS);
+  lifeTimer = setTimeout(() => void stop(), MAX_LIFETIME_MS);
+  } catch (err) {
+    await stop(); // revoke the account child session + close the relay before propagating
+    throw err;
+  }
+
+  return { termId, label, stop };
+}