@clawling/clawchat-plugin-openclaw 2026.6.30-4 → 2026.7.2-1

package/src/friend-request-turn.ts

@@ -0,0 +1,87 @@
+/**
+ * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
+ *
+ * When the server fires a `friend.request` signal the runtime dispatches one
+ * deduped synthetic `message.send` envelope so the agent can reason about the
+ * pending request. The prompt text varies by the current "friend.add" permission
+ * policy state: a deny policy yields a decline/inform prompt; ask or allow
+ * yields a prompt that instructs the agent to review the request via the
+ * `clawchat_list_friend_requests` tool.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { PermState } from "./permissions.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+/**
+ * Returns canned prompt text for a friend-request reasoning turn based on the
+ * current "friend.add" permission policy state.
+ *
+ * - `deny`  → inform the agent it should decline; no accept instruction.
+ * - `ask` / `allow` → instruct the agent to review the pending request.
+ */
+export function friendRequestPromptFor(state: PermState): string {
+  if (state === "deny") {
+    return [
+      "A new friend request has arrived.",
+      "Your current friend-add policy is set to deny.",
+      "Do not add this contact.",
+      "You may inform the requester that you cannot add them at this time.",
+    ].join(" ");
+  }
+  return [
+    "A new friend request has arrived.",
+    "Please review the pending request by calling `clawchat_list_friend_requests`",
+    "and decide whether to accept it.",
+  ].join(" ");
+}
+
+export interface BuildFriendRequestEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /** Current "friend.add" permission policy state. */
+  state: PermState;
+  /** entity_id from the notify.signal payload (the requesting user). */
+  entityId: string;
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that triggers one agent reasoning
+ * turn for a pending friend request. The envelope shape mirrors the
+ * activation-bootstrap envelope; it targets the owner's direct conversation so
+ * the agent has context about who it is reasoning for.
+ */
+export function buildFriendRequestEnvelope(
+  params: BuildFriendRequestEnvelopeParams,
+): Envelope {
+  const { account, state, entityId } = params;
+  const text = friendRequestPromptFor(state);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-friend-request",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${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,
+        },
+      },
+    },
+  };
+}

package/src/gate-outcome.ts

@@ -0,0 +1,44 @@
+/**
+ * Maps backend owner-approval gate codes to structured tool outcomes.
+ *
+ * Backend gate codes (confirmed live contract):
+ *   21001 — pending owner approval (payload: { request_id, operation, expires_at })
+ *   21003 — policy forbidden       (payload: { operation })
+ *
+ * Returns null for any other code so callers can fall through to normal handling.
+ */
+
+export type PendingApprovalOutcome = {
+  status: "pending_owner_approval";
+  request_id: string;
+  operation: string;
+  expires_at: number;
+};
+
+export type ForbiddenOutcome = {
+  status: "forbidden_by_owner";
+  operation: string;
+};
+
+export type GateOutcome = PendingApprovalOutcome | ForbiddenOutcome;
+
+export function mapGateOutcome(
+  code: number,
+  data: Record<string, unknown>,
+): GateOutcome | null {
+  if (code === 21001) {
+    return {
+      status: "pending_owner_approval",
+      request_id: typeof data.request_id === "string" ? data.request_id : "",
+      operation: typeof data.operation === "string" ? data.operation : "",
+      expires_at: typeof data.expires_at === "number" ? data.expires_at : 0,
+    };
+  }
+  if (code === 21003) {
+    return {
+      status: "forbidden_by_owner",
+      operation: typeof data.operation === "string" ? data.operation : "",
+    };
+  }
+  return null;
+}

package/src/inbound.ts

@@ -8,6 +8,7 @@ import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import type { MediaItem } from "./media-runtime.ts";
 import { extractMediaFragments, fragmentsToText, type MentionedUser } from "./message-mapper.ts";
 import { hasRenderableText, isInboundMessagePayload } from "./protocol.ts";
+import type { PermissionResultMetadata } from "./permission-result.ts";
 
 export interface IngestTurnParams {
   channel: "clawchat-plugin-openclaw";
@@ -81,6 +82,20 @@ export interface DispatchInboundParams {
     text: string;
     chatId: string;
   }) => Promise<boolean>;
+  /**
+   * Optional consumer for `permission_result` system-message receipts.
+   *
+   * When `sender.id === "system"` and `payload.metadata.kind ===
+   * "permission_result"`, the guard calls this callback with the metadata
+   * object instead of performing the generic system-message drop. The
+   * callback is responsible for deduplication and synthetic-turn dispatch
+   * (see `src/permission-result.ts`).
+   *
+   * When absent, `permission_result` frames fall through to the existing
+   * system-message drop (safe default — no regression for callers that have
+   * not yet wired the consumer).
+   */
+  consumePermissionResult?: (metadata: PermissionResultMetadata) => Promise<void>;
   log?: { info?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -241,6 +256,19 @@ export async function dispatchOpenclawClawlingInbound(
     return;
   }
   if (sender.id === "system") {
+    // Intercept `permission_result` receipts before the generic system-message
+    // drop. The discriminator is `payload.metadata.kind === "permission_result"`;
+    // all other system messages (group-join notifications, etc.) still drop.
+    const rawPayload = envelope.payload as Record<string, unknown>;
+    const meta = rawPayload.metadata as Record<string, unknown> | undefined;
+    if (
+      params.consumePermissionResult &&
+      meta != null &&
+      meta.kind === "permission_result"
+    ) {
+      await params.consumePermissionResult(meta as unknown as PermissionResultMetadata);
+      return;
+    }
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip system message msg=${payload.message_id}`,
     );

package/src/permission-result.ts

@@ -0,0 +1,128 @@
+/**
+ * Consumer for `permission_result` system-message receipts.
+ *
+ * When the backend delivers a `permission_result` outcome as a
+ * `message.send` system frame (`sender.id="system"`, `payload.metadata.kind
+ * ="permission_result"`), this module deduplicates by `request_id` and
+ * produces a synthetic context-note turn so the agent can close the loop
+ * on the original permission request.
+ *
+ * Wire shape (authoritative):
+ * ```
+ * payload.metadata = {
+ *   kind: "permission_result",
+ *   operation: "friend.add",
+ *   outcome: "approved" | "denied" | "expired" | "failed",
+ *   reason: "owner_allowed" | …,
+ *   request_id: "prq_…",
+ * }
+ * ```
+ * The discriminator is `payload.metadata.kind === "permission_result"`.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export interface PermissionResultMetadata {
+  kind: "permission_result";
+  operation: string;
+  outcome: "approved" | "denied" | "expired" | "failed";
+  reason: string;
+  request_id: string;
+}
+
+// Module-level dedup set — `request_id` values are stable backend identifiers.
+// A duplicate receipt (e.g. from WS replay on reconnect) must not re-trigger
+// an agent turn.
+const _seenRequestIds = new Set<string>();
+
+/**
+ * @internal Test helper — reset the dedup set between isolated test runs.
+ * Never call this in production code.
+ */
+export function _resetPermissionResultDedup(): void {
+  _seenRequestIds.clear();
+}
+
+function buildOutcomeNote(metadata: PermissionResultMetadata): string {
+  const { operation, outcome, reason } = metadata;
+  const outcomeLabel =
+    outcome === "approved"
+      ? "approved"
+      : outcome === "denied"
+        ? "denied"
+        : outcome === "expired"
+          ? "expired"
+          : "failed";
+  const resolution =
+    outcome === "approved"
+      ? "The requested action has been completed."
+      : "No further action was taken.";
+  return [
+    `Permission request for operation "${operation}" has been ${outcomeLabel}.`,
+    `Reason: ${reason}.`,
+    resolution,
+  ].join(" ");
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that delivers a
+ * `permission_result` context note to the agent.
+ *
+ * Mirrors the `buildFriendRequestEnvelope` pattern: a synthetic inbound
+ * `message.send` targeting the owner's direct conversation, routed through
+ * `handleInboundEnvelope` so the agent can reason about the outcome.
+ */
+export function buildPermissionResultEnvelope(params: {
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">;
+  metadata: PermissionResultMetadata;
+}): Envelope {
+  const { account, metadata } = params;
+  const text = buildOutcomeNote(metadata);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-permission-result",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${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,
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Handles a `permission_result` receipt. Deduplicates by `request_id`
+ * (idempotent — WS replay on reconnect may deliver the same receipt again).
+ *
+ * Returns a synthetic context-note {@link Envelope} on a fresh receipt so
+ * the caller can feed it to `handleInboundEnvelope`; returns `null` when
+ * the `request_id` has already been processed.
+ */
+export function handlePermissionResult(
+  metadata: PermissionResultMetadata,
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">,
+): Envelope | null {
+  if (_seenRequestIds.has(metadata.request_id)) return null;
+  _seenRequestIds.add(metadata.request_id);
+  return buildPermissionResultEnvelope({ account, metadata });
+}

package/src/permissions.ts

@@ -0,0 +1,13 @@
+export type PermState = "ask" | "allow" | "deny";
+
+export interface PermissionPolicy {
+  byOperation: Record<string, PermState>;
+  momentVisibility: string[];
+}
+
+export class PermissionCache {
+  private p: PermissionPolicy = { byOperation: {}, momentVisibility: [] };
+  get(): PermissionPolicy { return this.p; }
+  set(p: PermissionPolicy): void { this.p = p; }
+  stateOf(op: string): PermState { return this.p.byOperation[op] ?? "ask"; }
+}

package/src/runtime.ts

@@ -38,7 +38,8 @@ import { dispatchOpenclawClawlingInbound, type IngestTurnParams } from "./inboun
 import {
   PendingConsentStore,
   handleOwnerConsentReply,
-  readEffectiveSkillVersions,
+  managedSkillExists,
+  readLocalSkillState,
   resolveBundledSkillsDir,
   resolveManagedSkillsDir,
   runSkillUpdateCheck,
@@ -78,6 +79,9 @@ import {
 import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
 import { openclawLlmContextDebug } from "./llm-context-debug.ts";
 import { GroupSettingsCache } from "./group-settings.ts";
+import { PermissionCache } from "./permissions.ts";
+import { buildFriendRequestEnvelope } from "./friend-request-turn.ts";
+import { handlePermissionResult } from "./permission-result.ts";
 
 type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
 type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
@@ -1752,6 +1756,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     context: wsLogContext,
   });
   const groupSettingsCache = new GroupSettingsCache();
+  const permissionCache = new PermissionCache();
   // Findings 2 & 3 — gate group dispatch on the IN-FLIGHT settings pull, not just
   // the first one. The pull is fire-and-forget, so replayed/live group messages
   // could otherwise enter the governance gate against a stale/empty cache
@@ -1829,6 +1834,28 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
     })();
   };
+  // Best-effort pull of the agent's permission policy from the backend.
+  // Called at startup (bypassRefresh: true, mirrors pullGroupSettings startup)
+  // and on every successful (re)connect after hello-ok. On failure, logs and
+  // keeps the stale cache — never throws, never blocks message handling.
+  const pullPermissions = (opts?: { bypassRefresh?: boolean }): void => {
+    void (async () => {
+      try {
+        const policy = opts?.bypassRefresh
+          ? await (conversationApiClient ??= buildConversationApiClient()).getMyPermissions()
+          : await getConversationApiClient().getMyPermissions();
+        permissionCache.set(policy);
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull ok ops=${Object.keys(policy.byOperation).length}`,
+        );
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw permissions pull failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        // Keep stale cache; never throw.
+      }
+    })();
+  };
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -1962,6 +1989,8 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       // Re-pull per-group agent settings on every successful (re)connect so the
       // cache stays current after a network interruption or token refresh.
       pullGroupSettings();
+      // Re-pull permission policy alongside group settings on every (re)connect.
+      pullPermissions();
       // §A.1 — arm the proactive refresh timer from the live token's `exp`
       // every time a connection becomes ready (re-armed after every refresh via
       // the gateway re-enter).
@@ -2126,6 +2155,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // The bundled `./skills` dir is READ-ONLY here: a first-boot fallback for the
   // "current installed version" only — never written (it lives in node_modules
   // → may be read-only and is clobbered on `openclaw plugins update`).
+  // Update detection converges on raw sha256 (readLocalSkillState), not the
+  // frontmatter version, so a same-version content fix still applies; a
+  // manifest `removed` id tombstones the LOCAL managed copy (never bundled)
+  // via removeManagedSkill, deleting only ids the official manifest names.
   const skillUpdateConsent = new PendingConsentStore();
   const managedSkillsDir = resolveManagedSkillsDir();
   let bundledSkillsDir: string | null = null;
@@ -2138,13 +2171,30 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }`,
     );
   }
-  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+  // A usr_... id is not a valid chat_id — member-backend rejects it with
+  // "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;
+    if (!ownerUserId) return null;
+    const conversationId = store
+      ?.getActivationConversation?.({ platform: "openclaw", accountId })
+      ?.conversationId?.trim();
+    return conversationId || null;
+  };
+  const sendOwnerSkillMessage = async (text: string): Promise<void> => {
+    const conversationId = resolveOwnerDirectConversationId();
+    if (!conversationId) {
+      log?.info?.(
+        `[${accountId}] clawchat-plugin-openclaw skill-update owner message skipped: no activation conversation recorded`,
+      );
+      return;
+    }
     await sendOpenclawClawlingText({
       client,
       account,
-      to: { chatId: ownerUserId, chatType: "direct" },
+      to: { chatId: conversationId, chatType: "direct" },
       text,
       log,
     });
@@ -2158,10 +2208,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       return;
     }
     // Effective current = managed copy if present, else bundled (host precedence).
-    const localVersions = await readEffectiveSkillVersions(managedSkillsDir, bundledSkillsDir);
     await runSkillUpdateCheck({
       ownerUserId,
-      localVersions,
+      readLocalState: (id) => readLocalSkillState(managedSkillsDir, bundledSkillsDir, id),
+      hasManagedSkill: (id) => managedSkillExists(managedSkillsDir, id),
       fetchFn: globalThis.fetch,
       store: skillUpdateConsent,
       sendOwnerMessage: sendOwnerSkillMessage,
@@ -2193,6 +2243,11 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     });
   };
 
+  // Debounce flag for lighter-awareness consolidated notes.
+  // A single queueMicrotask coalesces all awareness signals that arrive in
+  // the same synchronous turn into exactly one handleInboundEnvelope call.
+  let pendingAwarenessNote = false;
+
   client.on("notify:signal", (env: Envelope) => {
     // §9.4 reliable system notification. The plugin holds no friend/roster
     // cache (friends are fetched on demand via REST tools), so there is nothing
@@ -2204,11 +2259,17 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         ? (env.payload as Record<string, unknown>)
         : undefined;
       const type = typeof payload?.type === "string" ? payload.type : "";
+      const entityId = typeof payload?.entity_id === "string" ? payload.entity_id : "";
       if (type === "agent.config.changed") {
         log?.info?.(
           `[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`,
         );
         pullGroupSettings();
+      } else if (type === "agent.permission.changed") {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw agent.permission.changed signal received; re-pulling permissions`,
+        );
+        pullPermissions();
       } else if (type === "clawchat.skill.update.check") {
         // Content-free trigger: check the official skill source in code and, if
         // there is an update, ask the owner in chat for consent. The atomic
@@ -2223,6 +2284,66 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
             }`,
           );
         });
+      } else if (type === "friend.request") {
+        // Dedup is already applied above by notifySignalObserver.observe (the live
+        // frame and its reliable-inbox replay share the same event_id and collapse
+        // to one observation). Build one synthetic reasoning turn so the agent can
+        // act on the pending request; the prompt text varies by policy state.
+        const state = permissionCache.stateOf("friend.add");
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw friend.request signal received; dispatching reasoning turn entity_id=${entityId} policy=${state}`,
+        );
+        void handleInboundEnvelope(buildFriendRequestEnvelope({ account, state, entityId }));
+      } else if (
+        type === "friend.added" ||
+        type === "friend.removed" ||
+        type === "friend.profile_updated" ||
+        type.startsWith("conversation.")
+      ) {
+        // Lighter-awareness: log + optional single consolidated note. Never
+        // injects a full reasoning turn per event (unlike friend.request).
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw ${type} signal received; lighter-awareness handling`,
+        );
+        if (account.awarenessNote && !pendingAwarenessNote) {
+          pendingAwarenessNote = true;
+          queueMicrotask(() => {
+            pendingAwarenessNote = false;
+            const now = Date.now();
+            void handleInboundEnvelope({
+              version: "2",
+              event: EVENT.MESSAGE_SEND,
+              trace_id: `clawchat-plugin-openclaw-awareness-${now}`,
+              emitted_at: now,
+              chat_id: account.ownerUserId,
+              chat_type: "direct",
+              to: { id: account.userId, type: "direct" },
+              sender: { id: "clawchat-awareness", type: "direct", nick_name: "ClawChat" },
+              payload: {
+                message_id: `clawchat-plugin-openclaw-awareness-${now}`,
+                message_mode: "normal",
+                message: {
+                  body: {
+                    fragments: [
+                      {
+                        kind: "text",
+                        text: "ClawChat awareness: your contacts or conversations have been updated.",
+                      },
+                    ],
+                  },
+                  context: { mentions: [], reply: null },
+                  streaming: {
+                    status: "static",
+                    sequence: 0,
+                    mutation_policy: "sealed",
+                    started_at: null,
+                    completed_at: null,
+                  },
+                },
+              },
+            } as unknown as Envelope);
+          });
+        }
       }
     }
   });
@@ -2787,10 +2908,10 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   });
 
   const forwardGroupApprovalSlashToOwner = async (turn: IngestTurnParams): Promise<IngestTurnResult> => {
-    const ownerUserId = account.ownerUserId?.trim();
-    if (!ownerUserId) {
+    const ownerConversationId = resolveOwnerDirectConversationId();
+    if (!ownerConversationId) {
       log?.error?.(
-        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_user_id chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        `[${accountId}] clawchat-plugin-openclaw group approval command suppressed reason=missing_owner_conversation chat_id=${turn.peer.id} msg=${turn.messageId}`,
       );
       return "skipped";
     }
@@ -2798,7 +2919,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       await sendOpenclawClawlingText({
         client,
         account,
-        to: { chatId: ownerUserId, chatType: "direct" },
+        to: { chatId: ownerConversationId, chatType: "direct" },
         text: groupOwnerAttentionText(turn.peer.id, turn.rawBody),
         log,
       });
@@ -2924,6 +3045,18 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         account,
         log,
         consumeOwnerConsent: consumeOwnerSkillConsent,
+        consumePermissionResult: async (metadata) => {
+          // A permission_result receipt closes the loop on an earlier request.
+          // Dedup by request_id; on a fresh receipt feed the synthetic context
+          // note back to the agent so it can react to the outcome.
+          const note = handlePermissionResult(metadata, account);
+          if (note) {
+            log?.info?.(
+              `[${accountId}] clawchat-plugin-openclaw permission_result receipt op=${metadata.operation} outcome=${metadata.outcome} request_id=${metadata.request_id}; dispatching context note`,
+            );
+            void handleInboundEnvelope(note);
+          }
+        },
         ingest: async (turn) => {
           ingestResult = await ingestTurn(turn);
         },
@@ -3020,6 +3153,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // rotating `account.token` out from under the already-constructed WS client.
   // Settling this releases the Finding-2 group-dispatch gate.
   pullGroupSettings({ bypassRefresh: true });
+  // Initial pull of permission policy at startup (best-effort; errors logged,
+  // stale cache kept). Uses bypassRefresh for the same reason as pullGroupSettings.
+  pullPermissions({ bypassRefresh: true });
   // Safety: never strand a held group message if the runtime is torn down while a
   // pull is in flight. `waitWithTimeout` already releases group waiters on abort,
   // but force the gate open too so any later `wait()` resolves immediately.