@alfe.ai/openclaw-chat 0.9.9 → 0.9.10

package/README.md

@@ -4,19 +4,27 @@ OpenClaw chat plugin for Alfe — web widget and mobile app channels
 
 ## What It Does
 
-OpenClaw plugin that registers the `alfe-chat` channel with the OpenClaw agent runtime. Follows the standard OpenClaw plugin pattern:
+OpenClaw plugin that registers the `alfe` channel with the OpenClaw agent runtime. It:
 
-- Exports a plugin object with `id`, `name`, `activate`, `deactivate`
-- Connects to the Alfe daemon IPC for capability registration
-- Gracefully degrades if the daemon is unavailable
+- connects to Alfe's chat relay over an authenticated WebSocket;
+- dispatches web, mobile, voice, and agent-to-agent turns through OpenClaw;
+- streams tool/thinking activity and persists bounded local history;
+- uploads agent-produced media through the attachment presign flow; and
+- exposes `list_agents`, `message_agent`, `end_conversation`, and
+  `chat_present_components` to the model.
 
 ## Key Files
 
 ```
 src/
-├── plugin.ts           # Plugin entry point (activate/deactivate lifecycle)
-├── index.ts            # Public re-exports
-└── types.ts            # Plugin-specific type definitions
+├── plugin.ts              # Activation, relay RPC, dispatch, inbound attachments
+├── alfe-channel.ts         # Channel config and outbound delivery
+├── a2a-tools.ts            # Cross-agent and interactive-component tools
+├── session-store.ts        # Atomic local conversation persistence
+├── transcript-activity.ts  # Bounded OpenClaw transcript replay
+├── outbound-media.ts       # Bounded local-media upload
+├── index.ts                # Public re-exports
+└── types.ts                # Plugin-specific type definitions
 ```
 
 ## Development
@@ -24,6 +32,8 @@ src/
 ```bash
 pnpm install
 pnpm --filter @alfe.ai/openclaw-chat build
+pnpm --filter @alfe.ai/openclaw-chat typecheck
+pnpm --filter @alfe.ai/openclaw-chat lint
 ```
 
 ## Testing
@@ -32,10 +42,9 @@ pnpm --filter @alfe.ai/openclaw-chat build
 pnpm --filter @alfe.ai/openclaw-chat test
 ```
 
-## Dependencies
-
-- **@alfe.ai/openclaw** — OpenClaw runtime plugin API
-- **openclaw** — OpenClaw runtime plugin API
+`openclaw` is an optional peer dependency supplied by the host runtime. Alfe
+API calls use `@alfe.ai/agent-api-client`; runtime configuration comes from
+`@alfe.ai/config`; the relay transport is `@alfe.ai/chat`.
 
 ## Links
 

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { C as AlfeResolvedAccount, E as SessionSummary, S as AlfePluginConfig, T as SessionData, b as createAlfeChannelPlugin, g as plugin, w as ChatMessage, x as AlfeChannelConfig } from "./plugin.cjs";
+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";
 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 { C as AlfeResolvedAccount, E as SessionSummary, S as AlfePluginConfig, T as SessionData, b as createAlfeChannelPlugin, g as plugin, w as ChatMessage, x as AlfeChannelConfig } from "./plugin.js";
+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";
 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 { _ as createAlfeChannelPlugin, p as plugin } from "./plugin2.js";
+import { S as createAlfeChannelPlugin, _ as plugin } from "./plugin2.js";
 export { createAlfeChannelPlugin, plugin as default };

package/dist/plugin.cjs

@@ -3,19 +3,24 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_plugin = require("./plugin2.cjs");
+exports.A2A_REPLY_SYSTEM_PROMPT = require_plugin.A2A_REPLY_SYSTEM_PROMPT;
 exports.CROSS_AGENT_TOOLS_SYSTEM_PROMPT = require_plugin.CROSS_AGENT_TOOLS_SYSTEM_PROMPT;
+exports.MAX_INBOUND_ATTACHMENT_SIZE = require_plugin.MAX_INBOUND_ATTACHMENT_SIZE;
 exports.VOICE_REPLY_SYSTEM_PROMPT = require_plugin.VOICE_REPLY_SYSTEM_PROMPT;
 exports.__agentTurnQueueForTest = require_plugin.__agentTurnQueueForTest;
 exports.__resetAgentTurnQueueForTest = require_plugin.__resetAgentTurnQueueForTest;
 exports.__setActiveRunForTest = require_plugin.__setActiveRunForTest;
 exports.admitAgentEvent = require_plugin.admitAgentEvent;
 exports.buildA2ACompletePayload = require_plugin.buildA2ACompletePayload;
+exports.buildAttachmentLocalFilename = require_plugin.buildAttachmentLocalFilename;
 exports.buildOriginEnvelopeContext = require_plugin.buildOriginEnvelopeContext;
 exports.buildToolActivity = require_plugin.buildToolActivity;
+exports.buildTurnEnvelopeContext = require_plugin.buildTurnEnvelopeContext;
 exports.computeOpenClawSdkAnchors = require_plugin.computeOpenClawSdkAnchors;
 exports.decideChatServiceStart = require_plugin.decideChatServiceStart;
 exports.default = require_plugin.plugin;
 exports.joinAssistantText = require_plugin.joinAssistantText;
+exports.readAttachmentBodyBounded = require_plugin.readAttachmentBodyBounded;
 exports.resolveAbortTargetKeys = require_plugin.resolveAbortTargetKeys;
 exports.rewriteAssistantText = require_plugin.rewriteAssistantText;
 exports.stripLeakedToolSummary = require_plugin.stripLeakedToolSummary;

package/dist/plugin.d.cts

@@ -229,7 +229,7 @@ interface AlfeChannelOutboundDeps {
   }) => Promise<AlfeOutboundSessionSummary[]>;
   getSession: (sessionId: string) => Promise<AlfeOutboundSession | null>;
   createSession: (sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string) => Promise<unknown>;
-  addMessage: (sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[]) => Promise<void>;
+  addMessage: (sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]) => Promise<void>;
 }
 //#endregion
 //#region src/alfe-channel.d.ts
@@ -247,15 +247,7 @@ interface OutboundDeliveryResult {
   conversationId: string;
   timestamp: number;
 }
-/**
- * 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
- * `resolveTarget`). Persists + broadcasts through the same `sendViaChat` path
- * as a normal reply, so the components ride the standard `message` frame and
- * are replayed on backfill. Components are sanitized (unsafe URLs dropped)
- * before delivery.
- */
+/** Persist only bucket-backed media; passthrough URLs have no stable id. */
 
 /**
  * Creates the Alfe ChannelPlugin object for registration with OpenClaw.
@@ -655,6 +647,23 @@ declare function decideChatServiceStart(state: {
   clientPresent: boolean;
   clientConnected: boolean;
 }): 'skip' | 'recycle' | 'connect';
+interface AttachmentRef {
+  id: string;
+  type: string;
+  mimeType: string;
+  url: string;
+  filename?: string;
+  size?: number;
+}
+declare const MAX_INBOUND_ATTACHMENT_SIZE: number;
+/**
+ * Read a response body without ever retaining more than the attachment cap.
+ * `arrayBuffer()` cannot enforce a cap until after the entire response has
+ * already been allocated, so both declared and streamed sizes are checked.
+ */
+declare function readAttachmentBodyBounded(response: Response, maxBytes?: number): Promise<Uint8Array>;
+/** Build one safe, collision-resistant filename inside the attachment dir. */
+declare function buildAttachmentLocalFilename(att: Pick<AttachmentRef, 'id' | 'filename'>): string;
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
@@ -702,6 +711,14 @@ declare const VOICE_REPLY_SYSTEM_PROMPT: string;
  * disambiguate; this rides the system prompt on every turn (~40 tokens).
  */
 declare const CROSS_AGENT_TOOLS_SYSTEM_PROMPT: string;
+/**
+ * Rules for an inbound agent-to-agent turn. This must ride the runtime-rendered
+ * `GroupSystemPrompt` field; arbitrary extra-context keys are not shown to the
+ * model. Keep the instruction structural: `end_conversation` is the plugin's
+ * authoritative turn-local completion signal. The relay still accepts the
+ * legacy trailing `[RESOLVED]` sentinel for older plugin versions.
+ */
+declare const A2A_REPLY_SYSTEM_PROMPT: string;
 /**
  * Per-turn envelope context derived from the RPC `origin` flag, returned as a
  * `GroupSystemPrompt` block — the PROVEN runtime-rendered seam for per-turn
@@ -727,6 +744,8 @@ declare const CROSS_AGENT_TOOLS_SYSTEM_PROMPT: string;
  * Exported pure for unit testing (mirrors the codebase's pure-helper pattern).
  */
 declare function buildOriginEnvelopeContext(origin: string | undefined): Record<string, unknown>;
+/** Build the single live per-turn prompt block without competing object keys. */
+declare function buildTurnEnvelopeContext(origin: string | undefined, isA2A: boolean): Record<string, unknown>;
 declare const plugin: {
   id: string;
   name: string;
@@ -736,4 +755,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { AlfeResolvedAccount as C, SessionSummary as E, AlfePluginConfig as S, SessionData as T, resolveAbortTargetKeys as _, VOICE_REPLY_SYSTEM_PROMPT as a, createAlfeChannelPlugin as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, plugin as g, joinAssistantText as h, RunEventGate as i, admitAgentEvent as l, decideChatServiceStart as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, rewriteAssistantText as v, ChatMessage as w, AlfeChannelConfig as x, stripLeakedToolSummary as y };
+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 };

package/dist/plugin.d.ts

@@ -229,7 +229,7 @@ interface AlfeChannelOutboundDeps {
   }) => Promise<AlfeOutboundSessionSummary[]>;
   getSession: (sessionId: string) => Promise<AlfeOutboundSession | null>;
   createSession: (sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string) => Promise<unknown>;
-  addMessage: (sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[]) => Promise<void>;
+  addMessage: (sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]) => Promise<void>;
 }
 //#endregion
 //#region src/alfe-channel.d.ts
@@ -247,15 +247,7 @@ interface OutboundDeliveryResult {
   conversationId: string;
   timestamp: number;
 }
-/**
- * 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
- * `resolveTarget`). Persists + broadcasts through the same `sendViaChat` path
- * as a normal reply, so the components ride the standard `message` frame and
- * are replayed on backfill. Components are sanitized (unsafe URLs dropped)
- * before delivery.
- */
+/** Persist only bucket-backed media; passthrough URLs have no stable id. */
 
 /**
  * Creates the Alfe ChannelPlugin object for registration with OpenClaw.
@@ -655,6 +647,23 @@ declare function decideChatServiceStart(state: {
   clientPresent: boolean;
   clientConnected: boolean;
 }): 'skip' | 'recycle' | 'connect';
+interface AttachmentRef {
+  id: string;
+  type: string;
+  mimeType: string;
+  url: string;
+  filename?: string;
+  size?: number;
+}
+declare const MAX_INBOUND_ATTACHMENT_SIZE: number;
+/**
+ * Read a response body without ever retaining more than the attachment cap.
+ * `arrayBuffer()` cannot enforce a cap until after the entire response has
+ * already been allocated, so both declared and streamed sizes are checked.
+ */
+declare function readAttachmentBodyBounded(response: Response, maxBytes?: number): Promise<Uint8Array>;
+/** Build one safe, collision-resistant filename inside the attachment dir. */
+declare function buildAttachmentLocalFilename(att: Pick<AttachmentRef, 'id' | 'filename'>): string;
 declare function enqueueAgentTurn(task: () => Promise<void>, opts?: {
   coalesceKey?: string;
   onSuperseded?: () => void;
@@ -702,6 +711,14 @@ declare const VOICE_REPLY_SYSTEM_PROMPT: string;
  * disambiguate; this rides the system prompt on every turn (~40 tokens).
  */
 declare const CROSS_AGENT_TOOLS_SYSTEM_PROMPT: string;
+/**
+ * Rules for an inbound agent-to-agent turn. This must ride the runtime-rendered
+ * `GroupSystemPrompt` field; arbitrary extra-context keys are not shown to the
+ * model. Keep the instruction structural: `end_conversation` is the plugin's
+ * authoritative turn-local completion signal. The relay still accepts the
+ * legacy trailing `[RESOLVED]` sentinel for older plugin versions.
+ */
+declare const A2A_REPLY_SYSTEM_PROMPT: string;
 /**
  * Per-turn envelope context derived from the RPC `origin` flag, returned as a
  * `GroupSystemPrompt` block — the PROVEN runtime-rendered seam for per-turn
@@ -727,6 +744,8 @@ declare const CROSS_AGENT_TOOLS_SYSTEM_PROMPT: string;
  * Exported pure for unit testing (mirrors the codebase's pure-helper pattern).
  */
 declare function buildOriginEnvelopeContext(origin: string | undefined): Record<string, unknown>;
+/** Build the single live per-turn prompt block without competing object keys. */
+declare function buildTurnEnvelopeContext(origin: string | undefined, isA2A: boolean): Record<string, unknown>;
 declare const plugin: {
   id: string;
   name: string;
@@ -736,4 +755,4 @@ declare const plugin: {
   deactivate(api: PluginApi): Promise<void>;
 };
 //#endregion
-export { AlfeResolvedAccount as C, SessionSummary as E, AlfePluginConfig as S, SessionData as T, resolveAbortTargetKeys as _, VOICE_REPLY_SYSTEM_PROMPT as a, createAlfeChannelPlugin as b, __setActiveRunForTest as c, buildOriginEnvelopeContext as d, buildToolActivity as f, plugin as g, joinAssistantText as h, RunEventGate as i, admitAgentEvent as l, decideChatServiceStart as m, AnchorEnv as n, __agentTurnQueueForTest as o, computeOpenClawSdkAnchors as p, CROSS_AGENT_TOOLS_SYSTEM_PROMPT as r, __resetAgentTurnQueueForTest as s, ActiveRunRef as t, buildA2ACompletePayload as u, rewriteAssistantText as v, ChatMessage as w, AlfeChannelConfig as x, stripLeakedToolSummary as y };
+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 };

package/dist/plugin.js

@@ -1,2 +1,2 @@
-import { a as __setActiveRunForTest, c as buildOriginEnvelopeContext, d as decideChatServiceStart, f as joinAssistantText, g as stripLeakedToolSummary, h as rewriteAssistantText, i as __resetAgentTurnQueueForTest, l as buildToolActivity, m as resolveAbortTargetKeys, n as VOICE_REPLY_SYSTEM_PROMPT, o as admitAgentEvent, p as plugin, r as __agentTurnQueueForTest, s as buildA2ACompletePayload, t as CROSS_AGENT_TOOLS_SYSTEM_PROMPT, u as computeOpenClawSdkAnchors } from "./plugin2.js";
-export { CROSS_AGENT_TOOLS_SYSTEM_PROMPT, VOICE_REPLY_SYSTEM_PROMPT, __agentTurnQueueForTest, __resetAgentTurnQueueForTest, __setActiveRunForTest, admitAgentEvent, buildA2ACompletePayload, buildOriginEnvelopeContext, buildToolActivity, computeOpenClawSdkAnchors, decideChatServiceStart, plugin as default, joinAssistantText, resolveAbortTargetKeys, rewriteAssistantText, stripLeakedToolSummary };
+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 };