@axiom-lattice/protocols 4.9.0 → 4.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.9.0",
+  "version": "4.11.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,26 @@ export interface OutboundMessage {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * 流式回复的一个片段。
+ *
+ * `text` 是**累计全文**（不是增量）—— 与微信 `stream.content` 的语义一致：
+ * 每次推送都是"把当前消息刷新成这段内容"。实现方据此避免各自维护拼接状态。
+ */
+export interface OutboundStreamChunk {
+  /** 截至目前要展示的**累计**全文。 */
+  text: string;
+  /** 是否结束（最后一次刷新必须为 `true`）。 */
+  done: boolean;
+  /**
+   * 结束原因；仅对 `done: true` 有意义。未提供视为正常完成。
+   *
+   * 适配器可据此决定是否发送运行中途产生的附加内容（例如企业微信卡片）：
+   * 失败/中断/超时的轮次不应把半成品当成正常结果展示。
+   */
+  reason?: "completed" | "failed" | "interrupted" | "timeout";
+}
+
 export interface DispatchResult {
   success: boolean;
   bindingId?: string;
@@ -76,6 +96,25 @@ 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 暂停等待人工输入时的问题/提示投影到会话中。
    *

package/src/ModelProviderProtocol.ts

@@ -34,6 +34,21 @@ export type ModelProviderApiStyle = "chat-completions" | "responses";
  */
 export type ModelProviderLlmProvider = LLMConfig["provider"];
 
+/**
+ * What a model can do.
+ *
+ * Lives on the **model** row, not the provider: one provider is a set of
+ * credentials plus one base URL, and a single DashScope-compatible endpoint
+ * serves chat, embedding and speech at once. Putting this on the provider would
+ * force a tenant to create three providers pointing at the same address with
+ * the same secret.
+ *
+ * `"asr"` is speech-to-text; the runtime is the `stt` lattice, not
+ * `models`. The kinds are deliberately independent: each has its own lattice
+ * manager, its own loader guard, and its own client type.
+ */
+export type ModelKind = "chat" | "embedding" | "asr";
+
 /**
  * Build the tenant-scoped model key.
  *
@@ -360,6 +375,14 @@ export interface ProviderModelInput extends DiscoveredModel {
    * or carry `modelKwargs` the server needs, without duplicating the provider.
    */
   extra?: Record<string, unknown>;
+  /**
+   * What this model does.
+   *
+   * Omitted means "keep the stored kind"; a brand-new row defaults to
+   * `"chat"`. Discovery cannot tell the kinds apart from `/v1/models`, so the
+   * admin sets it.
+   */
+  kind?: ModelKind;
   /**
    * Whether this is the tenant's default model.
    *
@@ -390,6 +413,12 @@ export interface ModelSelection {
    * lose the config it already had.
    */
   extra?: Record<string, unknown>;
+  /**
+   * What this model does.
+   *
+   * Omitted means "leave the stored kind alone", the same rule as `extra`.
+   */
+  kind?: ModelKind;
   /**
    * Whether this is the tenant's default model.
    *
@@ -424,6 +453,13 @@ export interface ModelProviderModelEntry {
    */
   modelId: string;
 
+  /**
+   * What this model does — chat, embedding or speech-to-text.
+   *
+   * Rows created before this column existed are all `"chat"`.
+   */
+  kind: ModelKind;
+
   /**
    * Optional human-readable name from the upstream
    */
@@ -576,6 +612,12 @@ export interface TenantModelPublicEntry {
    */
   modelKey: string;
 
+  /**
+   * What this model does. Pickers filter on it: a chat selector must not offer
+   * an embedding model, and the collection picker must not offer a chat model.
+   */
+  kind: ModelKind;
+
   /**
    * Optional human-readable name
    */
@@ -703,6 +745,21 @@ export interface ModelProviderProbeRequest {
    * Wire protocol to speak. Defaults to `openai-compatible`.
    */
   protocol?: ModelProviderWireProtocol;
+
+  /**
+   * What kind of model to probe.
+   *
+   * A model-list probe proves the address and the credential, not that a model
+   * can actually run. For embeddings the meaningful check is one inference
+   * request, which is why the caller names the model and the kind.
+   */
+  kind?: ModelKind;
+
+  /**
+   * Model id to probe. Required when `kind` is `"embedding"`: the probe sends
+   * one tiny input to that model and reports the resulting vector's dimension.
+   */
+  modelId?: string;
 }
 
 /**
@@ -736,6 +793,14 @@ export interface ModelProviderProbeResult {
    * errors rather than as an unreachable probe.
    */
   error?: ModelProviderUpstreamErrorCode;
+
+  /**
+   * Dimension of the vector an embedding probe got back.
+   *
+   * Absent for a model-list probe, and for an upstream that answered but
+   * returned no usable vector.
+   */
+  dimensions?: number;
 }
 
 /**

package/src/VectorStoreProviderProtocol.ts

@@ -17,6 +17,15 @@ export interface VectorStoreCreateParams {
   tableName: string;
   /** Embedding model key to use for embedding operations */
   embeddingKey: string;
+  /**
+   * Tenant whose embedding model the key belongs to.
+   *
+   * Tenant model keys are `${providerId}/${modelId}` and resolve per tenant, so
+   * a provider cannot look one up without knowing whose it is. Omitted means the
+   * deployment namespace (`"default"`), which is where boot-time registrations
+   * live.
+   */
+  tenantId?: string;
   /** Provider-specific configuration */
   config?: Record<string, unknown>;
 }