@alfe.ai/openclaw-chat 0.9.14 → 0.9.16

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { A as SessionData, D as AlfePluginConfig, E as AlfeChannelConfig, O as AlfeResolvedAccount, T as createAlfeChannelPlugin, b as plugin, j as SessionSummary, k as ChatMessage } from "./plugin.cjs";
+import { A as AlfeResolvedAccount, D as createAlfeChannelPlugin, M as SessionData, N as SessionSummary, O as AlfeChannelConfig, b as plugin, j as ChatMessage, k as AlfePluginConfig } from "./plugin.cjs";
 export { type AlfeChannelConfig, type AlfePluginConfig, type AlfeResolvedAccount, type ChatMessage, type SessionData, type SessionSummary, createAlfeChannelPlugin, plugin as default };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as SessionData, D as AlfePluginConfig, E as AlfeChannelConfig, O as AlfeResolvedAccount, T as createAlfeChannelPlugin, b as plugin, j as SessionSummary, k as ChatMessage } from "./plugin.js";
+import { A as AlfeResolvedAccount, D as createAlfeChannelPlugin, M as SessionData, N as SessionSummary, O as AlfeChannelConfig, b as plugin, j as ChatMessage, k as AlfePluginConfig } from "./plugin.js";
 export { type AlfeChannelConfig, type AlfePluginConfig, type AlfeResolvedAccount, type ChatMessage, type SessionData, type SessionSummary, createAlfeChannelPlugin, plugin as default };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { S as createAlfeChannelPlugin, _ as plugin } from "./plugin2.js";
+import { _ as plugin, w as createAlfeChannelPlugin } from "./plugin2.js";
 export { createAlfeChannelPlugin, plugin as default };

package/dist/plugin.cjs

@@ -22,5 +22,7 @@ exports.default = require_plugin.plugin;
 exports.joinAssistantText = require_plugin.joinAssistantText;
 exports.readAttachmentBodyBounded = require_plugin.readAttachmentBodyBounded;
 exports.resolveAbortTargetKeys = require_plugin.resolveAbortTargetKeys;
+exports.resolveRequestedRunId = require_plugin.resolveRequestedRunId;
 exports.rewriteAssistantText = require_plugin.rewriteAssistantText;
 exports.stripLeakedToolSummary = require_plugin.stripLeakedToolSummary;
+exports.withReplyRunId = require_plugin.withReplyRunId;

package/dist/plugin.d.cts

@@ -214,6 +214,7 @@ interface AlfeOutboundSessionSummary {
 interface AlfeOutboundSession {
   sessionId: string;
   userId?: string;
+  tenantId?: string;
 }
 interface AlfeChannelOutboundDeps {
   getChatClient: () => AlfeOutboundChatClient | null;
@@ -471,6 +472,10 @@ interface RunEventGate {
  * Isolation is preserved: turns to a daemon are serialised
  * (`enqueueAgentTurn`) and the listener is torn down before the next turn
  * dispatches, so the first relevant event locks onto THIS turn's main run.
+ * For callers that supply an idempotency key the gate is instead PRE-ARMED
+ * with that service run id (see `resolveRequestedRunId` / `withReplyRunId`,
+ * which seed the same value as the runtime's own run id), so no lock-on step
+ * is needed and only the service-owned run is ever admitted.
  * Concurrent heartbeat/cron runs and subagent / side-question runs carry a
  * different `runId` and are excluded — exactly the leakage the gate exists to
  * prevent. When a run IS control-UI-visible and both keys are present, a
@@ -480,6 +485,13 @@ interface RunEventGate {
  * pinned against real 2026.6.10 event shapes.
  */
 declare function admitAgentEvent(gate: RunEventGate, evt: Pick<AgentEventPayload, 'runId' | 'stream' | 'sessionKey'>): boolean;
+/**
+ * Seed OpenClaw's runtime/event id with the chat service request that owns the
+ * turn. Older callers omit the idempotency key and retain a runtime-owned id.
+ */
+declare function resolveRequestedRunId(idempotencyKey: unknown): string | null;
+/** Preserve OpenClaw-provided reply options while seeding this exact run id. */
+declare function withReplyRunId(params: Record<string, unknown>, runId: string): Record<string, unknown>;
 interface PluginServiceContext {
   config: Record<string, unknown>;
   workspaceDir?: string;
@@ -667,6 +679,7 @@ declare function buildAttachmentLocalFilename(att: Pick<AttachmentRef, 'id' | 'f
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
+  onStarted?: () => void;
 }): Promise<void>;
 /**
  * Test-only: reset the agent-turn backlog between unit tests. Not used at
@@ -681,6 +694,7 @@ declare const __agentTurnQueueForTest: {
 interface ActiveRunRef {
   requestSessionKey: string;
   routeSessionKey: string | null;
+  runId?: string;
 }
 /** Test-only: set/clear the active-run ref for handleChatAbort unit tests. */
 declare function __setActiveRunForTest(ref: ActiveRunRef | null): void;
@@ -692,7 +706,7 @@ declare function __setActiveRunForTest(ref: ActiveRunRef | null): void;
  * sessionKey that does NOT match the running turn yields no candidates — we
  * never abort another session's run on a shared daemon.
  */
-declare function resolveAbortTargetKeys(active: ActiveRunRef | null, abortSessionKey: string | undefined): string[];
+declare function resolveAbortTargetKeys(active: ActiveRunRef | null, abortSessionKey: string | undefined, abortRunId?: string): string[];
 /**
  * Speech-style reply guidance injected into the agent's SYSTEM PROMPT for a
  * live voice-call turn (`origin:'voice'`). The user is speaking on a call and
@@ -755,4 +769,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { SessionData as A, rewriteAssistantText as C, AlfePluginConfig as D, AlfeChannelConfig as E, AlfeResolvedAccount as O, resolveAbortTargetKeys as S, createAlfeChannelPlugin as T, computeOpenClawSdkAnchors as _, MAX_INBOUND_ATTACHMENT_SIZE as a, plugin as b, __agentTurnQueueForTest as c, admitAgentEvent as d, buildA2ACompletePayload as f, buildTurnEnvelopeContext as g, buildToolActivity as h, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as i, SessionSummary as j, ChatMessage as k, __resetAgentTurnQueueForTest as l, buildOriginEnvelopeContext as m, ActiveRunRef as n, RunEventGate as o, buildAttachmentLocalFilename as p, AnchorEnv as r, VOICE_REPLY_SYSTEM_PROMPT as s, A2A_REPLY_SYSTEM_PROMPT as t, __setActiveRunForTest as u, decideChatServiceStart as v, stripLeakedToolSummary as w, readAttachmentBodyBounded as x, joinAssistantText as y };
+export { AlfeResolvedAccount as A, resolveRequestedRunId as C, createAlfeChannelPlugin as D, withReplyRunId as E, SessionData as M, SessionSummary as N, AlfeChannelConfig as O, resolveAbortTargetKeys as S, stripLeakedToolSummary as T, computeOpenClawSdkAnchors as _, MAX_INBOUND_ATTACHMENT_SIZE as a, plugin as b, __agentTurnQueueForTest as c, admitAgentEvent as d, buildA2ACompletePayload as f, buildTurnEnvelopeContext as g, buildToolActivity as h, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as i, ChatMessage as j, AlfePluginConfig as k, __resetAgentTurnQueueForTest as l, buildOriginEnvelopeContext as m, ActiveRunRef as n, RunEventGate as o, buildAttachmentLocalFilename as p, AnchorEnv as r, VOICE_REPLY_SYSTEM_PROMPT as s, A2A_REPLY_SYSTEM_PROMPT as t, __setActiveRunForTest as u, decideChatServiceStart as v, rewriteAssistantText as w, readAttachmentBodyBounded as x, joinAssistantText as y };

package/dist/plugin.d.ts

@@ -214,6 +214,7 @@ interface AlfeOutboundSessionSummary {
 interface AlfeOutboundSession {
   sessionId: string;
   userId?: string;
+  tenantId?: string;
 }
 interface AlfeChannelOutboundDeps {
   getChatClient: () => AlfeOutboundChatClient | null;
@@ -471,6 +472,10 @@ interface RunEventGate {
  * Isolation is preserved: turns to a daemon are serialised
  * (`enqueueAgentTurn`) and the listener is torn down before the next turn
  * dispatches, so the first relevant event locks onto THIS turn's main run.
+ * For callers that supply an idempotency key the gate is instead PRE-ARMED
+ * with that service run id (see `resolveRequestedRunId` / `withReplyRunId`,
+ * which seed the same value as the runtime's own run id), so no lock-on step
+ * is needed and only the service-owned run is ever admitted.
  * Concurrent heartbeat/cron runs and subagent / side-question runs carry a
  * different `runId` and are excluded — exactly the leakage the gate exists to
  * prevent. When a run IS control-UI-visible and both keys are present, a
@@ -480,6 +485,13 @@ interface RunEventGate {
  * pinned against real 2026.6.10 event shapes.
  */
 declare function admitAgentEvent(gate: RunEventGate, evt: Pick<AgentEventPayload, 'runId' | 'stream' | 'sessionKey'>): boolean;
+/**
+ * Seed OpenClaw's runtime/event id with the chat service request that owns the
+ * turn. Older callers omit the idempotency key and retain a runtime-owned id.
+ */
+declare function resolveRequestedRunId(idempotencyKey: unknown): string | null;
+/** Preserve OpenClaw-provided reply options while seeding this exact run id. */
+declare function withReplyRunId(params: Record<string, unknown>, runId: string): Record<string, unknown>;
 interface PluginServiceContext {
   config: Record<string, unknown>;
   workspaceDir?: string;
@@ -667,6 +679,7 @@ declare function buildAttachmentLocalFilename(att: Pick<AttachmentRef, 'id' | 'f
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
+  onStarted?: () => void;
 }): Promise<void>;
 /**
  * Test-only: reset the agent-turn backlog between unit tests. Not used at
@@ -681,6 +694,7 @@ declare const __agentTurnQueueForTest: {
 interface ActiveRunRef {
   requestSessionKey: string;
   routeSessionKey: string | null;
+  runId?: string;
 }
 /** Test-only: set/clear the active-run ref for handleChatAbort unit tests. */
 declare function __setActiveRunForTest(ref: ActiveRunRef | null): void;
@@ -692,7 +706,7 @@ declare function __setActiveRunForTest(ref: ActiveRunRef | null): void;
  * sessionKey that does NOT match the running turn yields no candidates — we
  * never abort another session's run on a shared daemon.
  */
-declare function resolveAbortTargetKeys(active: ActiveRunRef | null, abortSessionKey: string | undefined): string[];
+declare function resolveAbortTargetKeys(active: ActiveRunRef | null, abortSessionKey: string | undefined, abortRunId?: string): string[];
 /**
  * Speech-style reply guidance injected into the agent's SYSTEM PROMPT for a
  * live voice-call turn (`origin:'voice'`). The user is speaking on a call and
@@ -755,4 +769,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { SessionData as A, rewriteAssistantText as C, AlfePluginConfig as D, AlfeChannelConfig as E, AlfeResolvedAccount as O, resolveAbortTargetKeys as S, createAlfeChannelPlugin as T, computeOpenClawSdkAnchors as _, MAX_INBOUND_ATTACHMENT_SIZE as a, plugin as b, __agentTurnQueueForTest as c, admitAgentEvent as d, buildA2ACompletePayload as f, buildTurnEnvelopeContext as g, buildToolActivity as h, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as i, SessionSummary as j, ChatMessage as k, __resetAgentTurnQueueForTest as l, buildOriginEnvelopeContext as m, ActiveRunRef as n, RunEventGate as o, buildAttachmentLocalFilename as p, AnchorEnv as r, VOICE_REPLY_SYSTEM_PROMPT as s, A2A_REPLY_SYSTEM_PROMPT as t, __setActiveRunForTest as u, decideChatServiceStart as v, stripLeakedToolSummary as w, readAttachmentBodyBounded as x, joinAssistantText as y };
+export { AlfeResolvedAccount as A, resolveRequestedRunId as C, createAlfeChannelPlugin as D, withReplyRunId as E, SessionData as M, SessionSummary as N, AlfeChannelConfig as O, resolveAbortTargetKeys as S, stripLeakedToolSummary as T, computeOpenClawSdkAnchors as _, MAX_INBOUND_ATTACHMENT_SIZE as a, plugin as b, __agentTurnQueueForTest as c, admitAgentEvent as d, buildA2ACompletePayload as f, buildTurnEnvelopeContext as g, buildToolActivity as h, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as i, ChatMessage as j, AlfePluginConfig as k, __resetAgentTurnQueueForTest as l, buildOriginEnvelopeContext as m, ActiveRunRef as n, RunEventGate as o, buildAttachmentLocalFilename as p, AnchorEnv as r, VOICE_REPLY_SYSTEM_PROMPT as s, A2A_REPLY_SYSTEM_PROMPT as t, __setActiveRunForTest as u, decideChatServiceStart as v, rewriteAssistantText as w, readAttachmentBodyBounded as x, joinAssistantText as y };

package/dist/plugin.js

@@ -1,2 +1,2 @@
-import { _ as plugin, a as __agentTurnQueueForTest, b as rewriteAssistantText, c as admitAgentEvent, d as buildOriginEnvelopeContext, f as buildToolActivity, g as joinAssistantText, h as decideChatServiceStart, i as VOICE_REPLY_SYSTEM_PROMPT, l as buildA2ACompletePayload, m as computeOpenClawSdkAnchors, n as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, o as __resetAgentTurnQueueForTest, p as buildTurnEnvelopeContext, r as MAX_INBOUND_ATTACHMENT_SIZE, s as __setActiveRunForTest, t as A2A_REPLY_SYSTEM_PROMPT, u as buildAttachmentLocalFilename, v as readAttachmentBodyBounded, x as stripLeakedToolSummary, y as resolveAbortTargetKeys } from "./plugin2.js";
-export { A2A_REPLY_SYSTEM_PROMPT, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { C as withReplyRunId, S as stripLeakedToolSummary, _ as plugin, a as __agentTurnQueueForTest, b as resolveRequestedRunId, c as admitAgentEvent, d as buildOriginEnvelopeContext, f as buildToolActivity, g as joinAssistantText, h as decideChatServiceStart, i as VOICE_REPLY_SYSTEM_PROMPT, l as buildA2ACompletePayload, m as computeOpenClawSdkAnchors, n as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, o as __resetAgentTurnQueueForTest, p as buildTurnEnvelopeContext, r as MAX_INBOUND_ATTACHMENT_SIZE, s as __setActiveRunForTest, t as A2A_REPLY_SYSTEM_PROMPT, u as buildAttachmentLocalFilename, v as readAttachmentBodyBounded, x as rewriteAssistantText, y as resolveAbortTargetKeys } from "./plugin2.js";
+export { A2A_REPLY_SYSTEM_PROMPT, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, resolveRequestedRunId, rewriteAssistantText, stripLeakedToolSummary, withReplyRunId };

package/dist/plugin2.cjs

@@ -8,8 +8,8 @@ let node_url = require("node:url");
 let node_os = require("node:os");
 let _alfe_ai_chat = require("@alfe.ai/chat");
 let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
-let _alfe_ai_openclaw_plugin_kit = require("@alfe.ai/openclaw-plugin-kit");
 let _alfe_ai_config = require("@alfe.ai/config");
+let _alfe_ai_openclaw_plugin_kit = require("@alfe.ai/openclaw-plugin-kit");
 //#region src/outbound-media.ts
 /**
 * Outbound media upload — agent → user.
@@ -622,6 +622,21 @@ async function sendViaChat(deps, ctx, mediaUrl, components) {
 	};
 }
 /**
+* Send to a server-authorized native identity conversation. The cloud
+* Conversation/Participant rows already exist when this is called; bind the
+* local session to the exact same key before reusing the normal delivery path.
+*/
+async function sendIdentityMessageViaChat(deps, target, text) {
+	const existing = await deps.getSession(target.conversationId);
+	if (existing) {
+		if (existing.userId !== target.userId || existing.tenantId !== target.tenantId) throw new Error("identity_direct_session_mismatch");
+	} else await deps.createSession(target.conversationId, "", "alfe", target.tenantId, target.userId);
+	return sendViaChat(deps, {
+		to: `conv:${target.conversationId}`,
+		text
+	}, void 0);
+}
+/**
 * Present interactive components (link buttons, quick replies) into a
 * conversation — the outbound path for the `chat_present_components` tool.
 * `to` is a `conv:{id}` or `user:{id}` target (same vocabulary as the channel's
@@ -1654,8 +1669,92 @@ async function collectTranscriptActivity(conversationId, routes) {
 	return merged.length > MAX_ENTRIES ? merged.slice(merged.length - MAX_ENTRIES) : merged;
 }
 //#endregion
+//#region src/session-wire-budget.ts
+/**
+* Keep daemon -> chat-relay history responses below the relay's WebSocket
+* frame limit. `sessions.get` is assembled on the daemon, so relay-side
+* activity thinning happens too late to protect this inbound hop.
+*/
+/**
+* The production relay historically accepted 1 MiB daemon frames. Leave
+* enough headroom for WebSocket/RPC envelope drift and non-history metadata.
+*/
+const SESSION_GET_FRAME_BUDGET_BYTES = 900 * 1024;
+const SESSION_GET_FRAME_BUDGET_ERROR = "sessions.get response metadata exceeds frame budget";
+function responseFrameBytes(requestId, payload) {
+	return Buffer.byteLength(JSON.stringify({
+		id: requestId,
+		ok: true,
+		payload
+	}), "utf8");
+}
+function largestFittingSuffix(items, fits) {
+	let low = 0;
+	let high = items.length;
+	while (low < high) {
+		const keep = Math.ceil((low + high) / 2);
+		if (fits(items.slice(items.length - keep))) low = keep;
+		else high = keep - 1;
+	}
+	return items.slice(items.length - low);
+}
+/**
+* Preserve the newest useful history without ever letting one oversized
+* `sessions.get` response tear down the daemon's shared relay connection.
+* Activity is shed before messages; if messages alone exceed the budget,
+* their oldest entries are shed as well. Persistence is untouched.
+*/
+function boundSessionGetResponse(requestId, payload, maxFrameBytes = SESSION_GET_FRAME_BUDGET_BYTES) {
+	const originalFrameBytes = responseFrameBytes(requestId, payload);
+	if (originalFrameBytes <= maxFrameBytes) return {
+		payload,
+		frameBytes: originalFrameBytes,
+		truncatedMessages: 0,
+		truncatedActivity: 0
+	};
+	const originalActivity = payload.activity;
+	let activity = originalActivity;
+	if (originalActivity) activity = largestFittingSuffix(originalActivity, (suffix) => responseFrameBytes(requestId, {
+		...payload,
+		activity: suffix
+	}) <= maxFrameBytes);
+	let candidate = {
+		...payload,
+		...originalActivity ? { activity } : {}
+	};
+	let frameBytes = responseFrameBytes(requestId, candidate);
+	if (frameBytes <= maxFrameBytes) return {
+		payload: candidate,
+		frameBytes,
+		truncatedMessages: 0,
+		truncatedActivity: (originalActivity?.length ?? 0) - (activity?.length ?? 0)
+	};
+	candidate = {
+		...payload,
+		messages: payload.messages,
+		...originalActivity ? { activity: [] } : {}
+	};
+	const messages = largestFittingSuffix(payload.messages, (suffix) => responseFrameBytes(requestId, {
+		...candidate,
+		messages: suffix
+	}) <= maxFrameBytes);
+	candidate = {
+		...candidate,
+		messages
+	};
+	frameBytes = responseFrameBytes(requestId, candidate);
+	if (frameBytes > maxFrameBytes) throw new Error(SESSION_GET_FRAME_BUDGET_ERROR);
+	return {
+		payload: candidate,
+		frameBytes,
+		truncatedMessages: payload.messages.length - messages.length,
+		truncatedActivity: originalActivity?.length ?? 0
+	};
+}
+//#endregion
 //#region src/a2a-tools.ts
 const MAX_AGENT_ID_CHARS = 256;
+const MAX_IDENTITY_ID_CHARS$1 = 256;
 const MAX_A2A_MESSAGE_CHARS = 32e3;
 const MAX_THREAD_ID_CHARS = 128;
 const MAX_A2A_DEPTH = 20;
@@ -1692,7 +1791,7 @@ function disarmA2AEndSignal() {
 function isA2AEndSignalled() {
 	return conversationEndRequested;
 }
-function buildA2ATools(getChatClient, log, present) {
+function buildA2ATools(getChatClient, log, present, messageIdentity) {
 	const requireClient = () => {
 		const client = getChatClient();
 		if (!client) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("chat service not connected yet — try again in a moment");
@@ -1784,6 +1883,39 @@ function buildA2ATools(getChatClient, log, present) {
 			}
 		})
 	];
+	if (messageIdentity) tools.push((0, _alfe_ai_openclaw_plugin_kit.defineTool)({
+		name: "message_identity",
+		description: "Send a new direct message to a person by universal identity ID. Use list_identities or lookup_identity first. The chat service verifies that the identity maps to exactly one current member of this tenant, creates or reuses the durable direct conversation, and then sends the message.",
+		parameters: {
+			type: "object",
+			properties: {
+				identity_id: {
+					type: "string",
+					minLength: 5,
+					maxLength: MAX_IDENTITY_ID_CHARS$1,
+					pattern: "^idn_[A-Za-z0-9_-]+$",
+					description: "Target universal identity ID (idn_...)"
+				},
+				message: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_A2A_MESSAGE_CHARS,
+					description: "Message to send to the person"
+				}
+			},
+			required: ["identity_id", "message"]
+		},
+		handler: async (params) => {
+			const identityId = params.identity_id;
+			const message = params.message;
+			if (typeof identityId !== "string" || identityId.length > MAX_IDENTITY_ID_CHARS$1 || !/^idn_[A-Za-z0-9_-]+$/.test(identityId) || typeof message !== "string" || message.length < 1 || message.length > MAX_A2A_MESSAGE_CHARS) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("Invalid message_identity parameters");
+			log.info(`message_identity tool: sending to ${identityId}`);
+			return messageIdentity({
+				identityId,
+				message
+			});
+		}
+	}));
 	if (present) tools.push((0, _alfe_ai_openclaw_plugin_kit.defineTool)({
 		name: "chat_present_components",
 		description: "Attach interactive UI components to a chat message so the user can act with a tap instead of typing. PREFER components whenever you offer the user a discrete set of choices — a quick_reply or select reads far better than \"reply 1, 2, or 3\". Use:\n  • quick_reply — one-tap canned replies for a short set of options.\n  • select — a single choice from a longer list (dropdown).\n  • multi_select — let the user pick MANY options, then submit.\n  • confirm — an approval / yes-no decision (primary + secondary button).\n  • link_button — an actionable LINK (open a dashboard, a browser-takeover deep link). URL must be https on an Alfe-owned host.\n  • copy_button — let the user copy a value (token, id, snippet) to their clipboard.\nChoosing/submitting an interactive component sends the chosen value back AS THE USER'S NEXT MESSAGE, so the conversation continues normally — you will see it as ordinary user input. Don't button-spam: components are for real interactions, not decoration, and each message allows at most 10. Components degrade to plain text on clients that don't render them, so keep the essentials in `text` too.\nExamples:\n  Approval: { to:\"conv:abc\", text:\"Deploy to production?\", components:[ { type:\"confirm\", id:\"c1\", confirmLabel:\"Deploy\", confirmValue:\"yes, deploy\", cancelLabel:\"Cancel\", cancelValue:\"no, hold off\" } ] }\n  Pick one: { to:\"user:u_123\", text:\"Which environment?\", components:[ { type:\"select\", id:\"s1\", placeholder:\"Choose an environment\", options:[ { label:\"Dev\", value:\"dev\" }, { label:\"Staging\", value:\"staging\" }, { label:\"Prod\", value:\"prod\" } ] } ] }\n  Link: { to:\"conv:abc\", text:\"I need you to finish the login step.\", components:[ { type:\"link_button\", id:\"b1\", label:\"Open browser session\", url:\"https://app.alfe.ai/agents/x?tab=browser\", target:\"new-tab\", style:\"primary\" } ] }",
@@ -2109,6 +2241,28 @@ function isValidIdentityId(value) {
 */
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 const pkg = require$1("../package.json");
+let cachedAgentApi = null;
+function getAgentApiClient(apiKeyOverride) {
+	let resolved;
+	try {
+		resolved = (0, _alfe_ai_config.resolveConfig)();
+	} catch {}
+	const normalizedOverride = apiKeyOverride?.trim();
+	const apiKey = normalizedOverride ?? resolved?.apiKey;
+	if (!apiKey) throw new Error("Alfe API key is not configured");
+	const apiUrl = normalizedOverride === void 0 ? resolved?.apiUrl ?? (0, _alfe_ai_config.getEndpointFromToken)(apiKey) : (0, _alfe_ai_config.getEndpointFromToken)(apiKey);
+	if (cachedAgentApi?.apiKey === apiKey && cachedAgentApi.apiUrl === apiUrl) return cachedAgentApi.client;
+	const client = new _alfe_ai_agent_api_client.AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+	cachedAgentApi = {
+		apiKey,
+		apiUrl,
+		client
+	};
+	return client;
+}
 /**
 * Decide whether an agent-event belongs to THIS turn's run and should be
 * forwarded as a delta / activity frame.
@@ -2130,6 +2284,10 @@ const pkg = require$1("../package.json");
 * Isolation is preserved: turns to a daemon are serialised
 * (`enqueueAgentTurn`) and the listener is torn down before the next turn
 * dispatches, so the first relevant event locks onto THIS turn's main run.
+* For callers that supply an idempotency key the gate is instead PRE-ARMED
+* with that service run id (see `resolveRequestedRunId` / `withReplyRunId`,
+* which seed the same value as the runtime's own run id), so no lock-on step
+* is needed and only the service-owned run is ever admitted.
 * Concurrent heartbeat/cron runs and subagent / side-question runs carry a
 * different `runId` and are excluded — exactly the leakage the gate exists to
 * prevent. When a run IS control-UI-visible and both keys are present, a
@@ -2148,6 +2306,25 @@ function admitAgentEvent(gate, evt) {
 	if (gate.sessionKey && evt.sessionKey && evt.sessionKey !== gate.sessionKey) return false;
 	return true;
 }
+/**
+* Seed OpenClaw's runtime/event id with the chat service request that owns the
+* turn. Older callers omit the idempotency key and retain a runtime-owned id.
+*/
+function resolveRequestedRunId(idempotencyKey) {
+	return typeof idempotencyKey === "string" && idempotencyKey.length > 0 && idempotencyKey.length <= 256 ? idempotencyKey : null;
+}
+/** Preserve OpenClaw-provided reply options while seeding this exact run id. */
+function withReplyRunId(params, runId) {
+	const existing = params.replyOptions;
+	const replyOptions = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+	return {
+		...params,
+		replyOptions: {
+			...replyOptions,
+			runId
+		}
+	};
+}
 function asString(v) {
 	return typeof v === "string" && v.length > 0 ? v : void 0;
 }
@@ -2713,6 +2890,7 @@ function enqueueAgentTurn(task, opts) {
 			run: task,
 			coalesceKey: opts?.coalesceKey,
 			onSuperseded: opts?.onSuperseded ?? (() => void 0),
+			onStarted: opts?.onStarted ?? (() => void 0),
 			resolve,
 			reject
 		};
@@ -2738,6 +2916,9 @@ async function drainAgentTurns() {
 			const entry = agentTurnBacklog.shift();
 			if (!entry) break;
 			try {
+				try {
+					entry.onStarted();
+				} catch {}
 				await entry.run();
 				entry.resolve();
 			} catch (err) {
@@ -2774,7 +2955,8 @@ function __setActiveRunForTest(ref) {
 * sessionKey that does NOT match the running turn yields no candidates — we
 * never abort another session's run on a shared daemon.
 */
-function resolveAbortTargetKeys(active, abortSessionKey) {
+function resolveAbortTargetKeys(active, abortSessionKey, abortRunId) {
+	if (abortRunId && (!active?.runId || active.runId !== abortRunId || abortSessionKey !== void 0 && active.requestSessionKey !== abortSessionKey)) return [];
 	const keys = [];
 	if (active && (!abortSessionKey || active.requestSessionKey === abortSessionKey)) {
 		if (active.routeSessionKey) keys.push(active.routeSessionKey);
@@ -2796,8 +2978,8 @@ function resolveAbortTargetKeys(active, abortSessionKey) {
 * persisted.
 */
 function handleChatAbort(request, log) {
-	const { sessionKey } = request.params;
-	const targetKeys = resolveAbortTargetKeys(activeRun, sessionKey);
+	const { sessionKey, runId } = request.params;
+	const targetKeys = resolveAbortTargetKeys(activeRun, sessionKey, runId);
 	let aborted = false;
 	if (abortEmbeddedAgentRun && resolveActiveRunSessionId) {
 		for (const key of targetKeys) {
@@ -2894,7 +3076,7 @@ async function handleAgentRequest(request, log) {
 		chatClient?.sendResponse(request.id, false, { message: "OpenClaw SDK not available — cannot dispatch" });
 		return;
 	}
-	const { message, sessionKey: legacySessionKey, userId, conversationId, conversationType, tenantId, clientType, origin, displayName, identityId, identityProvider, attachments: rawAttachments, a2a, chatMessageId } = request.params;
+	const { message, sessionKey: legacySessionKey, userId, conversationId, conversationType, tenantId, clientType, origin, displayName, identityId, identityProvider, idempotencyKey, attachments: rawAttachments, a2a, chatMessageId } = request.params;
 	const isA2A = !!a2a;
 	if (!message && !rawAttachments?.length) {
 		chatClient?.sendResponse(request.id, false, { message: "Missing message" });
@@ -2905,8 +3087,9 @@ async function handleAgentRequest(request, log) {
 	const sessionId = conversationId ?? legacySessionKey;
 	if (!await getSession(sessionId)) await createSession(sessionId, "", "alfe", tenantId, userId);
 	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId, void 0, userAttachmentsToStored(rawAttachments));
+	const requestedRunId = resolveRequestedRunId(idempotencyKey);
 	const runGate = {
-		runId: null,
+		runId: requestedRunId,
 		sessionKey: null
 	};
 	let lastThinkingLen = 0;
@@ -3091,11 +3274,19 @@ async function handleAgentRequest(request, log) {
 		}
 		activeRun = {
 			requestSessionKey: legacySessionKey,
-			routeSessionKey
+			routeSessionKey,
+			...requestedRunId ? { runId: requestedRunId } : {}
 		};
+		const dispatchChannel = requestedRunId ? {
+			...runtime.channel,
+			reply: {
+				...runtime.channel.reply,
+				dispatchReplyWithBufferedBlockDispatcher: (params) => runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher(withReplyRunId(params, requestedRunId))
+			}
+		} : runtime.channel;
 		const result = await dispatchInbound({
 			cfg,
-			runtime: { channel: runtime.channel },
+			runtime: { channel: dispatchChannel },
 			channel: "alfe",
 			channelLabel,
 			accountId: "default",
@@ -3242,7 +3433,7 @@ async function handleSessionsGet(request, log) {
 			});
 			return;
 		}
-		chatClient?.sendResponse(request.id, true, {
+		const response = boundSessionGetResponse(request.id, {
 			sessionId: session.sessionId,
 			agentId: session.agentId,
 			channel: session.channel,
@@ -3257,6 +3448,8 @@ async function handleSessionsGet(request, log) {
 			})),
 			activity: await resolveHistoryActivity(session)
 		});
+		if (response.truncatedMessages > 0 || response.truncatedActivity > 0) log.warn(`sessions.get history bounded for relay frame: messagesDropped=${String(response.truncatedMessages)} activityDropped=${String(response.truncatedActivity)} frameBytes=${String(response.frameBytes)}`);
+		chatClient?.sendResponse(request.id, true, response.payload);
 	} catch (err) {
 		const errMsg = err instanceof Error ? err.message : String(err);
 		log.error(`sessions.get failed: ${errMsg}`);
@@ -3270,6 +3463,7 @@ const plugin = {
 	version: pkg.version,
 	activate(api) {
 		const log = api.logger;
+		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
 		const outboundDeps = {
 			getChatClient: () => chatClient,
 			log,
@@ -3292,11 +3486,27 @@ const plugin = {
 					components: clean
 				});
 			};
-			const a2aTools = buildA2ATools(() => chatClient, log, present);
+			const messageIdentity = async (args) => {
+				if (!chatClient?.isConnected) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("chat service not connected yet — try again in a moment");
+				const direct = await getAgentApiClient(pluginConfig.apiKey).ensureDirectConversation(args.identityId);
+				const sent = await sendIdentityMessageViaChat(outboundDeps, {
+					conversationId: direct.conversationId,
+					tenantId: direct.tenantId,
+					userId: direct.userId
+				}, args.message);
+				return {
+					status: "sent",
+					identityId: direct.identityId,
+					displayName: direct.displayName,
+					conversationId: sent.conversationId,
+					messageId: sent.messageId,
+					newConversation: direct.created
+				};
+			};
+			const a2aTools = buildA2ATools(() => chatClient, log, present, messageIdentity);
 			for (const tool of a2aTools) api.registerTool(tool);
 			log.info(`Registered ${String(a2aTools.length)} agent tools`);
 		}
-		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
 		const startChatService = async () => {
 			const action = decideChatServiceStart({
 				connectInFlight: connectingPromise !== null,
@@ -3337,16 +3547,28 @@ const plugin = {
 									if (request.method === "agent") {
 										const params = request.params;
 										const coalesceKey = params.coalesce === "replace" && typeof params.sessionKey === "string" ? params.sessionKey : void 0;
-										await enqueueAgentTurn(() => handleAgentRequest(request, log), coalesceKey ? {
-											coalesceKey,
-											onSuperseded: () => {
-												log.info(`Agent turn superseded before start (coalesce=replace): ${coalesceKey}`);
+										chatClient?.sendResponse(request.id, true, {
+											status: "accepted",
+											phase: "queued"
+										});
+										await enqueueAgentTurn(() => handleAgentRequest(request, log), {
+											onStarted: () => {
 												chatClient?.sendResponse(request.id, true, {
-													superseded: true,
-													sessionKey: coalesceKey
+													status: "accepted",
+													phase: "started"
 												});
-											}
-										} : void 0);
+											},
+											...coalesceKey ? {
+												coalesceKey,
+												onSuperseded: () => {
+													log.info(`Agent turn superseded before start (coalesce=replace): ${coalesceKey}`);
+													chatClient?.sendResponse(request.id, true, {
+														superseded: true,
+														sessionKey: coalesceKey
+													});
+												}
+											} : {}
+										});
 									} else if (request.method === "chat.abort") handleChatAbort(request, log);
 									else if (request.method === "sessions.list") await handleSessionsList(request, log);
 									else if (request.method === "sessions.get") await handleSessionsGet(request, log);
@@ -3481,6 +3703,7 @@ const plugin = {
 		}
 		pluginRuntime = null;
 		dispatchInbound = null;
+		cachedAgentApi = null;
 		(0, _alfe_ai_openclaw_plugin_kit.resetActivation)(CHAT_ACTIVATION_KEY);
 		log.info("Chat plugin deactivated");
 	}
@@ -3606,6 +3829,12 @@ Object.defineProperty(exports, "resolveAbortTargetKeys", {
 		return resolveAbortTargetKeys;
 	}
 });
+Object.defineProperty(exports, "resolveRequestedRunId", {
+	enumerable: true,
+	get: function() {
+		return resolveRequestedRunId;
+	}
+});
 Object.defineProperty(exports, "rewriteAssistantText", {
 	enumerable: true,
 	get: function() {
@@ -3618,3 +3847,9 @@ Object.defineProperty(exports, "stripLeakedToolSummary", {
 		return stripLeakedToolSummary;
 	}
 });
+Object.defineProperty(exports, "withReplyRunId", {
+	enumerable: true,
+	get: function() {
+		return withReplyRunId;
+	}
+});

package/dist/plugin2.d.cts

@@ -1,2 +1,2 @@
-import { C as rewriteAssistantText, S as resolveAbortTargetKeys, _ as computeOpenClawSdkAnchors, a as MAX_INBOUND_ATTACHMENT_SIZE, b as plugin, c as __agentTurnQueueForTest, d as admitAgentEvent, f as buildA2ACompletePayload, g as buildTurnEnvelopeContext, h as buildToolActivity, i as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, l as __resetAgentTurnQueueForTest, m as buildOriginEnvelopeContext, n as ActiveRunRef, o as RunEventGate, p as buildAttachmentLocalFilename, r as AnchorEnv, s as VOICE_REPLY_SYSTEM_PROMPT, t as A2A_REPLY_SYSTEM_PROMPT, u as __setActiveRunForTest, v as decideChatServiceStart, w as stripLeakedToolSummary, x as readAttachmentBodyBounded, y as joinAssistantText } from "./plugin.cjs";
-export { A2A_REPLY_SYSTEM_PROMPT, ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { C as resolveRequestedRunId, E as withReplyRunId, S as resolveAbortTargetKeys, T as stripLeakedToolSummary, _ as computeOpenClawSdkAnchors, a as MAX_INBOUND_ATTACHMENT_SIZE, b as plugin, c as __agentTurnQueueForTest, d as admitAgentEvent, f as buildA2ACompletePayload, g as buildTurnEnvelopeContext, h as buildToolActivity, i as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, l as __resetAgentTurnQueueForTest, m as buildOriginEnvelopeContext, n as ActiveRunRef, o as RunEventGate, p as buildAttachmentLocalFilename, r as AnchorEnv, s as VOICE_REPLY_SYSTEM_PROMPT, t as A2A_REPLY_SYSTEM_PROMPT, u as __setActiveRunForTest, v as decideChatServiceStart, w as rewriteAssistantText, x as readAttachmentBodyBounded, y as joinAssistantText } from "./plugin.cjs";
+export { A2A_REPLY_SYSTEM_PROMPT, ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, resolveRequestedRunId, rewriteAssistantText, stripLeakedToolSummary, withReplyRunId };

package/dist/plugin2.d.ts

@@ -1,2 +1,2 @@
-import { C as rewriteAssistantText, S as resolveAbortTargetKeys, _ as computeOpenClawSdkAnchors, a as MAX_INBOUND_ATTACHMENT_SIZE, b as plugin, c as __agentTurnQueueForTest, d as admitAgentEvent, f as buildA2ACompletePayload, g as buildTurnEnvelopeContext, h as buildToolActivity, i as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, l as __resetAgentTurnQueueForTest, m as buildOriginEnvelopeContext, n as ActiveRunRef, o as RunEventGate, p as buildAttachmentLocalFilename, r as AnchorEnv, s as VOICE_REPLY_SYSTEM_PROMPT, t as A2A_REPLY_SYSTEM_PROMPT, u as __setActiveRunForTest, v as decideChatServiceStart, w as stripLeakedToolSummary, x as readAttachmentBodyBounded, y as joinAssistantText } from "./plugin.js";
-export { A2A_REPLY_SYSTEM_PROMPT, ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+import { C as resolveRequestedRunId, E as withReplyRunId, S as resolveAbortTargetKeys, T as stripLeakedToolSummary, _ as computeOpenClawSdkAnchors, a as MAX_INBOUND_ATTACHMENT_SIZE, b as plugin, c as __agentTurnQueueForTest, d as admitAgentEvent, f as buildA2ACompletePayload, g as buildTurnEnvelopeContext, h as buildToolActivity, i as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, l as __resetAgentTurnQueueForTest, m as buildOriginEnvelopeContext, n as ActiveRunRef, o as RunEventGate, p as buildAttachmentLocalFilename, r as AnchorEnv, s as VOICE_REPLY_SYSTEM_PROMPT, t as A2A_REPLY_SYSTEM_PROMPT, u as __setActiveRunForTest, v as decideChatServiceStart, w as rewriteAssistantText, x as readAttachmentBodyBounded, y as joinAssistantText } from "./plugin.js";
+export { A2A_REPLY_SYSTEM_PROMPT, ActiveRunRef, AnchorEnv, CROSS_AGENT_TOOLS_SYSTEM_PROMPT, MAX_INBOUND_ATTACHMENT_SIZE, RunEventGate, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildAttachmentLocalFilename, buildOriginEnvelopeContext, buildToolActivity, buildTurnEnvelopeContext, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, readAttachmentBodyBounded, resolveAbortTargetKeys, resolveRequestedRunId, rewriteAssistantText, stripLeakedToolSummary, withReplyRunId };

package/dist/plugin2.js

@@ -8,8 +8,8 @@ import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { ChatServiceClient, resolveAlfeChat } from "@alfe.ai/chat";
 import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
+import { getEndpointFromToken, resolveConfig } from "@alfe.ai/config";
 import { defineTool, getActivationKey, publicToolError, resetActivation } from "@alfe.ai/openclaw-plugin-kit";
-import { resolveConfig } from "@alfe.ai/config";
 //#region src/outbound-media.ts
 /**
 * Outbound media upload — agent → user.
@@ -622,6 +622,21 @@ async function sendViaChat(deps, ctx, mediaUrl, components) {
 	};
 }
 /**
+* Send to a server-authorized native identity conversation. The cloud
+* Conversation/Participant rows already exist when this is called; bind the
+* local session to the exact same key before reusing the normal delivery path.
+*/
+async function sendIdentityMessageViaChat(deps, target, text) {
+	const existing = await deps.getSession(target.conversationId);
+	if (existing) {
+		if (existing.userId !== target.userId || existing.tenantId !== target.tenantId) throw new Error("identity_direct_session_mismatch");
+	} else await deps.createSession(target.conversationId, "", "alfe", target.tenantId, target.userId);
+	return sendViaChat(deps, {
+		to: `conv:${target.conversationId}`,
+		text
+	}, void 0);
+}
+/**
 * Present interactive components (link buttons, quick replies) into a
 * conversation — the outbound path for the `chat_present_components` tool.
 * `to` is a `conv:{id}` or `user:{id}` target (same vocabulary as the channel's
@@ -1654,8 +1669,92 @@ async function collectTranscriptActivity(conversationId, routes) {
 	return merged.length > MAX_ENTRIES ? merged.slice(merged.length - MAX_ENTRIES) : merged;
 }
 //#endregion
+//#region src/session-wire-budget.ts
+/**
+* Keep daemon -> chat-relay history responses below the relay's WebSocket
+* frame limit. `sessions.get` is assembled on the daemon, so relay-side
+* activity thinning happens too late to protect this inbound hop.
+*/
+/**
+* The production relay historically accepted 1 MiB daemon frames. Leave
+* enough headroom for WebSocket/RPC envelope drift and non-history metadata.
+*/
+const SESSION_GET_FRAME_BUDGET_BYTES = 900 * 1024;
+const SESSION_GET_FRAME_BUDGET_ERROR = "sessions.get response metadata exceeds frame budget";
+function responseFrameBytes(requestId, payload) {
+	return Buffer.byteLength(JSON.stringify({
+		id: requestId,
+		ok: true,
+		payload
+	}), "utf8");
+}
+function largestFittingSuffix(items, fits) {
+	let low = 0;
+	let high = items.length;
+	while (low < high) {
+		const keep = Math.ceil((low + high) / 2);
+		if (fits(items.slice(items.length - keep))) low = keep;
+		else high = keep - 1;
+	}
+	return items.slice(items.length - low);
+}
+/**
+* Preserve the newest useful history without ever letting one oversized
+* `sessions.get` response tear down the daemon's shared relay connection.
+* Activity is shed before messages; if messages alone exceed the budget,
+* their oldest entries are shed as well. Persistence is untouched.
+*/
+function boundSessionGetResponse(requestId, payload, maxFrameBytes = SESSION_GET_FRAME_BUDGET_BYTES) {
+	const originalFrameBytes = responseFrameBytes(requestId, payload);
+	if (originalFrameBytes <= maxFrameBytes) return {
+		payload,
+		frameBytes: originalFrameBytes,
+		truncatedMessages: 0,
+		truncatedActivity: 0
+	};
+	const originalActivity = payload.activity;
+	let activity = originalActivity;
+	if (originalActivity) activity = largestFittingSuffix(originalActivity, (suffix) => responseFrameBytes(requestId, {
+		...payload,
+		activity: suffix
+	}) <= maxFrameBytes);
+	let candidate = {
+		...payload,
+		...originalActivity ? { activity } : {}
+	};
+	let frameBytes = responseFrameBytes(requestId, candidate);
+	if (frameBytes <= maxFrameBytes) return {
+		payload: candidate,
+		frameBytes,
+		truncatedMessages: 0,
+		truncatedActivity: (originalActivity?.length ?? 0) - (activity?.length ?? 0)
+	};
+	candidate = {
+		...payload,
+		messages: payload.messages,
+		...originalActivity ? { activity: [] } : {}
+	};
+	const messages = largestFittingSuffix(payload.messages, (suffix) => responseFrameBytes(requestId, {
+		...candidate,
+		messages: suffix
+	}) <= maxFrameBytes);
+	candidate = {
+		...candidate,
+		messages
+	};
+	frameBytes = responseFrameBytes(requestId, candidate);
+	if (frameBytes > maxFrameBytes) throw new Error(SESSION_GET_FRAME_BUDGET_ERROR);
+	return {
+		payload: candidate,
+		frameBytes,
+		truncatedMessages: payload.messages.length - messages.length,
+		truncatedActivity: originalActivity?.length ?? 0
+	};
+}
+//#endregion
 //#region src/a2a-tools.ts
 const MAX_AGENT_ID_CHARS = 256;
+const MAX_IDENTITY_ID_CHARS$1 = 256;
 const MAX_A2A_MESSAGE_CHARS = 32e3;
 const MAX_THREAD_ID_CHARS = 128;
 const MAX_A2A_DEPTH = 20;
@@ -1692,7 +1791,7 @@ function disarmA2AEndSignal() {
 function isA2AEndSignalled() {
 	return conversationEndRequested;
 }
-function buildA2ATools(getChatClient, log, present) {
+function buildA2ATools(getChatClient, log, present, messageIdentity) {
 	const requireClient = () => {
 		const client = getChatClient();
 		if (!client) throw publicToolError("chat service not connected yet — try again in a moment");
@@ -1784,6 +1883,39 @@ function buildA2ATools(getChatClient, log, present) {
 			}
 		})
 	];
+	if (messageIdentity) tools.push(defineTool({
+		name: "message_identity",
+		description: "Send a new direct message to a person by universal identity ID. Use list_identities or lookup_identity first. The chat service verifies that the identity maps to exactly one current member of this tenant, creates or reuses the durable direct conversation, and then sends the message.",
+		parameters: {
+			type: "object",
+			properties: {
+				identity_id: {
+					type: "string",
+					minLength: 5,
+					maxLength: MAX_IDENTITY_ID_CHARS$1,
+					pattern: "^idn_[A-Za-z0-9_-]+$",
+					description: "Target universal identity ID (idn_...)"
+				},
+				message: {
+					type: "string",
+					minLength: 1,
+					maxLength: MAX_A2A_MESSAGE_CHARS,
+					description: "Message to send to the person"
+				}
+			},
+			required: ["identity_id", "message"]
+		},
+		handler: async (params) => {
+			const identityId = params.identity_id;
+			const message = params.message;
+			if (typeof identityId !== "string" || identityId.length > MAX_IDENTITY_ID_CHARS$1 || !/^idn_[A-Za-z0-9_-]+$/.test(identityId) || typeof message !== "string" || message.length < 1 || message.length > MAX_A2A_MESSAGE_CHARS) throw publicToolError("Invalid message_identity parameters");
+			log.info(`message_identity tool: sending to ${identityId}`);
+			return messageIdentity({
+				identityId,
+				message
+			});
+		}
+	}));
 	if (present) tools.push(defineTool({
 		name: "chat_present_components",
 		description: "Attach interactive UI components to a chat message so the user can act with a tap instead of typing. PREFER components whenever you offer the user a discrete set of choices — a quick_reply or select reads far better than \"reply 1, 2, or 3\". Use:\n  • quick_reply — one-tap canned replies for a short set of options.\n  • select — a single choice from a longer list (dropdown).\n  • multi_select — let the user pick MANY options, then submit.\n  • confirm — an approval / yes-no decision (primary + secondary button).\n  • link_button — an actionable LINK (open a dashboard, a browser-takeover deep link). URL must be https on an Alfe-owned host.\n  • copy_button — let the user copy a value (token, id, snippet) to their clipboard.\nChoosing/submitting an interactive component sends the chosen value back AS THE USER'S NEXT MESSAGE, so the conversation continues normally — you will see it as ordinary user input. Don't button-spam: components are for real interactions, not decoration, and each message allows at most 10. Components degrade to plain text on clients that don't render them, so keep the essentials in `text` too.\nExamples:\n  Approval: { to:\"conv:abc\", text:\"Deploy to production?\", components:[ { type:\"confirm\", id:\"c1\", confirmLabel:\"Deploy\", confirmValue:\"yes, deploy\", cancelLabel:\"Cancel\", cancelValue:\"no, hold off\" } ] }\n  Pick one: { to:\"user:u_123\", text:\"Which environment?\", components:[ { type:\"select\", id:\"s1\", placeholder:\"Choose an environment\", options:[ { label:\"Dev\", value:\"dev\" }, { label:\"Staging\", value:\"staging\" }, { label:\"Prod\", value:\"prod\" } ] } ] }\n  Link: { to:\"conv:abc\", text:\"I need you to finish the login step.\", components:[ { type:\"link_button\", id:\"b1\", label:\"Open browser session\", url:\"https://app.alfe.ai/agents/x?tab=browser\", target:\"new-tab\", style:\"primary\" } ] }",
@@ -2109,6 +2241,28 @@ function isValidIdentityId(value) {
 */
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+let cachedAgentApi = null;
+function getAgentApiClient(apiKeyOverride) {
+	let resolved;
+	try {
+		resolved = resolveConfig();
+	} catch {}
+	const normalizedOverride = apiKeyOverride?.trim();
+	const apiKey = normalizedOverride ?? resolved?.apiKey;
+	if (!apiKey) throw new Error("Alfe API key is not configured");
+	const apiUrl = normalizedOverride === void 0 ? resolved?.apiUrl ?? getEndpointFromToken(apiKey) : getEndpointFromToken(apiKey);
+	if (cachedAgentApi?.apiKey === apiKey && cachedAgentApi.apiUrl === apiUrl) return cachedAgentApi.client;
+	const client = new AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+	cachedAgentApi = {
+		apiKey,
+		apiUrl,
+		client
+	};
+	return client;
+}
 /**
 * Decide whether an agent-event belongs to THIS turn's run and should be
 * forwarded as a delta / activity frame.
@@ -2130,6 +2284,10 @@ const pkg = require("../package.json");
 * Isolation is preserved: turns to a daemon are serialised
 * (`enqueueAgentTurn`) and the listener is torn down before the next turn
 * dispatches, so the first relevant event locks onto THIS turn's main run.
+* For callers that supply an idempotency key the gate is instead PRE-ARMED
+* with that service run id (see `resolveRequestedRunId` / `withReplyRunId`,
+* which seed the same value as the runtime's own run id), so no lock-on step
+* is needed and only the service-owned run is ever admitted.
 * Concurrent heartbeat/cron runs and subagent / side-question runs carry a
 * different `runId` and are excluded — exactly the leakage the gate exists to
 * prevent. When a run IS control-UI-visible and both keys are present, a
@@ -2148,6 +2306,25 @@ function admitAgentEvent(gate, evt) {
 	if (gate.sessionKey && evt.sessionKey && evt.sessionKey !== gate.sessionKey) return false;
 	return true;
 }
+/**
+* Seed OpenClaw's runtime/event id with the chat service request that owns the
+* turn. Older callers omit the idempotency key and retain a runtime-owned id.
+*/
+function resolveRequestedRunId(idempotencyKey) {
+	return typeof idempotencyKey === "string" && idempotencyKey.length > 0 && idempotencyKey.length <= 256 ? idempotencyKey : null;
+}
+/** Preserve OpenClaw-provided reply options while seeding this exact run id. */
+function withReplyRunId(params, runId) {
+	const existing = params.replyOptions;
+	const replyOptions = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+	return {
+		...params,
+		replyOptions: {
+			...replyOptions,
+			runId
+		}
+	};
+}
 function asString(v) {
 	return typeof v === "string" && v.length > 0 ? v : void 0;
 }
@@ -2713,6 +2890,7 @@ function enqueueAgentTurn(task, opts) {
 			run: task,
 			coalesceKey: opts?.coalesceKey,
 			onSuperseded: opts?.onSuperseded ?? (() => void 0),
+			onStarted: opts?.onStarted ?? (() => void 0),
 			resolve,
 			reject
 		};
@@ -2738,6 +2916,9 @@ async function drainAgentTurns() {
 			const entry = agentTurnBacklog.shift();
 			if (!entry) break;
 			try {
+				try {
+					entry.onStarted();
+				} catch {}
 				await entry.run();
 				entry.resolve();
 			} catch (err) {
@@ -2774,7 +2955,8 @@ function __setActiveRunForTest(ref) {
 * sessionKey that does NOT match the running turn yields no candidates — we
 * never abort another session's run on a shared daemon.
 */
-function resolveAbortTargetKeys(active, abortSessionKey) {
+function resolveAbortTargetKeys(active, abortSessionKey, abortRunId) {
+	if (abortRunId && (!active?.runId || active.runId !== abortRunId || abortSessionKey !== void 0 && active.requestSessionKey !== abortSessionKey)) return [];
 	const keys = [];
 	if (active && (!abortSessionKey || active.requestSessionKey === abortSessionKey)) {
 		if (active.routeSessionKey) keys.push(active.routeSessionKey);
@@ -2796,8 +2978,8 @@ function resolveAbortTargetKeys(active, abortSessionKey) {
 * persisted.
 */
 function handleChatAbort(request, log) {
-	const { sessionKey } = request.params;
-	const targetKeys = resolveAbortTargetKeys(activeRun, sessionKey);
+	const { sessionKey, runId } = request.params;
+	const targetKeys = resolveAbortTargetKeys(activeRun, sessionKey, runId);
 	let aborted = false;
 	if (abortEmbeddedAgentRun && resolveActiveRunSessionId) {
 		for (const key of targetKeys) {
@@ -2894,7 +3076,7 @@ async function handleAgentRequest(request, log) {
 		chatClient?.sendResponse(request.id, false, { message: "OpenClaw SDK not available — cannot dispatch" });
 		return;
 	}
-	const { message, sessionKey: legacySessionKey, userId, conversationId, conversationType, tenantId, clientType, origin, displayName, identityId, identityProvider, attachments: rawAttachments, a2a, chatMessageId } = request.params;
+	const { message, sessionKey: legacySessionKey, userId, conversationId, conversationType, tenantId, clientType, origin, displayName, identityId, identityProvider, idempotencyKey, attachments: rawAttachments, a2a, chatMessageId } = request.params;
 	const isA2A = !!a2a;
 	if (!message && !rawAttachments?.length) {
 		chatClient?.sendResponse(request.id, false, { message: "Missing message" });
@@ -2905,8 +3087,9 @@ async function handleAgentRequest(request, log) {
 	const sessionId = conversationId ?? legacySessionKey;
 	if (!await getSession(sessionId)) await createSession(sessionId, "", "alfe", tenantId, userId);
 	await addMessage(sessionId, "user", message, userId ?? senderId, displayName ?? senderId, void 0, userAttachmentsToStored(rawAttachments));
+	const requestedRunId = resolveRequestedRunId(idempotencyKey);
 	const runGate = {
-		runId: null,
+		runId: requestedRunId,
 		sessionKey: null
 	};
 	let lastThinkingLen = 0;
@@ -3091,11 +3274,19 @@ async function handleAgentRequest(request, log) {
 		}
 		activeRun = {
 			requestSessionKey: legacySessionKey,
-			routeSessionKey
+			routeSessionKey,
+			...requestedRunId ? { runId: requestedRunId } : {}
 		};
+		const dispatchChannel = requestedRunId ? {
+			...runtime.channel,
+			reply: {
+				...runtime.channel.reply,
+				dispatchReplyWithBufferedBlockDispatcher: (params) => runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher(withReplyRunId(params, requestedRunId))
+			}
+		} : runtime.channel;
 		const result = await dispatchInbound({
 			cfg,
-			runtime: { channel: runtime.channel },
+			runtime: { channel: dispatchChannel },
 			channel: "alfe",
 			channelLabel,
 			accountId: "default",
@@ -3242,7 +3433,7 @@ async function handleSessionsGet(request, log) {
 			});
 			return;
 		}
-		chatClient?.sendResponse(request.id, true, {
+		const response = boundSessionGetResponse(request.id, {
 			sessionId: session.sessionId,
 			agentId: session.agentId,
 			channel: session.channel,
@@ -3257,6 +3448,8 @@ async function handleSessionsGet(request, log) {
 			})),
 			activity: await resolveHistoryActivity(session)
 		});
+		if (response.truncatedMessages > 0 || response.truncatedActivity > 0) log.warn(`sessions.get history bounded for relay frame: messagesDropped=${String(response.truncatedMessages)} activityDropped=${String(response.truncatedActivity)} frameBytes=${String(response.frameBytes)}`);
+		chatClient?.sendResponse(request.id, true, response.payload);
 	} catch (err) {
 		const errMsg = err instanceof Error ? err.message : String(err);
 		log.error(`sessions.get failed: ${errMsg}`);
@@ -3270,6 +3463,7 @@ const plugin = {
 	version: pkg.version,
 	activate(api) {
 		const log = api.logger;
+		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
 		const outboundDeps = {
 			getChatClient: () => chatClient,
 			log,
@@ -3292,11 +3486,27 @@ const plugin = {
 					components: clean
 				});
 			};
-			const a2aTools = buildA2ATools(() => chatClient, log, present);
+			const messageIdentity = async (args) => {
+				if (!chatClient?.isConnected) throw publicToolError("chat service not connected yet — try again in a moment");
+				const direct = await getAgentApiClient(pluginConfig.apiKey).ensureDirectConversation(args.identityId);
+				const sent = await sendIdentityMessageViaChat(outboundDeps, {
+					conversationId: direct.conversationId,
+					tenantId: direct.tenantId,
+					userId: direct.userId
+				}, args.message);
+				return {
+					status: "sent",
+					identityId: direct.identityId,
+					displayName: direct.displayName,
+					conversationId: sent.conversationId,
+					messageId: sent.messageId,
+					newConversation: direct.created
+				};
+			};
+			const a2aTools = buildA2ATools(() => chatClient, log, present, messageIdentity);
 			for (const tool of a2aTools) api.registerTool(tool);
 			log.info(`Registered ${String(a2aTools.length)} agent tools`);
 		}
-		const pluginConfig = (((api.config ?? {}).plugins?.entries)?.["@alfe.ai/openclaw-chat"] ?? {}).config ?? {};
 		const startChatService = async () => {
 			const action = decideChatServiceStart({
 				connectInFlight: connectingPromise !== null,
@@ -3337,16 +3547,28 @@ const plugin = {
 									if (request.method === "agent") {
 										const params = request.params;
 										const coalesceKey = params.coalesce === "replace" && typeof params.sessionKey === "string" ? params.sessionKey : void 0;
-										await enqueueAgentTurn(() => handleAgentRequest(request, log), coalesceKey ? {
-											coalesceKey,
-											onSuperseded: () => {
-												log.info(`Agent turn superseded before start (coalesce=replace): ${coalesceKey}`);
+										chatClient?.sendResponse(request.id, true, {
+											status: "accepted",
+											phase: "queued"
+										});
+										await enqueueAgentTurn(() => handleAgentRequest(request, log), {
+											onStarted: () => {
 												chatClient?.sendResponse(request.id, true, {
-													superseded: true,
-													sessionKey: coalesceKey
+													status: "accepted",
+													phase: "started"
 												});
-											}
-										} : void 0);
+											},
+											...coalesceKey ? {
+												coalesceKey,
+												onSuperseded: () => {
+													log.info(`Agent turn superseded before start (coalesce=replace): ${coalesceKey}`);
+													chatClient?.sendResponse(request.id, true, {
+														superseded: true,
+														sessionKey: coalesceKey
+													});
+												}
+											} : {}
+										});
 									} else if (request.method === "chat.abort") handleChatAbort(request, log);
 									else if (request.method === "sessions.list") await handleSessionsList(request, log);
 									else if (request.method === "sessions.get") await handleSessionsGet(request, log);
@@ -3481,9 +3703,10 @@ const plugin = {
 		}
 		pluginRuntime = null;
 		dispatchInbound = null;
+		cachedAgentApi = null;
 		resetActivation(CHAT_ACTIVATION_KEY);
 		log.info("Chat plugin deactivated");
 	}
 };
 //#endregion
-export { createAlfeChannelPlugin as S, plugin as _, __agentTurnQueueForTest as a, rewriteAssistantText as b, admitAgentEvent as c, buildOriginEnvelopeContext as d, buildToolActivity as f, joinAssistantText as g, decideChatServiceStart as h, VOICE_REPLY_SYSTEM_PROMPT as i, buildA2ACompletePayload as l, computeOpenClawSdkAnchors as m, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as n, __resetAgentTurnQueueForTest as o, buildTurnEnvelopeContext as p, MAX_INBOUND_ATTACHMENT_SIZE as r, __setActiveRunForTest as s, A2A_REPLY_SYSTEM_PROMPT as t, buildAttachmentLocalFilename as u, readAttachmentBodyBounded as v, stripLeakedToolSummary as x, resolveAbortTargetKeys as y };
+export { withReplyRunId as C, stripLeakedToolSummary as S, plugin as _, __agentTurnQueueForTest as a, resolveRequestedRunId as b, admitAgentEvent as c, buildOriginEnvelopeContext as d, buildToolActivity as f, joinAssistantText as g, decideChatServiceStart as h, VOICE_REPLY_SYSTEM_PROMPT as i, buildA2ACompletePayload as l, computeOpenClawSdkAnchors as m, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as n, __resetAgentTurnQueueForTest as o, buildTurnEnvelopeContext as p, MAX_INBOUND_ATTACHMENT_SIZE as r, __setActiveRunForTest as s, A2A_REPLY_SYSTEM_PROMPT as t, buildAttachmentLocalFilename as u, readAttachmentBodyBounded as v, createAlfeChannelPlugin as w, rewriteAssistantText as x, resolveAbortTargetKeys as y };

package/openclaw.plugin.json

@@ -26,6 +26,6 @@
     }
   },
   "contracts": {
-    "tools": ["list_agents", "message_agent", "end_conversation", "chat_present_components"]
+    "tools": ["list_agents", "message_agent", "message_identity", "end_conversation", "chat_present_components"]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/openclaw-chat",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "OpenClaw chat plugin for Alfe — web widget and mobile app channels",
   "type": "module",
   "main": "./dist/plugin.js",
@@ -27,10 +27,10 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@alfe.ai/chat": "^0.0.18",
-    "@alfe.ai/openclaw-plugin-kit": "0.2.0",
-    "@alfe.ai/agent-api-client": "^0.17.0",
-    "@alfe.ai/config": "^0.4.1"
+    "@alfe.ai/agent-api-client": "^0.17.1",
+    "@alfe.ai/chat": "^0.0.19",
+    "@alfe.ai/config": "^0.4.1",
+    "@alfe.ai/openclaw-plugin-kit": "0.2.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.0"