@marswave/cola-plugin-sdk - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3-beta.0

distribution/source/types.d.ts

@@ -202,2 +202,9 @@ export type PluginErrorOrigin = 'app' | 'infra' | 'agent' | 'unknown';
         get(): Readonly<Record<string, unknown>>;
+        /**
+         * Shallow-merge `partial` into this plugin's persisted config.
+         * Only the keys present in `partial` change; others are preserved.
+         * Hot-updates the running config (no restart). A plugin can only ever
+         * write its OWN config — the host binds the plugin id internally.
+         */
+        patch(partial: Record<string, unknown>): Promise<void>;
     };
@@ -211,2 +218,8 @@ events: PluginEvents;
 };
+export type InboundConversation = {
+    kind: 'direct' | 'group' | 'channel';
+    /** Group/channel id for group conversations; the peer id for direct. */
+    id: string;
+    name?: string;
+};
 export type DeliverPayload = {
@@ -216,2 +229,6 @@ sessionId: SessionId;
     deliveryContext?: InboundDeliveryContext;
+    /** Defaults to a 'direct' conversation when omitted (backward compatible). */
+    conversation?: InboundConversation;
+    /** For group/channel conversations: whether the bot was @mentioned. */
+    mentionedBot?: boolean;
     message: string;
@@ -371,2 +388,11 @@ attachments?: string[];
     outbound?: ChannelOutboundAdapter;
+    /**
+     * Optional override for the guidance message sent when an unauthorized
+     * sender (DM) or group tries to use the channel. Defaults to a host
+     * template that names the `cola channel allow[-group]` command.
+     */
+    unauthorizedHint?(target: {
+        kind: 'user' | 'group';
+        id: string;
+    }): string;
     auth?: ChannelAuthAdapter;
@@ -373,0 +399,0 @@ };

package.json

 {
   "name": "@marswave/cola-plugin-sdk",
-  "version": "0.0.2",
+  "version": "0.0.3-beta.0",
   "description": "SDK for building Cola channel plugins that connect external messaging platforms to Cola.",
@@ -5,0 +5,0 @@ "license": "MIT",

README.md

@@ -104,3 +104,3 @@ # Cola Plugin SDK
   "dependencies": {
-    "@marswave/cola-plugin-sdk": "^0.5.0"
+    "@marswave/cola-plugin-sdk": "^0.0.2"
   },
@@ -110,4 +110,3 @@ "cola": {
       "id": "example",
-      "entry": "./dist/index.js",
-      "minSdkVersion": "0.5.0"
+      "entry": "./dist/index.js"
     },
@@ -153,2 +152,33 @@ "channel": {
 
+### Group Chats And Access
+
+By default a delivered message is treated as a direct (DM) message. To support
+group chats, set `conversation` on the deliver payload and report whether the
+bot was @mentioned:
+
+```ts
+await ctx.deliver({
+  sessionId: ['group', groupId],
+  sender: { id: senderId, name: senderName },
+  conversation: { kind: 'group', id: groupId }, // 'group' | 'channel' | 'direct'
+  mentionedBot, // detected from the inbound message; required for group/channel
+  message: text
+})
+```
+
+A group message without `mentionedBot: true` is silently ignored, so the agent
+only joins when explicitly addressed. Omitting `conversation` entirely is
+treated as a direct message (backward compatible).
+
+Access is authorized on two axes:
+
+- **DMs** are authorized per sender: `cola channel allow <pluginId> <senderId>`.
+- **Groups** are authorized as a whole: `cola channel allow-group <pluginId> <groupId>`,
+  so every member is allowed without listing each one.
+
+Unauthorized DMs, and groups that @mention the bot but are not authorized,
+receive a rate-limited guidance hint naming the command to run. Override the text
+with `channel.unauthorizedHint(target)`. Manage authorization with
+`cola channel allow / revoke / allow-group / revoke-group / allowlist`.
+
 ### Host Runtime
@@ -159,3 +189,7 @@
 - `identity` for channel user binding.
-- `config.get()` for readonly plugin config.
+- `config.get()` for readonly plugin config, and `config.patch(partial)` to
+  shallow-merge into this plugin's OWN persisted config. It hot-updates the
+  running config without a restart, ignores the reserved `pluginDir` key, and
+  can only ever write the calling plugin's config. Use it to persist
+  credentials obtained at runtime, such as after a scan-to-register flow.
 - `events.on()` for session events — session lifecycle, compaction, agent
@@ -162,0 +196,0 @@ loop, turn boundaries, assistant message stream, `tool:call` /

README.zh.md

@@ -72,5 +72,36 @@ # Cola Plugin SDK 中文说明
 
+### 群聊与访问授权
+
+默认情况下，投递的消息会被当作私聊（DM）。要支持群聊，需要在 deliver payload
+上设置 `conversation`，并标明机器人是否被 @提及：
+
+```ts
+await ctx.deliver({
+  sessionId: ['group', groupId],
+  sender: { id: senderId, name: senderName },
+  conversation: { kind: 'group', id: groupId }, // 'group' | 'channel' | 'direct'
+  mentionedBot, // 从入站消息里检测；group/channel 必填
+  message: text
+})
+```
+
+没有 `mentionedBot: true` 的群消息会被静默忽略，agent 只在被显式 @ 时才介入。
+完全省略 `conversation` 会被当作私聊（向后兼容）。
+
+授权分两条轴：
+
+- **私聊**按 sender 授权：`cola channel allow <pluginId> <senderId>`。
+- **群组**整体授权：`cola channel allow-group <pluginId> <groupId>`，这样群里
+  每个成员都被允许，无需逐个添加。
+
+未授信的私聊，以及 @提及了机器人但未授权的群组，会收到限流（默认 10 分钟冷却）的
+引导提示，提示里会写明要执行的命令。可用 `channel.unauthorizedHint(target)` 覆盖文案。授权管理
+命令：`cola channel allow / revoke / allow-group / revoke-group / allowlist`。
+
 ### Host Runtime
 
-`ctx.runtime` 暴露插件可以安全使用的宿主能力，包括身份绑定、只读配置、
+`ctx.runtime` 暴露插件可以安全使用的宿主能力，包括身份绑定、只读配置
+（`config.get()`）、写回本插件自有配置（`config.patch(partial)`：浅合并进
+本插件持久化配置，热更新无需重启，忽略保留键 `pluginDir`，且只能写自己的
+配置——适合在运行时把拿到的凭据写回，例如扫码注册之后）、
 session events（session 生命周期、compaction、agent 循环、turn、assistant
@@ -77,0 +108,0 @@ message stream、`tool:call`/`tool:result`、运行时 `tool:execution_*`，

Fixed alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Improved metrics

Total package byte prevSize

40273

11.66%

Lines of code

577

4.72%

Number of lines in readme file

290

13.28%

Number of medium supply chain risk alerts

2

-33.33%

No dependency changes