@clawling/clawchat-plugin-openclaw 2026.9.14-2 → 2026.9.17-1

package/src/api-client.ts

@@ -1,6 +1,8 @@
 import {
   ClawlingApiError,
   type AgentAppView,
+  type AgentConnectCheckInput,
+  type AgentConnectCheckResult,
   type AgentMetadataPatch,
   type AgentProfile,
   type AgentConnectResult,
@@ -17,9 +19,24 @@ import {
   type UserSearchHit,
 } from "./api-types.ts";
 import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
+import type { OnboardingReportFields } from "./onboarding-report.ts";
 import type { PermissionPolicy, PermState } from "./permissions.ts";
 import { CHANNEL_ID } from "./config.ts";
 
+/** Params for `agentsConnect` — exchange an invite code for an agent token. */
+export interface AgentsConnectInput {
+  /** The invite code entered by the operator. */
+  code: string;
+  /** Platform the agent is attaching from (e.g. "openclaw"). */
+  platform: string;
+  /** Agent type tag (e.g. "bot"). */
+  type: string;
+  /** Existing configured ClawChat user id, when re-activating an account. */
+  user_id?: string;
+  /** agent_kind / os / lane / wiki_version / matched_install — see onboarding-context.ts */
+  context?: Record<string, string>;
+}
+
 export interface PluginReportInput {
   deviceId: string;
   platform: string;
@@ -27,10 +44,12 @@ export interface PluginReportInput {
   agentVersion: string;
   runtimeName: string;
   runtimeVersion: string;
+  /** Agent-written onboarding facts (`~/clawchat/onboarding.json`); optional. */
+  onboarding?: OnboardingReportFields | null;
 }
 
-export function buildPluginReportBody(input: PluginReportInput): Record<string, string> {
-  return {
+export function buildPluginReportBody(input: PluginReportInput): Record<string, unknown> {
+  const body: Record<string, unknown> = {
     device_id: input.deviceId,
     platform: input.platform,
     plugin_version: input.pluginVersion,
@@ -38,6 +57,12 @@ export function buildPluginReportBody(input: PluginReportInput): Record<string,
     runtime_name: input.runtimeName,
     runtime_version: input.runtimeVersion,
   };
+  const ob = input.onboarding;
+  if (ob?.wiki_report_id !== undefined) body.wiki_report_id = ob.wiki_report_id;
+  if (ob?.capability_tier !== undefined) body.capability_tier = ob.capability_tier;
+  if (ob?.capability_ceiling !== undefined) body.capability_ceiling = ob.capability_ceiling;
+  if (ob?.capabilities !== undefined) body.capabilities = ob.capabilities;
+  return body;
 }
 
 export interface ApiClientOptions {
@@ -133,6 +158,8 @@ export interface OpenclawClawlingApiClient {
     text: string;
   }): Promise<{ comment: MomentComment }>;
   deleteMomentComment(params: { momentId: number; commentId: number }): Promise<{ ok: boolean }>;
+  /** Find-or-create the direct conversation with a friend (`POST /v1/conversations/direct`); 19012 when not a friend. */
+  getDirectConversation(peerId: string): Promise<{ conversation: { id: string; type: string } }>;
   getConversation(conversationId: string): Promise<{ conversation: ConversationDetails }>;
   leaveConversation(conversationId: string): Promise<{ ok: boolean }>;
   addConversationMember(
@@ -147,19 +174,16 @@ export interface OpenclawClawlingApiClient {
   uploadMedia(params: { buffer: Buffer; filename: string; mime?: string }): Promise<UploadResult>;
   /**
    * Exchange an invite code for an agent token.
-   * Request body shape: `{ code, platform, type, user_id?, plugin_version? }`.
-   * `plugin_version` is included when `ApiClientOptions.pluginVersion` is set.
+   * Request body shape: `{ code, platform, type, user_id?, plugin_version?, agent_kind?, os?, lane?, wiki_version?, matched_install? }`.
+   * `plugin_version` is included when `ApiClientOptions.pluginVersion` is set;
+   * `context` is flattened onto the top-level body (see `onboarding-context.ts`).
    */
-  agentsConnect(params: {
-    /** The invite code entered by the operator. */
-    code: string;
-    /** Platform the agent is attaching from (e.g. "openclaw"). */
-    platform: string;
-    /** Agent type tag (e.g. "bot"). */
-    type: string;
-    /** Existing configured ClawChat user id, when re-activating an account. */
-    user_id?: string;
-  }): Promise<AgentConnectResult>;
+  agentsConnect(params: AgentsConnectInput): Promise<AgentConnectResult>;
+  /**
+   * POST /v1/agents/connect/check — non-consuming pairability pre-check. Same
+   * `X-Device-Id` as `agentsConnect` so the funnel row is keyed identically.
+   */
+  agentsConnectCheck(input: AgentConnectCheckInput): Promise<AgentConnectCheckResult>;
   /**
    * Upload an avatar image via `POST /v1/files/upload-url`. The resulting
    * `url` is what you then pass to `updateMyProfile({ avatar_url: url })`.
@@ -211,14 +235,25 @@ const CODE_INTERNAL = 1; // CodeInternal — transient.
 const CODE_BAD_REQUEST = 400; // bad body / device id — permanent (client bug).
 /**
  * CodeInvalidRefresh — returned for BOTH a genuinely revoked/invalid refresh
- * token AND a single-use refresh token that was already CONSUMED by a prior
- * successful rotation (a duplicate-supervisor / concurrent-refresh / stale-store
- * race). The stateless `authRefresh` cannot tell the two apart, so it reports
- * `permanent`; the stateful `RefreshManager` re-classifies a consumed-rotation
- * race back to transient (see §B race) before any auto-logout.
+ * token AND a refresh token that was already CONSUMED by a prior successful
+ * rotation (a duplicate-supervisor / concurrent-refresh / stale-store race), once
+ * the backend's short replay grace window no longer covers it. The stateless
+ * `authRefresh` cannot tell the two apart, so it reports `permanent`; the
+ * stateful `RefreshManager` re-classifies a consumed-rotation race back to
+ * transient (see §B race) before any auto-logout.
  */
 export const CODE_INVALID_REFRESH = 10003;
 
+/**
+ * §B attempt deadline — total wall clock for one refresh attempt (request AND
+ * response body). A hit aborts the request and is TRANSIENT. Kept below
+ * `MIN_REFRESH_INTERVAL_MS` (30s) so the min-interval floor, not the deadline,
+ * sets the retry cadence: a retry of the same refresh token then lands inside
+ * the backend refresh grace window if the server rotated but the response was
+ * lost.
+ */
+export const REFRESH_REQUEST_TIMEOUT_MS = 20_000;
+
 /**
  * §0/§B — call `POST /v1/auth/refresh` to rotate the access+refresh token.
  *
@@ -228,9 +263,14 @@ export const CODE_INVALID_REFRESH = 10003;
  * always HTTP 200 — branch on the envelope `code`, NOT on HTTP status. This is
  * a standalone function (not a method on the token-bearing client) precisely
  * because no bearer token participates.
+ *
+ * The whole attempt is bounded by `REFRESH_REQUEST_TIMEOUT_MS` (§B attempt
+ * deadline): the request is aborted via its signal, and the deadline is also
+ * raced against the attempt so a fetch implementation that ignores the signal
+ * cannot hang the caller.
  */
 export async function authRefresh(
-  opts: { baseUrl: string; fetchImpl?: typeof fetch },
+  opts: { baseUrl: string; fetchImpl?: typeof fetch; timeoutMs?: number },
   params: AuthRefreshParams,
 ): Promise<AuthRefreshResult> {
   const baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -238,6 +278,31 @@ export async function authRefresh(
   if (!params.refreshToken?.trim()) {
     return { kind: "permanent", code: CODE_INVALID_REFRESH, message: "missing refresh token" };
   }
+  const timeoutMs = opts.timeoutMs ?? REFRESH_REQUEST_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<AuthRefreshResult>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort(new Error("refresh request timed out"));
+      resolve({ kind: "transient", message: `refresh request timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      authRefreshAttempt(baseUrl, fetchImpl, params, controller.signal),
+      deadline,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function authRefreshAttempt(
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  params: AuthRefreshParams,
+  signal: AbortSignal,
+): Promise<AuthRefreshResult> {
   let res: Response;
   try {
     res = await fetchImpl(`${baseUrl}/v1/auth/refresh`, {
@@ -248,6 +313,8 @@ export async function authRefresh(
         "x-device-id": params.deviceId,
       },
       body: JSON.stringify({ refresh_token: params.refreshToken.trim() }),
+      // Still in effect while the body is read below.
+      signal,
     });
   } catch (err) {
     // Network error / timeout / DNS — TRANSIENT (no rotation committed).
@@ -292,8 +359,9 @@ export async function authRefresh(
     const refreshToken = typeof data.refresh_token === "string" ? data.refresh_token : "";
     if (!accessToken || !refreshToken) {
       // Rotation succeeded server-side but the body is malformed — transient so
-      // we retry; the next attempt will return 10003 (rotation single-use) and
-      // escalate to permanent (§B transient→permanent).
+      // we retry; inside the backend grace window the retry redeems the old
+      // token again, after it the retry returns 10003 and escalates to
+      // permanent (§B transient→permanent).
       return { kind: "transient", status: 200, message: "refresh: rotation body incomplete" };
     }
     return { kind: "success", accessToken, refreshToken };
@@ -639,6 +707,17 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         `/v1/moments/${encodeURIComponent(String(params.momentId))}/comments/${encodeURIComponent(String(params.commentId))}`,
       );
     },
+    async getDirectConversation(peerId): Promise<{ conversation: { id: string; type: string } }> {
+      assertNonBlankId(peerId, "getDirectConversation: peerId");
+      return await call<{ conversation: { id: string; type: string } }>(
+        "POST",
+        "/v1/conversations/direct",
+        {
+          body: JSON.stringify({ peer_id: peerId.trim() }),
+          headers: { "content-type": "application/json" },
+        },
+      );
+    },
     async getConversation(conversationId): Promise<{ conversation: ConversationDetails }> {
       return await call<{ conversation: ConversationDetails }>(
         "GET",
@@ -698,7 +777,20 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
         },
       );
     },
-    async agentsConnect({ code: inviteCode, platform, type, user_id: userId }): Promise<AgentConnectResult> {
+    async agentsConnectCheck({ code, platform, user_id: userId, context }): Promise<AgentConnectCheckResult> {
+      if (!code?.trim()) {
+        throw new ClawlingApiError("validation", "agentsConnectCheck: code is required");
+      }
+      const body: Record<string, string> = { code: code.trim(), platform: platform.trim() };
+      if (userId?.trim()) body.user_id = userId.trim();
+      if (opts.pluginVersion?.trim()) body.plugin_version = opts.pluginVersion.trim();
+      for (const [k, v] of Object.entries(context ?? {})) if (v) body[k] = v;
+      return await call<AgentConnectCheckResult>("POST", "/v1/agents/connect/check", {
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      });
+    },
+    async agentsConnect({ code: inviteCode, platform, type, user_id: userId, context }): Promise<AgentConnectResult> {
       if (!inviteCode?.trim()) {
         throw new ClawlingApiError("validation", "agentsConnect: inviteCode is required");
       }
@@ -719,6 +811,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       if (opts.pluginVersion?.trim()) {
         body.plugin_version = opts.pluginVersion.trim();
       }
+      for (const [k, v] of Object.entries(context ?? {})) if (v) body[k] = v;
       return await call<AgentConnectResult>("POST", "/v1/agents/connect", {
         // `X-Device-Id` is added globally via `authHeaders` on every request.
         headers: { "content-type": "application/json" },

package/src/api-types.ts

@@ -146,6 +146,24 @@ export interface AgentConnectResult {
   conversation?: AgentConnectConversation;
 }
 
+/** Body of POST /v1/agents/connect/check. Same optional telemetry as /connect. */
+export interface AgentConnectCheckInput {
+  code: string;
+  platform: string;
+  user_id?: string;
+  /** agent_kind / os / lane / wiki_version / matched_install — see onboarding-context.ts */
+  context?: Record<string, string>;
+}
+
+/** data of POST /v1/agents/connect/check. Older backends omit `bound_agent`. */
+export interface AgentConnectCheckResult {
+  pairable: boolean;
+  status: string;
+  expires_at?: string;
+  user_id_status?: string;
+  bound_agent?: boolean;
+}
+
 export type AgentAppView = { id: string; app_id?: string; name: string; url: string };
 
 export type ClawlingApiErrorKind =

package/src/config.ts

@@ -114,6 +114,8 @@ export type OpenclawClawlingAccountConfig = {
   richInteractions?: boolean;
   /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
   awarenessNote?: boolean;
+  /** Speak first to a newly added non-owner friend (default true). */
+  friendGreeting?: boolean;
   /** Auto-install the Liveware Sample demo app when no liveware app is registered (default true). */
   livewareSample?: boolean;
   reconnect?: OpenclawClawlingReconnectConfig;
@@ -174,6 +176,7 @@ export const openclawClawlingAccountConfigSchema = {
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
     awarenessNote: { type: "boolean" },
+    friendGreeting: { type: "boolean" },
     livewareSample: { type: "boolean" },
     reconnect: {
       type: "object",
@@ -311,6 +314,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardToolCalls: boolean;
   richInteractions: boolean;
   awarenessNote: boolean;
+  friendGreeting: boolean;
   livewareSample: boolean;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
@@ -649,6 +653,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
   const awarenessNote =
     typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
+  const friendGreeting =
+    typeof channel.friendGreeting === "boolean" ? channel.friendGreeting : true;
   const livewareSample =
     typeof channel.livewareSample === "boolean" ? channel.livewareSample : true;
 
@@ -678,6 +684,7 @@ export function resolveOpenclawClawlingAccount(
     forwardToolCalls,
     richInteractions,
     awarenessNote,
+    friendGreeting,
     livewareSample,
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),

package/src/connect-check.ts

@@ -0,0 +1,98 @@
+import { ClawlingApiError } from "./api-types.ts";
+import type { OpenclawClawlingApiClient } from "./api-client.ts";
+import { AGENTS_CONNECT_PLATFORM, RECONNECT_GUIDE_URL } from "./onboarding-context.ts";
+
+export interface ConnectPreCheck {
+  pairable: boolean;
+  status: string;
+  boundAgent: boolean;
+  userIdStatus: string;
+}
+
+/**
+ * Non-consuming pre-check of a connect code. Records the "checked" funnel
+ * stage server-side and tells us whether the code is bound to an existing
+ * agent (the reconnect prompt). Any transport-level failure — older backend,
+ * rate limit, network — degrades to `null`: the pre-check is telemetry plus a
+ * courtesy, never a gate in front of `/connect`.
+ */
+export async function preCheckConnectCode(
+  client: Pick<OpenclawClawlingApiClient, "agentsConnectCheck">,
+  input: { code: string; userId?: string; context?: Record<string, string> },
+  log: (message: string) => void,
+): Promise<ConnectPreCheck | null> {
+  try {
+    const res = await client.agentsConnectCheck({
+      code: input.code,
+      platform: AGENTS_CONNECT_PLATFORM,
+      ...(input.userId ? { user_id: input.userId } : {}),
+      ...(input.context ? { context: input.context } : {}),
+    });
+    // A 200 with no data says nothing about the code: degrade exactly like an
+    // unreachable endpoint (Hermes' `evaluate_precheck({})` does the same).
+    if (!res || typeof res !== "object" || Object.keys(res).length === 0) {
+      log("Connect-code pre-check returned no data; continuing without it.");
+      return null;
+    }
+    return {
+      pairable: res.pairable === true,
+      status: typeof res.status === "string" ? res.status : "",
+      boundAgent: res.bound_agent === true,
+      userIdStatus: typeof res.user_id_status === "string" ? res.user_id_status : "",
+    };
+  } catch (err) {
+    const kind = err instanceof ClawlingApiError ? err.kind : "error";
+    log(`Connect-code pre-check unavailable (${kind}); continuing without it.`);
+    return null;
+  }
+}
+
+/** Owner-facing explanation for `pairable: false`. No flags, no minutes, one URL. */
+export function unpairableMessage(pre: ConnectPreCheck): string {
+  if (pre.userIdStatus === "owner_mismatch" && pre.boundAgent) {
+    // The server cannot tell us whether the bound agent shares this identity's
+    // owner, only that it is a different agent — so say exactly that.
+    return (
+      "This connect code is the reconnect prompt for a different agent than the identity stored here. " +
+      "Ask your owner to send the reconnect prompt from THIS agent's chat in the ClawChat app."
+    );
+  }
+  if (pre.userIdStatus === "invalid") {
+    return (
+      "The identity stored here is not a valid ClawChat user id, so it cannot be restored. " +
+      "Activate as a brand-new agent with --new-account."
+    );
+  }
+  if (pre.userIdStatus === "owner_mismatch") {
+    return (
+      "This connect code belongs to a different ClawChat account than the identity stored here. " +
+      "Ask the owner of THIS agent for a code, or activate as a brand-new agent with --new-account."
+    );
+  }
+  switch (pre.status) {
+    case "paired":
+      return (
+        "This connect code was already redeemed. If this agent lost its connection, ask your owner " +
+        `to send you the reconnect prompt from the ClawChat app and follow ${RECONNECT_GUIDE_URL}; ` +
+        "otherwise ask for a fresh code."
+      );
+    case "expired":
+    case "invalid":
+      return `This connect code is ${pre.status}. Ask your owner for a fresh code from the ClawChat app.`;
+    default:
+      return `This connect code is not pairable (status=${pre.status || "unknown"}). Ask your owner for a fresh code from the ClawChat app.`;
+  }
+}
+
+/**
+ * Refusal for a new-identity intent (`--new-account` or the interactive
+ * choice) on a bound code: without a user_id, `/connect` restores the bound
+ * agent instead of creating one. No flags, no minutes, no URL.
+ */
+export function boundCodeNewIdentityMessage(): string {
+  return (
+    "This is a reconnect code bound to an existing agent, so it cannot create a new agent. " +
+    "Ask your owner for a normal connect code from the ClawChat app, or use this reconnect prompt " +
+    "on the agent it belongs to."
+  );
+}

package/src/friend-greeting.ts

@@ -0,0 +1,91 @@
+/**
+ * First message to a newly added NON-owner friend.
+ *
+ * `friend.added` used to be a pure awareness event. The server creates the
+ * direct conversation inside the friend-accept transaction, but the signal
+ * only carries the counterparty `usr_…` — so the runtime resolves the
+ * conversation through `POST /v1/conversations/direct` and then feeds ONE
+ * synthetic inbound turn (built here) into the normal dispatch path, the same
+ * way the activation bootstrap greets the owner.
+ *
+ * The prompt is deliberately distinct from the owner activation prompt: this
+ * reader is a stranger, so "you are connected and ready" makes no sense and
+ * the agent must say whose agent it is instead.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export const FRIEND_GREETING_FALLBACK = [
+  "A ClawChat user has just become your friend. You are now in a direct conversation with them; they are not your owner.",
+  "Reply now with one short, friendly greeting message in this conversation: introduce yourself by name, say you are an AI agent acting on behalf of your owner, and invite them to tell you what they need.",
+  "Send it as a normal chat reply. Do not write or create any files or notes, and do not call tools just to greet.",
+  "Do not share your owner's private information, and do not ask the user for personal information.",
+].join("\n");
+
+// Cross-plugin, user-editable override read lazily so edits apply on the next
+// friend without a restart. Any read failure falls back to the built-in text.
+// Mirrors `buildActivationBootstrapText` (`~/clawchat/greeting.md`).
+export function buildFriendGreetingText(homeDir: string = os.homedir()): string {
+  const greetingPath = path.join(homeDir, "clawchat", "friend-greeting.md");
+  try {
+    const raw = fs.readFileSync(greetingPath);
+    const override = new TextDecoder("utf-8", { fatal: true }).decode(raw).trim();
+    if (override.length > 0) {
+      return override;
+    }
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      console.warn(`clawchat.friend-greeting failed to read override ${greetingPath}:`, error);
+    }
+  }
+  return FRIEND_GREETING_FALLBACK;
+}
+
+export interface BuildFriendGreetingEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /** The resolved direct conversation (`cnv_…`) shared with the new friend. */
+  conversationId: string;
+  /** The new friend's `usr_…` id — becomes the sender so the turn's session and sender metadata resolve to them. */
+  friendUserId: string;
+}
+
+/**
+ * Synthetic inbound envelope for the friend greeting turn. Same invariant as
+ * `buildActivationBootstrapEnvelope`: `conversationId` MUST be a conversation
+ * idcode — the agent's reply inherits this chat_id, and anything else is
+ * refused at the outbound boundary after a full LLM turn has been spent.
+ */
+export function buildFriendGreetingEnvelope(params: BuildFriendGreetingEnvelopeParams): Envelope {
+  const { account, conversationId, friendUserId } = params;
+  const text = buildFriendGreetingText();
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-friend-greeting-${now}`,
+    emitted_at: now,
+    chat_id: conversationId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: { id: friendUserId, type: "direct", nick_name: "" },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-friend-greeting-${conversationId}-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  } as unknown as Envelope;
+}