@axiom-lattice/gateway 2.1.112 → 2.1.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/gateway",
-  "version": "2.1.112",
+  "version": "2.1.113",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -41,8 +41,8 @@
     "redis": "^5.0.1",
     "uuid": "^9.0.1",
     "zod": "3.25.76",
-    "@axiom-lattice/core": "2.1.99",
-    "@axiom-lattice/pg-stores": "1.0.90",
+    "@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"
   },

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/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 };
+  },
+};

package/src/export_registrations/agent.registration.ts

@@ -0,0 +1,80 @@
+import type { ExportableEntityDefinition, ExportableEntity, ImportPreviewResult } from '@axiom-lattice/core';
+import { getStoreLattice } from '@axiom-lattice/core';
+import type { AssistantStore } from '@axiom-lattice/protocols';
+
+function getStore(): AssistantStore {
+  return getStoreLattice('default', 'assistant').store as unknown as AssistantStore;
+}
+
+export const agentRegistration: ExportableEntityDefinition = {
+  entityType: 'agent',
+  label: 'Agent(智能体)',
+  category: 'core',
+  dependsOn: ['skill'],
+  cascadeParents: [],
+
+  async listForExport(tenantId: string): Promise<ExportableEntity[]> {
+    const store = getStore();
+    const agents = await store.getAllAssistants(tenantId);
+    return agents.map((a) => ({
+      _exportId: '',
+      data: {
+        id: a.id,
+        name: a.name,
+        description: a.description,
+        graphDefinition: a.graphDefinition,
+      },
+    }));
+  },
+
+  async previewImport(
+    tenantId: string,
+    entities: ExportableEntity[],
+  ): Promise<ImportPreviewResult> {
+    const store = getStore();
+    const existing = await store.getAllAssistants(tenantId);
+    const existingIds = new Set(existing.map((a) => a.id));
+
+    const conflicts: ImportPreviewResult['conflicts'] = [];
+    const insertions: ImportPreviewResult['insertions'] = [];
+
+    for (const entity of entities) {
+      const id = entity.data.id as string;
+      if (existingIds.has(id)) {
+        conflicts.push({
+          _exportId: entity._exportId,
+          entityType: 'agent',
+          conflictType: 'id_exists',
+          existingId: id,
+          existingName: (entity.data.name as string) || id,
+        });
+      } else {
+        insertions.push({
+          _exportId: entity._exportId,
+          entityType: 'agent',
+          name: (entity.data.name as string) || id,
+        });
+      }
+    }
+
+    return { conflicts, insertions, errors: [] };
+  },
+
+  async applyImport(tenantId, entity, resolution) {
+    const store = getStore();
+    const data = entity.data as Record<string, unknown>;
+    const id = resolution.action === 'rename' && resolution.newId ? resolution.newId : data.id as string;
+
+    if (resolution.action === 'overwrite') {
+      try { await store.deleteAssistant(tenantId, id); } catch { /* may not exist */ }
+    }
+
+    await store.createAssistant(tenantId, id, {
+      name: data.name as string,
+      description: (data.description as string) || '',
+      graphDefinition: data.graphDefinition as Record<string, unknown>,
+    });
+
+    return { newId: id };
+  },
+};

package/src/export_registrations/binding.registration.ts

@@ -0,0 +1,106 @@
+import type { ExportableEntityDefinition, ExportableEntity, ImportPreviewResult } from '@axiom-lattice/core';
+import { getStoreLattice } from '@axiom-lattice/core';
+import type { BindingRegistry } from '@axiom-lattice/protocols';
+
+function getStore(): BindingRegistry {
+  return getStoreLattice('default', 'channelBinding').store as unknown as BindingRegistry;
+}
+
+export const bindingRegistration: ExportableEntityDefinition = {
+  entityType: 'binding',
+  label: 'Binding(渠道绑定)',
+  category: 'core',
+  dependsOn: ['agent', 'channel_installation'],
+  cascadeParents: [],
+  referenceFields: { agentId: 'agent', channelInstallationId: 'channel_installation' },
+
+  async listForExport(tenantId: string): Promise<ExportableEntity[]> {
+    const store = getStore();
+    const bindings = await store.list({ tenantId, limit: 10000, offset: 0 });
+    return bindings.map((b) => ({
+      _exportId: '',
+      data: {
+        channel: b.channel,
+        channelInstallationId: b.channelInstallationId,
+        senderId: b.senderId,
+        agentId: b.agentId,
+        threadId: b.threadId,
+        workspaceId: b.workspaceId,
+        projectId: b.projectId,
+        threadMode: b.threadMode,
+        senderDisplayName: b.senderDisplayName,
+        senderMetadata: b.senderMetadata,
+        enabled: b.enabled,
+      },
+    }));
+  },
+
+  async previewImport(
+    tenantId: string,
+    entities: ExportableEntity[],
+  ): Promise<ImportPreviewResult> {
+    const store = getStore();
+    const existing = await store.list({ tenantId, limit: 10000, offset: 0 });
+
+    const existingKeys = new Set(
+      existing.map((b) => `${b.channel}:${b.channelInstallationId}:${b.senderId}`),
+    );
+
+    const conflicts: ImportPreviewResult['conflicts'] = [];
+    const insertions: ImportPreviewResult['insertions'] = [];
+
+    for (const entity of entities) {
+      const d = entity.data as Record<string, unknown>;
+      const key = `${d.channel}:${d.channelInstallationId}:${d.senderId}`;
+      if (existingKeys.has(key)) {
+        conflicts.push({
+          _exportId: entity._exportId,
+          entityType: 'binding',
+          conflictType: 'unique_constraint',
+          existingName: `${d.channel}:${d.senderId}`,
+          field: 'channel+channelInstallationId+senderId',
+        });
+      } else {
+        insertions.push({
+          _exportId: entity._exportId,
+          entityType: 'binding',
+          name: `${d.channel}:${d.senderId}`,
+        });
+      }
+    }
+
+    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') {
+      const existing = await store.list({ tenantId, limit: 10000, offset: 0 });
+      const match = existing.find(
+        (b) => b.channel === d.channel && b.channelInstallationId === d.channelInstallationId && b.senderId === d.senderId,
+      );
+      if (match) {
+        await store.delete(match.id);
+      }
+    }
+
+    await store.create({
+      channel: d.channel as string,
+      channelInstallationId: d.channelInstallationId as string,
+      tenantId,
+      senderId: d.senderId as string,
+      agentId: d.agentId as string,
+      threadMode: (d.threadMode as 'fixed' | 'per_conversation') || 'fixed',
+      senderDisplayName: d.senderDisplayName as string | undefined,
+      senderMetadata: d.senderMetadata as Record<string, unknown> | undefined,
+      workspaceId: d.workspaceId as string | undefined,
+      projectId: d.projectId as string | undefined,
+    });
+
+    return { newId: undefined };
+  },
+};

package/src/export_registrations/channel-installation.registration.ts

@@ -0,0 +1,88 @@
+import type { ExportableEntityDefinition, ExportableEntity, ImportPreviewResult } from '@axiom-lattice/core';
+import { getStoreLattice } from '@axiom-lattice/core';
+import type { ChannelInstallationStore } from '@axiom-lattice/protocols';
+
+function getStore(): ChannelInstallationStore {
+  return getStoreLattice('default', 'channelInstallation').store as unknown as ChannelInstallationStore;
+}
+
+export const channelInstallationRegistration: ExportableEntityDefinition = {
+  entityType: 'channel_installation',
+  label: 'Channel Installation(渠道安装)',
+  category: 'core',
+  dependsOn: ['agent'],
+  cascadeParents: [],
+  referenceFields: { fallbackAgentId: 'agent' },
+
+  async listForExport(tenantId: string): Promise<ExportableEntity[]> {
+    const store = getStore();
+    const installations = await store.getInstallationsByTenant(tenantId);
+    return installations.map((i) => ({
+      _exportId: '',
+      data: {
+        id: i.id,
+        channel: i.channel,
+        name: i.name,
+        config: i.config,
+        enabled: i.enabled,
+        fallbackAgentId: i.fallbackAgentId,
+        rejectWhenNoBinding: i.rejectWhenNoBinding,
+      },
+    }));
+  },
+
+  async previewImport(
+    tenantId: string,
+    entities: ExportableEntity[],
+  ): Promise<ImportPreviewResult> {
+    const store = getStore();
+    const existing = await store.getInstallationsByTenant(tenantId);
+    const existingIds = new Set(existing.map((i) => i.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: 'channel_installation',
+          conflictType: 'id_exists',
+          existingId: id,
+          existingName: (d.name as string) || id,
+        });
+      } else {
+        insertions.push({
+          _exportId: entity._exportId,
+          entityType: 'channel_installation',
+          name: (d.name as string) || id,
+        });
+      }
+    }
+
+    return { conflicts, insertions, errors: [] };
+  },
+
+  async applyImport(tenantId, entity, resolution) {
+    const store = getStore();
+    const data = entity.data as Record<string, unknown>;
+    const id = resolution.action === 'rename' && resolution.newId ? resolution.newId : data.id as string;
+
+    if (resolution.action === 'overwrite') {
+      try { await store.deleteInstallation(tenantId, id); } catch { /* may not exist */ }
+    }
+
+    await store.createInstallation(tenantId, id, {
+      channel: data.channel as 'lark' | 'email' | 'slack' | 'wechat',
+      name: data.name as string | undefined,
+      config: data.config as any,
+      enabled: data.enabled as boolean | undefined,
+      fallbackAgentId: data.fallbackAgentId as string | undefined,
+      rejectWhenNoBinding: data.rejectWhenNoBinding as boolean | undefined,
+    });
+
+    return { newId: id };
+  },
+};

package/src/export_registrations/collection.registration.ts

@@ -0,0 +1,85 @@
+import type { ExportableEntityDefinition, ExportableEntity, ImportPreviewResult } from '@axiom-lattice/core';
+import { getStoreLattice } from '@axiom-lattice/core';
+import type { CollectionStore } from '@axiom-lattice/protocols';
+
+function getStore(): CollectionStore {
+  return getStoreLattice('default', 'collection').store as unknown as CollectionStore;
+}
+
+export const collectionRegistration: ExportableEntityDefinition = {
+  entityType: 'collection',
+  label: 'Collection(知识库)',
+  category: 'core',
+  dependsOn: [],
+  cascadeParents: [],
+
+  async listForExport(tenantId: string): Promise<ExportableEntity[]> {
+    const store = getStore();
+    const collections = await store.getAllCollections(tenantId);
+    return collections.map((c) => ({
+      _exportId: '',
+      data: {
+        id: c.id,
+        name: c.name,
+        label: c.label,
+        embeddingKey: c.embeddingKey,
+        schema: c.schema,
+      },
+    }));
+  },
+
+  async previewImport(
+    tenantId: string,
+    entities: ExportableEntity[],
+  ): Promise<ImportPreviewResult> {
+    const store = getStore();
+    const existing = await store.getAllCollections(tenantId);
+    const existingNames = new Set(existing.map((c) => c.name));
+
+    const conflicts: ImportPreviewResult['conflicts'] = [];
+    const insertions: ImportPreviewResult['insertions'] = [];
+
+    for (const entity of entities) {
+      const d = entity.data as Record<string, unknown>;
+      const name = d.name as string;
+      if (existingNames.has(name)) {
+        conflicts.push({
+          _exportId: entity._exportId,
+          entityType: 'collection',
+          conflictType: 'unique_constraint',
+          existingName: name,
+          field: 'name',
+        });
+      } else {
+        insertions.push({
+          _exportId: entity._exportId,
+          entityType: 'collection',
+          name: name,
+        });
+      }
+    }
+
+    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>;
+    const name = d.name as string;
+
+    if (resolution.action === 'overwrite') {
+      try { await store.deleteCollection(tenantId, name); } catch { /* may not exist */ }
+    }
+
+    await store.createCollection(tenantId, {
+      name,
+      label: d.label as string,
+      embeddingKey: d.embeddingKey as string,
+      schema: d.schema as any,
+    });
+
+    return { newId: undefined };
+  },
+};