@axiom-lattice/protocols 3.0.4 → 4.0.1

package/src/A2AApiKeyStoreProtocol.ts

@@ -1,7 +1,8 @@
 /**
  * A2AApiKeyStoreProtocol
  *
- * Persistence interface for A2A API keys with tenant/project/workspace scoping.
+ * Persistence interface for A2A API keys scoped by tenant + required project,
+ * with an optional assistantIds whitelist.
  */
 
 import type { A2AApiKeyEntry } from "./A2AProtocol";
@@ -10,8 +11,10 @@ export interface A2AApiKeyRecord {
   id: string;
   key: string;
   tenantId: string;
-  projectId?: string;
-  workspaceId?: string;
+  /** Required project scope — must exist in the tenant */
+  projectId: string;
+  /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
+  assistantIds?: string[];
   label?: string;
   enabled: boolean;
   createdAt: Date;
@@ -20,8 +23,10 @@ export interface A2AApiKeyRecord {
 
 export interface CreateA2AApiKeyInput {
   tenantId: string;
-  projectId?: string;
-  workspaceId?: string;
+  /** Required project scope — must exist in the tenant */
+  projectId: string;
+  /** Assistant whitelist; empty/undefined = all exposed agents in the tenant */
+  assistantIds?: string[];
   label?: string;
 }
 
@@ -29,6 +34,9 @@ export interface A2AApiKeyStore {
   /** Look up a key record by its bearer token value (for auth). */
   findByKey(key: string): Promise<A2AApiKeyRecord | null>;
 
+  /** Look up a key record by its management identifier. */
+  findById(id: string): Promise<A2AApiKeyRecord | null>;
+
   /** List all keys, optionally filtered by tenant. */
   list(params: { tenantId?: string; limit?: number; offset?: number }): Promise<A2AApiKeyRecord[]>;
 

package/src/A2AProtocol.ts

@@ -1,190 +1,50 @@
 /**
- * A2AProtocol - Google Agent-to-Agent Protocol type definitions
- *
- * Based on the A2A open protocol spec for AI agent interoperability.
- * @see https://github.com/google/A2A
+ * A2AProtocol - re-exports standard A2A 0.3 types from @a2a-js/sdk
+ * plus Axiom-specific auth/exposure types.
  */
+export type {
+  AgentCard,
+  AgentSkill as A2ASkill,
+  Task as A2ATask,
+  Message as A2AMessage,
+  Part as A2APart,
+  TaskState as A2ATaskState,
+} from "@a2a-js/sdk";
 
-// ─── Agent Card ───────────────────────────────────────────────────────────
-
-export interface A2ASkill {
-  id: string;
-  name: string;
-  description: string;
-  tags: string[];
-  examples: string[];
-}
-
-export interface A2ACapabilities {
-  streaming: boolean;
-  pushNotifications: boolean;
-  stateTransitionHistory: boolean;
-}
-
-export interface A2AProvider {
-  organization: string;
-  url?: string;
-}
-
-export interface AgentCard {
-  name: string;
-  description: string;
-  url: string;
-  provider: A2AProvider;
-  version: string;
-  documentationUrl?: string;
-  capabilities: A2ACapabilities;
-  defaultInputModes: string[];
-  defaultOutputModes: string[];
-  skills: A2ASkill[];
-}
-
-// ─── Artifact / Part ──────────────────────────────────────────────────────
-
-export interface A2ATextPart {
-  type: "text";
-  text: string;
-}
-
-export interface A2AFilePart {
-  type: "file";
-  file: {
-    name: string;
-    mimeType: string;
-    bytes?: string;
-    uri?: string;
-  };
-}
-
-export interface A2ADataPart {
-  type: "data";
-  data: Record<string, unknown>;
-}
-
-export type A2APart = A2ATextPart | A2AFilePart | A2ADataPart;
-
-// ─── Message ──────────────────────────────────────────────────────────────
-
-export interface A2AMessage {
-  role: "user" | "agent";
-  parts: A2APart[];
-  messageId?: string;
-  contextId?: string;
-  referenceTaskIds?: string[];
-  metadata?: Record<string, unknown>;
-}
-
-// ─── Task ─────────────────────────────────────────────────────────────────
-
-export type A2ATaskState =
-  | "working"
-  | "input-required"
-  | "completed"
-  | "failed"
-  | "canceled"
-  | "rejected";
-
-export interface A2ATaskStatus {
-  state: A2ATaskState;
-  message?: A2AMessage;
-  timestamp: string;
-}
-
-export interface A2AArtifact {
-  name?: string;
-  description?: string;
-  parts: A2APart[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2ATask {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  status: A2ATaskStatus;
-  artifacts: A2AArtifact[];
-  history?: A2AMessage[];
-  metadata?: Record<string, unknown>;
-}
-
-// ─── Request / Response ───────────────────────────────────────────────────
-
-export interface A2ATaskSendRequest {
-  id?: string;
-  sessionId?: string;
-  message: A2AMessage;
-  pushNotification?: A2APushNotification;
-  historyLength?: number;
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2APushNotification {
-  url: string;
-  token?: string;
-}
-
-export interface A2ATaskUpdatePayload {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  status: A2ATaskStatus;
-  final?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-export interface A2ATaskArtifactUpdatePayload {
-  id: string;
-  sessionId?: string;
-  contextId?: string;
-  artifact: A2AArtifact;
-  final?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-// ─── SSE Events ───────────────────────────────────────────────────────────
-
-export type A2ASSEEvent =
-  | { event: "task"; data: A2ATaskUpdatePayload }
-  | { event: "status-update"; data: A2ATaskUpdatePayload }
-  | { event: "artifact-update"; data: A2ATaskArtifactUpdatePayload }
-  | { event: "error"; data: { code: string; message: string } };
-
-// ─── Config ───────────────────────────────────────────────────────────────
-
-export interface A2AConfig {
-  agentName: string;
-  agentDescription: string;
-  agentUrl: string;
-  organization: string;
-  version?: string;
-  capabilities?: Partial<A2ACapabilities>;
-  defaultInputModes?: string[];
-  defaultOutputModes?: string[];
-  skills?: A2ASkill[];
-  apiKeyMap: Map<string, A2AApiKeyEntry>;
+/**
+ * Per-agent A2A exposure configuration — controls whether an agent is
+ * reachable over A2A and which skills are advertised on its AgentCard.
+ */
+export interface A2AExposure {
+  /** Whether this agent is exposed over the A2A protocol */
+  enabled: boolean;
+  /** Skills advertised on the AgentCard; defaults to a single generic skill when omitted */
+  skills?: Array<{ id: string; name: string; description: string; tags?: string[]; examples?: string[] }>;
+  /** Supported input modes (MIME types); defaults to text modes when omitted */
+  inputModes?: string[];
+  /** Supported output modes (MIME types); defaults to text modes when omitted */
+  outputModes?: string[];
 }
 
+/**
+ * In-memory API key entry used for request authentication.
+ * Empty/undefined assistantIds means all exposed agents in the tenant.
+ */
 export interface A2AApiKeyEntry {
   key: string;
-  tenantId?: string;
-  projectId?: string;
-  workspaceId?: string;
+  tenantId: string;
+  projectId: string;
+  assistantIds?: string[];
 }
 
-export const A2A_DEFAULT_CAPABILITIES: A2ACapabilities = {
-  streaming: true,
-  pushNotifications: false,
-  stateTransitionHistory: false,
-};
-
-export const A2A_DEFAULT_INPUT_MODES = ["text", "text/plain"];
-export const A2A_DEFAULT_OUTPUT_MODES = ["text", "text/plain", "text/markdown"];
-
+/**
+ * Authentication context attached to an incoming A2A request after key validation.
+ */
 export interface A2AAuthContext {
   authenticated: boolean;
   apiKey?: string;
   tenantId?: string;
   projectId?: string;
-  workspaceId?: string;
+  assistantIds?: string[];
   source?: "bearer" | "x-api-key";
 }

package/src/AgentWebAppRuntimeProtocol.ts

@@ -0,0 +1,168 @@
+import type {
+  AgentWebAppAppearance,
+  AgentWebAppFeatures,
+} from "./AgentWebAppStoreProtocol";
+
+/** Server-owned metadata that isolates an external user's Web App thread. */
+export interface AgentWebAppThreadMetadata {
+  source: "web_app";
+  webAppId: string;
+  userId: string;
+  projectId: string;
+  label?: string;
+}
+
+/** Public, redacted projection of a thread owned by an Agent Web App identity. */
+export interface AgentWebAppRuntimeThread {
+  id: string;
+  projectId: string;
+  label?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Reviewed public message projection. Structured internal content is not exposed. */
+export interface AgentWebAppRuntimeMessage {
+  id: string;
+  role: "human" | "ai";
+  content?: string | AgentWebAppGenUIBlock[];
+}
+
+export interface AgentWebAppCalloutWidget {
+  kind: "callout";
+  text: string;
+  title?: string;
+  tone?: "info" | "success" | "warning";
+}
+
+export interface AgentWebAppTableWidget {
+  kind: "table";
+  columns: string[];
+  rows: string[][];
+  caption?: string;
+}
+
+/** V1 declarative GenUI block. It deliberately has no HTML, URL, or executable fields. */
+export interface AgentWebAppGenUIBlock {
+  type: "widget";
+  widget: AgentWebAppCalloutWidget | AgentWebAppTableWidget;
+}
+
+/** Public initialization data available to an external Agent Web App. */
+export interface AgentWebAppBootstrap {
+  webApp: {
+    id: string;
+    name: string;
+    description?: string;
+    assistant: {
+      id: string;
+      name: string;
+      description?: string;
+    };
+    defaultProjectId: string;
+    defaultModelKey?: string;
+    features: AgentWebAppFeatures;
+    appearance: AgentWebAppAppearance;
+    identityAssurance: "unverified";
+  };
+  projects: Array<{
+    id: string;
+    name: string;
+  }>;
+  models: Array<{
+    key: string;
+    label: string;
+  }>;
+  /** Latest owned thread, created implicitly only when thread management is disabled. */
+  thread?: AgentWebAppRuntimeThread;
+}
+
+/** Human-in-the-loop interruption exposed through the Web App runtime. */
+export interface AgentWebAppInterrupt {
+  id: string;
+  type: string;
+  prompt: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Stable machine-readable error codes returned by the Web App runtime.
+ *
+ * `INVALID_REQUEST` covers redacted request-validation failures and
+ * `INTERNAL_ERROR` covers redacted unexpected server failures.
+ */
+export type AgentWebAppErrorCode =
+  | "WEB_APP_NOT_FOUND"
+  | "WEB_APP_DISABLED"
+  | "USER_ID_REQUIRED"
+  | "INVALID_USER_ID"
+  | "PROJECT_NOT_ALLOWED"
+  | "PROJECT_SELECTOR_DISABLED"
+  | "MODEL_NOT_ALLOWED"
+  | "FEATURE_DISABLED"
+  | "THREAD_NOT_FOUND"
+  | "STREAM_CONFLICT"
+  | "STREAM_FAILED"
+  | "INVALID_REQUEST"
+  | "INTERNAL_ERROR";
+
+/** Public error payload returned by the Web App runtime. */
+export interface AgentWebAppError {
+  code: AgentWebAppErrorCode;
+  message: string;
+  retryable: boolean;
+}
+
+/** Stable stream events projected from internal agent execution output. */
+export type AgentWebAppStreamEvent =
+  | { type: "message.delta"; text: string }
+  | { type: "message.completed"; messageId: string }
+  | { type: "tool.started"; id: string; name: string }
+  | { type: "tool.completed"; id: string }
+  | { type: "interrupt.created"; interrupt: AgentWebAppInterrupt }
+  | { type: "genui.render"; block: AgentWebAppGenUIBlock }
+  | { type: "error"; error: AgentWebAppError }
+  | { type: "stream.completed" };
+
+const MAX_WIDGET_TEXT = 2_000;
+const MAX_TABLE_COLUMNS = 12;
+const MAX_TABLE_ROWS = 100;
+
+/** Validate and copy one strict public GenUI block at a trust boundary. */
+export function parseAgentWebAppGenUIBlock(value: unknown): AgentWebAppGenUIBlock | undefined {
+  if (!isExactRecord(value, ["type", "widget"]) || value.type !== "widget" || !isRecord(value.widget)) return undefined;
+  const widget = value.widget;
+  if (widget.kind === "callout") {
+    if (!hasOnlyKeys(widget, ["kind", "text"], ["title", "tone"]) || !boundedText(widget.text)) return undefined;
+    if (widget.title !== undefined && !boundedText(widget.title)) return undefined;
+    if (widget.tone !== undefined && widget.tone !== "info" && widget.tone !== "success" && widget.tone !== "warning") return undefined;
+    return { type: "widget", widget: { kind: "callout", text: widget.text, ...(typeof widget.title === "string" ? { title: widget.title } : {}), ...(widget.tone ? { tone: widget.tone } : {}) } };
+  }
+  if (widget.kind === "table") {
+    if (!hasOnlyKeys(widget, ["kind", "columns", "rows"], ["caption"]) || !Array.isArray(widget.columns) || !Array.isArray(widget.rows)) return undefined;
+    const columns = widget.columns;
+    const rows = widget.rows;
+    if (columns.length === 0 || columns.length > MAX_TABLE_COLUMNS || !columns.every(boundedText)) return undefined;
+    if (rows.length > MAX_TABLE_ROWS || !rows.every((row) => Array.isArray(row) && row.length === columns.length && row.every(boundedText))) return undefined;
+    if (widget.caption !== undefined && !boundedText(widget.caption)) return undefined;
+    return { type: "widget", widget: { kind: "table", columns: [...columns], rows: rows.map((row) => [...row]), ...(typeof widget.caption === "string" ? { caption: widget.caption } : {}) } };
+  }
+  return undefined;
+}
+
+function boundedText(value: unknown): value is string {
+  return typeof value === "string" && value.length <= MAX_WIDGET_TEXT;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isExactRecord(value: unknown, keys: string[]): value is Record<string, unknown> {
+  return isRecord(value) && Object.keys(value).length === keys.length && keys.every((key) => key in value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, required: string[], optional: string[]): boolean {
+  const keys = Object.keys(value);
+  return required.every((key) => key in value) && keys.every((key) => required.includes(key) || optional.includes(key));
+}

package/src/AgentWebAppStoreProtocol.ts

@@ -0,0 +1,104 @@
+/** Lifecycle state of an Agent Web App publication. */
+export type AgentWebAppStatus = "draft" | "active" | "disabled";
+
+/** Project and model boundaries exposed by an Agent Web App. */
+export interface AgentWebAppScope {
+  defaultProjectId: string;
+  allowedProjectIds: string[];
+  defaultModelKey?: string;
+  allowedModelKeys?: string[];
+}
+
+/** Runtime capabilities enabled for an Agent Web App. */
+export interface AgentWebAppFeatures {
+  projectSelector: boolean;
+  modelSelector: boolean;
+  threadManagement: boolean;
+  attachments: boolean;
+  hitl: boolean;
+  genUI: boolean;
+}
+
+/** Optional display customization for an Agent Web App. */
+export interface AgentWebAppAppearance {
+  title?: string;
+  welcomeMessage?: string;
+  primaryColor?: string;
+}
+
+/** Persisted React SDK publication of an assistant. */
+export interface AgentWebApp {
+  id: string;
+  tenantId: string;
+  assistantId: string;
+  name: string;
+  description?: string;
+  status: AgentWebAppStatus;
+  integration: {
+    type: "react_sdk";
+  };
+  scope: AgentWebAppScope;
+  features: AgentWebAppFeatures;
+  appearance: AgentWebAppAppearance;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Client-provided fields used to create an Agent Web App. */
+export interface CreateAgentWebAppInput {
+  assistantId: string;
+  name: string;
+  description?: string;
+  integration: {
+    type: "react_sdk";
+  };
+  scope: AgentWebAppScope;
+  features: AgentWebAppFeatures;
+  appearance: AgentWebAppAppearance;
+}
+
+/** Editable fields accepted when updating an Agent Web App. Nested objects use merge semantics. */
+export interface UpdateAgentWebAppInput {
+  name?: string;
+  description?: string;
+  scope?: Partial<AgentWebAppScope>;
+  features?: Partial<AgentWebAppFeatures>;
+  appearance?: Partial<AgentWebAppAppearance>;
+}
+
+/** Internal persistence patch. Nested objects are complete replacements when provided. */
+export interface AgentWebAppStorePatch {
+  name?: string;
+  description?: string;
+  scope?: AgentWebAppScope;
+  features?: AgentWebAppFeatures;
+  appearance?: AgentWebAppAppearance;
+  status?: AgentWebAppStatus;
+}
+
+/** Optional optimistic concurrency guard for an Agent Web App update. */
+export interface AgentWebAppUpdateOptions {
+  /** Update only when the persisted timestamp exactly matches this snapshot. */
+  expectedUpdatedAt?: Date;
+}
+
+/** Tenant-scoped persistence operations for Agent Web Apps. */
+export interface AgentWebAppStore {
+  list(tenantId: string, assistantId?: string): Promise<AgentWebApp[]>;
+  getById(tenantId: string, webAppId: string): Promise<AgentWebApp | null>;
+  /**
+   * Resolve a globally identifiable publication for an external runtime request.
+   *
+   * The returned record still carries its owning tenant; callers must derive all
+   * tenant scope from that record and must not accept a tenant from the browser.
+   */
+  findById(webAppId: string): Promise<AgentWebApp | null>;
+  create(tenantId: string, input: CreateAgentWebAppInput): Promise<AgentWebApp>;
+  update(
+    tenantId: string,
+    webAppId: string,
+    patch: AgentWebAppStorePatch,
+    options?: AgentWebAppUpdateOptions,
+  ): Promise<AgentWebApp | null>;
+  delete(tenantId: string, webAppId: string): Promise<boolean>;
+}

package/src/SkillStoreProtocol.ts

@@ -250,4 +250,25 @@ export interface SkillStore {
    * @returns The resource content as string, or null if not found
    */
   loadSkillResource?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<string | null>;
+
+  /**
+   * Load a resource without text decoding.
+   * @returns The resource bytes, or null if the resource does not exist
+   */
+  loadSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<Buffer | null>;
+
+  /**
+   * Write a resource file into a skill's resources directory
+   * @param tenantId Tenant identifier
+   * @param id Skill identifier
+   * @param resourcePath Path to the resource relative to resources/ directory
+   * @param content Resource content
+   * @param context Optional runtime context for sandbox resolution
+   */
+  writeSkillResource?(tenantId: string, id: string, resourcePath: string, content: string, context?: SkillStoreContext): Promise<void>;
+
+  /**
+   * Write a resource without text encoding.
+   */
+  writeSkillResourceRaw?(tenantId: string, id: string, resourcePath: string, data: Buffer, context?: SkillStoreContext): Promise<void>;
 }