@otterware/openclaw-otter 0.1.3 → 0.2.1

package/control.js

@@ -1,12 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
 /** A held tab is released this long after Otter last sent input or a heartbeat (it quit, say). */
 export const CONTROL_TTL_MS = 30_000;
 /** How long a batch waits for one sent before it, before giving up on that one. */
 const GAP_MS = 150;
+/** A tab nobody watches or holds for this long loses its DevTools connection. */
+const IDLE_MS = 60_000;
+const EVENTS_KEPT = 200;
+const CALL_TIMEOUT_MS = 5_000;
+/** Files travel base64 in one gateway message (16 MB at most). */
+export const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+const UPLOADS_KEPT_MS = 10 * 60_000;
+
+/** What the agent's browser tool may still do while you hold a tab: read pages, not act on them. */
+export const READ_ACTIONS = new Set([
+  "doctor",
+  "status",
+  "tabs",
+  "snapshot",
+  "screenshot",
+  "requests",
+  "errors",
+  "text",
+]);
+
+const WORLD = "otter-watch";
+const BINDING = "__otterSaw";
+/**
+ * Runs in a world of its own, where the page can't see or stop it: where clicks land, the field
+ * being typed in, and what you copy (Chromium's clipboard isn't yours, so the copy is read here).
+ */
+const WATCH_SCRIPT = `(() => {
+  if (globalThis.${BINDING}Ready || window !== top) return;
+  globalThis.${BINDING}Ready = true;
+  const say = (event) => { try { ${BINDING}(JSON.stringify(event)); } catch {} };
+  let move = null;
+  addEventListener("pointermove", (event) => {
+    if (!event.isTrusted) return;
+    if (!move) setTimeout(() => { say(move); move = null; }, 33);
+    move = { type: "pointer", phase: "move", x: event.clientX, y: event.clientY };
+  }, true);
+  addEventListener("pointerdown", (event) => {
+    if (event.isTrusted) say({ type: "pointer", phase: "click", x: event.clientX, y: event.clientY });
+  }, true);
+  const field = () => {
+    let found = document.activeElement;
+    while (found?.shadowRoot?.activeElement) found = found.shadowRoot.activeElement;
+    return found;
+  };
+  let copying = false;
+  addEventListener("keydown", (event) => {
+    if (!event.isTrusted) return;
+    const key = event.key.toLowerCase();
+    if ((event.ctrlKey || event.metaKey) && !event.altKey && (key === "c" || key === "x")) {
+      copying = true;
+      setTimeout(() => { copying = false; });
+    }
+    const typed = field();
+    if (!typed || typed === document.body || typed === document.documentElement) return;
+    const box = typed.getBoundingClientRect();
+    say({ type: "typing", x: box.x, y: box.y, width: box.width, height: box.height });
+  }, true);
+  const selection = () => {
+    const typed = field();
+    if ((typed instanceof HTMLInputElement || typed instanceof HTMLTextAreaElement) && typed.selectionStart !== null)
+      return typed.value.slice(typed.selectionStart, typed.selectionEnd ?? typed.selectionStart);
+    return String(document.getSelection() ?? "");
+  };
+  for (const type of ["copy", "cut"]) {
+    addEventListener(type, (event) => {
+      if (copying && event.isTrusted) say({ type: "clipboard", text: selection().slice(0, 1048576) });
+    }, true);
+    addEventListener(type, (event) => {
+      if (!copying || !event.isTrusted || !event.defaultPrevented) return;
+      const text = event.clipboardData?.getData("text/plain");
+      if (text) say({ type: "clipboard", text: text.slice(0, 1048576) });
+    });
+  }
+})();`;
 
 const MOUSE_TYPES = { move: "mouseMoved", down: "mousePressed", up: "mouseReleased" };
 const BUTTONS = new Set(["none", "left", "middle", "right"]);
 const num = (value) => (Number.isFinite(value) ? value : 0);
 
+/** Headless Linux Chromium only copies, cuts (and with ⌘, selects all or undoes) when told to. */
+export function editingCommand(key, modifiers) {
+  const modifier = modifiers & 0b0111;
+  if (modifier !== 2 && modifier !== 4) return null;
+  const lower = key.toLowerCase();
+  const command =
+    lower === "c"
+      ? "copy"
+      : lower === "x"
+        ? "cut"
+        : modifier !== 4
+          ? null
+          : lower === "a"
+            ? "selectAll"
+            : lower === "z"
+              ? modifiers & 8
+                ? "redo"
+                : "undo"
+              : null;
+  return command ? { commands: [command] } : null;
+}
+
 /** The DevTools call that replays one of Otter's input events, as a person's input. */
 export function cdpInput(event) {
   const modifiers = num(event?.modifiers);
@@ -39,16 +140,22 @@ export function cdpInput(event) {
       ];
     case "key": {
       if (typeof event.key !== "string" || typeof event.code !== "string") return null;
+      if (event.action === "up")
+        return [
+          "Input.dispatchKeyEvent",
+          { type: "keyUp", key: event.key, code: event.code, modifiers },
+        ];
       const text = typeof event.text === "string" ? event.text : undefined;
       return [
         "Input.dispatchKeyEvent",
         {
-          type: event.action === "up" ? "keyUp" : text ? "keyDown" : "rawKeyDown",
+          type: text ? "keyDown" : "rawKeyDown",
           key: event.key,
           code: event.code,
           windowsVirtualKeyCode: num(event.keyCode),
           nativeVirtualKeyCode: num(event.keyCode),
           ...(text ? { text, unmodifiedText: text } : {}),
+          ...editingCommand(event.key, modifiers),
           modifiers,
         },
       ];
@@ -57,12 +164,26 @@ export function cdpInput(event) {
       return typeof event.text === "string"
         ? ["Input.insertText", { text: event.text.slice(0, 10_000) }]
         : null;
+    case "dialog":
+      return [
+        "Page.handleJavaScriptDialog",
+        {
+          accept: event.accept === true,
+          ...(typeof event.promptText === "string" ? { promptText: event.promptText } : {}),
+        },
+      ];
+    case "navigate":
+      return typeof event.url === "string" && /^https?:\/\//i.test(event.url)
+        ? ["Page.navigate", { url: event.url }]
+        : null;
+    case "reload":
+      return ["Page.reload", {}];
     default:
       return null;
   }
 }
 
-/** A page's own DevTools connection: input is sent without waiting for Chromium's replies. */
+/** A page's own DevTools connection. Input goes without waiting for Chromium's replies. */
 export async function connectTarget(cdpUrl, targetId) {
   const list = await fetch(new URL("/json/list", cdpUrl), { signal: AbortSignal.timeout(5000) })
     .then((response) => response.json())
@@ -83,79 +204,329 @@ export async function connectTarget(cdpUrl, targetId) {
     );
   });
   let id = 0;
+  const replies = new Map();
+  const listeners = new Set();
+  socket.addEventListener("message", ({ data }) => {
+    const message = JSON.parse(String(data));
+    if (message.id === undefined) {
+      for (const listener of listeners) listener(message.method, message.params ?? {});
+      return;
+    }
+    const reply = replies.get(message.id);
+    if (!reply) return;
+    replies.delete(message.id);
+    if (message.error) reply.reject(new Error(message.error.message));
+    else reply.resolve(message.result ?? {});
+  });
+  socket.addEventListener("close", () => {
+    for (const reply of replies.values()) reply.reject(new Error("That tab has closed."));
+    replies.clear();
+  });
   return {
     open: () => socket.readyState === WebSocket.OPEN,
     send: (method, params) => socket.send(JSON.stringify({ id: ++id, method, params })),
+    // Bounded: a page showing a pop-up holds back what runs script in it, and a request left
+    // waiting keeps the plugin from being updated.
+    call: (method, params = {}) =>
+      new Promise((resolve, reject) => {
+        const n = ++id;
+        const timer = setTimeout(() => {
+          replies.delete(n);
+          reject(new Error("The agent's browser didn't answer."));
+        }, CALL_TIMEOUT_MS);
+        replies.set(n, {
+          resolve: (value) => (clearTimeout(timer), resolve(value)),
+          reject: (error) => (clearTimeout(timer), reject(error)),
+        });
+        socket.send(JSON.stringify({ id: n, method, params }));
+      }),
+    on: (listener) => listeners.add(listener),
     close: () => socket.close(),
   };
 }
 
 /**
- * Who holds which of the agent's tabs, and their input. Batches carry a sequence number, so
- * they're replayed in the order Otter sent them however the gateway runs its requests.
+ * The agent's tabs as Otter sees them: who holds which (and their input, replayed in the order
+ * Otter numbered it however the gateway runs requests), and what happens on them (where the
+ * pointer lands, what's typed in, pop-ups, file pickers, copies) for whoever watches.
  */
-export function createBrowserControl({ cdpUrlFor, connect = connectTarget, now = Date.now }) {
-  const held = new Map();
+export function createBrowserControl({
+  cdpUrlFor,
+  answerDialog,
+  openDialog,
+  connect = connectTarget,
+  now = Date.now,
+  uploads = path.join(tmpdir(), "otter-uploads"),
+}) {
+  const tabs = new Map();
+  // Event numbers start over when the plugin does (an update, a gateway restart): say which run.
+  const run = randomUUID();
 
+  let sweeper;
+  const tabOf = (targetId) => {
+    let tab = tabs.get(targetId);
+    if (!tab) {
+      tab = {
+        targetId,
+        lock: null,
+        events: [],
+        seq: 0,
+        waiters: new Set(),
+        seen: now(),
+        chain: Promise.resolve(),
+      };
+      tabs.set(targetId, tab);
+      sweeper ??= setInterval(() => sweep(), IDLE_MS);
+      sweeper.unref?.();
+    }
+    return tab;
+  };
   const holding = (targetId) => {
-    const tab = held.get(targetId);
-    if (tab && tab.until > now()) return tab;
-    if (tab) drop(targetId);
+    const tab = tabs.get(targetId);
+    if (tab?.lock && tab.lock.until > now()) return tab;
+    if (tab?.lock) unlock(tab);
     return undefined;
   };
-  const drop = (targetId) => {
-    const tab = held.get(targetId);
-    held.delete(targetId);
-    clearTimeout(tab?.gap);
-    void tab?.page?.then((page) => page.close()).catch(() => {});
+  const unlock = (tab) => {
+    clearTimeout(tab.lock?.gap);
+    for (const batch of tab.lock?.waiting.values() ?? []) batch.done();
+    tab.lock = null;
+    tab.chooser = null;
+    void tab.page
+      ?.then(
+        (page) =>
+          page.open() && page.call("Page.setInterceptFileChooserDialog", { enabled: false }),
+      )
+      .catch(() => {});
+  };
+  /** Lets go of tabs nobody has held or watched for a while, and their DevTools connections. */
+  const sweep = (all = false) => {
+    for (const [targetId, tab] of tabs) {
+      if (!all && (holding(targetId) || now() - tab.seen < IDLE_MS)) continue;
+      if (tab.lock) unlock(tab);
+      for (const wake of tab.waiters) wake();
+      tabs.delete(targetId);
+      void tab.page?.then((page) => page.close()).catch(() => {});
+    }
+    if (tabs.size === 0 && sweeper) {
+      clearInterval(sweeper);
+      sweeper = undefined;
+    }
+  };
+  const tell = (tab, event) => {
+    tab.seq += 1;
+    tab.events.push({ ...event, seq: tab.seq });
+    if (tab.events.length > EVENTS_KEPT) tab.events.shift();
+    for (const wake of tab.waiters) wake();
+  };
+  const watch = (tab, page) => {
+    page.on((method, params) => {
+      if (method === "Runtime.bindingCalled" && params.name === BINDING) {
+        try {
+          tell(tab, JSON.parse(params.payload));
+        } catch {}
+      } else if (method === "Page.javascriptDialogOpening") {
+        tab.dialog = {
+          dialogType: params.type,
+          message: String(params.message ?? "").slice(0, 4000),
+          defaultPrompt: String(params.defaultPrompt ?? "").slice(0, 4000),
+        };
+        tell(tab, { type: "dialog", ...tab.dialog });
+      } else if (method === "Page.javascriptDialogClosed") {
+        tab.dialog = null;
+        tell(tab, { type: "dialogClosed" });
+      } else if (method === "Page.fileChooserOpened" && tab.lock) {
+        tab.chooser = { backendNodeId: params.backendNodeId };
+        tell(tab, { type: "fileChooser", multiple: params.mode === "selectMultiple" });
+      }
+    });
+    // Not waited for: a page showing a pop-up holds every command until it closes, and runs them
+    // in order then. Binding calls only arrive with Runtime on (its other events are ignored).
+    for (const [method, params] of [
+      ["Runtime.enable", {}],
+      ["Runtime.addBinding", { name: BINDING, executionContextName: WORLD }],
+      ["Page.enable", {}],
+      [
+        "Page.addScriptToEvaluateOnNewDocument",
+        { source: WATCH_SCRIPT, worldName: WORLD, runImmediately: true },
+      ],
+    ])
+      void page.call(method, params).catch(() => {});
+  };
+  const open = async (tab, targetId, profile) => {
+    const page = await connect(await cdpUrlFor(profile), targetId);
+    watch(tab, page);
+    // A pop-up already open before we connected isn't announced again.
+    const already = await openDialog?.(targetId, profile).catch(() => null);
+    if (already && !tab.dialog) {
+      tab.dialog = already;
+      tell(tab, { type: "dialog", ...already });
+    }
+    return page;
   };
-  const open = (targetId, profile) => cdpUrlFor(profile).then((url) => connect(url, targetId));
   const pageOf = async (tab, targetId, profile) => {
-    tab.page ??= open(targetId, profile);
+    tab.profile = profile;
+    tab.page ??= open(tab, targetId, profile);
     const page = await tab.page.catch(() => null);
     if (page?.open()) return page;
-    tab.page = open(targetId, profile);
+    tab.page = open(tab, targetId, profile);
     return tab.page;
   };
+
+  const replay = async (tab, page, event) => {
+    // Answered through OpenClaw when it can, so it knows the pop-up is gone and the agent can go on.
+    if (event?.type === "dialog" && answerDialog) {
+      const answer = { accept: event.accept === true, promptText: event.promptText };
+      if (
+        await answerDialog(tab.targetId, tab.profile, answer).then(
+          () => true,
+          () => false,
+        )
+      )
+        return;
+    }
+    if (event?.type === "history") {
+      const { currentIndex, entries } = await page.call("Page.getNavigationHistory");
+      const entry = entries?.[currentIndex + (event.delta === -1 ? -1 : 1)];
+      if (entry) page.send("Page.navigateToHistoryEntry", { entryId: entry.id });
+      return;
+    }
+    const call = cdpInput(event);
+    if (call) page.send(...call);
+  };
+  /**
+   * Replays the batches now in order, one after another for the tab: a pop-up's answer or a
+   * history move waits on a reply, and what follows must not overtake it.
+   */
   const flush = (tab, page) => {
-    const missing = tab.next;
-    while (tab.waiting.has(tab.next)) {
-      for (const event of tab.waiting.get(tab.next)) {
-        const call = cdpInput(event);
-        if (call) page.send(...call);
-      }
-      tab.waiting.delete(tab.next);
-      tab.next += 1;
+    const lock = tab.lock;
+    const missing = lock.next;
+    while (lock.waiting.has(lock.next)) {
+      const batch = lock.waiting.get(lock.next);
+      lock.waiting.delete(lock.next);
+      lock.next += 1;
+      tab.chain = tab.chain
+        .then(async () => {
+          // Handed back meanwhile: what's still queued is dropped, not sent over the agent.
+          for (const event of batch.events) {
+            if (tab.lock !== lock) return;
+            await replay(tab, page, event).catch(() => {});
+          }
+        })
+        .finally(batch.done);
     }
     // A batch is missing: let it arrive, then go on without it. Batches arriving behind it
     // don't push that back.
-    if (tab.gap && tab.next === missing && tab.waiting.size > 0) return;
-    clearTimeout(tab.gap);
-    tab.gap = undefined;
-    if (tab.waiting.size === 0) return;
-    tab.gap = setTimeout(() => {
-      tab.gap = undefined;
-      tab.next = Math.min(...tab.waiting.keys());
+    if (lock.gap && lock.next === missing && lock.waiting.size > 0) return;
+    clearTimeout(lock.gap);
+    lock.gap = undefined;
+    if (lock.waiting.size === 0) return;
+    lock.gap = setTimeout(() => {
+      lock.gap = undefined;
+      if (tab.lock !== lock) return;
+      lock.next = Math.min(...lock.waiting.keys());
       flush(tab, page);
     }, GAP_MS);
   };
 
   return {
-    anyHeld: () => [...held.keys()].some((targetId) => holding(targetId)),
-    take(targetId) {
-      const tab = holding(targetId);
-      if (tab) tab.until = now() + CONTROL_TTL_MS;
-      else held.set(targetId, { until: now() + CONTROL_TTL_MS, next: 1, waiting: new Map() });
+    /** The plugin is being replaced: let go of everything. */
+    dispose: () => sweep(true),
+    /** Whether the agent's browser tool may run this call now: reads always, actions unless held. */
+    allows: (params) =>
+      READ_ACTIONS.has(params?.action) || ![...tabs.keys()].some((id) => holding(id)),
+    async take(targetId, profile) {
+      sweep();
+      const held = holding(targetId);
+      if (held) {
+        held.lock.until = now() + CONTROL_TTL_MS;
+        held.seen = now();
+        return;
+      }
+      const tab = tabOf(targetId);
+      tab.seen = now();
+      tab.lock = { until: now() + CONTROL_TTL_MS, next: 1, waiting: new Map() };
+      // The page's own file picker is offered to you while you hold it.
+      const page = await pageOf(tab, targetId, profile);
+      void page.call("Page.setInterceptFileChooserDialog", { enabled: true }).catch(() => {});
+    },
+    release(targetId) {
+      const tab = tabs.get(targetId);
+      if (tab?.lock) unlock(tab);
     },
-    release: drop,
     async input(targetId, profile, seq, events) {
       const tab = holding(targetId);
       if (!tab) throw new Error("Take control of this tab first.");
-      tab.until = now() + CONTROL_TTL_MS;
-      if (!Number.isInteger(seq) || seq < tab.next || !Array.isArray(events)) return;
-      tab.waiting.set(seq, events.slice(0, 200));
+      tab.lock.until = now() + CONTROL_TTL_MS;
+      tab.seen = now();
+      if (!Number.isInteger(seq) || seq < tab.lock.next || !Array.isArray(events)) return;
+      const lock = tab.lock;
+      // The request stays open until its batch is replayed: answering a pop-up goes through
+      // OpenClaw, which drops the call once the request that made it returns.
+      const replayed = new Promise((done) =>
+        lock.waiting.set(seq, { events: events.slice(0, 200), done }),
+      );
+      const page = await pageOf(tab, targetId, profile);
+      if (tab.lock === lock) flush(tab, page);
+      await replayed;
+    },
+    /**
+     * What happened on the tab since `since`, waiting up to `waitMs` for something to. Without
+     * `since`: no events, just where they're up to and any open pop-up.
+     */
+    async events(targetId, profile, since, waitMs, from) {
+      if (from !== run) since = undefined;
+      sweep();
+      const tab = tabOf(targetId);
+      tab.seen = now();
+      await pageOf(tab, targetId, profile);
+      const state = () => ({
+        run,
+        seq: tab.seq,
+        dialog: tab.dialog ?? null,
+        events: Number.isInteger(since) ? tab.events.filter((e) => e.seq > since) : [],
+      });
+      if (!Number.isInteger(since) || since < tab.seq || !(waitMs > 0)) return state();
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          tab.waiters.delete(done);
+          resolve();
+        };
+        const timer = setTimeout(done, Math.min(waitMs, 25_000));
+        tab.waiters.add(done);
+      });
+      tab.seen = now();
+      return state();
+    },
+    /** The files you picked for the page's own picker (none cancels it). */
+    async upload(targetId, profile, files) {
+      const tab = holding(targetId);
+      if (!tab) throw new Error("Take control of this tab first.");
+      const chooser = tab.chooser;
+      if (!chooser) throw new Error("The page isn't asking for a file.");
+      tab.chooser = null;
+      const picked = Array.isArray(files) ? files : [];
+      const total = picked.reduce((sum, f) => sum + String(f?.data ?? "").length * 0.75, 0);
+      if (total > MAX_UPLOAD_BYTES) throw new Error("Those files are too large (10 MB at most).");
+      const dir = path.join(uploads, randomUUID());
+      const paths = [];
+      if (picked.length > 0) {
+        for (const [i, file] of picked.entries()) {
+          // A folder each, so two files of the same name both reach the page as named.
+          const at = path.join(dir, String(i));
+          await mkdir(at, { recursive: true });
+          const name = path.basename(String(file?.name ?? "")) || `file-${i + 1}`;
+          await writeFile(path.join(at, name), Buffer.from(String(file?.data ?? ""), "base64"));
+          paths.push(path.join(at, name));
+        }
+        setTimeout(() => void rm(dir, { recursive: true, force: true }), UPLOADS_KEPT_MS).unref?.();
+      }
       const page = await pageOf(tab, targetId, profile);
-      if (held.get(targetId) === tab) flush(tab, page);
+      await page.call("DOM.setFileInputFiles", {
+        files: paths,
+        backendNodeId: chooser.backendNodeId,
+      });
     },
   };
 }

package/index.js

@@ -1,19 +1,46 @@
+import { AsyncResource } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import {
   createChannelPluginBase,
   createChatChannelPlugin,
   defineChannelPluginEntry,
 } from "openclaw/plugin-sdk/channel-core";
+import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";
+import { defineStableChannelIngressIdentity } from "openclaw/plugin-sdk/channel-ingress-runtime";
 import { resolveAgentWorkspaceDir } from "openclaw/plugin-sdk/agent-runtime";
 import { dispatchGatewayMethod } from "openclaw/plugin-sdk/gateway-method-runtime";
 import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
 import { createBrowserControl } from "./control.js";
+import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";
 import { readWorkspaceFile } from "./files.js";
-import { accountOf, inboxKey, OTTER_TARGET, pointerOf, tell } from "./otter.js";
+import {
+  accountOf,
+  chatOf,
+  chatTarget,
+  isOwnerConfigured,
+  messageOf,
+  OTTER_TARGET,
+  OWNER,
+  pointerOf,
+  sessionOf,
+  tell,
+} from "./otter.js";
+
+/**
+ * Where a message sent from Otter starts its run: outside the request that carried it,
+ * so the run is the channel's owner's and not that connection's, and outlives it.
+ */
+const receiving = new AsyncResource("otter-inbound");
+
+const owner = defineStableChannelIngressIdentity({
+  key: "otter-sender",
+  normalize: (value) => String(value).trim(),
+  sensitivity: "pii",
+});
 
 async function deliver(ctx, payload) {
   const account = accountOf(ctx.cfg);
-  const pointer = pointerOf({ sessionKey: ctx.sessionKey, payload });
+  const pointer = pointerOf({ sessionKey: ctx.sessionKey, to: ctx.to, payload });
   await tell(account, pointer, { signal: ctx.signal });
   return { channel: "otter", messageId: randomUUID(), timestamp: pointer.at };
 }
@@ -38,33 +65,120 @@ export const otterChannel = createChatChannelPlugin({
       },
     }),
     messaging: {
-      targetResolver: { looksLikeId: () => true, hint: `"${OTTER_TARGET}"` },
-      // Every delivery to Otter lands in the agent's Otter session, whatever the gateway's DM scope.
-      resolveOutboundSessionRoute: ({ agentId }) => ({
-        sessionKey: inboxKey(agentId),
-        baseSessionKey: inboxKey(agentId),
-        recipientSessionExact: true,
-        peer: { kind: "direct", id: OTTER_TARGET },
-        chatType: "direct",
-        from: "otter",
-        to: OTTER_TARGET,
-      }),
+      targetResolver: {
+        looksLikeId: () => true,
+        hint: `"${OTTER_TARGET}", or "chat:<session key>" for one of Otter's chats`,
+      },
+      // A delivery to a chat is kept in its session; any other, in the agent's Otter session.
+      resolveOutboundSessionRoute: ({ agentId, target }) => {
+        const chat = chatOf(target);
+        const sessionKey = sessionOf(target, agentId);
+        const to = chat ? chatTarget(chat) : OTTER_TARGET;
+        return {
+          sessionKey,
+          baseSessionKey: sessionKey,
+          recipientSessionExact: true,
+          peer: { kind: "direct", id: to },
+          chatType: "direct",
+          from: "otter",
+          to,
+        };
+      },
     },
   },
   outbound: {
     deliveryMode: "direct",
-    resolveTarget: () => ({ ok: true, to: OTTER_TARGET }),
+    resolveTarget: (params) => {
+      const chat = chatOf(params?.to);
+      return { ok: true, to: chat ? chatTarget(chat) : OTTER_TARGET };
+    },
     sendText: (ctx) => deliver(ctx),
     sendPayload: (ctx) => deliver(ctx, ctx.payload),
   },
 });
 
+/** Runs what you sent from Otter as the channel's owner: an inbound message, as from any chat app. */
+async function receive(api, cfg, message) {
+  const { sessionKey, agentId, text, messageId, files } = message;
+  const inbound = api.runtime.channel.inbound;
+  const saved = await Promise.all(
+    files.map((file) =>
+      api.runtime.channel.media.saveMediaBuffer(
+        Buffer.from(file.content, "base64"),
+        file.mimeType,
+        "inbound",
+        undefined,
+        typeof file.fileName === "string" ? file.fileName : undefined,
+      ),
+    ),
+  );
+  const channelIngress = await inbound.ingress.resolve({
+    channelId: "otter",
+    accountId: "default",
+    identity: owner,
+    subject: { stableId: OWNER },
+    conversation: { kind: "direct", id: sessionKey },
+    contextBinding: { agentId, sessionKey, messageId, inboundEventKind: "user_request" },
+    event: { kind: "message", authMode: "inbound", mayPair: false },
+    policy: { dmPolicy: "allowlist" },
+    allowFrom: [OWNER],
+    readStoreAllowFrom: async () => [],
+  });
+  const to = chatTarget(sessionKey);
+  const ctxPayload = await inbound.buildContext({
+    channelIngress,
+    channel: "otter",
+    accountId: "default",
+    messageId,
+    timestamp: Date.now(),
+    from: `otter:${OWNER}`,
+    sender: { id: OWNER, name: "Otter" },
+    conversation: { kind: "direct", id: sessionKey },
+    route: { agentId, accountId: "default", routeSessionKey: sessionKey },
+    reply: { to, originatingTo: to },
+    message: { body: text, rawBody: text, commandBody: text, bodyForAgent: text },
+    ...(saved.length > 0 && {
+      media: toInboundMediaFacts(
+        saved.map((file) => ({ path: file.path, contentType: file.contentType, messageId })),
+      ),
+    }),
+  });
+  await inbound.dispatch({
+    cfg,
+    channel: "otter",
+    accountId: "default",
+    route: { agentId, sessionKey },
+    ctxPayload,
+    replyOptions: { runId: messageId, sourceReplyDeliveryMode: "automatic" },
+    // The reply is kept in the chat's session, which Otter is reading as it's written.
+    delivery: { deliver: async () => ({ visibleReplySent: true }) },
+  });
+}
+
 export default defineChannelPluginEntry({
   id: "otter",
   name: "Otter",
   description: "Send what your agents want you to see to Otter.",
   plugin: otterChannel,
   registerFull(api) {
+    // What you send in an Otter chat, as the gateway's owner: `chat.send`'s run, with the authority
+    // a configured channel owner has (an automation another chat made, for one).
+    api.registerGatewayMethod(
+      "otter.chat.send",
+      async ({ params, context }) => {
+        const cfg = context?.getRuntimeConfig?.() ?? api.config;
+        if (!isOwnerConfigured(cfg)) throw new Error("otter_not_owner");
+        const message = messageOf(params);
+        receiving.runInAsyncScope(() =>
+          runDetachedWebhookWork(() => receive(api, cfg, message)).catch((error) =>
+            api.logger?.warn?.(`otter: a message from Otter failed: ${String(error)}`),
+          ),
+        );
+        return { runId: message.messageId, status: "started" };
+      },
+      { scope: "operator.admin" },
+    );
+
     // Otter's preview of a file an agent linked: PDFs and other files sessions.files.get won't send.
     api.registerGatewayMethod(
       "otter.files.get",
@@ -81,15 +195,43 @@ export default defineChannelPluginEntry({
 
     // Take control of the agent's browser from Otter: your input goes to the tab as a person's
     // would, and the agent's browser waits until you hand it back.
+    const browser = async (method, path, query, body) => {
+      const result = await dispatchGatewayMethod("browser.request", {
+        method,
+        path,
+        ...(query ? { query } : {}),
+        ...(body ? { body } : {}),
+      });
+      if (!result?.ok) throw new Error(result?.error?.message ?? "The browser didn't answer.");
+      return result.payload;
+    };
+    const pendingDialog = async (targetId, profile) => {
+      const query = { ...(profile ? { profile } : {}), targetId };
+      return (await browser("GET", "/dialogs", query))?.browserState?.dialogs?.pending?.[0];
+    };
     const control = createBrowserControl({
-      async cdpUrlFor(profile) {
-        const result = await dispatchGatewayMethod("browser.request", {
-          method: "GET",
-          path: "/profiles",
+      async openDialog(targetId, profile) {
+        const open = await pendingDialog(targetId, profile);
+        return open
+          ? {
+              dialogType: String(open.type),
+              message: String(open.message ?? ""),
+              defaultPrompt: String(open.defaultValue ?? ""),
+            }
+          : null;
+      },
+      async answerDialog(targetId, profile, { accept, promptText }) {
+        const pending = await pendingDialog(targetId, profile);
+        if (!pending) throw new Error("No pop-up is open.");
+        await browser("POST", "/hooks/dialog", profile ? { profile } : undefined, {
+          targetId,
+          dialogId: pending.id,
+          accept,
+          ...(typeof promptText === "string" ? { promptText } : {}),
         });
-        if (!result?.ok)
-          throw new Error(result?.error?.message ?? "Couldn't find the agent's browser.");
-        const profiles = result.payload?.profiles ?? [];
+      },
+      async cdpUrlFor(profile) {
+        const profiles = (await browser("GET", "/profiles"))?.profiles ?? [];
         const found = profiles.find((p) => (profile ? p.name === profile : p.isDefault));
         const url = typeof found?.cdpUrl === "string" ? URL.parse(found.cdpUrl) : null;
         if (!url || !["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))
@@ -97,15 +239,18 @@ export default defineChannelPluginEntry({
         return url.href;
       },
     });
+    api.lifecycle?.onDispose?.(() => control.dispose());
     const targetOf = (params) => {
       if (typeof params?.targetId !== "string" || !params.targetId)
         throw new Error("targetId is required");
       return params.targetId;
     };
+    const profileOf = (params) =>
+      typeof params?.profile === "string" ? params.profile : undefined;
     api.registerGatewayMethod(
       "otter.browser.control",
-      ({ params }) => {
-        if (params?.take === true) control.take(targetOf(params));
+      async ({ params }) => {
+        if (params?.take === true) await control.take(targetOf(params), profileOf(params));
         else control.release(targetOf(params));
         return { controlled: params?.take === true };
       },
@@ -114,18 +259,37 @@ export default defineChannelPluginEntry({
     api.registerGatewayMethod(
       "otter.browser.input",
       async ({ params }) => {
-        const profile = typeof params?.profile === "string" ? params.profile : undefined;
-        await control.input(targetOf(params), profile, params?.seq, params?.events);
+        await control.input(targetOf(params), profileOf(params), params?.seq, params?.events);
+        return {};
+      },
+      { scope: "operator.admin" },
+    );
+    api.registerGatewayMethod(
+      "otter.browser.events",
+      ({ params }) =>
+        control.events(
+          targetOf(params),
+          profileOf(params),
+          params?.since,
+          params?.waitMs,
+          params?.run,
+        ),
+      { scope: "operator.admin" },
+    );
+    api.registerGatewayMethod(
+      "otter.browser.upload",
+      async ({ params }) => {
+        await control.upload(targetOf(params), profileOf(params), params?.files);
         return {};
       },
       { scope: "operator.admin" },
     );
     api.on("before_tool_call", (event) =>
-      /(^|__)browser$/.test(event.toolName) && control.anyHeld()
+      /(^|__)browser$/.test(event.toolName) && !control.allows(event.params)
         ? {
             block: true,
             blockReason:
-              "The user has taken control of the browser. Wait until they hand it back, then try again.",
+              "The user has taken control of the browser. Reading pages still works; wait until they hand it back before acting on one.",
           }
         : undefined,
     );

package/otter.js

@@ -5,25 +5,48 @@ export const inboxKey = (agentId) => `agent:${agentId}:otter:inbox`;
 
 export const OTTER_TARGET = "inbox";
 
+/** Who sends what you type in Otter: the gateway's owner once `commands.ownerAllowFrom` lists `otter:owner`. */
+export const OWNER = "owner";
+export const OWNER_ENTRY = `otter:${OWNER}`;
+
+/** A chat in Otter is a target of its own: what's sent to it is kept in its session. */
+export const chatTarget = (sessionKey) => `chat:${sessionKey}`;
+
 export const agentOf = (sessionKey) =>
   typeof sessionKey === "string" && sessionKey.startsWith("agent:")
     ? sessionKey.split(":")[1]
     : undefined;
 
+/** The chat a target names, if it names one. */
+export function chatOf(to) {
+  const target = typeof to === "string" ? to.trim().replace(/^otter:/, "") : "";
+  if (!target.startsWith("chat:")) return undefined;
+  const sessionKey = target.slice("chat:".length);
+  return agentOf(sessionKey) ? sessionKey : undefined;
+}
+
+/** The session a delivery to this target is kept in. */
+export const sessionOf = (to, agentId) => chatOf(to) ?? inboxKey(agentId);
+
+export const isOwnerConfigured = (cfg) =>
+  Array.isArray(cfg?.commands?.ownerAllowFrom) &&
+  cfg.commands.ownerAllowFrom.some((entry) => String(entry).trim() === OWNER_ENTRY);
+
 /**
  * What the relay is told of a delivery: never its text, only where to read it.
  * Otter's apps read it from the gateway themselves.
  */
-export function pointerOf({ sessionKey, payload, at = Date.now() }) {
+export function pointerOf({ sessionKey, to, payload, at = Date.now() }) {
   const data = payload?.channelData ?? {};
   const approval = data.execApproval;
   const question = data.askUser;
   const session = approval?.sessionKey ?? sessionKey;
-  const agentId = approval?.agentId ?? agentOf(session) ?? "main";
+  const chat = chatOf(to);
+  const agentId = approval?.agentId ?? agentOf(chat ?? session) ?? "main";
   return {
     kind: approval ? "approval" : question ? "question" : "message",
     agentId,
-    sessionKey: approval || question ? (session ?? null) : inboxKey(agentId),
+    sessionKey: approval || question ? (session ?? null) : (chat ?? inboxKey(agentId)),
     ...(approval && {
       approvalId: String(approval.approvalId),
       approvalKind: approval.approvalKind === "plugin" ? "plugin" : "exec",
@@ -56,3 +79,19 @@ export async function tell(account, pointer, { fetch = globalThis.fetch, signal
   if (!response.ok) throw new Error(`Otter's relay answered ${response.status}`);
   return true;
 }
+
+/** A message sent from Otter, checked: where it goes and what it carries. */
+export function messageOf(params) {
+  const { sessionKey, message, idempotencyKey, attachments } = params ?? {};
+  if (typeof sessionKey !== "string" || !agentOf(sessionKey))
+    throw new Error("sessionKey must be an agent's session");
+  if (typeof idempotencyKey !== "string" || !idempotencyKey.trim())
+    throw new Error("idempotencyKey is required");
+  const files = Array.isArray(attachments) ? attachments : [];
+  for (const file of files)
+    if (typeof file?.content !== "string" || typeof file?.mimeType !== "string")
+      throw new Error("each attachment needs its content (base64) and mimeType");
+  const text = typeof message === "string" ? message : "";
+  if (!text.trim() && files.length === 0) throw new Error("message or attachments are required");
+  return { sessionKey, agentId: agentOf(sessionKey), text, messageId: idempotencyKey, files };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otterware/openclaw-otter",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Otter as an OpenClaw channel: what your agents send you waits in Otter, and Otter tells your devices.",
   "license": "MIT",
   "repository": {