@axiom-lattice/gateway 2.1.111 → 2.1.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/gateway",
-  "version": "2.1.111",
+  "version": "2.1.113",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -41,11 +41,10 @@
     "redis": "^5.0.1",
     "uuid": "^9.0.1",
     "zod": "3.25.76",
-    "@axiom-lattice/agent-eval": "2.1.92",
-    "@axiom-lattice/core": "2.1.98",
-    "@axiom-lattice/pg-stores": "1.0.89",
-    "@axiom-lattice/protocols": "2.1.50",
-    "@axiom-lattice/queue-redis": "1.0.49"
+    "@axiom-lattice/core": "2.1.100",
+    "@axiom-lattice/pg-stores": "1.0.91",
+    "@axiom-lattice/protocols": "2.1.51",
+    "@axiom-lattice/queue-redis": "1.0.50"
   },
   "devDependencies": {
     "@types/bcrypt": "^6.0.0",

package/src/controllers/__tests__/workflow-tracking.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, jest, beforeEach } from "@jest/globals";
+
+const mockQueryWorkflowRuns = jest.fn();
+const mockGetRunSteps = jest.fn();
+const mockGetAllAssistants = jest.fn();
+const mockGetAgent = jest.fn();
+
+jest.mock("@axiom-lattice/core", () => ({
+  getStoreLattice: (_key: string, type: string) =>
+    type === "workflowTracking"
+      ? { store: { queryWorkflowRuns: mockQueryWorkflowRuns, getRunSteps: mockGetRunSteps } }
+      : { store: { getAllAssistants: mockGetAllAssistants } },
+  agentInstanceManager: { getAgent: mockGetAgent },
+  ThreadStatus: { IDLE: "IDLE", BUSY: "BUSY", INTERRUPTED: "INTERRUPTED" },
+}));
+
+function makeRun(id: string, startedAt: string) {
+  return {
+    id,
+    tenantId: "t1",
+    assistantId: "a1",
+    threadId: `th_${id}`,
+    status: "interrupted" as const,
+    topologyEdges: [],
+    totalEdges: 2,
+    completedEdges: 1,
+    startedAt: new Date(startedAt),
+    createdAt: new Date(startedAt),
+    updatedAt: new Date(startedAt),
+  };
+}
+
+function makeRequest(query: Record<string, string> = {}) {
+  return {
+    headers: { "x-tenant-id": "t1" },
+    query,
+    log: { error: jest.fn(), warn: jest.fn() },
+  } as never;
+}
+
+const mockReply = { status: jest.fn().mockReturnThis(), send: jest.fn() } as never;
+
+describe("getInboxItems", () => {
+  let getInboxItems: (req: never, reply: never) => Promise<{ data?: Record<string, unknown> }>;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    mockGetAllAssistants.mockResolvedValue([{ id: "a1", name: "Assistant One" }] as never);
+    mockGetRunSteps.mockResolvedValue([] as never);
+    mockGetAgent.mockImplementation(() => { throw new Error("no agent"); }); // fallback path
+    const mod = await import("../../controllers/workflow-tracking");
+    getInboxItems = mod.getInboxItems as never;
+  });
+
+  it("legacy mode: no query params returns all items without pagination fields", async () => {
+    mockQueryWorkflowRuns.mockResolvedValue({
+      records: [makeRun("r1", "2026-01-01"), makeRun("r2", "2026-01-02")],
+      total: 2,
+    } as never);
+
+    const res = await getInboxItems(makeRequest(), mockReply);
+
+    expect(mockQueryWorkflowRuns).toHaveBeenCalledWith("t1", { status: "interrupted" });
+    expect(res.data).toBeDefined();
+    const records = res.data!.records as unknown[];
+    expect(records).toHaveLength(2);
+    expect(res.data!.total).toBeUndefined();
+    expect(res.data!.page).toBeUndefined();
+  });
+
+  it("paged mode: passes limit/offset to store and returns total/page/pageSize", async () => {
+    mockQueryWorkflowRuns.mockResolvedValue({
+      records: [makeRun("r3", "2026-01-03")],
+      total: 42,
+    } as never);
+
+    const res = await getInboxItems(makeRequest({ page: "2", pageSize: "20" }), mockReply);
+
+    expect(mockQueryWorkflowRuns).toHaveBeenCalledWith("t1", { status: "interrupted", limit: 20, offset: 20 });
+    expect(res.data!.total).toBe(42);
+    expect(res.data!.page).toBe(2);
+    expect(res.data!.pageSize).toBe(20);
+    expect(res.data!.records).toHaveLength(1);
+  });
+
+  it("paged mode triggers when only pageSize is passed", async () => {
+    mockQueryWorkflowRuns.mockResolvedValue({ records: [], total: 0 } as never);
+
+    const res = await getInboxItems(makeRequest({ pageSize: "10" }), mockReply);
+
+    expect(mockQueryWorkflowRuns).toHaveBeenCalledWith("t1", { status: "interrupted", limit: 10, offset: 0 });
+    expect(res.data!.page).toBe(1);
+    expect(res.data!.pageSize).toBe(10);
+  });
+
+  it("sanitizes invalid page and caps pageSize at 100", async () => {
+    mockQueryWorkflowRuns.mockResolvedValue({ records: [], total: 0 } as never);
+
+    const res = await getInboxItems(makeRequest({ page: "abc", pageSize: "500" }), mockReply);
+
+    expect(mockQueryWorkflowRuns).toHaveBeenCalledWith("t1", { status: "interrupted", limit: 100, offset: 0 });
+    expect(res.data!.page).toBe(1);
+    expect(res.data!.pageSize).toBe(100);
+  });
+
+  it("returns empty records with pagination fields in paged mode", async () => {
+    mockQueryWorkflowRuns.mockResolvedValue({ records: [], total: 0 } as never);
+
+    const res = await getInboxItems(makeRequest({ page: "3", pageSize: "20" }), mockReply);
+
+    expect(res.data).toEqual({ records: [], total: 0, page: 3, pageSize: 20 });
+  });
+});

package/src/controllers/connections.ts

@@ -16,6 +16,13 @@ const testOrDiscoverBody = z.object({
 });
 
 function getTenant(request: FastifyRequest): string {
+  // First try to get from authenticated user context
+  const userTenantId = (request as any).user?.tenantId;
+  if (userTenantId) {
+    return userTenantId;
+  }
+
+  // Fallback to request headers for backward compatibility
   return (request.headers["x-tenant-id"] as string) || "default";
 }
 

package/src/controllers/eval.ts

@@ -25,12 +25,27 @@ export async function createProject(
     const store = getEvalStore();
     const id = uuidv4();
     const data = request.body as any;
+    const serverCfg = (data.targetServerConfig || {}) as Record<string, unknown>;
+    const judgeCfg = (data.judgeModelConfig || {}) as Record<string, unknown>;
+    const modelKey = (judgeCfg.modelKey as string) || "";
+    if (modelKey) {
+      const { modelLatticeManager } = await import("@axiom-lattice/core");
+      if (!modelLatticeManager.hasLattice(modelKey)) {
+        return reply.status(400).send({ success: false, message: `Judge model "${modelKey}" is not registered` });
+      }
+    }
     const project = await store.createProject(tenantId, id, {
       name: data.name,
       description: data.description,
       version: data.version,
-      judgeModelConfig: data.judgeModelConfig ?? {},
-      targetServerConfig: data.targetServerConfig ?? {},
+      judgeModelConfig: {
+        modelKey,
+        displayName: (judgeCfg.displayName as string) || "",
+      },
+      targetServerConfig: {
+        base_url: (serverCfg.base_url as string) || "",
+        api_key: (serverCfg.api_key as string) || "",
+      },
       concurrency: data.concurrency ?? 1,
       reportConfig: data.reportConfig,
     });
@@ -62,7 +77,7 @@ export async function listProjects(
         const first = models[0];
         const judgeModel = first
           ? { modelKey: first.key }
-          : { provider: "openai", model: "gpt-4" };
+          : {};
 
         const host = request.hostname || "localhost";
         const baseUrl = `http://${host}:${process.env.PORT || 4001}`;
@@ -125,7 +140,32 @@ export async function updateProject(
     if (!existing) {
       return reply.status(404).send({ success: false, message: "Project not found" });
     }
-    const updated = await store.updateProject(tenantId, pid, request.body as any);
+    const body = request.body as Record<string, unknown>;
+    const updateData: Record<string, unknown> = { ...body };
+    // Strip in_process from user input — it is server-controlled
+    const serverCfg = (body.targetServerConfig || {}) as Record<string, unknown>;
+    if (body.targetServerConfig !== undefined) {
+      updateData.targetServerConfig = {
+        base_url: (serverCfg.base_url as string) || "",
+        api_key: (serverCfg.api_key as string) || "",
+      };
+    }
+    // Only allow modelKey/displayName — never raw provider/apiKey/baseURL
+    if (body.judgeModelConfig !== undefined) {
+      const judgeCfg = (body.judgeModelConfig || {}) as Record<string, unknown>;
+      const modelKey = (judgeCfg.modelKey as string) || "";
+      if (modelKey) {
+        const { modelLatticeManager } = await import("@axiom-lattice/core");
+        if (!modelLatticeManager.hasLattice(modelKey)) {
+          return reply.status(400).send({ success: false, message: `Judge model "${modelKey}" is not registered` });
+        }
+      }
+      updateData.judgeModelConfig = {
+        modelKey,
+        displayName: (judgeCfg.displayName as string) || "",
+      };
+    }
+    const updated = await store.updateProject(tenantId, pid, updateData);
     return {
       success: true,
       message: "Successfully updated project",

package/src/controllers/export-import.ts

@@ -0,0 +1,166 @@
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { ExportImportService } from '../services/ExportImportService';
+import { ExportableEntityRegistry } from '@axiom-lattice/core';
+
+const service = new ExportImportService();
+
+function getTenantId(request: FastifyRequest): string {
+  return (request as any).user?.tenantId || (request.headers['x-tenant-id'] as string) || 'default';
+}
+
+/** GET /api/tenants/exportable-types */
+export async function getExportableTypes(
+  _request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const types = service.listExportableTypes();
+  return reply.send({ success: true, data: types });
+}
+
+/** POST /api/tenants/:tenantId/export */
+export async function exportConfig(
+  request: FastifyRequest<{ Params: { tenantId: string }; Body: { entityTypes: string[]; entityIds?: Record<string, string[]> } }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+  const { entityTypes, entityIds } = request.body;
+
+  if (!Array.isArray(entityTypes) || entityTypes.length === 0) {
+    return reply.status(400).send({ success: false, message: 'entityTypes must be a non-empty array' });
+  }
+
+  const preview = await service.exportPreview(tenantId, entityTypes);
+
+  if (preview.missingDependencies.length > 0 || preview.cascadeAdditions.length > 0) {
+    return reply.send({
+      success: true,
+      data: {
+        needsConfirmation: true,
+        missingDependencies: preview.missingDependencies,
+        cascadeAdditions: preview.cascadeAdditions,
+      },
+    });
+  }
+
+  const { jobId, bundle } = await service.export(tenantId, entityTypes, entityIds);
+  return reply.send({
+    success: true,
+    data: {
+      jobId,
+      summary: Object.fromEntries(
+        Object.entries(bundle.entities).map(([type, entities]) => [type, entities.length]),
+      ),
+    },
+  });
+}
+
+/** POST /api/tenants/:tenantId/export/confirm */
+export async function exportConfigConfirm(
+  request: FastifyRequest<{ Params: { tenantId: string }; Body: { entityTypes: string[]; entityIds?: Record<string, string[]> } }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+  const { entityTypes, entityIds } = request.body;
+
+  const { jobId, bundle } = await service.export(tenantId, entityTypes, entityIds);
+  return reply.send({
+    success: true,
+    data: {
+      jobId,
+      summary: Object.fromEntries(
+        Object.entries(bundle.entities).map(([type, entities]) => [type, entities.length]),
+      ),
+    },
+  });
+}
+
+/** POST /api/tenants/:tenantId/export/entities */
+export async function previewEntities(
+  request: FastifyRequest<{ Params: { tenantId: string }; Body: { entityTypes: string[] } }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+  const { entityTypes } = request.body;
+
+  try {
+    const registry = ExportableEntityRegistry.getInstance();
+    const result: Record<string, Array<{ id: string; name: string; description?: string }>> = {};
+
+    for (const type of entityTypes) {
+      const def = registry.get(type);
+      const entities = await def.listForExport(tenantId);
+      result[type] = entities.map((e) => ({
+        id: e.data.id as string,
+        name: (e.data.name as string) || (e.data.id as string),
+        description: e.data.description as string | undefined,
+      }));
+    }
+
+    return reply.send({ success: true, data: result });
+  } catch (err) {
+    return reply.status(400).send({ success: false, message: (err as Error).message });
+  }
+}
+
+/** GET /api/tenants/:tenantId/export/:jobId/download */
+export async function downloadExport(
+  request: FastifyRequest<{ Params: { tenantId: string; jobId: string } }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+  const bundle = service.getExportJob(request.params.jobId, tenantId);
+
+  if (!bundle) {
+    return reply.status(404).send({ success: false, message: 'Export job not found or expired' });
+  }
+
+  return reply
+    .header('Content-Type', 'application/json')
+    .header('Content-Disposition', `attachment; filename="tenant-export-${bundle.sourceTenantId}.json"`)
+    .send({ success: true, data: bundle });
+}
+
+/** POST /api/tenants/:tenantId/import/preview */
+export async function importPreview(
+  request: FastifyRequest<{ Params: { tenantId: string }; Body: { bundle: any } }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+  const { bundle } = request.body;
+
+  if (!bundle) {
+    return reply.status(400).send({ success: false, message: 'No bundle provided in request body' });
+  }
+
+  try {
+    const preview = await service.previewImport(tenantId, bundle);
+    return reply.send({ success: true, data: preview });
+  } catch (err) {
+    return reply.status(400).send({
+      success: false,
+      message: `Invalid export file: ${(err as Error).message}`,
+    });
+  }
+}
+
+/** POST /api/tenants/:tenantId/import/apply */
+export async function importApply(
+  request: FastifyRequest<{
+    Params: { tenantId: string };
+    Body: { bundle: any; resolutions: Record<string, any> };
+  }>,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenantId = getTenantId(request) || request.params.tenantId;
+
+  try {
+    const { bundle, resolutions } = request.body;
+    const result = await service.applyImport(tenantId, bundle, resolutions);
+    return reply.send({ success: true, data: result });
+  } catch (err) {
+    return reply.status(400).send({
+      success: false,
+      message: `Import failed: ${(err as Error).message}`,
+    });
+  }
+}

package/src/controllers/run.ts

@@ -73,6 +73,27 @@ export const createRun = async (
     });
 
 
+    // ADR-026: background mode — enqueue only, returns 202.
+    // Chunk delivery is handled by the thread-level resume_stream SSE.
+    if (background) {
+      const messageInput = message_id
+        ? { ...input, id: message_id }
+        : input;
+
+      const result = await agent.addMessage({
+        input: messageInput,
+        command,
+        custom_run_config: mergedConfig,
+      }, mode as QueueMode);
+
+      reply.status(202).send({
+        success: true,
+        messageId: result.messageId,
+        queued: true,
+      });
+      return;
+    }
+
     // Handle streaming requests
     if (streaming) {
       // Setup SSE
@@ -198,12 +219,17 @@ export const resumeStream = async (
         project_id,
       });
 
-      // Get the stream from agent's chunk buffer
-      const stream = agent.chunkStream(message_id, [MessageChunkTypes.THREAD_IDLE]);
+      // ADR-026: Thread-level SSE, lives until client disconnect.
+      // Empty stopTypes means the iterator never stops on its own —
+      // MESSAGE_COMPLETED, THREAD_IDLE etc. pass through as data.
+      // Client disconnect (close event) or client abort (reply.raw.destroyed)
+      // terminate the loop.
+      const stream = agent.chunkStream(message_id, []);
+      let closed = false;
+      request.raw.on('close', () => { closed = true; });
 
-      // Stream the chunks to the client
       for await (const chunk of stream) {
-        // console.log(chunk);
+        if (closed || reply.raw.destroyed) break;
         reply.raw.write(`data: ${JSON.stringify(chunk)}\n\n`);
       }
     } catch (error: any) {

package/src/controllers/workflow-tracking.ts

@@ -1,5 +1,5 @@
 import { FastifyRequest, FastifyReply } from "fastify";
-import { getStoreLattice, agentInstanceManager, ThreadStatus } from "@axiom-lattice/core";
+import { getStoreLattice, agentInstanceManager, ThreadStatus, abortWorkflowRun as signalAbort } from "@axiom-lattice/core";
 import type { WorkflowTrackingStore, WorkflowRun, RunStep } from "@axiom-lattice/protocols";
 import { MessageChunkTypes } from "@axiom-lattice/protocols";
 
@@ -189,10 +189,18 @@ export async function getAllWorkflowRuns(
 }
 
 // GET /api/workflows/inbox
+// Pagination semantics:
+// - No page/pageSize → legacy mode: all interrupted items, data = { records } (unchanged shape).
+// - page and/or pageSize → paged mode: store-level pagination over interrupted runs,
+//   data = { records, total, page, pageSize }. total = number of interrupted RUNS
+//   (each run expands to 0..N inbox items after the agent-state check).
+const INBOX_DEFAULT_PAGE_SIZE = 20;
+const INBOX_MAX_PAGE_SIZE = 100;
+
 export async function getInboxItems(
-  request: FastifyRequest,
+  request: FastifyRequest<{ Querystring: { page?: string; pageSize?: string } }>,
   reply: FastifyReply
-): Promise<ApiResponse<{ records: any[] }>> {
+): Promise<ApiResponse<{ records: any[]; total?: number; page?: number; pageSize?: number }>> {
   const tenantId = getTenantId(request);
 
   try {
@@ -214,10 +222,32 @@ export async function getInboxItems(
       // names unavailable, will fall back to ID
     }
 
-    const runs = await store.getWorkflowRunsByTenantId(tenantId);
-    const pendingRuns = runs.filter(r => r.status === "interrupted");
+    const { page: pageParam, pageSize: pageSizeParam } = request.query;
+    const paged = pageParam !== undefined || pageSizeParam !== undefined;
+    const page = Math.max(1, parseInt(pageParam ?? "", 10) || 1);
+    const pageSize = Math.min(INBOX_MAX_PAGE_SIZE, Math.max(1, parseInt(pageSizeParam ?? "", 10) || INBOX_DEFAULT_PAGE_SIZE));
+
+    let pendingRuns: WorkflowRun[];
+    let total: number | undefined;
+    if (paged) {
+      const result = await store.queryWorkflowRuns(tenantId, {
+        status: "interrupted",
+        limit: pageSize,
+        offset: (page - 1) * pageSize,
+      });
+      pendingRuns = result.records;
+      total = result.total;
+    } else {
+      const result = await store.queryWorkflowRuns(tenantId, { status: "interrupted" });
+      pendingRuns = result.records;
+    }
+
     if (pendingRuns.length === 0) {
-      return { success: true, message: "No pending workflows", data: { records: [] } };
+      return {
+        success: true,
+        message: "No pending workflows",
+        data: paged ? { records: [], total, page, pageSize } : { records: [] },
+      };
     }
 
     // Parallelize agent checks across interrupted workflows
@@ -283,15 +313,13 @@ export async function getInboxItems(
 
     const results = await Promise.all(checkPromises);
     const inboxItems = results.flat();
-
-    inboxItems.sort((a, b) =>
-      new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
-    );
+    // Runs are already sorted by updatedAt DESC, id DESC from queryWorkflowRuns.
+    // flatMap preserves run order within each run.
 
     return {
       success: true,
       message: "Successfully retrieved inbox items",
-      data: { records: inboxItems },
+      data: paged ? { records: inboxItems, total, page, pageSize } : { records: inboxItems },
     };
   } catch (error) {
     request.log.error(error, "Failed to get inbox items");
@@ -597,3 +625,69 @@ export async function replyInboxTask(
     });
   }
 }
+
+/**
+ * Abort a running workflow.
+ *
+ * Stops the main graph execution AND signals all in-progress
+ * sub-agent invokes to cancel.
+ */
+export async function abortWorkflowRun(
+  request: FastifyRequest,
+  reply: FastifyReply
+): Promise<void> {
+  try {
+    const { runId } = request.params as { runId: string };
+    const tenantId = getTenantId(request);
+
+    const store = getTrackingStore();
+    if (!store) {
+      return reply.status(404).send({
+        success: false,
+        message: "No workflow tracking store configured",
+      });
+    }
+
+    const run = await store.getWorkflowRun(runId);
+    if (!run) {
+      return reply.status(404).send({
+        success: false,
+        message: "Workflow run not found",
+      });
+    }
+
+    // Persist abort intent FIRST — prevents restart after server crash
+    await store.updateWorkflowRun(runId, {
+      status: "cancelled",
+      errorMessage: "Aborted by user",
+      completedAt: new Date(),
+    }).catch(() => {});
+
+    // Stop the main graph execution
+    const workspace_id = request.headers["x-workspace-id"] as string;
+    const project_id = request.headers["x-project-id"] as string;
+    const agent = agentInstanceManager.getAgent({
+      assistant_id: run.assistantId,
+      thread_id: run.threadId,
+      tenant_id: tenantId,
+      workspace_id,
+      project_id,
+    });
+    await agent.abort();
+
+    // Signal sub-agents via AbortController registry
+    signalAbort(runId);
+
+    return reply.status(200).send({
+      success: true,
+      message: "Workflow aborted",
+      data: { runId, assistantId: run.assistantId, threadId: run.threadId },
+    });
+  } catch (error) {
+    request.log.error(error, "Failed to abort workflow run");
+    return reply.status(500).send({
+      success: false,
+      message: `Abort failed: ${(error as Error).message}`,
+    });
+  }
+}

package/src/export_registrations/a2a-api-key.registration.ts

@@ -0,0 +1,89 @@
+import type { ExportableEntityDefinition, ExportableEntity, ImportPreviewResult } from '@axiom-lattice/core';
+import { getStoreLattice } from '@axiom-lattice/core';
+import type { A2AApiKeyStore } from '@axiom-lattice/protocols';
+
+function getStore(): A2AApiKeyStore {
+  return getStoreLattice('default', 'a2aApiKey').store as unknown as A2AApiKeyStore;
+}
+
+export const a2aApiKeyRegistration: ExportableEntityDefinition = {
+  entityType: 'a2a_api_key',
+  label: 'A2A API Key(API密钥)',
+  category: 'core',
+  dependsOn: [],
+  cascadeParents: [],
+
+  async listForExport(tenantId: string): Promise<ExportableEntity[]> {
+    const store = getStore();
+    const keys = await store.list({ tenantId, limit: 10000, offset: 0 });
+    return keys.map((k) => ({
+      _exportId: '',
+      data: {
+        id: k.id,
+        tenantId: k.tenantId,
+        projectId: k.projectId,
+        workspaceId: k.workspaceId,
+        label: k.label,
+        enabled: k.enabled,
+      },
+    }));
+  },
+
+  async previewImport(
+    tenantId: string,
+    entities: ExportableEntity[],
+  ): Promise<ImportPreviewResult> {
+    const store = getStore();
+    const existing = await store.list({ tenantId, limit: 10000, offset: 0 });
+    const existingIds = new Set(existing.map((k) => k.id));
+
+    const conflicts: ImportPreviewResult['conflicts'] = [];
+    const insertions: ImportPreviewResult['insertions'] = [];
+
+    for (const entity of entities) {
+      const d = entity.data as Record<string, unknown>;
+      const id = d.id as string;
+
+      if (existingIds.has(id)) {
+        conflicts.push({
+          _exportId: entity._exportId,
+          entityType: 'a2a_api_key',
+          conflictType: 'id_exists',
+          existingId: id,
+          existingName: (d.label as string) || id,
+        });
+      } else {
+        insertions.push({
+          _exportId: entity._exportId,
+          entityType: 'a2a_api_key',
+          name: (d.label as string) || id,
+        });
+      }
+    }
+
+    return { conflicts, insertions, errors: [] };
+  },
+
+  async applyImport(tenantId, entity, resolution) {
+    if (resolution.action === 'skip') return {};
+
+    const store = getStore();
+    const d = entity.data as Record<string, unknown>;
+
+    if (resolution.action === 'overwrite') {
+      try {
+        await store.delete(d.id as string);
+      } catch { /* may not exist */ }
+    }
+
+    // Always generate a new key_value — key_value is globally unique
+    await store.create({
+      tenantId,
+      projectId: d.projectId as string | undefined,
+      workspaceId: d.workspaceId as string | undefined,
+      label: d.label as string | undefined,
+    });
+
+    return { newId: undefined };
+  },
+};