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

Comparing version 0.0.4-dev.202606041251.c8b2bed3 to 0.0.4

distribution/source/index.d.ts

@@ -1,2 +0,2 @@
-export { type Plugin, type PluginMeta, type PluginLogger, type PluginErrorOrigin, type PluginErrorClassification, type PluginRuntime, type PluginEvents, type PluginSessionEvent, type PluginEventHandler, type SessionId, type ChannelSender, type InboundDeliveryContext, type DeliveryContext, type PluginCommandContext, type PluginCommandResult, type PluginCommandDefinition, type ChannelDefinition, type ChannelMeta, type ChannelCapabilities, type ChannelGatewayAdapter, type ChannelStatusResult, type GatewayContext, type ChannelOutboundAdapter, type OutboundContext, type ReactionAction, type ReactionContext, type ChannelAuthAdapter, type AuthContext, type ChannelConfigAdapter, type ChannelConfigField, type ChannelConfigFieldOption, type ChannelConfigSchema, type ChannelAgentPromptAdapter, type ChannelAgentTool, type ChannelAgentToolContext, type ChannelAgentToolResult, type PluginTool, type PluginToolScope, type PluginToolContext, type PluginToolResult, type PluginStartContext, type PluginEventScope, type PluginEventSubscribeOptions, type PluginSessionEventOrigin, type PluginToolContent, type PromptContext, type DeliverPayload, type DeliverFn, type SttLanguage, type SttStream, type PluginStt, type TtsLanguage, type PluginTts } from './types.js';
+export { type Plugin, type PluginMeta, type PluginLogger, type PluginErrorOrigin, type PluginErrorClassification, type PluginRuntime, type PluginEvents, type PluginSessionEvent, type PluginEventHandler, type SessionId, type ChannelSender, type InboundDeliveryContext, type DeliveryContext, type PluginCommandContext, type PluginCommandResult, type PluginCommandDefinition, type ChannelDefinition, type ChannelMeta, type ChannelCapabilities, type ChannelGatewayAdapter, type ChannelStatusResult, type GatewayContext, type ChannelMediaKind, type ChannelMediaCapabilities, type ChannelOutboundAdapter, type OutboundContext, type ReactionAction, type ReactionContext, type ChannelAuthAdapter, type AuthContext, type ChannelConfigAdapter, type ChannelConfigField, type ChannelConfigFieldOption, type ChannelConfigSchema, type ChannelAgentPromptAdapter, type ChannelAgentTool, type ChannelAgentToolContext, type ChannelAgentToolResult, type PluginTool, type PluginToolScope, type PluginToolContext, type PluginToolResult, type PluginStartContext, type PluginEventScope, type PluginEventSubscribeOptions, type PluginSessionEventOrigin, type PluginToolContent, type PromptContext, type DeliverPayload, type DeliverFn, type SttLanguage, type SttStream, type PluginStt, type TtsLanguage, type PluginTts, type PluginLlm, type PluginLlmOptions } from './types.js';
 export { createPollLoop, withBackoff } from './helpers.js';
@@ -3,0 +3,0 @@ import type { Plugin, ChannelDefinition, PluginCommandDefinition } from './types.js';

distribution/source/types.d.ts

@@ -79,2 +79,3 @@ export type PluginErrorOrigin = 'app' | 'infra' | 'agent' | 'unknown';
     promptId?: string;
+    reason?: 'manual' | 'threshold' | 'overflow';
 } | {
@@ -85,2 +86,3 @@ type: 'compact:end';
     promptId?: string;
+    reason?: 'manual' | 'threshold' | 'overflow';
     aborted?: boolean;
@@ -196,2 +198,30 @@ errorMessage?: string;
 };
+export type PluginLlmOptions = {
+    systemPrompt?: string;
+    /**
+     * Covers the entire call — for `streamText` the whole stream duration,
+     * not just time to first token. Defaults to 60s; raise it for long
+     * generations.
+     */
+    timeoutMs?: number;
+};
+export type PluginLlm = {
+    /**
+     * Run a one-shot generation against the user's primary model and resolve
+     * with the plain-text response. Throws when no provider/API key is
+     * configured or the call fails.
+     */
+    generateText(prompt: string, opts?: PluginLlmOptions): Promise<string>;
+    /**
+     * Like `generateText`, but forces the model to return JSON matching
+     * `schema` (a JSON Schema object). The result is validated against the
+     * schema before resolving; throws on mismatch.
+     */
+    generateObject<T = unknown>(prompt: string, schema: Record<string, unknown>, opts?: PluginLlmOptions): Promise<T>;
+    /**
+     * Like `generateText`, but yields incremental text deltas as they arrive.
+     * Errors (no provider key, stream failure) are thrown during iteration.
+     */
+    streamText(prompt: string, opts?: PluginLlmOptions): AsyncIterable<string>;
+};
 export type PluginRuntime = {
@@ -216,2 +246,3 @@ identity: {
     tts: PluginTts;
+    llm: PluginLlm;
     logger: PluginLogger;
@@ -307,2 +338,9 @@ version: string;
 };
+export type ChannelMediaKind = 'image' | 'video' | 'audio' | 'file';
+export type ChannelMediaCapabilities = {
+    maxBytesPerFile?: number;
+    maxBytesTotal?: number;
+    maxCount?: number;
+    supportedKinds?: ChannelMediaKind[];
+};
 export type ChannelOutboundAdapter = {
@@ -314,2 +352,3 @@ sendText(ctx: OutboundContext): Promise<void>;
     }): Promise<void>;
+    mediaCapabilities?: ChannelMediaCapabilities;
     sendTyping?(ctx: OutboundContext & {
@@ -316,0 +355,0 @@ active: boolean;

package.json

 {
   "name": "@marswave/cola-plugin-sdk",
-  "version": "0.0.4-dev.202606041251.c8b2bed3",
+  "version": "0.0.4",
   "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.0.2"
+    "@marswave/cola-plugin-sdk": "^0.0.3"
   },
@@ -110,3 +110,4 @@ "cola": {
       "id": "example",
-      "entry": "./dist/index.js"
+      "entry": "./dist/index.js",
+      "minColaVersion": "0.9.10"
     },
@@ -126,3 +127,3 @@ "channel": {
 
-Set `cola.plugin.minColaVersion`, for example `"0.99.0"`, only when the plugin
+Set `cola.plugin.minColaVersion`, for example `"0.9.10"`, only when the plugin
 uses runtime features that require a specific Cola app release. The plugin's own
@@ -151,2 +152,8 @@ package version and `@marswave/cola-plugin-sdk` dependency version do not force
 
+For media delivery, implement `sendMedia()` and declare `mediaCapabilities`.
+`supportedKinds` narrows uploads to `'image'`, `'video'`, `'audio'`, and/or
+`'file'`; omit it to accept every kind already enabled in `capabilities.send`.
+Use `maxBytesPerFile`, `maxBytesTotal`, and `maxCount` to publish the platform
+limits Cola should enforce before calling your adapter.
+
 ### Auth And Identity
@@ -207,2 +214,10 @@
 - `stt` and `tts` for host-provided local speech services when available.
+- `llm` for one-shot model calls using the user's configured primary model:
+  `llm.generateText(prompt, opts?)` resolves with plain text,
+  `llm.generateObject(prompt, schema, opts?)` forces and validates a JSON
+  result against a JSON Schema, and `llm.streamText(prompt, opts?)` yields
+  incremental text deltas as an `AsyncIterable<string>`. All accept
+  `{ systemPrompt?, timeoutMs? }` (the timeout covers the entire call,
+  including the full stream) and throw when no provider key is configured
+  or the call fails.
 - `logger` for local logging and explicit error reporting.
@@ -209,0 +224,0 @@ - `reloadGateway()` for restarting receive loops after config or auth changes.

README.zh.md

@@ -50,3 +50,3 @@ # Cola Plugin SDK 中文说明
 只有当插件使用了某个 Cola 版本才提供的运行时能力时，才需要在
-`cola.plugin.minColaVersion` 声明最低 Cola app 版本。插件自身版本和
+`cola.plugin.minColaVersion` 声明最低 Cola app 版本，例如 `"0.9.10"`。插件自身版本和
 `@marswave/cola-plugin-sdk` 依赖版本本身不会要求用户升级 Cola。
@@ -70,2 +70,8 @@
 
+如果要发送媒体或文件，实现 `sendMedia()` 并声明 `mediaCapabilities`。
+`supportedKinds` 可以把上传限制在 `'image'`、`'video'`、`'audio'` 和/或
+`'file'`；不填则接受 `capabilities.send` 已启用的所有类型。
+`maxBytesPerFile`、`maxBytesTotal` 和 `maxCount` 用来发布平台限制，Cola 会在
+调用 adapter 前先按这些限制筛选。
+
 ### Auth 与身份绑定
@@ -115,2 +121,7 @@
 默认本插件 scope，传 `{ scope: 'all' }` 可订阅所有会话）、本地 STT/TTS、
+模型调用（`llm.generateText(prompt, opts?)` 返回纯文本，
+`llm.generateObject(prompt, schema, opts?)` 按 JSON Schema 强制返回并
+校验结构化结果，`llm.streamText(prompt, opts?)` 以 `AsyncIterable<string>`
+增量产出文本；均使用用户配置的主模型，可选 `{ systemPrompt?, timeoutMs? }`
+（超时覆盖整次调用，含流式全程），未配置 provider key 或调用失败时抛错）、
 日志上报，以及在配置或登录状态变化后重启 gateway 的 `reloadGateway()`。
@@ -117,0 +128,0 @@ 完整事件目录、`origin` 标签以及"不转发"契约见

No alert changes

Improved metrics

Total package byte prevSize

44165

8.33%

Lines of code

616

6.76%

Number of lines in readme file

310

5.08%

No dependency changes