privateer-agent 0.3.6 → 0.4.0

package/src/remote/relayClient.ts

@@ -34,6 +34,36 @@ function terminalLabel(): string {
 // bounds size, this bounds obvious secret leakage (bearer tokens, API keys, env
 // secrets, PEM private keys). The "output may contain secrets" warning still
 // stands; a determined leak (unusual formats) can slip through.
+// Pull the account signature / freshness ts off a control frame, if well-formed.
+// Undefined when absent or the wrong type → the terminal's authorizeControl fails
+// closed (an unsigned mutation is refused).
+function sig(frame: { sig?: unknown }): string | undefined {
+  return typeof frame.sig === "string" ? frame.sig : undefined;
+}
+function tsOf(frame: { ts?: unknown }): number | undefined {
+  return typeof frame.ts === "number" ? frame.ts : undefined;
+}
+
+// Parse a task_submit/task_spawn frame into a TaskSpec, keeping ONLY well-typed,
+// present fields (absent → left undefined). The daemon re-derives the canonical signed
+// args from this (taskControlArgs, undefined → null), so it must not invent fields.
+export function parseTaskSpec(frame: {
+  prompt?: string;
+  cwd?: string;
+  model?: string;
+  title?: string;
+  tools?: unknown;
+}): TaskSpec {
+  const spec: TaskSpec = { prompt: typeof frame.prompt === "string" ? frame.prompt : "" };
+  if (typeof frame.cwd === "string") spec.cwd = frame.cwd;
+  if (typeof frame.model === "string") spec.model = frame.model;
+  if (typeof frame.title === "string") spec.title = frame.title;
+  if (Array.isArray(frame.tools) && frame.tools.every((t) => typeof t === "string")) {
+    spec.tools = frame.tools as string[];
+  }
+  return spec;
+}
+
 function redactSecrets(s: string): string {
   if (!s) return s;
   return s
@@ -49,6 +79,19 @@ function safe(s: string, max: number): string {
   return clip(redactSecrets(s), max);
 }
 
+// An ad-hoc task the app asks the daemon to run headlessly (task_submit) or to spawn
+// as a live-drivable session (task_spawn). Only `prompt` is required; the rest fall back
+// to daemon defaults. The SAME field set is what the app canonical-signs into the control
+// envelope (client/services/accountSign.ts) and the daemon re-derives to verify (index.ts
+// taskControlArgs) — keep the two in sync, byte for byte, like the other signed frames.
+export interface TaskSpec {
+  prompt: string;
+  cwd?: string;
+  model?: string;
+  tools?: string[];
+  title?: string;
+}
+
 export interface RelayCallbacks {
   // A prompt arrived from the app — feed it into the turn loop (tagged remote).
   onPrompt: (text: string) => void;
@@ -59,6 +102,13 @@ export interface RelayCallbacks {
   // client and not reconnect. Optional: the routines daemon handles it too, but
   // callbacks that predate it keep compiling.
   onTerminate?: () => void;
+  // The account signed this terminal out server-side (revoked from the app's
+  // Linked Devices). Distinct from onTerminate: that only ends remote-access and
+  // leaves the login intact, whereas this wipes the machine login too. The owner
+  // should tear down the session (clear credentials, announce it) AND stop the
+  // relay. Optional so callbacks that predate the frame keep compiling; an older
+  // CLI that ignores it still gets signed out by the ≤25s heartbeat kill.
+  onRevoked?: () => 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
@@ -67,6 +117,86 @@ export interface RelayCallbacks {
   onNoQuarter?: (on: boolean) => void;
   // A controller attached — push a transcript snapshot so it can catch up.
   onControllerAttached: () => void;
+  // The app ran a slash command from its composer (e.g. "/model provider/id").
+  // Routed to the same command dispatcher the local REPL uses. Optional so
+  // callbacks that predate the app command UI keep compiling.
+  onCommand?: (text: string) => void;
+  // The app answered a CLI-initiated selection prompt (the id from requestSelect).
+  // A null value means the app dismissed the picker without choosing.
+  onSelectResponse?: (id: string, value: string | null) => void;
+  // The app answered a CLI-initiated text-input prompt (the id from requestInput).
+  // A null value means the app dismissed the prompt without submitting.
+  onInputResponse?: (id: string, value: string | null) => void;
+  // The app opened the extensions manager — reply with the current installed list
+  // (a sendExtensions frame). Optional so pre-extensions callbacks keep compiling.
+  onExtensionsList?: () => void;
+  // The app asked to install a Pi extension by source spec (npm:/git:/path).
+  // `sig`+`ts` authenticate the mutation with the account key (H2, verified via
+  // controlAuth) — a forged extensions_add would install attacker code, so it's signed.
+  onExtensionsAdd?: (source: string, sig?: string, ts?: number) => void;
+  // The app asked to remove a previously-installed extension by source spec.
+  onExtensionsRemove?: (source: string, sig?: string, ts?: number) => void;
+  // The app opened the skills manager — reply with the current skills list
+  // (a sendSkills frame). Optional so pre-skills callbacks keep compiling.
+  onSkillsList?: () => void;
+  // The app asked to create/overwrite a user skill (name + description + body). Signed
+  // (H2) — a forged skill would inject an auto-invoked system-prompt instruction.
+  onSkillCreate?: (skill: { name: string; description: string; instructions: string }, sig?: string, ts?: number) => void;
+  // The app asked to delete a user skill by name.
+  onSkillDelete?: (name: string, sig?: string, ts?: number) => void;
+  // The app toggled a user skill's model-invocation availability.
+  onSkillSetEnabled?: (name: string, enabled: boolean, sig?: string, ts?: number) => void;
+  // The app opened the routines manager — reply with the current routines list
+  // (a sendRoutines frame). Owned by the daemon, so these only fire on its relay.
+  onRoutinesList?: () => void;
+  // The app asked to create (no id) or edit (id) a routine. The raw draft object is
+  // handed through untyped; the daemon's routinesControl validates it. Signed (H2) —
+  // a forged routine runs a headless bypass-mode session (RCE), so it MUST be verified.
+  onRoutinesSave?: (draft: Record<string, unknown>, sig?: string, ts?: number) => void;
+  // The app asked to delete a routine by id or name.
+  onRoutinesDelete?: (idOrName: string, sig?: string, ts?: number) => void;
+  // The app paused/resumed a routine by id or name.
+  onRoutinesSetEnabled?: (idOrName: string, enabled: boolean, sig?: string, ts?: number) => void;
+  // The app asked to run a routine now, by id or name.
+  onRoutinesRun?: (idOrName: string, sig?: string, ts?: number) => void;
+  // The app submitted an AD-HOC one-shot task (not a stored routine) to run headlessly
+  // right now — a fresh restricted-tool bypass session whose result is sealed to the
+  // account outbox. Signed (H2) — a forged task_submit runs an arbitrary headless
+  // session (RCE), identical in blast radius to a forged routines_run, so it MUST be
+  // verified via controlAuth before it runs. Daemon-owned (fires only on its relay).
+  onTaskSubmit?: (spec: TaskSpec, sig?: string, ts?: number) => void;
+  // The app asked to SPAWN a fresh interactive session it can drive live (mode:"live").
+  // The daemon stands up a new RemoteBridge terminal and replies (sendTaskSpawned) with
+  // its termId so the app can attach. Same signed-RCE gate as task_submit.
+  onTaskSpawn?: (spec: TaskSpec, sig?: string, ts?: number) => void;
+  // The app opened the channels manager — reply with the current channel config
+  // (a sendChannels frame). Owned by the daemon, so these only fire on its relay.
+  onChannelsList?: () => void;
+  // The app asked to create/edit a platform's channel config. `draft` carries only
+  // NON-secret fields (roles/posture/tools/model). `sealedSecrets`, when present, is
+  // a base64 sealed-box the app sealed to THIS terminal's pinned pubkey (opened by the
+  // owner). `sig`+`ts` authenticate the WHOLE save with the account key the terminal
+  // pinned at link (accountVerify) — the owner rejects an unsigned/forged/stale save,
+  // so a hostile relay can neither forge a token nor inject an admin.
+  onChannelsSave?: (draft: Record<string, unknown>, sealedSecrets?: string, sig?: string, ts?: number) => void;
+  // The app asked to delete a platform's channel config, by platform name. Signed
+  // (H2) — a forged removal is a DoS (the bot stops until re-added).
+  onChannelsRemove?: (platform: string, sig?: string, ts?: number) => void;
+  // The app opened the workflows manager — reply with the current workflow summaries
+  // (a sendWorkflows frame). Owned by the daemon, so these only fire on its relay.
+  onWorkflowsList?: () => void;
+  // The app opened one workflow in its editor — reply with the full graph (sendWorkflow).
+  onWorkflowsGet?: (idOrName: string) => void;
+  // The app asked to create (no workflow.id) or edit (id) a workflow. The raw graph is
+  // handed through untyped; the daemon's workflowsControl strict-validates it. Signed
+  // (H2) — a forged save plants a `script` step that BYPASSES the permission gate (RCE),
+  // exactly like a forged routine, so it MUST be verified before it persists.
+  onWorkflowsSave?: (draft: Record<string, unknown>, sig?: string, ts?: number) => void;
+  // The app asked to delete a workflow by id or name. Signed (H2).
+  onWorkflowsRemove?: (idOrName: string, sig?: string, ts?: number) => void;
+  // The app asked to run a workflow now, by id or name. Signed (H2) and verified in
+  // STRICT mode (it executes a graph — non-idempotent, like task_spawn).
+  onWorkflowsRun?: (idOrName: string, sig?: string, ts?: number) => void;
   // A file finished transferring from the app (reassembled from chunks). Held to
   // ride along with the next remote prompt.
   onAttachment: (file: { name: string; mediaType: string; base64: string }) => void;
@@ -160,6 +290,13 @@ export class RelayClient {
     this.label = opts?.label ?? terminalLabel();
   }
 
+  // This terminal's relay id — the value the app signs into a control envelope's
+  // `termId` and the terminal verifies against (authorizeControl). Exposed so the
+  // interactive handlers (extensions_*/skills_*) can bind their own id.
+  get id(): string {
+    return this.termId;
+  }
+
   async start(): Promise<void> {
     this.closed = false;
     await this.connect();
@@ -255,6 +392,24 @@ export class RelayClient {
       seq?: number;
       data?: string;
       on?: boolean;
+      value?: string;
+      source?: string;
+      description?: string;
+      instructions?: string;
+      enabled?: boolean;
+      idOrName?: string;
+      routine?: Record<string, unknown>;
+      platform?: string;
+      draft?: Record<string, unknown>;
+      sealedSecrets?: string;
+      prompt?: string;
+      cwd?: string;
+      model?: string;
+      title?: string;
+      tools?: unknown;
+      mode?: string;
+      sig?: string;
+      ts?: number;
     };
     try {
       frame = JSON.parse(data.toString());
@@ -275,6 +430,9 @@ export class RelayClient {
       case "terminate":
         this.cb.onTerminate?.();
         break;
+      case "session_revoked":
+        this.cb.onRevoked?.();
+        break;
       case "approval_response":
         if (frame.id) this.cb.onApprovalResponse(frame.id, frame.decision === "deny" ? "deny" : "allow");
         break;
@@ -284,6 +442,100 @@ export class RelayClient {
       case "controller_attached":
         this.cb.onControllerAttached();
         break;
+      case "command":
+        if (typeof frame.text === "string") this.cb.onCommand?.(frame.text);
+        break;
+      case "select_response":
+        if (frame.id) this.cb.onSelectResponse?.(frame.id, typeof frame.value === "string" ? frame.value : null);
+        break;
+      case "input_response":
+        if (frame.id) this.cb.onInputResponse?.(frame.id, typeof frame.value === "string" ? frame.value : null);
+        break;
+      case "extensions_list":
+        this.cb.onExtensionsList?.();
+        break;
+      case "extensions_add":
+        if (typeof frame.source === "string") this.cb.onExtensionsAdd?.(frame.source, sig(frame), tsOf(frame));
+        break;
+      case "extensions_remove":
+        if (typeof frame.source === "string") this.cb.onExtensionsRemove?.(frame.source, sig(frame), tsOf(frame));
+        break;
+      case "skills_list":
+        this.cb.onSkillsList?.();
+        break;
+      case "skills_create":
+        if (typeof frame.name === "string") {
+          this.cb.onSkillCreate?.(
+            {
+              name: frame.name,
+              description: typeof frame.description === "string" ? frame.description : "",
+              instructions: typeof frame.instructions === "string" ? frame.instructions : "",
+            },
+            sig(frame),
+            tsOf(frame),
+          );
+        }
+        break;
+      case "skills_delete":
+        if (typeof frame.name === "string") this.cb.onSkillDelete?.(frame.name, sig(frame), tsOf(frame));
+        break;
+      case "skills_set_enabled":
+        if (typeof frame.name === "string") this.cb.onSkillSetEnabled?.(frame.name, frame.enabled === true, sig(frame), tsOf(frame));
+        break;
+      case "routines_list":
+        this.cb.onRoutinesList?.();
+        break;
+      case "routines_save":
+        if (frame.routine && typeof frame.routine === "object") this.cb.onRoutinesSave?.(frame.routine, sig(frame), tsOf(frame));
+        break;
+      case "routines_delete":
+        if (typeof frame.idOrName === "string") this.cb.onRoutinesDelete?.(frame.idOrName, sig(frame), tsOf(frame));
+        break;
+      case "routines_set_enabled":
+        if (typeof frame.idOrName === "string") this.cb.onRoutinesSetEnabled?.(frame.idOrName, frame.enabled === true, sig(frame), tsOf(frame));
+        break;
+      case "routines_run":
+        if (typeof frame.idOrName === "string") this.cb.onRoutinesRun?.(frame.idOrName, sig(frame), tsOf(frame));
+        break;
+      case "task_submit":
+        if (typeof frame.prompt === "string") this.cb.onTaskSubmit?.(parseTaskSpec(frame), sig(frame), tsOf(frame));
+        break;
+      case "task_spawn":
+        if (typeof frame.prompt === "string") this.cb.onTaskSpawn?.(parseTaskSpec(frame), sig(frame), tsOf(frame));
+        break;
+      case "channels_list":
+        this.cb.onChannelsList?.();
+        break;
+      case "channels_save":
+        if (frame.draft && typeof frame.draft === "object") {
+          this.cb.onChannelsSave?.(
+            frame.draft,
+            typeof frame.sealedSecrets === "string" ? frame.sealedSecrets : undefined,
+            sig(frame),
+            tsOf(frame),
+          );
+        }
+        break;
+      case "channels_remove":
+        if (typeof frame.platform === "string") this.cb.onChannelsRemove?.(frame.platform, sig(frame), tsOf(frame));
+        break;
+      case "workflows_list":
+        this.cb.onWorkflowsList?.();
+        break;
+      case "workflows_get":
+        if (typeof frame.idOrName === "string") this.cb.onWorkflowsGet?.(frame.idOrName);
+        break;
+      case "workflows_save":
+        // The graph rides in `draft` (same slot as channels_save), untyped — the daemon
+        // strict-validates it via workflowsControl.save after the signature check.
+        if (frame.draft && typeof frame.draft === "object") this.cb.onWorkflowsSave?.(frame.draft, sig(frame), tsOf(frame));
+        break;
+      case "workflows_remove":
+        if (typeof frame.idOrName === "string") this.cb.onWorkflowsRemove?.(frame.idOrName, sig(frame), tsOf(frame));
+        break;
+      case "workflows_run":
+        if (typeof frame.idOrName === "string") this.cb.onWorkflowsRun?.(frame.idOrName, sig(frame), tsOf(frame));
+        break;
       case "attach_begin":
         this.beginAttachment(frame);
         break;
@@ -368,6 +620,32 @@ export class RelayClient {
     return true;
   }
 
+  // Push a finished ad-hoc task result to any attached controller as a text event (the
+  // durable copy still goes to the outbox). Same shape as sendRoutineResult.
+  sendTaskResult(title: string, content: string): boolean {
+    if (!this.isConnected()) return false;
+    this.flushDeltas();
+    this.rawSend({ type: "event", event: { type: "text", text: safe(`⏺ Task "${title}"\n\n${content}`, 8000) } });
+    return true;
+  }
+
+  // Push a workflow's live step text / final result to any attached controller as a text
+  // event, so it renders in the daemon terminal's feed. Same durable-copy caveat as
+  // sendRoutineResult (the outbox is the source of truth).
+  sendWorkflowResult(name: string, content: string): boolean {
+    if (!this.isConnected()) return false;
+    this.flushDeltas();
+    this.rawSend({ type: "event", event: { type: "text", text: safe(`⏺ Workflow "${name}"\n\n${content}`, 8000) } });
+    return true;
+  }
+
+  // Tell the app that a live task session was stood up on `termId` (label for display),
+  // so it can open a controller connection to that terminal and drive it. Fire-and-forget
+  // over the daemon's management relay.
+  sendTaskSpawned(termId: string, label: string): void {
+    this.rawSend({ type: "task_spawned", termId, label });
+  }
+
   sendEvent(ev: EngineEvent): void {
     if (ev.type === "text") return this.bufferDelta("text", ev.text);
     if (ev.type === "reasoning") return this.bufferDelta("reasoning", ev.text);
@@ -428,13 +706,246 @@ export class RelayClient {
   // by design: deliberately NO cwd / hostname / username, matching terminalLabel's
   // stance (the server/controller learns as little as possible about the machine).
   // Empty/absent fields are omitted so the app renders less rather than blank.
-  sendContext(ctx: { model?: string; version?: string }): void {
+  sendContext(ctx: { model?: string; version?: string; terminalPub?: string }): void {
     const frame: Record<string, unknown> = { type: "context" };
     if (typeof ctx.model === "string" && ctx.model) frame.model = ctx.model;
     if (typeof ctx.version === "string" && ctx.version) frame.version = ctx.version;
+    // The terminal's identity public key (base64). NOT PII — it's a public key, and
+    // the app uses it to confirm this terminal is the one it PINNED at link time
+    // before sealing any secret to it (channel tokens). A malicious relay can swap
+    // it, which is exactly why the app checks it against the link-time pin.
+    if (typeof ctx.terminalPub === "string" && ctx.terminalPub) frame.terminalPub = ctx.terminalPub;
     this.rawSend(frame);
   }
 
+  // A one-line notice for the app's feed (e.g. "model → …", "unknown command").
+  // The generic command-feedback channel back to the driver.
+  sendNotice(text: string): void {
+    this.rawSend({ type: "notice", text: safe(text, 500) });
+  }
+
+  // Advertise the terminal's available slash commands (this CLI's built-ins PLUS
+  // whatever Pi extensions have registered) so the app's composer can autocomplete
+  // them. Pushed on controller attach. NON-PII: command names + descriptions only.
+  sendCommands(commands: { name: string; description?: string }[]): void {
+    this.rawSend({
+      type: "commands",
+      commands: commands.slice(0, 200).map((c) => ({ name: c.name, description: c.description ? safe(c.description, 200) : undefined })),
+    });
+  }
+
+  // Push the terminal's installed Pi extensions (the user's own packages; the moat
+  // is excluded upstream) to the app's extensions manager. Sent on request and after
+  // each add/remove. `busy` drives a progress indicator; `needsRestart` tells the app
+  // the change only takes effect on the next terminal launch. NON-PII: package
+  // sources + scope only. Installed list bounded like sendCommands.
+  sendExtensions(payload: {
+    installed: { source: string; scope: string; filtered?: boolean; installed?: boolean }[];
+    busy?: boolean;
+    message?: string;
+    needsRestart?: boolean;
+  }): void {
+    this.rawSend({
+      type: "extensions",
+      installed: payload.installed.slice(0, 200).map((e) => ({
+        source: safe(e.source, 200),
+        scope: e.scope === "project" ? "project" : "user",
+        filtered: !!e.filtered,
+        installed: !!e.installed,
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? safe(payload.message, 500) : undefined,
+      needsRestart: !!payload.needsRestart,
+    });
+  }
+
+  // Push the terminal's skills (user-authored + read-only package/project ones) to
+  // the app's skills manager. Sent on request and after each create/delete/toggle.
+  // `busy` drives a progress indicator; `needsRestart` tells the app a change only
+  // reaches the model (the <available_skills> prompt block) on the next launch —
+  // Run-now via /skill:name works immediately. NON-PII: names + descriptions +
+  // coarse source only. Items bounded like sendExtensions.
+  sendSkills(payload: {
+    items: { name: string; description: string; source: string; editable: boolean; disabled: boolean }[];
+    busy?: boolean;
+    message?: string;
+    needsRestart?: boolean;
+  }): void {
+    this.rawSend({
+      type: "skills",
+      items: payload.items.slice(0, 200).map((s) => ({
+        name: safe(s.name, 200),
+        description: safe(s.description, 1024),
+        source: safe(s.source, 200),
+        editable: !!s.editable,
+        disabled: !!s.disabled,
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? safe(payload.message, 500) : undefined,
+      needsRestart: !!payload.needsRestart,
+    });
+  }
+
+  // Push the daemon's saved routines to the app's routines manager. Sent on request
+  // and after each save/delete/pause/run. `busy` drives a progress indicator;
+  // `message` carries a one-line result/error. Unlike the feed/webhook paths this is
+  // the user's OWN config echoed back to their OWN app, so fields are size-clipped
+  // (clip, NOT redactSecrets) to keep an edit round-tripping faithfully — a prompt
+  // containing a literal "KEY=…" example must survive intact. List bounded like the
+  // other managers.
+  sendRoutines(payload: {
+    items: {
+      id: string;
+      name: string;
+      cron?: string;
+      at?: string;
+      prompt: string;
+      cwd: string;
+      model?: string;
+      delivery: string[];
+      tools?: string[];
+      enabled: boolean;
+      lastRun?: string;
+      lastStatus?: "ok" | "error";
+      lastError?: string;
+      nextRun?: string;
+    }[];
+    busy?: boolean;
+    message?: string;
+  }): void {
+    this.rawSend({
+      type: "routines",
+      items: payload.items.slice(0, 200).map((r) => ({
+        id: r.id,
+        name: clip(r.name, 200),
+        cron: r.cron ? clip(r.cron, 200) : undefined,
+        at: r.at ? clip(r.at, 64) : undefined,
+        prompt: clip(r.prompt, 8000),
+        cwd: clip(r.cwd, 1024),
+        model: r.model ? clip(r.model, 200) : undefined,
+        delivery: (r.delivery ?? []).slice(0, 20).map((d) => clip(String(d), 128)),
+        tools: r.tools ? r.tools.slice(0, 100).map((t) => clip(String(t), 128)) : undefined,
+        enabled: !!r.enabled,
+        lastRun: r.lastRun,
+        lastStatus: r.lastStatus,
+        lastError: r.lastError ? clip(r.lastError, 1000) : undefined,
+        nextRun: r.nextRun,
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? clip(payload.message, 500) : undefined,
+    });
+  }
+
+  // Push the daemon's channel config to the app's channels manager. Sent on request
+  // and after each save/remove. Like sendRoutines this is the user's OWN config
+  // echoed to their OWN app — but a bot token NEVER crosses this wire: only
+  // `secretsSet` (which secret fields are present, by NAME) is sent, so a relay /
+  // server compromise can't lift a token from this frame. List bounded like the
+  // other managers.
+  sendChannels(payload: {
+    items: {
+      platform: string;
+      configured: boolean;
+      running: boolean;
+      adminCount: number;
+      memberCount: number;
+      posture: string;
+      tools: string[];
+      model?: string;
+      secretsSet: string[];
+    }[];
+    busy?: boolean;
+    message?: string;
+  }): void {
+    this.rawSend({
+      type: "channels",
+      items: payload.items.slice(0, 20).map((c) => ({
+        platform: clip(String(c.platform), 32),
+        configured: !!c.configured,
+        running: !!c.running,
+        adminCount: Math.max(0, Math.floor(c.adminCount) || 0),
+        memberCount: Math.max(0, Math.floor(c.memberCount) || 0),
+        posture: clip(String(c.posture), 32),
+        tools: (c.tools ?? []).slice(0, 100).map((t) => clip(String(t), 128)),
+        model: c.model ? clip(c.model, 200) : undefined,
+        secretsSet: (c.secretsSet ?? []).slice(0, 20).map((s) => clip(String(s), 64)),
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? clip(payload.message, 500) : undefined,
+    });
+  }
+
+  // Push the daemon's saved workflows to the app's workflows manager as SUMMARIES (not
+  // the full graphs — the editor fetches one at a time via sendWorkflow). Sent on request
+  // and after each save/remove/run. The user's OWN config echoed to their OWN app, so
+  // fields are clipped (not redacted). List bounded like the other managers.
+  sendWorkflows(payload: {
+    items: {
+      id: string;
+      name: string;
+      description?: string;
+      entryPoint: string;
+      stepCount: number;
+      gateCount: number;
+      scriptCount: number;
+    }[];
+    busy?: boolean;
+    message?: string;
+  }): void {
+    this.rawSend({
+      type: "workflows",
+      items: payload.items.slice(0, 200).map((w) => ({
+        id: w.id,
+        name: clip(w.name, 200),
+        description: w.description ? clip(w.description, 1000) : undefined,
+        entryPoint: clip(w.entryPoint, 64),
+        stepCount: Math.max(0, Math.floor(w.stepCount) || 0),
+        gateCount: Math.max(0, Math.floor(w.gateCount) || 0),
+        scriptCount: Math.max(0, Math.floor(w.scriptCount) || 0),
+      })),
+      busy: !!payload.busy,
+      message: payload.message ? clip(payload.message, 500) : undefined,
+    });
+  }
+
+  // Push ONE full workflow graph to the app's editor (reply to workflows_get). The graph
+  // is the user's own authored config, so it's sent whole (clipped only by the relay's
+  // per-frame cap); `null` means the requested workflow wasn't found.
+  sendWorkflow(workflow: unknown | null): void {
+    this.rawSend({ type: "workflow", workflow: workflow ?? null });
+  }
+
+  // Ask the app to pick from a set of options — a CLI-initiated selection prompt.
+  // The app renders the same picker as /model and replies with a select_response
+  // (resolved by the bridge). Generic so any future prompt reuses one UI.
+  requestSelect(
+    id: string,
+    req: { title: string; options: { value: string; label: string; hint?: string }[]; current?: string },
+  ): void {
+    this.rawSend({
+      type: "select_request",
+      id,
+      title: safe(req.title, 200),
+      options: req.options.slice(0, 500).map((o) => ({ value: o.value, label: safe(o.label, 200), hint: o.hint ? safe(o.hint, 200) : undefined })),
+      current: req.current,
+    });
+  }
+
+  // Ask the app for a line of free-form text — a CLI-initiated input prompt. The
+  // app renders a text field and replies with an input_response (resolved by the
+  // bridge). Companion to requestSelect for prompts that aren't a fixed choice.
+  requestInput(
+    id: string,
+    req: { title: string; placeholder?: string },
+  ): void {
+    this.rawSend({
+      type: "input_request",
+      id,
+      title: safe(req.title, 200),
+      placeholder: req.placeholder ? safe(req.placeholder, 200) : undefined,
+    });
+  }
+
   requestApproval(id: string, req: PermissionRequest): void {
     this.rawSend({
       type: "approval_request",