@otterware/openclaw-otter 0.2.1 → 0.2.3

package/index.js

@@ -1,4 +1,3 @@
-import { AsyncResource } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import {
   createChannelPluginBase,
@@ -6,6 +5,7 @@ import {
   defineChannelPluginEntry,
 } from "openclaw/plugin-sdk/channel-core";
 import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";
+import { runInDetachedAsyncContext } from "openclaw/plugin-sdk/concurrency-runtime";
 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";
@@ -15,23 +15,19 @@ import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guar
 import { readWorkspaceFile } from "./files.js";
 import {
   accountOf,
-  chatOf,
   chatTarget,
+  isNewChat,
   isOwnerConfigured,
   messageOf,
-  OTTER_TARGET,
+  newChatKey,
+  otterTargetsNote,
   OWNER,
   pointerOf,
   sessionOf,
+  targetOf,
   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(),
@@ -67,13 +63,15 @@ export const otterChannel = createChatChannelPlugin({
     messaging: {
       targetResolver: {
         looksLikeId: () => true,
-        hint: `"${OTTER_TARGET}", or "chat:<session key>" for one of Otter's chats`,
+        hint: '"chat:<session key>" for one of Otter\'s chats, "new" for a new chat, or "inbox"',
       },
-      // A delivery to a chat is kept in its session; any other, in the agent's Otter session.
+      // A delivery to a chat is kept in its session; to "new", in a chat it starts (the gateway
+      // routes each delivery once, and sends it to that session); any other, in the inbox.
       resolveOutboundSessionRoute: ({ agentId, target }) => {
-        const chat = chatOf(target);
-        const sessionKey = sessionOf(target, agentId);
-        const to = chat ? chatTarget(chat) : OTTER_TARGET;
+        const to = targetOf(target);
+        const sessionKey = isNewChat(to)
+          ? newChatKey(agentId, randomUUID())
+          : sessionOf(target, agentId);
         return {
           sessionKey,
           baseSessionKey: sessionKey,
@@ -88,10 +86,7 @@ export const otterChannel = createChatChannelPlugin({
   },
   outbound: {
     deliveryMode: "direct",
-    resolveTarget: (params) => {
-      const chat = chatOf(params?.to);
-      return { ok: true, to: chat ? chatTarget(chat) : OTTER_TARGET };
-    },
+    resolveTarget: (params) => ({ ok: true, to: targetOf(params?.to) }),
     sendText: (ctx) => deliver(ctx),
     sendPayload: (ctx) => deliver(ctx, ctx.payload),
   },
@@ -161,6 +156,14 @@ export default defineChannelPluginEntry({
   description: "Send what your agents want you to see to Otter.",
   plugin: otterChannel,
   registerFull(api) {
+    // What Otter's targets are, for a turn in an Otter chat: the Codex harness leaves channels'
+    // message-tool hints out of its instructions, but every harness runs this hook.
+    api.on("before_prompt_build", (_event, ctx) =>
+      ctx?.channel === "otter" || ctx?.messageProvider === "otter"
+        ? { appendSystemContext: otterTargetsNote(ctx.sessionKey) }
+        : undefined,
+    );
+
     // 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(
@@ -169,7 +172,10 @@ export default defineChannelPluginEntry({
         const cfg = context?.getRuntimeConfig?.() ?? api.config;
         if (!isOwnerConfigured(cfg)) throw new Error("otter_not_owner");
         const message = messageOf(params);
-        receiving.runInAsyncScope(() =>
+        // The run starts outside the request that carried it (the gateway's context-free root,
+        // whatever request loaded this plugin), so it's the channel owner's, not that
+        // connection's, and outlives it.
+        runInDetachedAsyncContext(() =>
           runDetachedWebhookWork(() => receive(api, cfg, message)).catch((error) =>
             api.logger?.warn?.(`otter: a message from Otter failed: ${String(error)}`),
           ),

package/otter.js

@@ -12,6 +12,36 @@ 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}`;
 
+/** Like posting to a Slack channel rather than in a thread: each delivery starts a chat of its own. */
+export const NEW_CHAT_TARGET = "new";
+
+export const isNewChat = (to) =>
+  typeof to === "string" && to.trim().replace(/^otter:/, "") === NEW_CHAT_TARGET;
+
+/** A target as the channel keeps it: one of Otter's chats, a new one each time, or the inbox. */
+export function targetOf(to) {
+  const chat = chatOf(to);
+  if (chat) return chatTarget(chat);
+  return isNewChat(to) ? NEW_CHAT_TARGET : OTTER_TARGET;
+}
+
+/** A session for a new chat, an Otter chat like one you start. */
+export const newChatKey = (agentId, id) => `agent:${agentId}:otter-mail:${id}`;
+
+/**
+ * What an agent in an Otter chat is told about sending to Otter (the message tool, an automation's
+ * delivery), with this chat's own target.
+ */
+export function otterTargetsNote(sessionKey) {
+  const here = agentOf(sessionKey) ? chatTarget(sessionKey) : "chat:<session key>";
+  return [
+    "Otter delivery targets (channel `otter`), like a thread or a new post in Slack:",
+    `- "${here}": this chat. Any Otter chat is "chat:<its session key>".`,
+    '- "new": a new Otter chat for each delivery (an automation that should post a fresh chat every run, such as a morning brief).',
+    '- "inbox": the agent\'s single Otter inbox chat.',
+  ].join("\n");
+}
+
 export const agentOf = (sessionKey) =>
   typeof sessionKey === "string" && sessionKey.startsWith("agent:")
     ? sessionKey.split(":")[1]
@@ -41,7 +71,8 @@ export function pointerOf({ sessionKey, to, payload, at = Date.now() }) {
   const approval = data.execApproval;
   const question = data.askUser;
   const session = approval?.sessionKey ?? sessionKey;
-  const chat = chatOf(to);
+  // A new chat's session is the one its delivery was routed to.
+  const chat = chatOf(to) ?? (isNewChat(to) && agentOf(sessionKey) ? sessionKey : undefined);
   const agentId = approval?.agentId ?? agentOf(chat ?? session) ?? "main";
   return {
     kind: approval ? "approval" : question ? "question" : "message",

package/package.json

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