@axiom-lattice/protocols 4.7.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.7.0",
+  "version": "4.8.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

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

package/src/ConnectionStoreProtocol.ts

@@ -15,15 +15,51 @@ export interface ConnectionEntry {
   name: string;
   description?: string;
   config: Record<string, unknown>;
+  /**
+   * Names of config fields that hold secrets (API keys, passwords, tokens).
+   *
+   * Stores persist this list alongside the entry and use it to encrypt those
+   * config values at rest on write and transparently decrypt them on read.
+   * `config` in a returned entry is always the decrypted, real value — callers
+   * (gateway API, runtime plugin resolution) never see ciphertext.
+   *
+   * Absent/empty means the entry has no encrypted fields (e.g. legacy rows or
+   * connection types whose schema defines no password fields).
+   */
+  secretFields?: string[];
   createdAt: string;
   updatedAt: string;
 }
 
 export interface ConnectionStore {
   listByTenant(tenantId: string): Promise<ConnectionEntry[]>;
+  /**
+   * List a tenant's connections of one plugin type.
+   *
+   * `config` in the returned entries is decrypted — implementations decrypt the
+   * fields named by each entry's `secretFields` before returning.
+   */
   listByType(tenantId: string, type: string): Promise<ConnectionEntry[]>;
+  /**
+   * Read one connection by key.
+   *
+   * `config` in the returned entry is decrypted (see `listByType`).
+   */
   getByKey(tenantId: string, type: string, key: string): Promise<ConnectionEntry | null>;
+  /**
+   * Create a connection.
+   *
+   * Implementations encrypt the `secretFields` of `config` at rest; the
+   * returned entry carries the plaintext `config` the caller supplied.
+   */
   create(entry: Omit<ConnectionEntry, "id" | "createdAt" | "updatedAt">): Promise<ConnectionEntry>;
+  /**
+   * Update a connection.
+   *
+   * When `updates.config` is present, the effective secret fields are
+   * `updates.secretFields ?? existing.secretFields`; those fields are
+   * re-encrypted before persistence.
+   */
   update(tenantId: string, type: string, key: string, updates: Partial<ConnectionEntry>): Promise<ConnectionEntry | null>;
   delete(tenantId: string, type: string, key: string): Promise<boolean>;
 }

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";