@clawling/clawchat-plugin-openclaw 2026.10.9-2 → 2026.10.9-4

package/src/outbound.ts

@@ -814,23 +814,33 @@ export interface SendReactionParams {
   log?: LogSink;
 }
 
+/**
+ * Outcome of {@link sendOpenclawClawlingReaction}. `sent: false` means the
+ * frame never left the plugin; callers that report to the model must surface
+ * it as a failure, never as a reaction.
+ */
+export type SendReactionResult =
+  | { sent: true }
+  | { sent: false; reason: "invalid_chat_id" | "chat_rejected_by_server" };
+
 /**
  * Emit a Protocol-v2 `message.reaction`. Fire-and-forget: reactions are NOT
  * ack-aligned (the server mints the slot-key message_id, so the ack-by-trace_id
  * path used for message.send/reply does not apply). Matches the mobile client.
+ * Local refusals are returned, not thrown; a transport failure still throws.
  */
-export function sendOpenclawClawlingReaction(params: SendReactionParams): void {
+export function sendOpenclawClawlingReaction(params: SendReactionParams): SendReactionResult {
   if (!isValidChatId(params.chatId)) {
     params.log?.info?.(
       `clawchat reaction blocked chat_id=${params.chatId} reason=invalid_chat_id`,
     );
-    return;
+    return { sent: false, reason: "invalid_chat_id" };
   }
   if (isOutboundBlocked(params.client, params.chatId)) {
     params.log?.info?.(
       `clawchat reaction blocked chat_id=${params.chatId} reason=chat_rejected_by_server`,
     );
-    return;
+    return { sent: false, reason: "chat_rejected_by_server" };
   }
   const payload: MessageReactionPayload = {
     target_message_id: params.targetMessageId,
@@ -849,6 +859,7 @@ export function sendOpenclawClawlingReaction(params: SendReactionParams): void {
   params.log?.info?.(
     `clawchat reaction sent chat_id=${params.chatId} target=${params.targetMessageId} emoji=${params.emoji} removed=${params.removed}`,
   );
+  return { sent: true };
 }
 
 type OutboundClaimStore = Pick<ClawChatStore, "claimMessageOnce" | "markMessageAcknowledged">;
@@ -875,6 +886,31 @@ function ulid(now: number = Date.now()): string {
   return out.join("");
 }
 
+// Every message id shape a ClawChat message can carry. The server preserves a
+// client-supplied id verbatim and never parses it, so this is deliberately a
+// plausibility check, not the mint contract:
+//   - `msg-<ULID>`: clients (this plugin, mobile, hermes) and the server's own
+//     fallback mint; `msg_…` / short `msg-…` forms are kept for older ids;
+//   - `sys-<ULID>` / `sys-<request_id>`: server system injections;
+//   - a bare ULID: the server's user-message publisher;
+//   - `clawchat-plugin-openclaw-…`: this plugin's synthetic turn ids.
+// UUIDs are not accepted: no ClawChat message id the model sees has that
+// shape, while host transcript ids (e.g. from `sessions_search`) do.
+const PREFIXED_MESSAGE_ID = /^(?:msg[-_]|sys-|clawchat-plugin-openclaw-)\S+$/i;
+const BARE_ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+
+/**
+ * Whether `id` can be a real ClawChat message id. Rejects what a model makes
+ * up when it has no id (a label like `B`, `msg`, prose); the server only checks
+ * that a reaction target is non-empty, so such a value would "succeed" on no
+ * message. Callers trim first. Tools use this only as the fallback when the
+ * plugin store cannot answer whether it has seen the id in the chat.
+ */
+export function isPlausibleMessageId(id: unknown): id is string {
+  if (typeof id !== "string") return false;
+  return PREFIXED_MESSAGE_ID.test(id) || BARE_ULID.test(id);
+}
+
 /** Client-minted message id: `msg-` + ULID (protocol §7.6 format contract). */
 export function mintMessageId(): string {
   return `msg-${ulid()}`;

package/src/owner-identity.ts

@@ -0,0 +1,49 @@
+// The one definition of "who is the owner, and which chat is the owner's DM"
+// shared by dispatch, the host-tool guard and memory scope. The SQLite
+// activation row decides; the config `ownerUserId` mirror is only a fallback
+// once a working store has proved there is no activation row at all. An
+// unavailable store, a failed read, a cleared/rejected token or an incomplete
+// row never falls back to the mirror — the caller sees no owner (fail closed).
+
+export type ActivationIdentityLookup =
+  | { status: "unavailable" }
+  | { status: "absent" }
+  | {
+      status: "row";
+      row: { ownerUserId: string | null; conversationId: string | null; accessToken: string | null };
+    };
+
+/** Structural so focused fixtures can omit unrelated store methods. */
+export type OwnerIdentityStore = {
+  lookupActivationIdentity?(input: { platform: string; accountId: string }): ActivationIdentityLookup;
+};
+
+export type OwnerIdentity = { ownerUserId: string | null; conversationId: string | null };
+
+export function resolveOwnerIdentity(
+  store: OwnerIdentityStore | null | undefined,
+  accountId: string,
+  configOwnerUserId?: string | null,
+  warn?: (failure: string) => void,
+  rejectedActivationToken?: string,
+): OwnerIdentity {
+  const denied: OwnerIdentity = { ownerUserId: null, conversationId: null };
+  try {
+    const lookup = store?.lookupActivationIdentity?.({ platform: "openclaw", accountId });
+    if (!lookup || lookup.status === "unavailable") {
+      warn?.("owner-identity");
+      return denied;
+    }
+    if (lookup.status === "absent") {
+      return { ownerUserId: configOwnerUserId?.trim() || null, conversationId: null };
+    }
+    const { row } = lookup;
+    // Mirror the runtime overlay: never trust the activation rejected during this lifecycle.
+    if (!row.accessToken || row.accessToken === rejectedActivationToken) return denied;
+    const ownerUserId = row.ownerUserId?.trim() || null;
+    return { ownerUserId, conversationId: ownerUserId ? row.conversationId?.trim() || null : null };
+  } catch {
+    warn?.("owner-identity");
+    return denied;
+  }
+}

package/src/reply-dispatcher.ts

@@ -88,7 +88,13 @@ export interface ReplyDispatcherOptions {
    * framework error final; null/absent means English.
    */
   resolveOwnerLocale?: () => string | null;
-  log?: { info?: (m: string) => void; error?: (m: string) => void };
+  /**
+   * True when the turn was not started by the owner (any group turn, any
+   * non-owner direct chat). Reply media is then limited to http(s) URLs; local
+   * paths are never loaded. Legacy standalone callers default to owner behavior.
+   */
+  nonOwnerTurn?: boolean;
+  log?: { info?: (m: string) => void; warn?: (m: string) => void; error?: (m: string) => void };
 }
 
 type TypedReplyDispatcherResult = ReturnType<
@@ -435,6 +441,19 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     log,
   } = options;
   const isGroupTarget = target.chatType === "group";
+  let warnedLocalReplyMedia = false;
+  // Non-owner turns may only send remote (http/https) media. Local sources are
+  // dropped here, before any load, because the host's local media roots include
+  // the agent workspace. Warns once per dispatcher and never names the source.
+  function filterReplyMedia(urls: string[]): string[] {
+    if (!options.nonOwnerTurn) return urls;
+    const remote = urls.filter((source) => /^https?:\/\//i.test(source.trim()));
+    if (remote.length !== urls.length && !warnedLocalReplyMedia) {
+      warnedLocalReplyMedia = true;
+      log?.warn?.("clawchat-plugin-openclaw: non-owner reply media dropped; only http(s) URLs are allowed");
+    }
+    return remote;
+  }
   const outputVisibility = effectiveOutputVisibility(account, target.chatId, target.chatType);
   const splitFullOutput = outputVisibility === "full";
   const splitNormalBlockOutput = outputVisibility === "normal";
@@ -442,11 +461,10 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   // owner's usr_… id: chat_id is resolved by msghub through member-backend, and
   // a usr_… comes back "invalid conversation id" — the frame is dropped with no
   // negative ack to this client, so the owner silently never gets the approval
-  // request. Both ids are required: ownerUserId gates whether an owner exists at
-  // all, the conversation id is where a frame can actually be delivered.
+  // request. The resolver is the shared strict owner-identity lookup
+  // (src/owner-identity.ts): it yields a conversation only for an activation
+  // row with an owner, so the config `ownerUserId` mirror is not consulted.
   const ownerDirectTarget = (): { chatId: string; chatType: "direct" } | null => {
-    const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) return null;
     const conversationId = resolveOwnerConversationId?.()?.trim();
     return conversationId ? { chatId: conversationId, chatType: "direct" as const } : null;
   };
@@ -462,7 +480,8 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     });
   };
 
-  async function uploadMediaUrls(urls: string[]): Promise<ClawlingMediaFragment[]> {
+  async function uploadMediaUrls(inputUrls: string[]): Promise<ClawlingMediaFragment[]> {
+    const urls = filterReplyMedia(inputUrls);
     if (urls.length === 0) return [];
     const apiClient = buildApiClient();
     if (!apiClient) {
@@ -720,11 +739,8 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   ): Promise<void> => {
     const ownerTarget = ownerDirectTarget();
     if (!ownerTarget) {
-      const reason = account.ownerUserId?.trim()
-        ? "missing_owner_conversation"
-        : "missing_owner_user_id";
       log?.error?.(
-        `[${account.accountId}] clawchat-plugin-openclaw group owner attention suppressed reason=${reason} group=${target.chatId}`,
+        `[${account.accountId}] clawchat-plugin-openclaw group owner attention suppressed reason=missing_owner_conversation group=${target.chatId}`,
       );
       return;
     }
@@ -917,7 +933,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       if (consumeTerminalSend(info?.kind ?? "unknown")) return;
       const richFragment = buildRichInteractionFragment(payload);
       const text = richFragment && account.richInteractions ? "" : resolvePayloadText(payload);
-      const urls = resolveOutboundMediaUrls(payload).filter(Boolean);
+      const urls = filterReplyMedia(resolveOutboundMediaUrls(payload).filter(Boolean));
       log?.info?.(
         `[${account.accountId}] clawchat-plugin-openclaw deliver kind=${info?.kind ?? "unknown"} text_len=${text.length} media_urls=${urls.length} reasoning=${payload.isReasoning === true}`,
       );
@@ -1021,6 +1037,8 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
           log?.info?.(`[${account.accountId}] clawchat-plugin-openclaw final skipped: already delivered at a message boundary`);
           return;
         }
+        // A non-owner final whose only content was dropped local media sends nothing.
+        if (options.nonOwnerTurn && !finalText.trim() && !richFragment && finalUrls.length === 0) return;
         const mediaFragments = await uploadMediaUrls(finalUrls);
         const result = await sendStatic(
           finalText,
@@ -1097,7 +1115,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
         ? async (payload: ReplyPayload) => {
             if (consumeTerminalSend("reasoning")) return;
             const text = resolvePayloadText(payload);
-            await emitFullRuntimeText("reasoning", text, resolveOutboundMediaUrls(payload).filter(Boolean));
+            await emitFullRuntimeText("reasoning", text, filterReplyMedia(resolveOutboundMediaUrls(payload).filter(Boolean)));
             const trimmed = text.trim();
             if (trimmed) reasoningText = reasoningText ? `${reasoningText}\n${trimmed}` : trimmed;
           }
@@ -1120,7 +1138,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
             if (consumeTerminalSend("tool-result")) return;
             const text = resolvePayloadText(payload);
             if (isDefaultToolResultText(text)) return;
-            await emitFullRuntimeText("tool result", text, resolveOutboundMediaUrls(payload).filter(Boolean));
+            await emitFullRuntimeText("tool result", text, filterReplyMedia(resolveOutboundMediaUrls(payload).filter(Boolean)));
           }
         : undefined,
       onItemEvent: splitFullOutput

package/src/runtime.ts

@@ -1,4 +1,5 @@
 import { applyDmRecallDefault } from "./dm-recall-default.ts";
+import { HOST_FLOOR, HOST_TOOL_SEARCH_DEFAULT_ON, hostAtLeast, hostToolSearchEnabled } from "./host-version.ts";
 import {
   AckTimeoutError,
   AuthError,
@@ -86,7 +87,9 @@ import {
   type ClawChatStore,
   type MessageRow,
 } from "./storage.ts";
-import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.ts";
+import { getClawChatGroupPrompt, getClawChatPlatformPrompt, getClawChatUserPrompt } from "./plugin-prompts.ts";
+import { classifyChat, NON_OWNER_TOOL_ALLOWLIST } from "./turn-boundary.ts";
+import { resolveOwnerIdentity } from "./owner-identity.ts";
 import {
   loadClawChatPromptMetadata,
   type ClawChatGroupParticipantPrompt,
@@ -111,7 +114,8 @@ import { PermissionCache } from "./permissions.ts";
 import { buildAwarenessNoteEnvelope, buildMomentCommentNoteEnvelope } from "./awareness-note-turn.ts";
 import { handlePermissionResult } from "./permission-result.ts";
 
-type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
+type Log = { debug?: (m: string) => void; info?: (m: string) => void;
+  warn?: (m: string) => void; error?: (m: string) => void };
 type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
 type CompatibleChannelRuntime = PluginRuntime["channel"] & {
   inbound?: { buildContext?: ChannelContextBuilder };
@@ -140,6 +144,7 @@ type RuntimeConnectionStore = Pick<
       | "releaseActivationBootstrapClaim"
       | "markActivationBootstrapSent"
       | "getActivationConversation"
+      | "lookupActivationIdentity"
       | "getLastResolvedDeviceId"
       | "listRecentGroupMessages"
       | "recallMessage"
@@ -585,6 +590,8 @@ export interface StartGatewayParams {
   setStatus: (next: ChannelAccountSnapshot) => void;
   getStatus: () => ChannelAccountSnapshot;
   log?: Log;
+  /** Internal — set on recursive re-entry so the approve-unsupported warning is issued once per lifecycle. */
+  boundaryWarningIssued?: boolean;
   /** Test hook only. */
   store?: RuntimeConnectionStore | null;
   /** Test hook only. */
@@ -1057,6 +1064,9 @@ async function waitForActivationCredentials(params: {
   return null;
 }
 
+let warnedBelowHostFloor = false;
+let loggedHostToolSearch = false;
+
 export async function startOpenclawClawlingGateway(params: StartGatewayParams): Promise<void> {
   const { cfg, abortSignal, setStatus, getStatus, log } = params;
   let account = params.account;
@@ -1064,6 +1074,21 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   const runtime = getOpenclawClawlingRuntime();
   const accountId = account.accountId;
   const store = resolveConnectionStore(params, runtime);
+  if (!warnedBelowHostFloor && !hostAtLeast(runtime.version, HOST_FLOOR)) {
+    warnedBelowHostFloor = true;
+    log?.warn?.(`clawchat-plugin-openclaw: host ${runtime.version ?? "unknown"} is below ${HOST_FLOOR}; turns your owner did not start keep the host tools in their schema and rely on the before_tool_call block`);
+  }
+  if (
+    !loggedHostToolSearch &&
+    hostAtLeast(runtime.version, HOST_TOOL_SEARCH_DEFAULT_ON) &&
+    hostToolSearchEnabled(cfg)
+  ) {
+    loggedHostToolSearch = true;
+    log?.info?.("clawchat-plugin-openclaw: host tool search is on; turns your owner did not start can still use only the allowlisted tools (set tools.toolSearch.enabled=false to turn tool search off; this affects every turn)");
+  }
+  if (!params.boundaryWarningIssued && account.nonOwnerHostTools === "approve") {
+    log?.warn?.("clawchat-plugin-openclaw: non-owner-host-tools approve is not supported yet; using off");
+  }
   log?.info?.(
     `[${accountId}] clawchat-plugin-openclaw runtime start entered configured=${account.configured} enabled=${account.enabled} hasToken=${Boolean(account.token)} hasUserId=${Boolean(account.userId)} hasOwnerUserId=${Boolean(account.ownerUserId)} websocketUrl=${account.websocketUrl || "(empty)"}`,
   );
@@ -1897,6 +1922,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       if (abortSignal.aborted) return;
       void startOpenclawClawlingGateway({
         ...params,
+        boundaryWarningIssued: true,
         account: { ...params.account },
         // Carry the live refresh token forward (a rotation earlier this lifecycle
         // leaves the in-memory `cfg` stale; see refreshTokenOverride).
@@ -1944,6 +1970,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     // agent must NOT re-read it — thread the live refresh token forward instead.
     await startOpenclawClawlingGateway({
       ...params,
+      boundaryWarningIssued: true,
       account: {
         ...params.account,
         configured: true,
@@ -2552,14 +2579,24 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // "invalid conversation id" and msghub never acks the send. Proactive owner
   // messages must be addressed to the direct conversation recorded at
   // activation (parity with the hermes adapter's _owner_direct_chat_id).
-  const resolveOwnerDirectConversationId = (): string | null => {
-    const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) return null;
-    const conversationId = store
-      ?.getActivationConversation?.({ platform: "openclaw", accountId })
-      ?.conversationId?.trim();
-    return conversationId || null;
+  // One warning per failure class for this lifecycle; never logs ids or SQL.
+  const ownerIdentityWarnings = new Set<string>();
+  const warnOwnerIdentity = (failure: string) => {
+    if (ownerIdentityWarnings.has(failure)) return;
+    ownerIdentityWarnings.add(failure);
+    try {
+      log?.warn?.(`clawchat-plugin-openclaw: ${failure}; owner identity unavailable`);
+    } catch {
+      // Logging cannot change the (fail-closed) answer.
+    }
   };
+  const resolveOwnerDirectConversationId = (): string | null =>
+    // Shared strict resolver (src/owner-identity.ts): the SQLite activation
+    // row decides; the config `ownerUserId` mirror may be stale or absent and
+    // can neither hide nor invent the owner's direct chat. Unavailable storage
+    // or a cleared/rejected token yields no owner DM (fail closed).
+    resolveOwnerIdentity(store, accountId, account.ownerUserId, warnOwnerIdentity,
+      params.rejectedActivationToken).conversationId;
   // R3: the owner's direct conversation is never gated by the dead-chat send
   // guard. If it were, the very message explaining why the agent went dark
   // (skill-update notices, auth/logout notices, group owner-attention
@@ -3338,8 +3375,28 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
     turn = await withCachedGroupSenderNames(turn, memoryRoot);
     const conversationTarget = `${CHANNEL_ID}:${formatConversationSubject(turn.peer)}`;
-    const turnPrompt = await buildPromptForTurn(turn, memoryRoot);
     const senderIsOwner = turn.senderIsOwner === true || turn.senderId === account.ownerUserId;
+    // Owner turn <=> the owner's activation direct chat. Resolved per turn;
+    // any failure leaves it null, which classifies as non-owner (fail closed).
+    let ownerConversationId: string | null = null;
+    try {
+      ownerConversationId = resolveOwnerDirectConversationId();
+    } catch {
+      ownerConversationId = null;
+    }
+    const turnClass = classifyChat({
+      kind: turn.peer.kind,
+      chatId: turn.peer.id,
+      ownerDirectConversationId: ownerConversationId,
+    });
+    const narrowHostTools = turnClass === "non-owner";
+    const baseTurnPrompt = await buildPromptForTurn(turn, memoryRoot);
+    const nonOwnerMediaGuidance =
+      "To send an image or file here, include it in your final reply as an http(s) URL; local files cannot be sent from this chat.";
+    const turnPrompt = [
+      ...(narrowHostTools ? [getClawChatPlatformPrompt(), nonOwnerMediaGuidance] : []),
+      baseTurnPrompt,
+    ].filter(Boolean).join("\n\n");
     const ctxPayload = resolveChannelContextBuilder(rt)({
       channel: CHANNEL_ID,
       accountId: route.accountId ?? accountId,
@@ -3385,6 +3442,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ...(isOpenClawTextSlashCommand(turn.rawBody, cfg) && senderIsOwner
           ? { commands: { authorized: true, source: "text" } }
           : {}),
+        // toolPolicy: host 2026.8.1+ (floor)
+        ...(narrowHostTools ? { toolPolicy: { allow: [...NON_OWNER_TOOL_ALLOWLIST] } } : {}),
       },
       ...(memoryRoot ? { extra: { memoryRoot } } : {}),
       // Deliver the rendered ClawChat per-turn prompt (owner agent_behavior,
@@ -3440,7 +3499,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     if (stagedDirectPrompt) {
       stageClawChatPromptInjection({
         sessionKey: resolvedSessionKey,
-        prompt: turnPrompt,
+        prompt: baseTurnPrompt,
       });
     }
 
@@ -3501,6 +3560,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           // conversation, not `ownerUserId` (a usr_… chat_id is rejected by
           // member-backend). Passed as a thunk so it is resolved at send time.
           resolveOwnerConversationId: resolveOwnerDirectConversationId,
+          nonOwnerTurn: narrowHostTools,
           log,
         });
 
@@ -3514,8 +3574,15 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
           dispatcher,
           onSettled: () => markDispatchIdle(),
           run: () =>
-            runWithTerminalClawChatSendScope(terminalSendScopeId, () =>
-              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg: dispatchCfg, dispatcher, replyOptions }),
+            runWithTerminalClawChatSendScope({ scopeId: terminalSendScopeId, sessionKey: resolvedSessionKey }, () =>
+              rt.reply.dispatchReplyFromConfig({
+                ctx: ctxPayload,
+                cfg: dispatchCfg,
+                dispatcher,
+                replyOptions: narrowHostTools
+                  ? { ...replyOptions, toolsAllow: [...NON_OWNER_TOOL_ALLOWLIST] }
+                  : replyOptions,
+              }),
             ),
         });
         const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
@@ -4101,6 +4168,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       if (activationAccount.source === "sqlite" && !abortSignal.aborted) {
         await startOpenclawClawlingGateway({
           ...params,
+          boundaryWarningIssued: true,
           account: {
             ...params.account,
             configured: false,