@axiom-lattice/pg-stores 3.0.0 → 3.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@langchain/core": "1.1.30",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "4.0.0",
-    "@axiom-lattice/protocols": "4.0.0"
+    "@axiom-lattice/core": "4.1.0",
+    "@axiom-lattice/protocols": "4.0.1"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/PostgreSQLAgentWebAppStore.migrations.test.ts

@@ -0,0 +1,77 @@
+import { beforeEach, describe, expect, it } from "@jest/globals";
+
+const recordedMigrationNames: string[] = [];
+const clientSql: string[] = [];
+let migrationError: Error | null = null;
+
+jest.mock("pg", () => {
+  const client = {
+    query: async (sql: string, params?: unknown[]) => {
+      clientSql.push(sql);
+      if (migrationError && sql.includes("CREATE TABLE IF NOT EXISTS lattice_agent_web_apps")) {
+        throw migrationError;
+      }
+      if (sql.includes("information_schema.tables")) return { rows: [{ exists: true }] };
+      if (sql.includes("pg_index")) return { rows: [] };
+      if (sql.includes("INSERT INTO lattice_schema_migrations")) {
+        recordedMigrationNames.push(params?.[0] as string);
+      }
+      return { rows: [] };
+    },
+    release: () => undefined,
+  };
+  const pool = {
+    connect: async () => client,
+    query: async () => ({ rows: [] }),
+    end: async () => undefined,
+  };
+  return { Pool: function Pool() { return pool; } };
+});
+
+import { PostgreSQLAgentWebAppStore } from "../stores/PostgreSQLAgentWebAppStore";
+
+describe("PostgreSQLAgentWebAppStore standalone migrations", () => {
+  beforeEach(() => {
+    recordedMigrationNames.length = 0;
+    clientSql.length = 0;
+    migrationError = null;
+  });
+
+  it("registers and applies the agent web apps table migration", async () => {
+    const store = new PostgreSQLAgentWebAppStore({
+      poolConfig: "postgres://unused",
+      autoMigrate: false,
+    });
+
+    await store.initialize();
+
+    expect(recordedMigrationNames).toEqual(["create_agent_web_apps_table"]);
+    expect(clientSql.some((sql) => sql.includes("CREATE TABLE IF NOT EXISTS lattice_agent_web_apps"))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes("status VARCHAR(32) NOT NULL DEFAULT 'draft'"))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes(
+      "CONSTRAINT chk_lattice_agent_web_apps_status CHECK (status IN ('draft', 'active', 'disabled'))",
+    ))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes(
+      "created_at TIMESTAMPTZ NOT NULL DEFAULT date_trunc('milliseconds', NOW())",
+    ))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes(
+      "updated_at TIMESTAMPTZ NOT NULL DEFAULT date_trunc('milliseconds', NOW())",
+    ))).toBe(true);
+    expect(clientSql.some((sql) => sql.includes("idx_lattice_agent_web_apps_tenant_assistant"))).toBe(true);
+
+    await store.dispose();
+  });
+
+  it("surfaces an eager auto-migration rejection through initialize without retrying", async () => {
+    migrationError = new Error("migration failed");
+    const store = new PostgreSQLAgentWebAppStore({ poolConfig: "postgres://unused" });
+
+    await expect(store.initialize()).rejects.toThrow("migration failed");
+    await expect(store.list("tenant-1")).rejects.toThrow("migration failed");
+
+    expect(clientSql.filter((sql) =>
+      sql.includes("CREATE TABLE IF NOT EXISTS lattice_agent_web_apps")
+    )).toHaveLength(1);
+    await store.dispose();
+  });
+});

package/src/__tests__/PostgreSQLAgentWebAppStore.test.ts

@@ -0,0 +1,290 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import type {
+  AgentWebAppStorePatch,
+  CreateAgentWebAppInput,
+  UpdateAgentWebAppInput,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+import { PostgreSQLAgentWebAppStore } from "../stores/PostgreSQLAgentWebAppStore";
+
+const mockQuery = jest.fn();
+const now = new Date("2026-08-24T12:00:00.000Z");
+
+const input: CreateAgentWebAppInput = {
+  assistantId: "assistant-1",
+  name: "Support",
+  description: "Customer support",
+  integration: { type: "react_sdk" },
+  scope: {
+    defaultProjectId: "project-1",
+    allowedProjectIds: ["project-1", "project-2"],
+    defaultModelKey: "model-1",
+    allowedModelKeys: ["model-1"],
+  },
+  features: {
+    projectSelector: true,
+    modelSelector: true,
+    threadManagement: true,
+    attachments: false,
+    hitl: true,
+    genUI: false,
+  },
+  appearance: { title: "Help", primaryColor: "#123456" },
+};
+
+const row = {
+  id: "webapp_123",
+  tenant_id: "tenant-1",
+  assistant_id: "assistant-1",
+  name: "Support",
+  description: "Customer support",
+  status: "draft",
+  integration: input.integration,
+  scope: input.scope,
+  features: input.features,
+  appearance: input.appearance,
+  created_at: now,
+  updated_at: now,
+};
+
+describe("PostgreSQLAgentWebAppStore", () => {
+  const pool = { query: mockQuery } as unknown as Pool;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("creates a draft web app with a generated webapp id and JSONB values", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    const result = await store.create("tenant-1", input);
+
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("INSERT INTO lattice_agent_web_apps");
+    expect(sql).toContain("status");
+    expect(params[0]).toEqual(expect.stringMatching(/^webapp_[0-9a-f]{32}$/));
+    expect(params).toEqual([
+      expect.stringMatching(/^webapp_[0-9a-f]{32}$/),
+      "tenant-1",
+      "assistant-1",
+      "Support",
+      "Customer support",
+      "draft",
+      JSON.stringify(input.integration),
+      JSON.stringify(input.scope),
+      JSON.stringify(input.features),
+      JSON.stringify(input.appearance),
+    ]);
+    expect(result).toEqual({
+      id: "webapp_123",
+      tenantId: "tenant-1",
+      assistantId: "assistant-1",
+      name: "Support",
+      description: "Customer support",
+      status: "draft",
+      integration: input.integration,
+      scope: input.scope,
+      features: input.features,
+      appearance: input.appearance,
+      createdAt: now,
+      updatedAt: now,
+    });
+  });
+
+  it("lists tenant web apps in deterministic newest-first order", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await store.list("tenant-1");
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/WHERE tenant_id = \$1\s+ORDER BY created_at DESC, id DESC/),
+      ["tenant-1"],
+    );
+  });
+
+  it("optionally filters list by assistant", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await store.list("tenant-1", "assistant-1");
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/WHERE tenant_id = \$1 AND assistant_id = \$2/),
+      ["tenant-1", "assistant-1"],
+    );
+  });
+
+  it("gets by tenant and id and returns null when absent", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await expect(store.getById("tenant-1", "webapp_missing")).resolves.toBeNull();
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/WHERE tenant_id = \$1 AND id = \$2/),
+      ["tenant-1", "webapp_missing"],
+    );
+  });
+
+  it("finds a globally identifiable publication by primary key", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await expect(store.findById("webapp_123")).resolves.toMatchObject({
+      id: "webapp_123",
+      tenantId: "tenant-1",
+    });
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/WHERE id = \$1/),
+      ["webapp_123"],
+    );
+  });
+
+  it("updates only known mutable fields and scopes by tenant and id", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ ...row, name: "Renamed", description: null }] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+    const patch = {
+      name: "Renamed",
+      description: undefined,
+      assistantId: "assistant-evil",
+    } as unknown as UpdateAgentWebAppInput;
+
+    const result = await store.update("tenant-1", "webapp_123", patch);
+
+    const [sql, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(sql).toContain("name = $1");
+    expect(sql).toContain("description = $2");
+    expect(sql).toContain("updated_at = GREATEST(");
+    expect(sql).toContain("WHERE tenant_id = $3 AND id = $4");
+    expect(sql).not.toContain("assistant_id =");
+    expect(params).toEqual(["Renamed", null, "tenant-1", "webapp_123"]);
+    expect(result?.description).toBeUndefined();
+  });
+
+  it("updates a defined status and returns the persisted row", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ ...row, status: "active" }] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+    const patch: AgentWebAppStorePatch = { status: "active" };
+
+    const result = await store.update("tenant-1", "webapp_123", patch);
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /SET status = \$1, updated_at = GREATEST\(\s*date_trunc\('milliseconds', clock_timestamp\(\)\),\s*updated_at \+ interval '1 millisecond'\s*\)\s+WHERE tenant_id = \$2 AND id = \$3/,
+      ),
+      ["active", "tenant-1", "webapp_123"],
+    );
+    expect(result?.status).toBe("active");
+  });
+
+  it("monotonically advances a same-millisecond version so a stale writer conflicts", async () => {
+    const advanced = new Date(now.getTime() + 1);
+    mockQuery
+      .mockResolvedValueOnce({ rowCount: 1, rows: [{ ...row, status: "active", updated_at: advanced }] })
+      .mockResolvedValueOnce({ rowCount: 0, rows: [] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await expect(store.update(
+      "tenant-1",
+      "webapp_123",
+      { status: "active" },
+      { expectedUpdatedAt: now },
+    )).resolves.toMatchObject({ status: "active", updatedAt: advanced });
+    await expect(store.update(
+      "tenant-1",
+      "webapp_123",
+      { status: "disabled" },
+      { expectedUpdatedAt: now },
+    )).resolves.toBeNull();
+
+    const monotonicCasSql = expect.stringMatching(
+      /SET status = \$1, updated_at = GREATEST\(\s*date_trunc\('milliseconds', clock_timestamp\(\)\),\s*updated_at \+ interval '1 millisecond'\s*\)\s+WHERE tenant_id = \$2 AND id = \$3 AND date_trunc\('milliseconds', updated_at\) = \$4/,
+    );
+    expect(mockQuery).toHaveBeenNthCalledWith(
+      1,
+      monotonicCasSql,
+      ["active", "tenant-1", "webapp_123", now],
+    );
+    expect(mockQuery).toHaveBeenNthCalledWith(
+      2,
+      monotonicCasSql,
+      ["disabled", "tenant-1", "webapp_123", now],
+    );
+  });
+
+  it("serializes JSONB update fields", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+    const patch: UpdateAgentWebAppInput = {
+      scope: input.scope,
+      features: input.features,
+      appearance: input.appearance,
+    };
+
+    await store.update("tenant-1", "webapp_123", patch);
+
+    const [, params] = mockQuery.mock.calls[0] as [string, unknown[]];
+    expect(params).toEqual([
+      JSON.stringify(input.scope),
+      JSON.stringify(input.features),
+      JSON.stringify(input.appearance),
+      "tenant-1",
+      "webapp_123",
+    ]);
+  });
+
+  it("ignores undefined non-description fields as a read-only no-op", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [row] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+    const patch: AgentWebAppStorePatch = {
+      name: undefined,
+      scope: undefined,
+      features: undefined,
+      appearance: undefined,
+      status: undefined,
+    };
+
+    const result = await store.update("tenant-1", "webapp_123", patch);
+
+    expect(mockQuery).toHaveBeenCalledTimes(1);
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/^SELECT[\s\S]+WHERE tenant_id = \$1 AND id = \$2$/),
+      ["tenant-1", "webapp_123"],
+    );
+    expect(result?.updatedAt).toBe(now);
+  });
+
+  it("clears description when it is explicitly present as undefined", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ ...row, description: null }] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await store.update("tenant-1", "webapp_123", { description: undefined });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringContaining("SET description = $1, updated_at = GREATEST("),
+      [null, "tenant-1", "webapp_123"],
+    );
+  });
+
+  it("deletes by tenant and id and reports whether a row was removed", async () => {
+    mockQuery.mockResolvedValueOnce({ rowCount: 1, rows: [] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await expect(store.delete("tenant-1", "webapp_123")).resolves.toBe(true);
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.stringMatching(/DELETE FROM lattice_agent_web_apps\s+WHERE tenant_id = \$1 AND id = \$2/),
+      ["tenant-1", "webapp_123"],
+    );
+  });
+
+  it("rejects rows that violate the stored JSON contract", async () => {
+    mockQuery.mockResolvedValueOnce({ rows: [{ ...row, integration: { type: "iframe" } }] });
+    const store = new PostgreSQLAgentWebAppStore({ pool });
+
+    await expect(store.getById("tenant-1", "webapp_123")).rejects.toThrow(
+      "Invalid agent web app row",
+    );
+  });
+});

package/src/createPgStoreConfig.ts

@@ -17,6 +17,7 @@ import { ThreadMessageQueueStore } from "./stores/ThreadMessageQueueStore";
 import { ChannelBindingStore } from "./stores/ChannelBindingStore";
 import { PostgreSQLChannelInstallationStore } from "./stores/PostgreSQLChannelInstallationStore";
 import { PostgreSQLA2AApiKeyStore } from "./stores/PostgreSQLA2AApiKeyStore";
+import { PostgreSQLAgentWebAppStore } from "./stores/PostgreSQLAgentWebAppStore";
 import { PostgreSQLScheduleStorage } from "./stores/PostgreSQLScheduleStorage";
 import { PostgreSQLTaskStore } from "./stores/PostgreSQLTaskStore";
 import { PostgreSQLTaskWorkItemStore } from "./stores/PostgreSQLTaskWorkItemStore";
@@ -71,6 +72,7 @@ import { addFileContentType } from "./migrations/menu_items_add_file_type";
 import { createSharedResourcesTable } from "./migrations/shared_resources_migration";
 import { createCollectionsTable } from "./migrations/collection_migrations";
 import { createTaskWorkItemsMigration, addWorkItemProjectFieldsMigration, addTaskWorkItemEventKeyMigration } from "./migrations/task_work_items_migration";
+import { createAgentWebAppsTable } from "./migrations/agent_web_apps_migration";
 
 export async function createPgStoreConfig(connectionString: string) {
   const pool = new Pool({ connectionString });
@@ -131,6 +133,7 @@ export async function createPgStoreConfig(connectionString: string) {
   mm.register(addProjectKindColumn);          // v165
   mm.register(addA2AKeyAssistantIds);         // v167
   mm.register(addTaskWorkItemEventKeyMigration); // v168
+  mm.register(createAgentWebAppsTable);        // v169
 
   await mm.migrate();
 
@@ -163,6 +166,7 @@ export async function createPgStoreConfig(connectionString: string) {
     task: new PostgreSQLTaskStore(opts),
     taskWorkItem: taskWorkItemStore,
     a2aApiKey: new PostgreSQLA2AApiKeyStore(opts),
+    agentWebApp: new PostgreSQLAgentWebAppStore(opts),
     schedule: new PostgreSQLScheduleStorage(opts),
     menu: new MenuStore(opts),
     sharedResource: new PostgresSharedResourceStore(opts),

package/src/index.ts

@@ -50,12 +50,14 @@ export * from "./migrations/channel_installations_alter_migration";
 export * from "./migrations/channel_bindings_migration";
 export * from "./migrations/shared_resources_migration";
 export * from "./migrations/a2a_api_key_migration";
+export * from "./migrations/agent_web_apps_migration";
 export * from "./migrations/workflow_tracking_migrations";
 export * from "./stores/ChannelBindingStore";
 export * from "./stores/ThreadMessageQueueStore";
 export * from "./stores/ChannelIdentityMappingStore";
 export * from "./stores/PostgreSQLChannelInstallationStore";
 export * from "./stores/PostgreSQLA2AApiKeyStore";
+export * from "./stores/PostgreSQLAgentWebAppStore";
 export * from "./stores/PostgreSQLWorkflowTrackingStore";
 export * from "./stores/PostgreSQLEvalStore";
 export * from "./migrations/eval_migrations";
@@ -181,4 +183,12 @@ export type {
   ShareVisibility,
   CreateShareRequest,
   ShareResult,
+  AgentWebAppStore,
+  AgentWebApp,
+  AgentWebAppStatus,
+  AgentWebAppScope,
+  AgentWebAppFeatures,
+  AgentWebAppAppearance,
+  CreateAgentWebAppInput,
+  UpdateAgentWebAppInput,
 } from "@axiom-lattice/protocols";

package/src/migrations/agent_web_apps_migration.ts

@@ -0,0 +1,37 @@
+import type { PoolClient } from "pg";
+
+import type { Migration } from "./migration";
+
+export const createAgentWebAppsTable: Migration = {
+  version: 169,
+  name: "create_agent_web_apps_table",
+  up: async (client: PoolClient) => {
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS lattice_agent_web_apps (
+        id VARCHAR(255) PRIMARY KEY,
+        tenant_id VARCHAR(255) NOT NULL,
+        assistant_id VARCHAR(255) NOT NULL,
+        name VARCHAR(255) NOT NULL,
+        description TEXT,
+        status VARCHAR(32) NOT NULL DEFAULT 'draft'
+          CONSTRAINT chk_lattice_agent_web_apps_status CHECK (status IN ('draft', 'active', 'disabled')),
+        integration JSONB NOT NULL,
+        scope JSONB NOT NULL,
+        features JSONB NOT NULL,
+        appearance JSONB NOT NULL DEFAULT '{}'::jsonb,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT date_trunc('milliseconds', NOW()),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT date_trunc('milliseconds', NOW())
+      )
+    `);
+    await client.query(`
+      CREATE INDEX IF NOT EXISTS idx_lattice_agent_web_apps_tenant_assistant
+      ON lattice_agent_web_apps(tenant_id, assistant_id)
+    `);
+  },
+  down: async (client: PoolClient) => {
+    await client.query(
+      "DROP INDEX IF EXISTS idx_lattice_agent_web_apps_tenant_assistant",
+    );
+    await client.query("DROP TABLE IF EXISTS lattice_agent_web_apps");
+  },
+};