@axiom-lattice/protocols 4.7.1 → 4.9.0

package/package.json

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

package/src/AgentLatticeProtocol.ts

@@ -41,6 +41,12 @@ interface BaseAgentConfig {
   name: string; // Name
   description: string; // Description
   prompt: string; // Prompt
+  /**
+   * Owner user id when this config represents a user's personal assistant.
+   * `undefined` means a tenant/workspace-shared agent, which is the only kind
+   * discoverable in shared contexts (e.g. a public room's executor list).
+   */
+  ownerUserId?: string;
   /**
    * Key of the parent agent to inherit configuration from.
    * When set, unspecified fields are inherited from the parent agent's config.

package/src/ChannelAdapterProtocol.ts

@@ -81,7 +81,15 @@ export interface ChannelAdapter<TConfig = unknown> {
    *
    * 与 `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,
@@ -112,6 +120,10 @@ export interface ChannelAdapter<TConfig = unknown> {
    * 可选：断开持久连接并停止接收事件。
    * 当 channel installation 被禁用或删除时调用。
    * `installationId` 用于标识要断开的具体安装实例。
+   *
+   * 实现必须是**幂等**且对未连接的 installation 安全（no-op）：多副本下
+   * `ChannelConnectionLeader` 在失去租约时会对共享 store 中的全部启用安装
+   * 调用 `disconnect`，其中可能包含本副本从未 `connect` 的实例。
    */
   disconnect?(installationId: string): Promise<void>;
 }

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.

package/src/PluginDeploymentStoreProtocol.ts

@@ -0,0 +1,56 @@
+/** Lifecycle states of a published plugin's resident service. */
+export type PluginDeploymentStatus =
+  | "requested"
+  | "provisioning"
+  | "running"
+  | "paused"
+  | "stopping"
+  | "stopped"
+  | "failed";
+
+/** Lifecycle strategy: lazily paused vs. permanently resident. */
+export type PluginDeploymentMode = "onDemand" | "alwaysOn";
+
+/** Durable tenant-scoped record of one published plugin's resident service. */
+export interface PluginDeployment {
+  id: string;
+  tenantId: string;
+  pluginType: string;
+  pluginVersion: string;
+  mode: PluginDeploymentMode;
+  status: PluginDeploymentStatus;
+  /** Backend provider key, e.g. "microsandbox-remote" | "opensandbox". */
+  provider: string;
+  /** Deterministic sandbox identity (`plugin-<hash(tenantId, pluginType)>`). */
+  sandboxName: string;
+  /** Guest port published by the host server. */
+  port: number;
+  /** Resolved endpoint (scheme-less route or host:port); may change over time. */
+  endpoint?: string;
+  /** Image used to create the sandbox, when pinned. */
+  imageRef?: string;
+  /** Idle timeout before an onDemand deployment is paused. */
+  idleTimeoutMs: number;
+  lastHealthAt?: string;
+  lastError?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Persistence operations for plugin deployments. */
+export interface PluginDeploymentStore {
+  /** Lists every deployment for a tenant. */
+  listByTenant(tenantId: string): Promise<PluginDeployment[]>;
+  /** Returns the deployment for a plugin type, or undefined. */
+  get(tenantId: string, pluginType: string): Promise<PluginDeployment | undefined>;
+  /** Inserts or replaces a deployment keyed by tenant + plugin type. */
+  upsert(deployment: PluginDeployment): Promise<PluginDeployment>;
+  /** Applies a partial update (status/endpoint/health); returns the updated record. */
+  updateStatus(
+    tenantId: string,
+    pluginType: string,
+    patch: Partial<Omit<PluginDeployment, "id" | "tenantId" | "pluginType">>
+  ): Promise<PluginDeployment | undefined>;
+  /** Deletes a deployment. Returns whether a row was removed. */
+  delete(tenantId: string, pluginType: string): Promise<boolean>;
+}

package/src/PluginProtocol.ts

@@ -82,10 +82,13 @@ export interface PluginConnection {
 }
 
 /**
- * UI declaration for a plugin tool: an HTML file rendered as an MCP App when
- * the tool runs.
+ * UI declaration for a plugin tool: an HTML resource rendered as an MCP App
+ * when the tool runs.
  *
- * @property resource - Safe relative path (within the plugin directory) to an `.html` file.
+ * @property resource - For GLOBAL plugins, a `ui://` key into the plugin's
+ *   `meta.uiResources` map (inline HTML served without a sandbox read). For
+ *   tenant sandbox plugins, a safe relative path (within the plugin directory)
+ *   to an `.html` file on the tenant volume.
  * @property displayMode - Preferred display mode; defaults to `inline` (resolved by the compiler).
  * @property csp - Origins the UI needs (see `McpUiCsp`).
  * @property permissions - Sandbox permissions requested (see `McpUiPermissions`).

package/src/ProjectRoomProtocol.ts

@@ -69,6 +69,12 @@ export interface ProjectBotMembership {
   roomThreadId: string;
   joinedAt: Date;
   updatedAt: Date;
+  /**
+   * True for a not-yet-materialized "virtual" public-project entry (dynamic
+   * roster projection). Virtual entries have no persisted row; their id
+   * materializes just-in-time on first interaction. Absent on real members.
+   */
+  provisional?: boolean;
 }
 
 /** Identifies a human author of a project room message. */

package/src/TrustedRunContextProtocol.ts

@@ -22,6 +22,15 @@ export interface ProjectRoomTrustedRunContext {
    * naming any specific value (ADR-118).
    */
   source?: string;
+  /**
+   * Host-provided signal that this project has no authored roster.
+   *
+   * Optional; `true` when present, `undefined`/`false` is treated as absent. Core uses it to skip
+   * Project roster authorization for the run's caller and owner (any tenant agent may own a task) and
+   * to list the tenant's agents — not the persisted roster — as available executors. The host stamps
+   * it only for the workspace general project. Mirrors {@link ProjectTaskTrustedRunContext.rosterExempt}.
+   */
+  rosterExempt?: boolean;
 }
 
 /** Trusted Project Task identity persisted with a privileged queue message. */
@@ -111,17 +120,21 @@ export function parseTrustedRunContext(value: unknown): TrustedRunContext {
     "tenantId", "workspaceId", "projectId", "roomId", "sourceRoomMessageId", "membershipId",
     "assistantId", "inputMessageId", "role", "title",
   ] as const;
-  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility", "source"]);
+  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility", "source", "rosterExempt"]);
   const hasResponsibility = projectRoomValues !== undefined
     && Object.prototype.hasOwnProperty.call(projectRoomValues, "responsibility");
   const hasSource = projectRoomValues !== undefined
     && Object.prototype.hasOwnProperty.call(projectRoomValues, "source");
+  const hasRosterExempt = projectRoomValues !== undefined
+    && Object.prototype.hasOwnProperty.call(projectRoomValues, "rosterExempt");
   if (!projectRoomValues
     || requiredKeys.some((key) => typeof projectRoomValues[key] !== "string" || projectRoomValues[key].length === 0)
     || (hasResponsibility && projectRoomValues.responsibility !== undefined
       && (typeof projectRoomValues.responsibility !== "string" || projectRoomValues.responsibility.length === 0))
     || (hasSource && projectRoomValues.source !== undefined
       && (typeof projectRoomValues.source !== "string" || projectRoomValues.source.length === 0))
+    || (hasRosterExempt && projectRoomValues.rosterExempt !== undefined
+      && typeof projectRoomValues.rosterExempt !== "boolean")
     || (projectRoomValues.role !== "coordinator" && projectRoomValues.role !== "specialist")) {
     throw new Error("Invalid trusted agent run context");
   }
@@ -143,6 +156,9 @@ export function parseTrustedRunContext(value: unknown): TrustedRunContext {
   if (hasSource && typeof projectRoomValues.source === "string") {
     parsedProjectRoom.source = projectRoomValues.source;
   }
+  if (hasRosterExempt && projectRoomValues.rosterExempt === true) {
+    parsedProjectRoom.rosterExempt = true;
+  }
   return { projectRoom: parsedProjectRoom };
 }
 

package/src/__tests__/TrustedRunContextProtocol.test.ts

@@ -257,6 +257,45 @@ describe("parseTrustedRunContext", () => {
     })).toThrow("Invalid trusted agent run context");
   });
 
+  it("round-trips an explicit project room roster exemption", () => {
+    const parsed = parseTrustedRunContext({
+      projectRoom: { ...validProjectRoom(), rosterExempt: true },
+    });
+
+    expect(parsed.projectRoom?.rosterExempt).toBe(true);
+  });
+
+  it("leaves project room roster exemption undefined when absent", () => {
+    const parsed = parseTrustedRunContext({ projectRoom: validProjectRoom() });
+
+    expect(parsed.projectRoom?.rosterExempt).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(parsed.projectRoom, "rosterExempt")).toBe(false);
+  });
+
+  it("treats an explicit project room roster exemption of undefined as absent", () => {
+    const parsed = parseTrustedRunContext({
+      projectRoom: { ...validProjectRoom(), rosterExempt: undefined },
+    });
+
+    expect(parsed.projectRoom?.rosterExempt).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(parsed.projectRoom, "rosterExempt")).toBe(false);
+  });
+
+  it("drops an explicit project room roster exemption of false", () => {
+    const parsed = parseTrustedRunContext({
+      projectRoom: { ...validProjectRoom(), rosterExempt: false },
+    });
+
+    expect(parsed.projectRoom?.rosterExempt).toBeUndefined();
+    expect(Object.prototype.hasOwnProperty.call(parsed.projectRoom, "rosterExempt")).toBe(false);
+  });
+
+  it("rejects a non-boolean project room roster exemption", () => {
+    expect(() => parseTrustedRunContext({
+      projectRoom: { ...validProjectRoom(), rosterExempt: "yes" },
+    })).toThrow("Invalid trusted agent run context");
+  });
+
   it.each([...Object.keys(validProjectTask()), "source"])("rejects an empty project task %s", (field) => {
     expect(() => parseTrustedRunContext({
       projectTask: { ...validProjectTask(), [field]: "" },

package/src/index.ts

@@ -59,6 +59,7 @@ export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
 export * from "./ProjectRoomReadStateProtocol";
 export * from "./UserPushSubscriptionStoreProtocol";
+export * from "./PluginDeploymentStoreProtocol";
 export * from "./LeaseStoreProtocol";
 export * from "./OutboxStoreProtocol";
 export * from "./ExactDataSnapshot";