@otterware/openclaw-otter 0.2.2 → 0.2.4

package/index.js

@@ -17,12 +17,15 @@ import {
   accountOf,
   chatOf,
   chatTarget,
+  isNewChat,
   isOwnerConfigured,
   messageOf,
-  OTTER_TARGET,
+  newChatKey,
+  otterTargetsNote,
   OWNER,
   pointerOf,
-  sessionOf,
+  targetOf,
+  TARGETS_HINT,
   tell,
 } from "./otter.js";
 
@@ -61,13 +64,14 @@ export const otterChannel = createChatChannelPlugin({
     messaging: {
       targetResolver: {
         looksLikeId: () => true,
-        hint: `"${OTTER_TARGET}", or "chat:<session key>" for one of Otter's chats`,
+        hint: TARGETS_HINT,
       },
-      // 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 "chat:new", in a chat it starts (the gateway
+      // routes each delivery once, and sends it to that session).
       resolveOutboundSessionRoute: ({ agentId, target }) => {
-        const chat = chatOf(target);
-        const sessionKey = sessionOf(target, agentId);
-        const to = chat ? chatTarget(chat) : OTTER_TARGET;
+        const to = targetOf(target);
+        if (!to) return null;
+        const sessionKey = isNewChat(to) ? newChatKey(agentId, randomUUID()) : chatOf(to);
         return {
           sessionKey,
           baseSessionKey: sessionKey,
@@ -83,8 +87,10 @@ export const otterChannel = createChatChannelPlugin({
   outbound: {
     deliveryMode: "direct",
     resolveTarget: (params) => {
-      const chat = chatOf(params?.to);
-      return { ok: true, to: chat ? chatTarget(chat) : OTTER_TARGET };
+      const to = targetOf(params?.to);
+      return to
+        ? { ok: true, to }
+        : { ok: false, error: new Error(`Otter's targets are ${TARGETS_HINT}.`) };
     },
     sendText: (ctx) => deliver(ctx),
     sendPayload: (ctx) => deliver(ctx, ctx.payload),
@@ -155,6 +161,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(

package/otter.js

@@ -1,10 +1,5 @@
 // What the plugin does, apart from OpenClaw's SDK, so Otter's tests can run it.
 
-/** Where an agent's deliveries to Otter are kept: one session per agent, read by Otter's apps. */
-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}`;
@@ -12,6 +7,40 @@ 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 = "chat:new";
+
+const bare = (to) => (typeof to === "string" ? to.trim().replace(/^otter:/, "") : "");
+
+/** What's sent to the gateway's owner (`otter:owner`) starts a chat, as it names none. */
+export const isNewChat = (to) => bare(to) === NEW_CHAT_TARGET || bare(to) === OWNER;
+
+/** A target as the channel keeps it: one of Otter's chats, or a new one each time; else none. */
+export function targetOf(to) {
+  const chat = chatOf(to);
+  if (chat) return chatTarget(chat);
+  return isNewChat(to) ? NEW_CHAT_TARGET : undefined;
+}
+
+export const TARGETS_HINT =
+  '"chat:<session key>" for one of Otter\'s chats, or "chat:new" for a new one';
+
+/** 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 replying in a thread or a new post in Slack:",
+    `- "${here}": this chat. Any Otter chat is "chat:<its session key>".`,
+    '- "chat:new": a new Otter chat for each delivery (an automation that should post a fresh chat every run, such as a morning brief or an alert).',
+  ].join("\n");
+}
+
 export const agentOf = (sessionKey) =>
   typeof sessionKey === "string" && sessionKey.startsWith("agent:")
     ? sessionKey.split(":")[1]
@@ -19,15 +48,12 @@ export const agentOf = (sessionKey) =>
 
 /** The chat a target names, if it names one. */
 export function chatOf(to) {
-  const target = typeof to === "string" ? to.trim().replace(/^otter:/, "") : "";
+  const target = bare(to);
   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);
@@ -41,12 +67,13 @@ 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",
     agentId,
-    sessionKey: approval || question ? (session ?? null) : (chat ?? inboxKey(agentId)),
+    sessionKey: approval || question ? (session ?? null) : (chat ?? session ?? null),
     ...(approval && {
       approvalId: String(approval.approvalId),
       approvalKind: approval.approvalKind === "plugin" ? "plugin" : "exec",

package/package.json

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