@axiom-lattice/gateway 2.1.116 → 3.0.0

package/src/routes/a2a-test-connection.ts

@@ -0,0 +1,126 @@
+import { FastifyInstance } from "fastify";
+import { randomUUID } from "node:crypto";
+import type { AgentCard, LocalRuntimeConfig } from "@axiom-lattice/protocols";
+import { localA2AService } from "../services/local-a2a";
+import { normalizeA2AAgentCardUrl } from "../utils/a2a-url";
+import {
+  validateLocalRuntimeCommand,
+  validateLocalRuntimePort,
+} from "../utils/local-a2a-runtime";
+
+type TestConnectionError = Error & {
+  code?: string;
+  cause?: unknown;
+};
+
+function describeTestConnectionError(error: unknown, agentCardUrl: string): string {
+  if (!(error instanceof Error)) {
+    return `Failed to fetch agent card from ${agentCardUrl}: ${String(error)}`;
+  }
+
+  const cause = (error as TestConnectionError).cause;
+  const causeParts: string[] = [];
+  if (cause instanceof Error) {
+    causeParts.push(cause.message);
+    const causeCode = (cause as TestConnectionError).code;
+    if (causeCode && !causeParts.some((part) => part.includes(causeCode))) {
+      causeParts.push(causeCode);
+    }
+  } else if (typeof cause === "object" && cause !== null) {
+    const code = "code" in cause ? String(cause.code) : "";
+    const message = "message" in cause ? String(cause.message) : "";
+    if (message) causeParts.push(message);
+    if (code && !message.includes(code)) causeParts.push(code);
+  }
+
+  const detail = causeParts.length > 0 ? ` (${causeParts.join(", ")})` : "";
+  return `Failed to fetch agent card from ${agentCardUrl}: ${error.message}${detail}`;
+}
+
+async function ensureLocalRuntimeForConnectionTest(
+  localRuntime: LocalRuntimeConfig,
+  agentCardUrl: string,
+): Promise<{ runtimeId: string } | { error: string }> {
+  const commandValidation = validateLocalRuntimeCommand(localRuntime);
+  if (!commandValidation.ok) {
+    return { error: commandValidation.error };
+  }
+  const testRuntime = {
+    ...localRuntime,
+    agentCardUrl,
+    command: {
+      ...localRuntime.command,
+      executable: localRuntime.command.executable.trim(),
+    },
+  };
+  const portValidation = validateLocalRuntimePort(testRuntime, agentCardUrl);
+  if (!portValidation.ok) {
+    return { error: portValidation.error };
+  }
+
+  const state = await localA2AService.startProvider(
+    `test-${randomUUID()}`,
+    testRuntime,
+  );
+  if (state.status === "running") return { runtimeId: state.runtimeId };
+  const detail = state.message ? ` ${state.message}` : "";
+  localA2AService.removeState(state.runtimeId);
+  return { error: `Local managed A2A server could not start for connection test.${detail}` };
+}
+
+async function readShortResponseBody(resp: Response): Promise<string> {
+  const body = await resp.text().catch(() => "");
+  return body.length > 500 ? `${body.slice(0, 500)}...` : body;
+}
+
+export function registerA2ATestConnectionRoute(app: FastifyInstance): void {
+  app.post("/api/a2a/test-connection", async (request, reply) => {
+    const { agentCardUrl, apiKey, localRuntime } = (request.body ?? {}) as {
+      agentCardUrl?: string;
+      apiKey?: string;
+      localRuntime?: LocalRuntimeConfig;
+    };
+    const normalizedAgentCardUrl = normalizeA2AAgentCardUrl(
+      agentCardUrl,
+      localRuntime ? "http://" : "https://",
+    );
+    if (!normalizedAgentCardUrl) {
+      return reply.status(400).send({ success: false, error: "agentCardUrl is required" });
+    }
+
+    let testRuntimeId: string | null = null;
+    try {
+      const headers: Record<string, string> = {};
+      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+
+      if (localRuntime) {
+        const localStartResult = await ensureLocalRuntimeForConnectionTest(localRuntime, normalizedAgentCardUrl);
+        if ("error" in localStartResult) {
+          return reply.send({ success: true, data: { reachable: false, error: localStartResult.error } });
+        }
+        testRuntimeId = localStartResult.runtimeId;
+      }
+
+      const resp = await fetch(normalizedAgentCardUrl, { headers, signal: AbortSignal.timeout(8000) });
+      if (!resp.ok) {
+        const body = await readShortResponseBody(resp);
+        const suffix = body ? `: ${body}` : "";
+        return reply.send({ success: true, data: { reachable: false, error: `HTTP ${resp.status} ${resp.statusText}${suffix}` } });
+      }
+      const card = await resp.json() as AgentCard;
+      return reply.send({ success: true, data: { reachable: true, agentName: card.name, agentCard: card } });
+    } catch (error: unknown) {
+      return reply.send({
+        success: true,
+        data: {
+          reachable: false,
+          error: describeTestConnectionError(error, normalizedAgentCardUrl),
+        },
+      });
+    } finally {
+      if (testRuntimeId) {
+        localA2AService.removeState(testRuntimeId);
+      }
+    }
+  });
+}

package/src/routes/a2a.ts

@@ -23,6 +23,8 @@ import type {
 interface TaskRecord {
   id: string;
   threadId: string;
+  contextId?: string;
+  referenceTaskIds?: string[];
   messageId?: string;
   assistantId: string;
   tenantId: string;
@@ -36,6 +38,17 @@ interface TaskRecord {
 
 const taskStore = new Map<string, TaskRecord>();
 
+const MAX_CONTEXT_THREADS = 100;
+const contextThreadMap = new Map<string, string>();
+
+function cacheContextThread(contextId: string, threadId: string): void {
+  if (contextThreadMap.size >= MAX_CONTEXT_THREADS) {
+    const oldest = contextThreadMap.keys().next().value;
+    if (oldest !== undefined) contextThreadMap.delete(oldest);
+  }
+  contextThreadMap.set(contextId, threadId);
+}
+
 // ─── Key Store ────────────────────────────────────────────────────────────
 
 let _a2aKeyStore: A2AApiKeyStore | null = null;
@@ -200,10 +213,12 @@ type SendEventFn = (event: string, data: Record<string, unknown>) => void;
 async function streamChunksAsA2A(
   stream: AsyncIterable<{ type: unknown; data?: { content?: string } }>,
   taskId: string,
+  contextId: string | undefined,
   sendEvent: SendEventFn,
   onInterrupt?: () => void,
-): Promise<string> {
+): Promise<{ text: string; interrupted: boolean }> {
   let accumulatedText = "";
+  let interrupted = false;
 
   for await (const chunk of stream) {
     const chunkText = (chunk as { data?: { content?: string } }).data?.content || "";
@@ -212,6 +227,7 @@ async function streamChunksAsA2A(
     if (chunkType === MessageChunkTypes.INTERRUPT) {
       sendEvent("status-update", {
         id: taskId,
+        contextId,
         status: {
           state: "input-required",
           message: {
@@ -223,7 +239,8 @@ async function streamChunksAsA2A(
         final: false,
       });
       onInterrupt?.();
-      continue;
+      interrupted = true;
+      break;
     }
 
     if (
@@ -234,6 +251,7 @@ async function streamChunksAsA2A(
         accumulatedText += chunkText;
         sendEvent("status-update", {
           id: taskId,
+          contextId,
           status: {
             state: "working",
             message: {
@@ -248,7 +266,7 @@ async function streamChunksAsA2A(
     }
   }
 
-  return accumulatedText;
+  return { text: accumulatedText, interrupted };
 }
 
 // ─── Task Status ──────────────────────────────────────────────────────────
@@ -331,8 +349,52 @@ async function handleTasksSend(
     return;
   }
 
+  const contextId = body.message.contextId;
+  const referenceTaskIds = body.message.referenceTaskIds;
   const taskId = body.id || v4();
-  const threadId = v4();
+
+  let threadId: string;
+  let resolvedReferenceTaskIds: string[] | undefined;
+
+  // Explicit task continuation: if body.id matches a stored task
+  if (body.id) {
+    const existingTask = taskStore.get(body.id);
+    if (existingTask) {
+      if (existingTask.status === "input-required") {
+        threadId = existingTask.threadId;
+        resolvedReferenceTaskIds = referenceTaskIds;
+      } else if (
+        existingTask.status === "completed" ||
+        existingTask.status === "failed" ||
+        existingTask.status === "canceled"
+      ) {
+        threadId = v4();
+        resolvedReferenceTaskIds = referenceTaskIds
+          ? [...referenceTaskIds, body.id]
+          : [body.id];
+      } else {
+        threadId = v4();
+        resolvedReferenceTaskIds = referenceTaskIds;
+      }
+    } else {
+      threadId = v4();
+      resolvedReferenceTaskIds = referenceTaskIds
+        ? [...referenceTaskIds, body.id]
+        : [body.id];
+    }
+  } else if (contextId && contextThreadMap.has(contextId)) {
+    threadId = contextThreadMap.get(contextId)!;
+    console.warn({
+      event: "a2a:deprecated:contextId_thread_reuse",
+      message: "contextId-based thread reuse is deprecated; use referenceTaskIds and application-layer conversation state instead",
+      contextId,
+      threadId,
+    });
+    resolvedReferenceTaskIds = referenceTaskIds;
+  } else {
+    threadId = v4();
+    resolvedReferenceTaskIds = referenceTaskIds;
+  }
 
   const tenantId = auth.tenantId || config.defaultTenantId;
 
@@ -341,6 +403,8 @@ async function handleTasksSend(
   const record: TaskRecord = {
     id: taskId,
     threadId,
+    contextId,
+    referenceTaskIds: resolvedReferenceTaskIds,
     assistantId,
     tenantId,
     projectId: auth.projectId || undefined,
@@ -401,26 +465,29 @@ async function handleTasksSend(
       MessageChunkTypes.MESSAGE_COMPLETED,
     ]);
 
-    const accumulatedText = await streamChunksAsA2A(stream, taskId, sendEvent, () => {
+    const { text: accumulatedText, interrupted } = await streamChunksAsA2A(stream, taskId, contextId, sendEvent, () => {
       record.status = "input-required";
       record.updatedAt = isoNow();
     });
 
-    record.status = "completed";
-    record.updatedAt = isoNow();
-    record.history.push({
-      role: "agent",
-      parts: [buildTextPart(accumulatedText)],
-    });
+    if (!interrupted) {
+      record.status = "completed";
+      record.updatedAt = isoNow();
+      record.history.push({
+        role: "agent",
+        parts: [buildTextPart(accumulatedText)],
+      });
 
-    sendEvent("status-update", {
-      id: taskId,
-      status: {
-        state: "completed",
-        timestamp: isoNow(),
-      },
-      final: true,
-    });
+      sendEvent("status-update", {
+        id: taskId,
+        contextId,
+        status: {
+          state: "completed",
+          timestamp: isoNow(),
+        },
+        final: true,
+      });
+    }
   } catch (err) {
     record.status = "failed";
     record.updatedAt = isoNow();
@@ -432,6 +499,7 @@ async function handleTasksSend(
 
     sendEvent("status-update", {
       id: taskId,
+      contextId,
       status: {
         state: "failed",
         timestamp: isoNow(),
@@ -542,6 +610,7 @@ async function handleTasksStream(
   if (!record.messageId) {
     sendEvent("status-update", {
       id: taskId,
+      contextId: record.contextId,
       status: {
         state: record.status,
         timestamp: record.updatedAt,
@@ -557,16 +626,19 @@ async function handleTasksStream(
       MessageChunkTypes.MESSAGE_COMPLETED,
     ]);
 
-    await streamChunksAsA2A(stream, taskId, sendEvent);
+    const { interrupted } = await streamChunksAsA2A(stream, taskId, record.contextId, sendEvent);
 
-    sendEvent("status-update", {
-      id: taskId,
-      status: {
-        state: record.status,
-        timestamp: record.updatedAt,
-      },
-      final: true,
-    });
+    if (!interrupted) {
+      sendEvent("status-update", {
+        id: taskId,
+        contextId: record.contextId,
+        status: {
+          state: record.status,
+          timestamp: record.updatedAt,
+        },
+        final: true,
+      });
+    }
   } catch (err) {
     sendEvent("error", {
       code: "STREAM_ERROR",

package/src/routes/index.ts

@@ -65,11 +65,38 @@ import type { ChannelInstallationStore } from "@axiom-lattice/protocols";
 // } from "../controllers/thread_status";
 
 import { registerA2ABridgeRoutes } from './a2a-bridge';
+import { registerSTTRoutes } from './stt';
+import {
+  getLocalA2AProvider,
+  getLocalA2AStatus,
+  restartLocalA2AProvider,
+  startLocalA2AProvider,
+  stopLocalA2AProvider,
+} from "../controllers/local-a2a";
+import {
+  getLocalA2ATemplates,
+} from "../controllers/local-a2a-templates";
+import { registerA2ATestConnectionRoute } from "./a2a-test-connection";
 
 export const registerLatticeRoutes = (app: FastifyInstance, channelDeps?: { router: MessageRouter; installationStore: ChannelInstallationStore }): void => {
   // A2A Bridge — WebSocket-based reverse proxy for agents behind NAT
   registerA2ABridgeRoutes(app);
 
+  // STT (speech-to-text) transcription
+  registerSTTRoutes(app);
+
+  // Local A2A runtime management
+  app.get("/api/local-a2a", getLocalA2AStatus);
+
+  app.get("/api/local-a2a/templates", getLocalA2ATemplates);
+
+  app.get("/api/local-a2a/:assistantId", getLocalA2AProvider);
+  app.post("/api/local-a2a/:assistantId/start", startLocalA2AProvider);
+  app.post("/api/local-a2a/:assistantId/stop", stopLocalA2AProvider);
+  app.post("/api/local-a2a/:assistantId/restart", restartLocalA2AProvider);
+
+  registerA2ATestConnectionRoute(app);
+
   // 运行路由
   app.post<{
     Body: any;

package/src/routes/stt.ts

@@ -0,0 +1,102 @@
+import { FastifyInstance } from "fastify";
+import { getSTTClient, sttModelLatticeManager } from "@axiom-lattice/core";
+
+const ALLOWED_AUDIO_FORMATS = new Set([
+  "webm",
+  "wav",
+  "mp3",
+  "m4a",
+  "ogg",
+  "flac",
+  "aac",
+]);
+
+const MAX_AUDIO_FILE_SIZE = 25 * 1024 * 1024;
+
+/**
+ * Register STT (speech-to-text) transcription route.
+ *
+ * POST /api/stt/transcribe
+ *   Content-Type: multipart/form-data
+ *   Body: { file: File }
+ *   Query: ?model=default
+ *   Response: { text: string, confidence?: number }
+ */
+export const registerSTTRoutes = (app: FastifyInstance): void => {
+  // List registered STT models
+  app.get("/api/stt/models", async (_request, reply) => {
+    const models = sttModelLatticeManager.getAllSTTModelInfo();
+    return reply.send({ models });
+  });
+
+  app.post<{ Querystring: { model?: string } }>(
+    "/api/stt/transcribe",
+    {
+      schema: {
+        querystring: {
+          type: "object",
+          properties: {
+            model: { type: "string" },
+          },
+        },
+        response: {
+          200: {
+            type: "object",
+            properties: {
+              text: { type: "string" },
+              confidence: { type: "number" },
+            },
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const modelKey = request.query.model || "default";
+      const data = await request.file({
+        limits: { fileSize: MAX_AUDIO_FILE_SIZE },
+      });
+
+      if (!data) {
+        return reply.status(400).send({ error: "No audio file provided" });
+      }
+
+      const buffer = await data.toBuffer();
+      if (buffer.length === 0) {
+        return reply.status(400).send({ error: "Empty audio file" });
+      }
+
+      const format = (data.filename.split(".").pop() || "webm").toLowerCase();
+
+      if (!ALLOWED_AUDIO_FORMATS.has(format)) {
+        return reply
+          .status(400)
+          .send({ error: `Unsupported audio format: ${format}` });
+      }
+
+      try {
+        let client;
+        try {
+          client = getSTTClient(modelKey);
+        } catch {
+          return reply.status(404).send({ error: `STT model "${modelKey}" not found` });
+        }
+        const result = await client.transcribe(buffer, format);
+
+        return reply.send({
+          text: result.text,
+          confidence: result.confidence,
+        });
+      } catch (error: unknown) {
+        const sanitizedMessage =
+          error instanceof Error ? error.message : "Transcription failed";
+        request.log.error(
+          { error: sanitizedMessage },
+          "STT transcription failed",
+        );
+        return reply
+          .status(500)
+          .send({ error: "Transcription service error. Please try again." });
+      }
+    },
+  );
+};

package/src/services/__tests__/local-a2a.test.ts

@@ -0,0 +1,124 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  appendStderrTail,
+  LocalA2AService,
+  resolveLocalA2AWorkingDirectory,
+} from "../local-a2a";
+import type { LocalRuntimeConfig } from "@axiom-lattice/protocols";
+
+describe("LocalA2AService working directory resolution", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "local-a2a-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("prefers env override, then explicit command cwd", () => {
+    expect(resolveLocalA2AWorkingDirectory({
+      envWorkdir: "/env/root",
+      commandCwd: "/command/root",
+      currentCwd: tempDir,
+    })).toBe("/env/root");
+
+    expect(resolveLocalA2AWorkingDirectory({
+      envWorkdir: "",
+      commandCwd: "/command/root",
+      currentCwd: tempDir,
+    })).toBe("/command/root");
+  });
+
+  it("falls back to the nearest pnpm workspace root", () => {
+    writeFileSync(join(tempDir, "pnpm-workspace.yaml"), "packages: []\n");
+    const nested = join(tempDir, "examples", "deep_research");
+    mkdirSync(nested, { recursive: true });
+
+    expect(resolveLocalA2AWorkingDirectory({
+      commandCwd: undefined,
+      currentCwd: nested,
+    })).toBe(tempDir);
+  });
+
+  it("falls back to current cwd when no workspace root exists", () => {
+    expect(resolveLocalA2AWorkingDirectory({
+      commandCwd: undefined,
+      currentCwd: tempDir,
+    })).toBe(tempDir);
+  });
+});
+
+describe("LocalA2AService startup diagnostics", () => {
+  const originalAutoStart = process.env.LOCAL_A2A_AUTO_START;
+  const originalWorkdir = process.env.LOCAL_A2A_WORKDIR;
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "local-a2a-"));
+    process.env.LOCAL_A2A_AUTO_START = "true";
+    delete process.env.LOCAL_A2A_WORKDIR;
+  });
+
+  afterEach(() => {
+    if (originalAutoStart === undefined) {
+      delete process.env.LOCAL_A2A_AUTO_START;
+    } else {
+      process.env.LOCAL_A2A_AUTO_START = originalAutoStart;
+    }
+
+    if (originalWorkdir === undefined) {
+      delete process.env.LOCAL_A2A_WORKDIR;
+    } else {
+      process.env.LOCAL_A2A_WORKDIR = originalWorkdir;
+    }
+
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function runtime(command: LocalRuntimeConfig["command"]): LocalRuntimeConfig {
+    return {
+      label: "Test Runtime",
+      agentCardUrl: "http://127.0.0.1:1/.well-known/agent-card.json",
+      command,
+    };
+  }
+
+  it("fails before spawn when cwd is not accessible", async () => {
+    const service = new LocalA2AService();
+
+    const state = await service.startProvider("runtime-1", runtime({
+      executable: process.execPath,
+      args: ["-e", "process.exit(0)"],
+      cwd: join(tempDir, "missing"),
+    }));
+
+    expect(state.status).toBe("failed");
+    expect(state.message).toContain("Working directory is not accessible");
+  });
+
+  it("includes stderr tail when the child exits before ready", async () => {
+    const service = new LocalA2AService();
+
+    const state = await service.startProvider("runtime-2", runtime({
+      executable: process.execPath,
+      args: ["-e", "console.error('diagnostic stderr'); process.exit(1)"],
+      cwd: tempDir,
+    }));
+
+    expect(state.status).toBe("failed");
+    expect(state.message).toContain("Exited before becoming ready (1)");
+    expect(state.message).toContain("diagnostic stderr");
+  });
+
+  it("keeps only the last 4KB of stderr", () => {
+    const tail = appendStderrTail("prefix", `${"x".repeat(5000)}end`);
+
+    expect(tail.length).toBe(4096);
+    expect(tail.endsWith("end")).toBe(true);
+    expect(tail.startsWith("prefix")).toBe(false);
+  });
+});

package/src/services/eval-runner.ts

@@ -109,6 +109,10 @@ class EvalRunner {
     const concurrency = Math.max(1, Math.floor((project as unknown as Record<string, unknown>).concurrency as number) || 3);
     await store.createRun(tenantId, projectId, runId, { totalCases, concurrency });
 
+    const tsc = (project.targetServerConfig ?? {}) as Record<string, unknown>;
+    const workspaceId = (tsc.workspace_id as string) || "";
+    const projectIdFromConfig = (tsc.project_id as string) || "";
+
     const projectConfig: LatticeEvalProjectType = {
       projectName: project.name,
       version: project.version,
@@ -117,6 +121,8 @@ class EvalRunner {
       judge_agent_config: { modelKey: resolvedJudgeModelKey },
       lattice_server_config: {
         tenant_id: tenantId,
+        workspace_id: workspaceId,
+        project_id: projectIdFromConfig,
       },
       concurrency,
     };