@axiom-lattice/protocols 3.0.4 → 4.0.1

package/src/__tests__/agent-web-app-types.test.ts

@@ -0,0 +1,323 @@
+import type {
+  AgentWebApp,
+  AgentWebAppBootstrap,
+  AgentWebAppError,
+  AgentWebAppErrorCode,
+  AgentWebAppFeatures,
+  AgentWebAppRuntimeThread,
+  AgentWebAppScope,
+  AgentWebAppStore,
+  AgentWebAppStorePatch,
+  AgentWebAppStreamEvent,
+  AgentWebAppThreadMetadata,
+  CreateAgentWebAppInput,
+  UpdateAgentWebAppInput,
+} from "../index";
+
+type Equal<Left, Right> =
+  (<Value>() => Value extends Left ? 1 : 2) extends
+  (<Value>() => Value extends Right ? 1 : 2)
+    ? (<Value>() => Value extends Right ? 1 : 2) extends
+      (<Value>() => Value extends Left ? 1 : 2)
+      ? true
+      : false
+    : false;
+
+type Expect<Value extends true> = Value;
+
+type CreateAgentWebAppInputKeys =
+  | "assistantId"
+  | "name"
+  | "description"
+  | "integration"
+  | "scope"
+  | "features"
+  | "appearance";
+type UpdateAgentWebAppInputKeys =
+  | "name"
+  | "description"
+  | "scope"
+  | "features"
+  | "appearance";
+type AgentWebAppStorePatchKeys = UpdateAgentWebAppInputKeys | "status";
+
+type _CreateInputHasExactKeys = Expect<
+  Equal<keyof CreateAgentWebAppInput, CreateAgentWebAppInputKeys>
+>;
+type _UpdateInputHasExactKeys = Expect<
+  Equal<keyof UpdateAgentWebAppInput, UpdateAgentWebAppInputKeys>
+>;
+type _StorePatchHasExactKeys = Expect<
+  Equal<keyof AgentWebAppStorePatch, AgentWebAppStorePatchKeys>
+>;
+type _UpdateScopeIsPartial = Expect<
+  Equal<UpdateAgentWebAppInput["scope"], Partial<AgentWebAppScope> | undefined>
+>;
+type _UpdateFeaturesArePartial = Expect<
+  Equal<UpdateAgentWebAppInput["features"], Partial<AgentWebAppFeatures> | undefined>
+>;
+type _StoreScopeIsComplete = Expect<
+  Equal<AgentWebAppStorePatch["scope"], AgentWebAppScope | undefined>
+>;
+type _StoreFeaturesAreComplete = Expect<
+  Equal<AgentWebAppStorePatch["features"], AgentWebAppFeatures | undefined>
+>;
+
+type AgentWebAppBootstrapKeys = "webApp" | "projects" | "models" | "thread";
+type AgentWebAppBootstrapWebAppKeys =
+  | "id"
+  | "name"
+  | "description"
+  | "assistant"
+  | "defaultProjectId"
+  | "defaultModelKey"
+  | "features"
+  | "appearance"
+  | "identityAssurance";
+type AgentWebAppBootstrapAssistantKeys = "id" | "name" | "description";
+type AgentWebAppBootstrapProjectKeys = "id" | "name";
+type AgentWebAppBootstrapModelKeys = "key" | "label";
+type AgentWebAppBootstrapFeatureKeys =
+  | "projectSelector"
+  | "modelSelector"
+  | "threadManagement"
+  | "attachments"
+  | "hitl"
+  | "genUI";
+type AgentWebAppBootstrapAppearanceKeys = "title" | "welcomeMessage" | "primaryColor";
+
+type _BootstrapHasExactTopLevelKeys = Expect<
+  Equal<keyof AgentWebAppBootstrap, AgentWebAppBootstrapKeys>
+>;
+type _BootstrapWebAppHasExactKeys = Expect<
+  Equal<keyof AgentWebAppBootstrap["webApp"], AgentWebAppBootstrapWebAppKeys>
+>;
+type _BootstrapAssistantHasExactKeys = Expect<
+  Equal<
+    keyof AgentWebAppBootstrap["webApp"]["assistant"],
+    AgentWebAppBootstrapAssistantKeys
+  >
+>;
+type _BootstrapProjectHasExactKeys = Expect<
+  Equal<keyof AgentWebAppBootstrap["projects"][number], AgentWebAppBootstrapProjectKeys>
+>;
+type _BootstrapModelHasExactKeys = Expect<
+  Equal<keyof AgentWebAppBootstrap["models"][number], AgentWebAppBootstrapModelKeys>
+>;
+type _BootstrapThreadIsNarrowAndOptional = Expect<
+  Equal<AgentWebAppBootstrap["thread"], AgentWebAppRuntimeThread | undefined>
+>;
+type _BootstrapFeaturesHaveExactKeys = Expect<
+  Equal<
+    keyof AgentWebAppBootstrap["webApp"]["features"],
+    AgentWebAppBootstrapFeatureKeys
+  >
+>;
+type _BootstrapAppearanceHasExactKeys = Expect<
+  Equal<
+    keyof AgentWebAppBootstrap["webApp"]["appearance"],
+    AgentWebAppBootstrapAppearanceKeys
+  >
+>;
+
+const errorCodes = [
+  "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",
+] as const satisfies readonly AgentWebAppErrorCode[];
+
+type _ErrorCodesAreExact = Expect<
+  Equal<AgentWebAppErrorCode, (typeof errorCodes)[number]>
+>;
+
+const streamEventTypes = [
+  "message.delta",
+  "message.completed",
+  "tool.started",
+  "tool.completed",
+  "interrupt.created",
+  "genui.render",
+  "error",
+  "stream.completed",
+] as const satisfies readonly AgentWebAppStreamEvent["type"][];
+
+type _StreamEventTypesAreExact = Expect<
+  Equal<AgentWebAppStreamEvent["type"], (typeof streamEventTypes)[number]>
+>;
+
+const features = {
+  projectSelector: true,
+  modelSelector: true,
+  threadManagement: true,
+  attachments: true,
+  hitl: true,
+  genUI: true,
+} satisfies CreateAgentWebAppInput["features"];
+
+const createInput = {
+  assistantId: "assistant-1",
+  name: "Customer portal",
+  description: "Customer-facing support agent",
+  integration: { type: "react_sdk" },
+  scope: {
+    defaultProjectId: "project-1",
+    allowedProjectIds: ["project-1", "project-2"],
+    defaultModelKey: "model-1",
+    allowedModelKeys: ["model-1", "model-2"],
+  },
+  features,
+  appearance: { title: "Support", primaryColor: "#123456" },
+} satisfies CreateAgentWebAppInput;
+
+const webApp = {
+  id: "web-app-1",
+  tenantId: "tenant-1",
+  ...createInput,
+  status: "draft",
+  createdAt: new Date("2026-08-24T00:00:00.000Z"),
+  updatedAt: new Date("2026-08-24T00:00:00.000Z"),
+} satisfies AgentWebApp;
+
+const updateInput = {
+  name: "Updated portal",
+  scope: { defaultProjectId: "project-2" },
+  features: { modelSelector: false },
+} satisfies UpdateAgentWebAppInput;
+
+const storePatch = {
+  scope: createInput.scope,
+  features,
+} satisfies AgentWebAppStorePatch;
+
+// @ts-expect-error Persistence patches replace scope and must be complete.
+const incompleteStoreScope: AgentWebAppStorePatch = { scope: { defaultProjectId: "project-2" } };
+
+const threadMetadata = {
+  source: "web_app",
+  webAppId: webApp.id,
+  userId: "external-user-1",
+  projectId: "project-1",
+  label: "Support request",
+} satisfies AgentWebAppThreadMetadata;
+
+const bootstrap = {
+  webApp: {
+    id: webApp.id,
+    name: webApp.name,
+    description: webApp.description,
+    assistant: {
+      id: webApp.assistantId,
+      name: "Support agent",
+      description: "Answers support questions",
+    },
+    defaultProjectId: "project-1",
+    defaultModelKey: "model-1",
+    features,
+    appearance: webApp.appearance,
+    identityAssurance: "unverified",
+  },
+  projects: [
+    { id: "project-1", name: "General" },
+    { id: "project-2", name: "Enterprise" },
+  ],
+  models: [
+    { key: "model-1", label: "Fast" },
+    { key: "model-2", label: "Accurate" },
+  ],
+} satisfies AgentWebAppBootstrap;
+
+const error = {
+  code: "STREAM_FAILED",
+  message: "The stream failed",
+  retryable: true,
+} satisfies AgentWebAppError;
+
+const events = [
+  { type: "message.delta", text: "Hello" },
+  { type: "message.completed", messageId: "message-1" },
+  { type: "tool.started", id: "tool-1", name: "search" },
+  { type: "tool.completed", id: "tool-1" },
+  {
+    type: "interrupt.created",
+    interrupt: { id: "interrupt-1", type: "approval", prompt: "Continue?" },
+  },
+  { type: "genui.render", block: { type: "widget", widget: { kind: "callout", text: "Notice" } } },
+  { type: "error", error },
+  { type: "stream.completed" },
+] satisfies AgentWebAppStreamEvent[];
+
+const store = {
+  async list(_tenantId: string, _assistantId?: string) {
+    return [];
+  },
+  async getById(_tenantId: string, _webAppId: string) {
+    return null;
+  },
+  async findById(_webAppId: string) {
+    return null;
+  },
+  async create(tenantId: string, input: CreateAgentWebAppInput) {
+    return { ...webApp, ...input, tenantId };
+  },
+  async update(
+    _tenantId: string,
+    _webAppId: string,
+    _patch: AgentWebAppStorePatch,
+    _options?: { expectedUpdatedAt?: Date },
+  ) {
+    return null;
+  },
+  async delete(_tenantId: string, _webAppId: string) {
+    return false;
+  },
+} satisfies AgentWebAppStore;
+
+describe("Agent Web App protocol types", () => {
+  it("keeps stable public error code discriminants", () => {
+    expect(errorCodes).toEqual([
+      "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",
+    ]);
+    expect(error.code).toBe("STREAM_FAILED");
+  });
+
+  it("keeps stable public stream event discriminants", () => {
+    expect(streamEventTypes).toEqual([
+      "message.delta",
+      "message.completed",
+      "tool.started",
+      "tool.completed",
+      "interrupt.created",
+      "genui.render",
+      "error",
+      "stream.completed",
+    ]);
+    expect(events.map((event) => event.type)).toEqual(streamEventTypes);
+  });
+});
+
+void updateInput;
+void threadMetadata;
+void bootstrap;
+void store;

package/src/index.ts

@@ -39,12 +39,15 @@ export * from "./MenuProtocol";
 export * from "./EvalStoreProtocol";
 export * from "./TaskStoreProtocol";
 export * from "./TaskWorkItemProtocol";
+export * from "./TaskBeliefProtocol";
 
 export * from "./LocalA2ATemplateConfig";
 export * from "./ChannelAdapterProtocol";
 export * from "./A2AProtocol";
 export * from "./A2AApiKeyStoreProtocol";
 export * from "./ConversationStoreProtocol";
+export * from "./AgentWebAppStoreProtocol";
+export * from "./AgentWebAppRuntimeProtocol";
 
 // Workflow DSL (concise, public API)
 export * from "./WorkflowDSL";