@cueloop/daemon 0.1.0-alpha.11 → 0.1.0-alpha.111

package/src/harness-handoff.ts

@@ -0,0 +1,27 @@
+import type { Thread, ThreadAgentState } from "@cueloop/schema";
+
+/** Handoff transfers continuation context, never provider credentials or private session files. */
+export function harnessHandoffPrompt(thread: Thread, state: ThreadAgentState): string {
+  return `Prepare a continuation document for another agent taking over this Thread.
+Do not execute tools or change files. Return only the handoff text.
+Include the current goal, decisions, completed work, outstanding work, constraints, and suggested skills.
+Reference existing artifacts by path or URL instead of duplicating them.
+Redact credentials, passwords, and personal information.
+Thread: ${thread.id}
+Workspace: ${thread.workspace.repoRoot}
+Reviewed artifact:
+${thread.artifact.content.slice(0, 32768)}
+Pending continuation context:
+${state.continuation ?? ""}
+Recent conversation:
+${state.messages
+  .filter((message) => message.complete)
+  .map((message) => `${message.role}: ${message.text}`)
+  .join("\n")
+  .slice(-65536)}`;
+}
+
+/** The receiving agent treats the handoff as context rather than a fresh user instruction. */
+export function harnessContinuationPrompt(handoff: string, prompt: string): string {
+  return `Continuation context from the previous harness:\n${handoff}\n\nCurrent request:\n${prompt}`;
+}

package/src/harness-state-store.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HarnessStateStore } from "./harness-state-store";
+import { harnessStatePath } from "./paths";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-harness-state-"));
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("HarnessStateStore", () => {
+  test("redelivers an unacknowledged Message after reload", () => {
+    const store = new HarnessStateStore(home);
+    const binding = store.bind({
+      threadId: "ses_1",
+      harness: "fake",
+      harnessSessionId: "fake_1",
+    });
+    const delivery = store.enqueue({ bindingId: binding.id, messageId: "msg_1" });
+
+    expect(store.pending(binding.id)).toEqual([delivery]);
+
+    const reloaded = new HarnessStateStore(home);
+
+    expect(reloaded.pending(binding.id)).toEqual([delivery]);
+  });
+
+  test("does not redeliver an acknowledged Message", () => {
+    const store = new HarnessStateStore(home);
+    const binding = store.bind({
+      threadId: "ses_1",
+      harness: "fake",
+      harnessSessionId: "fake_1",
+    });
+    const delivery = store.enqueue({ bindingId: binding.id, messageId: "msg_1" });
+
+    store.acknowledge(delivery.id, "2026-09-20T20:00:00.000Z");
+
+    expect(new HarnessStateStore(home).pending(binding.id)).toEqual([]);
+  });
+
+  test("reuses the binding for the same harness session and thread", () => {
+    const store = new HarnessStateStore(home);
+    const input = {
+      threadId: "ses_1",
+      harness: "fake",
+      harnessSessionId: "fake_1",
+    };
+
+    expect(store.bind(input)).toEqual(store.bind(input));
+  });
+
+  test("deletes every harness binding and delivery for a Thread", () => {
+    const store = new HarnessStateStore(home);
+    const bindings = ["pi", "codex", "claude-code"].map((harness) =>
+      store.bind({ threadId: "ses_1", harness, harnessSessionId: `${harness}_1` }),
+    );
+    const deliveries = bindings.map((binding, index) =>
+      store.enqueue({ bindingId: binding.id, messageId: `msg_${index}` }),
+    );
+
+    expect(store.deleteThreadState("ses_1")).toBeTrue();
+    expect(store.deleteThreadState("ses_1")).toBeFalse();
+    const reloaded = new HarnessStateStore(home);
+
+    for (const binding of bindings) expect(reloaded.binding(binding.id)).toBeNull();
+    for (const delivery of deliveries) expect(reloaded.delivery(delivery.id)).toBeNull();
+  });
+
+  test("deletes state for Threads missing at startup", () => {
+    const store = new HarnessStateStore(home);
+
+    store.bind({ threadId: "ses_kept", harness: "pi", harnessSessionId: "pi_1" });
+    store.bind({ threadId: "ses_orphan", harness: "codex", harnessSessionId: "codex_1" });
+
+    expect(store.deleteOrphanedThreadState(new Set(["ses_kept"]))).toEqual(["ses_orphan"]);
+    expect(store.bindingsForSession("pi", "pi_1")).toHaveLength(1);
+    expect(store.bindingsForSession("codex", "codex_1")).toEqual([]);
+  });
+
+  test("does not discard pending deliveries when persisted state is corrupt", () => {
+    writeFileSync(harnessStatePath(home), "{broken");
+
+    expect(() => new HarnessStateStore(home)).toThrow();
+  });
+});

package/src/harness-state-store.ts

@@ -0,0 +1,218 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import type { Delivery, HarnessBinding } from "@cueloop/schema";
+import * as v from "valibot";
+import { harnessStatePath } from "./paths";
+import { DeliverySchema, HarnessBindingSchema } from "./validate";
+
+type BindInput = Pick<HarnessBinding, "threadId" | "harness" | "harnessSessionId">;
+type EnqueueInput = Pick<Delivery, "bindingId" | "messageId">;
+
+const HarnessStateSchema = v.object({
+  bindings: v.array(HarnessBindingSchema),
+  deliveries: v.array(DeliverySchema),
+});
+const FileErrorSchema = v.object({ code: v.string() });
+
+export class HarnessStateStore {
+  private readonly path: string;
+  private bindings = new Map<string, HarnessBinding>();
+  private deliveries = new Map<string, Delivery>();
+
+  constructor(home: string) {
+    this.path = harnessStatePath(home);
+    this.load();
+  }
+
+  bind(input: BindInput): HarnessBinding {
+    const existing = [...this.bindings.values()].find(
+      (binding) =>
+        binding.threadId === input.threadId &&
+        binding.harness === input.harness &&
+        binding.harnessSessionId === input.harnessSessionId,
+    );
+
+    if (existing) return existing;
+
+    const binding: HarnessBinding = {
+      ...input,
+      id: newRoutingId("bind"),
+      createdAt: new Date().toISOString(),
+    };
+
+    this.bindings.set(binding.id, binding);
+    this.persist();
+
+    return binding;
+  }
+
+  binding(id: string): HarnessBinding | null {
+    return this.bindings.get(id) ?? null;
+  }
+
+  bindingsForSession(harness: string, harnessSessionId: string): HarnessBinding[] {
+    return [...this.bindings.values()].filter(
+      (binding) => binding.harness === harness && binding.harnessSessionId === harnessSessionId,
+    );
+  }
+
+  deleteThreadState(threadId: string): boolean {
+    const bindingIds = new Set(
+      [...this.bindings.values()]
+        .filter((binding) => binding.threadId === threadId)
+        .map((binding) => binding.id),
+    );
+
+    return this.deleteBindingsAndDeliveries(bindingIds);
+  }
+
+  deleteOrphanedThreadState(existingThreadIds: ReadonlySet<string>): string[] {
+    const orphanedBindings = [...this.bindings.values()].filter(
+      (binding) => !existingThreadIds.has(binding.threadId),
+    );
+    const orphanedThreadIds = [...new Set(orphanedBindings.map((binding) => binding.threadId))];
+
+    this.deleteBindingsAndDeliveries(new Set(orphanedBindings.map((binding) => binding.id)));
+
+    return orphanedThreadIds;
+  }
+
+  private deleteBindingsAndDeliveries(bindingIds: ReadonlySet<string>): boolean {
+    if (bindingIds.size === 0) return false;
+
+    for (const bindingId of bindingIds) this.bindings.delete(bindingId);
+    for (const delivery of this.deliveries.values()) {
+      if (bindingIds.has(delivery.bindingId)) this.deliveries.delete(delivery.id);
+    }
+    this.persist();
+
+    return true;
+  }
+
+  consumeApprovedRetry(bindingId: string, messageId: string): boolean {
+    const binding = this.bindings.get(bindingId);
+
+    if (!binding) throw new Error(`no harness binding ${bindingId}`);
+
+    if (binding.approvedRetryMessageId === messageId) return false;
+
+    this.bindings.set(bindingId, { ...binding, approvedRetryMessageId: messageId });
+    this.persist();
+
+    return true;
+  }
+
+  /** The first binding is the submitter; other bindings need explicit future routing. */
+  submittingBinding(threadId: string): HarnessBinding | null {
+    return [...this.bindings.values()].find((binding) => binding.threadId === threadId) ?? null;
+  }
+
+  enqueue(input: EnqueueInput): Delivery {
+    const existing = [...this.deliveries.values()].find(
+      (delivery) =>
+        delivery.bindingId === input.bindingId && delivery.messageId === input.messageId,
+    );
+
+    if (existing) return existing;
+
+    const delivery: Delivery = {
+      ...input,
+      id: newRoutingId("del"),
+      status: "pending",
+      createdAt: new Date().toISOString(),
+    };
+
+    this.deliveries.set(delivery.id, delivery);
+    this.persist();
+
+    return delivery;
+  }
+
+  pending(bindingId: string): Delivery[] {
+    return [...this.deliveries.values()].filter(
+      (delivery) => delivery.bindingId === bindingId && delivery.status === "pending",
+    );
+  }
+
+  /** A pending delivery keeps its Thread's immutable Message body available for redelivery. */
+  pendingThreadIds(): Set<string> {
+    const ids = new Set<string>();
+
+    for (const delivery of this.deliveries.values()) {
+      if (delivery.status !== "pending") continue;
+
+      const binding = this.bindings.get(delivery.bindingId);
+
+      if (binding) ids.add(binding.threadId);
+    }
+
+    return ids;
+  }
+
+  acknowledged(bindingId: string, messageId: string): boolean {
+    return [...this.deliveries.values()].some(
+      (delivery) =>
+        delivery.bindingId === bindingId &&
+        delivery.messageId === messageId &&
+        delivery.status === "acknowledged",
+    );
+  }
+
+  delivery(deliveryId: string): Delivery | null {
+    return this.deliveries.get(deliveryId) ?? null;
+  }
+
+  acknowledge(deliveryId: string, acknowledgedAt = new Date().toISOString()): Delivery {
+    const delivery = this.deliveries.get(deliveryId);
+
+    if (!delivery) throw new Error(`no delivery ${deliveryId}`);
+
+    if (delivery.status === "acknowledged") return delivery;
+
+    const acknowledged: Delivery = {
+      ...delivery,
+      status: "acknowledged",
+      acknowledgedAt,
+    };
+
+    this.deliveries.set(deliveryId, acknowledged);
+    this.persist();
+
+    return acknowledged;
+  }
+
+  private load(): void {
+    let serialized: string;
+
+    try {
+      serialized = readFileSync(this.path, "utf8");
+    } catch (error) {
+      const parsed = v.safeParse(FileErrorSchema, error);
+
+      if (parsed.success && parsed.output.code === "ENOENT") {
+        return;
+      }
+
+      throw error;
+    }
+
+    const state = v.parse(HarnessStateSchema, JSON.parse(serialized));
+
+    this.bindings = new Map(state.bindings.map((binding) => [binding.id, binding]));
+    this.deliveries = new Map(state.deliveries.map((delivery) => [delivery.id, delivery]));
+  }
+
+  private persist(): void {
+    const temporaryPath = this.path + ".tmp";
+    const state = {
+      bindings: [...this.bindings.values()],
+      deliveries: [...this.deliveries.values()],
+    };
+
+    writeFileSync(temporaryPath, JSON.stringify(state, null, 2));
+    renameSync(temporaryPath, this.path);
+  }
+}
+
+function newRoutingId(prefix: "bind" | "del"): string {
+  return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}

package/src/herdr-split.test.ts

@@ -0,0 +1,106 @@
+/** launchHarnessInSplit: a stubbed herdr binary logs its argv, and the launcher splits the current pane, runs the harness in the new pane, and optionally types the plan-context seed - a no-op outside herdr. */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { launchHarnessInSplit } from "./herdr-split";
+
+const dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-split-"));
+
+/** A stub herdr binary that logs argv and prints the pane-split result (pane_id of the new split). */
+function makeStub(name: string, splitOk = true) {
+  const logPath = join(dir, `${name}.log`);
+  const binPath = join(dir, `${name}.sh`);
+  const splitResult = splitOk
+    ? `printf '{"result":{"pane":{"pane_id":"w1:p9"}}}'`
+    : `printf '{"result":{}}'`;
+
+  writeFileSync(
+    binPath,
+    `#!/bin/sh
+printf '%s\\n' "$*" >> "${logPath}"
+if [ "$1" = "pane" ] && [ "$2" = "split" ]; then ${splitResult}; fi
+exit 0
+`,
+  );
+  chmodSync(binPath, 0o755);
+
+  return { binPath, logPath };
+}
+
+function readLines(logPath: string): string[] {
+  if (!existsSync(logPath)) return [];
+
+  return readFileSync(logPath, "utf8").split("\n").filter(Boolean);
+}
+
+describe("launchHarnessInSplit", () => {
+  test("splits the current pane and runs the harness in the new pane", () => {
+    // Arrange
+    const stub = makeStub("run");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    const launched = launchHarnessInSplit({ command: "cc", cwd: "/repo/work" }, env);
+
+    // Assert
+    expect(launched).toBeTrue();
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo/work",
+      "pane send-text w1:p9 cc",
+      "pane send-keys w1:p9 enter",
+    ]);
+  });
+
+  test("types the plan-context seed into the split after launching", () => {
+    // Arrange
+    const stub = makeStub("seeded");
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    launchHarnessInSplit({ command: "pi", cwd: "/repo", seedText: "read plan ses_1" }, env);
+
+    // Assert
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo",
+      "pane send-text w1:p9 pi",
+      "pane send-keys w1:p9 enter",
+      "pane send-text w1:p9 read plan ses_1",
+    ]);
+  });
+
+  test("no-op outside herdr - returns false and spawns nothing", () => {
+    // Arrange
+    const stub = makeStub("outside");
+
+    // Act
+    const launched = launchHarnessInSplit(
+      { command: "cc", cwd: "/repo" },
+      { HERDR_BIN_PATH: stub.binPath },
+    );
+
+    // Assert
+    expect(launched).toBeFalse();
+    expect(existsSync(stub.logPath)).toBeFalse();
+  });
+
+  test("returns false when the split yields no pane id", () => {
+    // Arrange
+    const stub = makeStub("nopane", false);
+    const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
+
+    // Act
+    const launched = launchHarnessInSplit({ command: "cc", cwd: "/repo" }, env);
+
+    // Assert - the split ran but no harness was launched into a missing pane
+    expect(launched).toBeFalse();
+    expect(readLines(stub.logPath)).toEqual([
+      "pane split w1:p1 --direction right --ratio 0.4 --cwd /repo",
+    ]);
+  });
+});
+
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+});

package/src/herdr-split.ts

@@ -0,0 +1,90 @@
+/**
+ * Launches a bring-your-own review harness (claude code / pi / codex) in a herdr
+ * split beside the current pane - the Agent rail's "run it right here" spawn, so
+ * a reviewer chats with an agent about the plan without leaving the review tab.
+ * Best-effort and herdr-only: a no-op returning false outside herdr or on any
+ * spawn failure, each spawn bounded by a timeout.
+ */
+
+import { detectHerdr, type HerdrEnv } from "@cueloop/schema";
+import * as v from "valibot";
+
+const HERDR_SPAWN_TIMEOUT_MS = 2000;
+const SplitPaneSchema = v.object({
+  result: v.optional(v.object({ pane: v.optional(v.object({ pane_id: v.optional(v.string()) })) })),
+});
+
+/** How much of the current pane the launched harness split takes (herdr --ratio). */
+const HARNESS_SPLIT_RATIO = "0.4";
+
+export interface LaunchHarnessInSplitOptions {
+  command: string;
+  cwd: string;
+  seedText?: string;
+}
+
+/**
+ * Split the current pane and run the harness in it. Returns true when the split
+ * opened, false on any best-effort bail-out. No-op outside herdr.
+ */
+export function launchHarnessInSplit(
+  options: LaunchHarnessInSplitOptions,
+  env: HerdrEnv = process.env,
+): boolean {
+  const herdr = detectHerdr(env);
+
+  if (!herdr) return false;
+
+  try {
+    const split = Bun.spawnSync(
+      [
+        herdr.binPath,
+        "pane",
+        "split",
+        herdr.paneId,
+        "--direction",
+        "right",
+        "--ratio",
+        HARNESS_SPLIT_RATIO,
+        "--cwd",
+        options.cwd,
+      ],
+      { stdout: "pipe", stderr: "ignore", timeout: HERDR_SPAWN_TIMEOUT_MS },
+    );
+
+    if (split.exitCode !== 0) return false;
+
+    const parsed = v.safeParse(SplitPaneSchema, JSON.parse(split.stdout.toString()));
+
+    if (!parsed.success) return false;
+
+    const paneId = parsed.output.result?.pane?.pane_id;
+
+    if (!paneId) return false;
+
+    sendText(herdr.binPath, paneId, options.command);
+    sendKeys(herdr.binPath, paneId, "enter");
+
+    if (options.seedText) sendText(herdr.binPath, paneId, options.seedText);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sendText(binPath: string, paneId: string, text: string): void {
+  Bun.spawnSync([binPath, "pane", "send-text", paneId, text], {
+    stdout: "ignore",
+    stderr: "ignore",
+    timeout: HERDR_SPAWN_TIMEOUT_MS,
+  });
+}
+
+function sendKeys(binPath: string, paneId: string, keys: string): void {
+  Bun.spawnSync([binPath, "pane", "send-keys", paneId, keys], {
+    stdout: "ignore",
+    stderr: "ignore",
+    timeout: HERDR_SPAWN_TIMEOUT_MS,
+  });
+}

package/src/herdr-thread-surface-store.test.ts

@@ -0,0 +1,81 @@
+/** Herdr Thread-surface handles survive reload and reject corrupt records. */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HerdrThreadSurfaceStore } from "./herdr-thread-surface-store";
+import { herdrThreadSurfacesPath } from "./paths";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-herdr-store-"));
+});
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("HerdrThreadSurfaceStore", () => {
+  test("set then get returns the handle; get for an unknown session is null", () => {
+    const store = new HerdrThreadSurfaceStore(home);
+
+    store.set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    expect(store.get("ses_1")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+    expect(store.get("ses_missing")).toBeNull();
+  });
+
+  test("handles survive a reload from disk", () => {
+    new HerdrThreadSurfaceStore(home).set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    const reloaded = new HerdrThreadSurfaceStore(home);
+
+    expect(reloaded.get("ses_1")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+  });
+
+  test("delete removes the handle", () => {
+    const store = new HerdrThreadSurfaceStore(home);
+
+    store.set("ses_1", { tabId: "w1:t2", paneId: "w1:p2" });
+
+    store.delete("ses_1");
+
+    expect(store.get("ses_1")).toBeNull();
+  });
+
+  test("a corrupt file starts empty instead of throwing", () => {
+    writeFileSync(herdrThreadSurfacesPath(home), "not json");
+
+    const store = new HerdrThreadSurfaceStore(home);
+
+    expect(store.get("ses_1")).toBeNull();
+  });
+
+  test("malformed entries are dropped, well-formed ones survive", () => {
+    writeFileSync(
+      herdrThreadSurfacesPath(home),
+      JSON.stringify({
+        ses_ok: { tabId: "w1:t2", paneId: "w1:p2" },
+        ses_partial: { tabId: "w1:t2" },
+        ses_typed: { tabId: 1, paneId: 2 },
+        ses_invalid_mode: { tabId: "w1:t2", paneId: "w1:p3", mode: "window" },
+        ses_null: null,
+      }),
+    );
+
+    const store = new HerdrThreadSurfaceStore(home);
+
+    expect(store.get("ses_ok")).toEqual({ tabId: "w1:t2", paneId: "w1:p2" });
+    expect(store.get("ses_partial")).toBeNull();
+    expect(store.get("ses_typed")).toBeNull();
+    expect(store.get("ses_invalid_mode")).toBeNull();
+    expect(store.get("ses_null")).toBeNull();
+  });
+
+  test("a non-object top level starts empty", () => {
+    writeFileSync(herdrThreadSurfacesPath(home), JSON.stringify(["not", "a", "map"]));
+
+    expect(new HerdrThreadSurfaceStore(home).get("ses_1")).toBeNull();
+  });
+});

package/src/herdr-thread-surface-store.ts

@@ -0,0 +1,66 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as v from "valibot";
+import { herdrThreadSurfacesPath } from "./paths";
+
+/** Herdr-native handle, stored outside the canonical Thread. */
+export interface HerdrThreadSurfaceHandle {
+  mode?: "tab" | "pane";
+  layout?: "pair";
+  tabId: string;
+  paneId: string;
+}
+
+const HerdrThreadSurfaceHandleSchema = v.object({
+  tabId: v.string(),
+  paneId: v.string(),
+  mode: v.optional(v.picklist(["tab", "pane"])),
+  layout: v.optional(v.literal("pair")),
+});
+const HerdrThreadSurfaceMapSchema = v.record(v.string(), v.unknown());
+
+export class HerdrThreadSurfaceStore {
+  private surfaces = new Map<string, HerdrThreadSurfaceHandle>();
+  private readonly path: string;
+
+  constructor(home: string) {
+    this.path = herdrThreadSurfacesPath(home);
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      const parsed = v.parse(
+        HerdrThreadSurfaceMapSchema,
+        JSON.parse(readFileSync(this.path, "utf8")),
+      );
+
+      for (const [sessionId, value] of Object.entries(parsed)) {
+        const handle = v.safeParse(HerdrThreadSurfaceHandleSchema, value);
+
+        if (handle.success) this.surfaces.set(sessionId, handle.output);
+      }
+    } catch {
+      // A missing or corrupt side-store cannot block a pending Thread.
+    }
+  }
+
+  private persist(): void {
+    const tempPath = this.path + ".tmp";
+
+    writeFileSync(tempPath, JSON.stringify(Object.fromEntries(this.surfaces), null, 2));
+    renameSync(tempPath, this.path);
+  }
+
+  get(sessionId: string): HerdrThreadSurfaceHandle | null {
+    return this.surfaces.get(sessionId) ?? null;
+  }
+
+  set(sessionId: string, handle: HerdrThreadSurfaceHandle): void {
+    this.surfaces.set(sessionId, handle);
+    this.persist();
+  }
+
+  delete(sessionId: string): void {
+    if (this.surfaces.delete(sessionId)) this.persist();
+  }
+}