@otterware/openclaw-otter 0.1.3 → 0.2.0

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",

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.0",
   "description": "Otter as an OpenClaw channel: what your agents send you waits in Otter, and Otter tells your devices.",
   "license": "MIT",
   "repository": {