@axiom-lattice/protocols 4.8.0 → 4.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/ChannelAdapterProtocol.ts

@@ -43,6 +43,19 @@ export interface OutboundMessage {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * 流式回复的一个片段。
+ *
+ * `text` 是**累计全文**（不是增量）—— 与微信 `stream.content` 的语义一致：
+ * 每次推送都是"把当前消息刷新成这段内容"。实现方据此避免各自维护拼接状态。
+ */
+export interface OutboundStreamChunk {
+  /** 截至目前要展示的**累计**全文。 */
+  text: string;
+  /** 是否结束（最后一次刷新必须为 `true`）。 */
+  done: boolean;
+}
+
 export interface DispatchResult {
   success: boolean;
   bindingId?: string;
@@ -76,12 +89,39 @@ export interface ChannelAdapter<TConfig = unknown> {
     message: OutboundMessage,
     installation: ChannelInstallation,
   ): Promise<void>;
+  /**
+   * 可选：流式回复。
+   *
+   * 实现该方法后，`MessageRouter` 会在等待 `reply:ready` 的同时，把 agent
+   * 的**增量输出**按节流推给对方；`reply:ready` 到达时以 `done: true` 收尾。
+   *
+   * 实现约定：
+   * - 同一次入站消息的多次刷新必须关联到**同一条**消息（微信即同一个
+   *   `stream.id`，`req_id` 取 `replyTarget.rawTarget.frame`）；
+   * - 必须保证最终以 `done: true` 收尾（调用方保证至少会调一次）；
+   * - 失败不应抛出到派发链路（吞掉并记日志）。
+   *
+   * 未实现时行为与之前完全一致（只在 `reply:ready` 时调一次 `sendReply`）。
+   */
+  sendStreamChunk?(
+    replyTarget: ReplyTarget,
+    chunk: OutboundStreamChunk,
+    installation: ChannelInstallation,
+  ): Promise<void>;
   /**
    * 可选：把 Agent 暂停等待人工输入时的问题/提示投影到会话中。
    *
    * 与 `sendReply` 不同，这不是对某条入站消息的最终回复，而是运行中途
    * 产生的一条独立 bot 消息（例如 Project Room 的 clarify 卡片）。
-   * `message.metadata.inputMessageId` 关联触发该运行的入站队列消息。
+   *
+   * 支持两种（互斥的）关联方式，均由 `message.metadata` 承载：
+   * - `message.metadata.inputMessageId`：legacy presence 关联，指向触发该
+   *   运行的入站队列消息；需配合 `replyTarget.rawTarget` 中的
+   *   `sourceRoomMessageId` / `inputMessageId`。
+   * - `message.metadata.correlationKey`（可选）：**source-less/correlated**
+   *   中断，没有入站输入消息；由调用方提供关联键，幂等性以「每次中断」为单位
+   *   （idempotency key 派生自该 correlationKey），`replyTarget.rawTarget`
+   *   只需 `targetMembershipId`。
    */
   sendInterrupt?(
     replyTarget: ReplyTarget,

package/src/ChannelInstallationStoreProtocol.ts

@@ -1,5 +1,5 @@
 /** Channel types persisted by the installation store, including internal-only channels. */
-export type ChannelInstallationType = "lark" | "email" | "slack" | "wechat" | "room";
+export type ChannelInstallationType = "lark" | "email" | "slack" | "wechat" | "wecom" | "room";
 
 /** Channel types exposed by the public installation management API. */
 export type PublicChannelInstallationType = Exclude<ChannelInstallationType, "room">;
@@ -19,6 +19,19 @@ export interface WechatChannelInstallationConfig {
   uin?: string;
 }
 
+/**
+ * Credentials for a WeCom (企业微信) 智能机器人 installation using the
+ * long-connection (API 模式) transport. Only `botId` + `secret` are needed —
+ * no CorpID / AgentID / Token / EncodingAESKey, and no callback URL.
+ */
+export interface WecomChannelInstallationConfig {
+  /** 机器人 BotID. */
+  botId: string;
+  /** 长连接专用 Secret. */
+  secret: string;
+  assistantId?: string;
+}
+
 /** A persisted tenant-scoped channel installation. */
 export interface ChannelInstallation<TConfig = unknown> {
   id: string;
@@ -49,6 +62,7 @@ type PublicInstallationBase = Omit<CreateChannelInstallationInput, "channel" | "
 export type CreateChannelInstallationRequest = PublicInstallationBase & (
   | { channel: "lark"; config: LarkChannelInstallationConfig }
   | { channel: "wechat"; config: WechatChannelInstallationConfig }
+  | { channel: "wecom"; config: WecomChannelInstallationConfig }
   | { channel: "email" | "slack"; config: Record<string, unknown> }
 );
 

package/src/ModelLatticeProtocol.ts

@@ -24,6 +24,17 @@ export interface LLMConfig {
   streaming?: boolean;
   apiKeyEnvName?: string;
   apiKey?: string;
+  /**
+   * The upstream requires no credentials.
+   *
+   * A locally hosted model server — Ollama, vLLM, LM Studio — usually accepts
+   * unauthenticated requests. Without this flag a config carrying no key falls
+   * back to `process.env[apiKeyEnvName ?? "<PROVIDER>_API_KEY"]`, which would
+   * send the *gateway's own* deployment credential to whatever host the tenant
+   * configured. Setting it makes "no credential" an explicit statement rather
+   * than a missing value, so the fallback never runs.
+   */
+  noAuth?: boolean;
   baseURL?: string;
   modelKwargs?: Record<string, any>;
   extra?: Record<string, any>;

package/src/ModelProviderProtocol.ts

@@ -237,14 +237,16 @@ export interface CreateModelProviderRequest {
   baseURL: string;
 
   /**
-   * Upstream API key. Required: a provider must always carry a credential.
+   * Upstream API key. Optional: omitted means the upstream needs no
+   * authentication, which is the normal case for a locally hosted model server
+   * (Ollama, vLLM, LM Studio).
    *
-   * A keyless provider is not merely useless — it is unsafe. `initChatModel`
-   * falls back to `process.env[apiKeyEnvName ?? "OPENAI_API_KEY"]` when the
-   * config carries no key, so a keyless provider pointed at a tenant-chosen
-   * host would send the gateway's own deployment credential to it.
+   * A keyless provider must never fall back to the gateway's own environment
+   * credentials. `initChatModel` would otherwise reach for `OPENAI_API_KEY` and
+   * send the deployment's credential to the tenant's host. The runtime config
+   * carries an explicit no-auth marker instead — see `LLMConfig.noAuth`.
    */
-  apiKey: string;
+  apiKey?: string;
 
   /**
    * Whether this provider participates in discovery and registration
@@ -350,6 +352,21 @@ export interface ProviderModelInput extends DiscoveredModel {
    * Distinct from `enabled: false`, which means the tenant switched it off.
    */
   stale?: boolean;
+  /**
+   * Per-model LLM config, merged over the provider's own settings when the
+   * runtime client is built.
+   *
+   * This is what lets one model on a provider run at a different temperature,
+   * or carry `modelKwargs` the server needs, without duplicating the provider.
+   */
+  extra?: Record<string, unknown>;
+  /**
+   * Whether this is the tenant's default model.
+   *
+   * Omitted means "leave the stored flag alone": a discovery pass carries no
+   * opinion about which model is the default, and must not clear it.
+   */
+  isDefault?: boolean;
 }
 
 /**
@@ -365,6 +382,22 @@ export interface ModelSelection {
   enabled: boolean;
   /** The upstream no longer offers this model; the row is kept, flagged. */
   stale?: boolean;
+  /**
+   * Per-model LLM config, merged over the provider's own settings.
+   *
+   * Omitted means "leave whatever is stored alone" — the selection carries only
+   * what the caller is changing, and a model edited through the picker must not
+   * lose the config it already had.
+   */
+  extra?: Record<string, unknown>;
+  /**
+   * Whether this is the tenant's default model.
+   *
+   * At most one model per tenant may carry it. Omitted means "leave the stored
+   * flag alone"; a default can only be replaced, never dropped by omission —
+   * see `ModelProviderStore.getDefaultModel`.
+   */
+  isDefault?: boolean;
 }
 
 /**
@@ -418,6 +451,22 @@ export interface ModelProviderModelEntry {
    */
   stale?: boolean;
 
+  /**
+   * Per-model LLM config, merged over the provider's own settings when the
+   * runtime client is built. Absent when the model runs on the provider's
+   * settings alone.
+   */
+  extra?: Record<string, unknown>;
+
+  /**
+   * Whether this is the tenant's default model.
+   *
+   * At most one row per tenant carries it, enforced by a partial unique index.
+   * It is what a bare `"default"` model key resolves to for that tenant, and it
+   * cannot be deleted — replacing it means marking another model first.
+   */
+  isDefault?: boolean;
+
   /**
    * Timestamp of the discovery that produced this row
    */
@@ -563,6 +612,19 @@ export interface TenantModelPublicEntry {
    */
   stale: boolean;
 
+  /**
+   * Per-model LLM config, merged over the provider's own settings. Absent when
+   * the model runs on the provider's settings alone.
+   */
+  extra?: Record<string, unknown>;
+
+  /**
+   * Whether this is the tenant's default model — the one a bare `"default"`
+   * key resolves to, and the one a tenant without its own would otherwise take
+   * from the deployment.
+   */
+  isDefault?: boolean;
+
   /**
    * Whether this model can actually be executed by an agent.
    * Phase 1: true only for the `default` tenant.