@axiom-lattice/protocols 4.1.3 → 4.2.0

package/package.json

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

package/src/AgentWebAppRuntimeProtocol.ts

@@ -1,6 +1,7 @@
 import type {
   AgentWebAppAppearance,
   AgentWebAppFeatures,
+  AgentWebAppIdentityAssurance,
 } from "./AgentWebAppStoreProtocol";
 
 /** Server-owned metadata that isolates an external user's Web App thread. */
@@ -63,7 +64,7 @@ export interface AgentWebAppBootstrap {
     defaultModelKey?: string;
     features: AgentWebAppFeatures;
     appearance: AgentWebAppAppearance;
-    identityAssurance: "unverified";
+    identityAssurance: AgentWebAppIdentityAssurance;
   };
   projects: Array<{
     id: string;

package/src/AgentWebAppStoreProtocol.ts

@@ -17,6 +17,8 @@ export interface AgentWebAppFeatures {
   attachments: boolean;
   hitl: boolean;
   genUI: boolean;
+  /** File panel surface. Tolerated missing (treated as false) for records created before Phase 2. */
+  files?: boolean;
 }
 
 /** Optional display customization for an Agent Web App. */
@@ -26,6 +28,31 @@ export interface AgentWebAppAppearance {
   primaryColor?: string;
 }
 
+/** Identity assurance levels reported by the runtime. */
+export type AgentWebAppIdentityAssurance = "unverified" | "verified";
+
+/** How external callers may identify themselves for this web app. */
+export type AgentWebAppIdentityPolicy = "unverified" | "verified" | "both";
+
+/** One trusted issuer entry. `secret` pairs with HS256, `jwksUrl` with RS256. */
+export interface AgentWebAppIssuerConfig {
+  /** Exact `iss` claim match. */
+  iss: string;
+  /** Exact `aud` claim match; conventionally the webAppId. */
+  aud: string;
+  alg: "HS256" | "RS256";
+  /** Shared secret for HS256. */
+  secret?: string;
+  /** JWKS endpoint URL for RS256. */
+  jwksUrl?: string;
+}
+
+/** Identity configuration block for a web app. Absent = V1 unverified behavior. */
+export interface AgentWebAppIdentityConfig {
+  policy: AgentWebAppIdentityPolicy;
+  issuers: AgentWebAppIssuerConfig[];
+}
+
 /** Persisted React SDK publication of an assistant. */
 export interface AgentWebApp {
   id: string;
@@ -40,6 +67,7 @@ export interface AgentWebApp {
   scope: AgentWebAppScope;
   features: AgentWebAppFeatures;
   appearance: AgentWebAppAppearance;
+  identity?: AgentWebAppIdentityConfig;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -55,6 +83,7 @@ export interface CreateAgentWebAppInput {
   scope: AgentWebAppScope;
   features: AgentWebAppFeatures;
   appearance: AgentWebAppAppearance;
+  identity?: AgentWebAppIdentityConfig;
 }
 
 /** Editable fields accepted when updating an Agent Web App. Nested objects use merge semantics. */
@@ -64,6 +93,7 @@ export interface UpdateAgentWebAppInput {
   scope?: Partial<AgentWebAppScope>;
   features?: Partial<AgentWebAppFeatures>;
   appearance?: Partial<AgentWebAppAppearance>;
+  identity?: AgentWebAppIdentityConfig;
 }
 
 /** Internal persistence patch. Nested objects are complete replacements when provided. */
@@ -73,6 +103,7 @@ export interface AgentWebAppStorePatch {
   scope?: AgentWebAppScope;
   features?: AgentWebAppFeatures;
   appearance?: AgentWebAppAppearance;
+  identity?: AgentWebAppIdentityConfig;
   status?: AgentWebAppStatus;
 }
 

package/src/AgentWebAppStreamProjection.ts

@@ -0,0 +1,104 @@
+import { MessageChunkTypes, type MessageChunk } from "./MessageProtocol";
+import {
+  parseAgentWebAppGenUIBlock,
+  type AgentWebAppInterrupt,
+  type AgentWebAppStreamEvent,
+} from "./AgentWebAppRuntimeProtocol";
+
+/** Per-consumer projection metadata; it does not control Agent execution. */
+export interface AgentWebAppStreamProjectionContext {
+  readonly startedToolIds: Set<string>;
+  readonly allowInterrupts: boolean;
+  readonly allowGenUI: boolean;
+}
+
+/** Create projection metadata shared by all chunks in one public stream. */
+export function createAgentWebAppStreamProjectionContext(options: { allowInterrupts?: boolean; allowGenUI?: boolean } = {}): AgentWebAppStreamProjectionContext {
+  return { startedToolIds: new Set<string>(), allowInterrupts: options.allowInterrupts ?? true, allowGenUI: options.allowGenUI ?? false };
+}
+
+/** Purely project one internal Agent chunk onto zero or more stable public events. */
+export function projectAgentWebAppChunk(
+  chunk: MessageChunk,
+  context?: AgentWebAppStreamProjectionContext,
+): AgentWebAppStreamEvent[] {
+  if (chunk.type === MessageChunkTypes.AI) {
+    const events: AgentWebAppStreamEvent[] = [];
+    const startedToolIds = context?.startedToolIds ?? new Set<string>();
+    if (typeof chunk.data.content === "string" && chunk.data.content) events.push({ type: "message.delta", text: chunk.data.content });
+    if (context?.allowGenUI && Array.isArray(chunk.data.content)) {
+      for (const value of chunk.data.content) {
+        const block = parseAgentWebAppGenUIBlock(value);
+        if (block) events.push({ type: "genui.render", block });
+      }
+    }
+    for (const call of chunk.data.tool_call_chunks ?? []) {
+      if (call.id && call.name && !startedToolIds.has(call.id)) {
+        startedToolIds.add(call.id);
+        events.push({ type: "tool.started", id: call.id, name: call.name });
+      }
+    }
+    for (const call of chunk.data.tool_calls ?? []) {
+      if (!startedToolIds.has(call.id)) {
+        startedToolIds.add(call.id);
+        events.push({ type: "tool.started", id: call.id, name: call.name });
+      }
+    }
+    return events;
+  }
+  if (chunk.type === MessageChunkTypes.TOOL && chunk.data.tool_call_id) {
+    return [{ type: "tool.completed", id: chunk.data.tool_call_id }];
+  }
+  if (chunk.type === MessageChunkTypes.INTERRUPT) {
+    if (context && !context.allowInterrupts) return [{ type: "stream.completed" }];
+    const interrupt = publicInterrupt(chunk);
+    return interrupt
+      ? [{ type: "interrupt.created", interrupt }, { type: "stream.completed" }]
+      : [{ type: "stream.completed" }];
+  }
+  if (chunk.type === MessageChunkTypes.MESSAGE_COMPLETED) {
+    return [
+      { type: "message.completed", messageId: chunk.data.id },
+      { type: "stream.completed" },
+    ];
+  }
+  if (chunk.type === MessageChunkTypes.MESSAGE_FAILED) {
+    return [
+      { type: "error", error: { code: "STREAM_FAILED", message: "Stream failed", retryable: true } },
+      { type: "stream.completed" },
+    ];
+  }
+  return [];
+}
+
+function publicInterrupt(chunk: MessageChunk): AgentWebAppInterrupt | undefined {
+  const value = parseInterruptContent(chunk.data.content);
+  if (!value) return undefined;
+  const topLevelId = (chunk as unknown as { id?: unknown }).id;
+  const id = typeof topLevelId === "string" ? topLevelId : chunk.data.id;
+  if (!id) return undefined;
+  return {
+    id,
+    type: typeof value.type === "string" ? value.type : "input",
+    prompt: typeof value.prompt === "string"
+      ? value.prompt
+      : typeof value.message === "string" ? value.message : "Input required",
+    ...(isRecord(value.data) ? { data: value.data } : {}),
+  };
+}
+
+function parseInterruptContent(content: unknown): Record<string, unknown> | undefined {
+  if (!content) return {};
+  if (isRecord(content)) return content;
+  if (typeof content !== "string") return undefined;
+  try {
+    const parsed: unknown = JSON.parse(content);
+    return isRecord(parsed) ? parsed : { prompt: content };
+  } catch {
+    return { prompt: content };
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/McpLatticeProtocol.ts

@@ -29,8 +29,14 @@ export interface McpServerConfig {
   args?: string[];
   /** URL for HTTP/SSE transport */
   url?: string;
-  /** Environment variables */
+  /** Environment variables (stdio transport; credentials passed to the server process) */
   env?: Record<string, string>;
+  /**
+   * Custom HTTP headers sent with every request (streamable_http / sse only).
+   * Commonly used for authentication, e.g. `{ Authorization: "Bearer <token>" }`.
+   * Ignored for stdio transport. Values are encrypted at rest by config stores.
+   */
+  headers?: Record<string, string>;
   /** Connection timeout in milliseconds */
   timeout?: number;
   /** Retry attempts on connection failure */

package/src/McpServerConfigStoreProtocol.ts

@@ -38,7 +38,8 @@ export interface McpServerConfigEntry {
   selectedTools: string[];
 
   /**
-   * Whether the env field is encrypted in storage
+   * Whether secret values (env vars and headers) are encrypted at rest.
+   * Field name kept for backward compatibility; it covers config.headers too.
    */
   isEnvEncrypted: boolean;
 

package/src/ProjectRoomMessageStoreProtocol.ts

@@ -23,4 +23,12 @@ export interface ProjectRoomMessageStore {
 
   /** Finds a room message by identifier within a tenant. */
   findById(tenantId: string, id: string): Promise<ProjectRoomMessage | null>;
+
+  /** Counts messages created strictly after a horizon, optionally excluding one human author. */
+  countAfter(input: {
+    tenantId: string;
+    roomId: string;
+    after: Date;
+    excludeAuthorUserId?: string;
+  }): Promise<number>;
 }

package/src/ProjectRoomReadStateProtocol.ts

@@ -0,0 +1,20 @@
+/** A user's per-room read marker used to compute unread counts. */
+export interface ProjectRoomReadState {
+  tenantId: string;
+  roomId: string;
+  userId: string;
+  /** Read horizon: messages created strictly after this instant are unread. */
+  lastReadAt: Date;
+  updatedAt: Date;
+}
+
+/** Persistence operations for per-user, per-room read markers. */
+export interface ProjectRoomReadStateStore {
+  /** Returns the user's read marker for a room, or null when never reported. */
+  get(tenantId: string, roomId: string, userId: string): Promise<ProjectRoomReadState | null>;
+  /**
+   * Upserts the read marker monotonically: an earlier lastReadAt never moves
+   * the marker backwards. Returns the stored state after the write.
+   */
+  markRead(input: { tenantId: string; roomId: string; userId: string; lastReadAt: Date }): Promise<ProjectRoomReadState>;
+}

package/src/ProjectRoomRealtimeProtocol.ts

@@ -83,25 +83,41 @@ export type ProjectRoomTaskChangedEvent = ProjectRoomEventOf<
   }
 >;
 
+/** A read-marker update broadcast on the acting user's channel. */
+export type ProjectRoomReadChangedEvent = ProjectRoomEventOf<
+  "read.changed",
+  { projectId: string; roomId: string; lastReadAt: string }
+>;
+
+/** A membership mutation that may change a user's room subscription set. */
+export type ProjectRoomMembershipAffectedEvent = ProjectRoomEventOf<
+  "membership.affected",
+  { change: "added" | "removed" | "role_changed"; projectId: string; roomId: string }
+>;
+
 /** All identified business events retained by the realtime broker. */
 export type ProjectRoomBusinessEvent =
   | ProjectRoomMessageCreatedEvent
   | ProjectRoomRosterChangedEvent
   | ProjectRoomMembershipChangedEvent
-  | ProjectRoomTaskChangedEvent;
+  | ProjectRoomTaskChangedEvent
+  | ProjectRoomReadChangedEvent
+  | ProjectRoomMembershipAffectedEvent;
 
 /** A business event before the broker assigns its process-local ID. */
 export type ProjectRoomBusinessEventDraft =
   | Omit<ProjectRoomMessageCreatedEvent, "id">
   | Omit<ProjectRoomRosterChangedEvent, "id">
   | Omit<ProjectRoomMembershipChangedEvent, "id">
-  | Omit<ProjectRoomTaskChangedEvent, "id">;
+  | Omit<ProjectRoomTaskChangedEvent, "id">
+  | Omit<ProjectRoomReadChangedEvent, "id">
+  | Omit<ProjectRoomMembershipAffectedEvent, "id">;
 
 /** A connection control event; control events are never replayed. */
 export type ProjectRoomControlEvent =
   | { type: "ready"; data: { epoch: string; headEventId: string | null } }
   | { type: "resync"; data: { reason: "SERVER_RESTART" | "CURSOR_EXPIRED" | "SLOW_CONSUMER" } }
-  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" } };
+  | { type: "access.revoked"; data: { reason: "PROJECT_ACCESS_REVOKED" | "TOKEN_EXPIRED" | "CONNECTION_SUPERSEDED" } };
 
 /** The authenticated identity used by Project Room realtime access checks. */
 export interface ProjectRoomRealtimeActor {
@@ -194,6 +210,15 @@ export function isProjectRoomEventId(value: unknown): value is string {
   return parseProjectRoomEventId(value) !== undefined;
 }
 
+/** projectId sentinel marking a per-user event channel inside the room broker. */
+export const PROJECT_ROOM_USER_CHANNEL_PROJECT = "__user_channel__";
+
+/** Builds the per-user broker scope used for membership and read broadcasts. */
+export function projectRoomUserEventScope(tenantId: string, userId: string): ProjectRoomEventScope {
+  if (!tenantId || !userId) throw new TypeError("Project Room user scope requires non-empty identifiers");
+  return { tenantId, roomId: `__user__:${userId}`, projectId: PROJECT_ROOM_USER_CHANNEL_PROJECT };
+}
+
 function isoDate(value: unknown): string | undefined {
   if (typeof value !== "object" || value === null) return undefined;
   try {

package/src/__tests__/ProjectRoomReadStateProtocol.test.ts

@@ -0,0 +1,16 @@
+import { projectRoomUserEventScope, parseProjectRoomEventId } from "../ProjectRoomRealtimeProtocol";
+
+describe("projectRoomUserEventScope", () => {
+  it("builds a stable per-user scope that cannot collide with room scopes", () => {
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual({
+      tenantId: "t1", roomId: "__user__:u1", projectId: "__user_channel__",
+    });
+    expect(projectRoomUserEventScope("t1", "u1")).toEqual(projectRoomUserEventScope("t1", "u1"));
+    expect(projectRoomUserEventScope("t1", "u2")).not.toEqual(projectRoomUserEventScope("t1", "u1"));
+  });
+  it("user scope ids are valid broker event id candidates", () => {
+    const scope = projectRoomUserEventScope("t1", "u1");
+    expect(typeof scope.roomId).toBe("string");
+    expect(parseProjectRoomEventId(`${"0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d"}:1`)?.sequence).toBe(1);
+  });
+});

package/src/__tests__/ProjectRoomStores.test.ts

@@ -264,6 +264,10 @@ class FakeProjectRoomMessageStore implements ProjectRoomMessageStore {
     const [tenantId, id] = args;
     return tenantId === "tenant-1" && id === "message-1" ? message : null;
   }
+
+  async countAfter(input: Parameters<ProjectRoomMessageStore["countAfter"]>[0]): Promise<number> {
+    return input.tenantId === "tenant-1" && input.roomId === "room-1" ? 1 : 0;
+  }
 }
 
 describe("ProjectRoomStore", () => {

package/src/index.ts

@@ -48,6 +48,7 @@ export * from "./A2AApiKeyStoreProtocol";
 export * from "./ConversationStoreProtocol";
 export * from "./AgentWebAppStoreProtocol";
 export * from "./AgentWebAppRuntimeProtocol";
+export * from "./AgentWebAppStreamProjection";
 export * from "./CapabilityBundleStoreProtocol";
 export * from "./CapabilityRuntimeProtocol";
 export * from "./ProjectRoomProtocol";
@@ -55,6 +56,7 @@ export * from "./ProjectRoomStoreProtocol";
 export * from "./ProjectMembershipStoreProtocol";
 export * from "./ProjectBotMembershipStoreProtocol";
 export * from "./ProjectRoomMessageStoreProtocol";
+export * from "./ProjectRoomReadStateProtocol";
 export * from "./ExactDataSnapshot";
 export * from "./ProjectRoomRealtimeProtocol";