@vellumai/assistant 0.8.1 → 0.8.3

package/src/a2a/__tests__/protocol-helpers.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+
+import { TERMINAL_TASK_STATES } from "../protocol-constants.js";
+import {
+  INTERNAL_ERROR,
+  INVALID_PARAMS,
+  INVALID_REQUEST,
+  makeJsonRpcError,
+  makeJsonRpcSuccess,
+  METHOD_NOT_FOUND,
+  PARSE_ERROR,
+  TASK_NOT_CANCELABLE,
+  TASK_NOT_FOUND,
+  UNSUPPORTED_OPERATION,
+} from "../protocol-errors.js";
+
+describe("makeJsonRpcError", () => {
+  test("produces a valid JSON-RPC 2.0 error response", () => {
+    const response = makeJsonRpcError(1, PARSE_ERROR, "Parse error");
+
+    expect(response).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      error: {
+        code: -32700,
+        message: "Parse error",
+      },
+    });
+  });
+
+  test("includes data field when provided", () => {
+    const response = makeJsonRpcError(
+      "req-1",
+      INVALID_PARAMS,
+      "Invalid params",
+      { field: "message" },
+    );
+
+    expect(response).toEqual({
+      jsonrpc: "2.0",
+      id: "req-1",
+      error: {
+        code: -32602,
+        message: "Invalid params",
+        data: { field: "message" },
+      },
+    });
+  });
+
+  test("omits data field when not provided", () => {
+    const response = makeJsonRpcError(null, INTERNAL_ERROR, "Internal error");
+
+    expect(response.error).toBeDefined();
+    expect("data" in response.error!).toBe(false);
+  });
+
+  test("accepts null id", () => {
+    const response = makeJsonRpcError(null, PARSE_ERROR, "Parse error");
+
+    expect(response.id).toBeNull();
+  });
+});
+
+describe("makeJsonRpcSuccess", () => {
+  test("produces a valid JSON-RPC 2.0 success response", () => {
+    const response = makeJsonRpcSuccess(1, { status: "ok" });
+
+    expect(response).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      result: { status: "ok" },
+    });
+  });
+
+  test("does not include an error field", () => {
+    const response = makeJsonRpcSuccess("req-2", null);
+
+    expect("error" in response).toBe(false);
+    expect(response.result).toBeNull();
+  });
+});
+
+describe("error code constants", () => {
+  test("standard JSON-RPC codes", () => {
+    expect(PARSE_ERROR).toBe(-32700);
+    expect(INVALID_REQUEST).toBe(-32600);
+    expect(METHOD_NOT_FOUND).toBe(-32601);
+    expect(INVALID_PARAMS).toBe(-32602);
+    expect(INTERNAL_ERROR).toBe(-32603);
+  });
+
+  test("A2A-specific codes", () => {
+    expect(TASK_NOT_FOUND).toBe(-32001);
+    expect(TASK_NOT_CANCELABLE).toBe(-32002);
+    expect(UNSUPPORTED_OPERATION).toBe(-32004);
+  });
+});
+
+describe("TERMINAL_TASK_STATES", () => {
+  test("contains exactly the four terminal states", () => {
+    expect(TERMINAL_TASK_STATES.size).toBe(4);
+    expect(TERMINAL_TASK_STATES.has("completed")).toBe(true);
+    expect(TERMINAL_TASK_STATES.has("failed")).toBe(true);
+    expect(TERMINAL_TASK_STATES.has("canceled")).toBe(true);
+    expect(TERMINAL_TASK_STATES.has("rejected")).toBe(true);
+  });
+
+  test("does not contain non-terminal states", () => {
+    expect(TERMINAL_TASK_STATES.has("submitted")).toBe(false);
+    expect(TERMINAL_TASK_STATES.has("working")).toBe(false);
+    expect(TERMINAL_TASK_STATES.has("input_required")).toBe(false);
+  });
+});

package/src/a2a/__tests__/task-store.test.ts

@@ -0,0 +1,246 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { mock } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+  truncateForLog: (value: string) => value,
+}));
+
+import { getDb, getSqliteFrom } from "../../memory/db-connection.js";
+import { initializeDb } from "../../memory/db-init.js";
+import type { A2AMessage, Artifact } from "../protocol-types.js";
+import {
+  completeWithArtifacts,
+  createTask,
+  getPushUrl,
+  getTask,
+  linkConversation,
+  updateState,
+} from "../task-store.js";
+
+initializeDb();
+
+function makeRequestMessage(overrides?: Partial<A2AMessage>): A2AMessage {
+  return {
+    message_id: crypto.randomUUID(),
+    role: "user",
+    parts: [{ kind: "text", text: "Hello from sender" }],
+    ...overrides,
+  };
+}
+
+describe("a2a-task-store", () => {
+  beforeEach(() => {
+    const raw = getSqliteFrom(getDb());
+    raw.run("DELETE FROM a2a_tasks");
+  });
+
+  // ── State transitions ───────────────────────────────────────────
+
+  test("createTask returns a task in submitted state", () => {
+    const msg = makeRequestMessage();
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: msg,
+    });
+
+    expect(task.id).toBeTruthy();
+    expect(task.status.state).toBe("submitted");
+    expect(task.artifacts).toBeUndefined();
+  });
+
+  test("submitted -> working -> completed lifecycle", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    const working = updateState(task.id, "working", "Processing...");
+    expect(working.status.state).toBe("working");
+    expect(working.status.message).toBeDefined();
+
+    const completed = updateState(task.id, "completed");
+    expect(completed.status.state).toBe("completed");
+  });
+
+  test("cannot transition from terminal state (completed -> working)", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "completed");
+
+    expect(() => updateState(task.id, "working")).toThrow(/terminal state/);
+  });
+
+  test("cannot transition from failed state", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "failed");
+
+    expect(() => updateState(task.id, "working")).toThrow(/terminal state/);
+  });
+
+  test("cannot transition from canceled state", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "canceled");
+
+    expect(() => updateState(task.id, "submitted")).toThrow(/terminal state/);
+  });
+
+  test("cannot transition from rejected state", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "rejected");
+
+    expect(() => updateState(task.id, "working")).toThrow(/terminal state/);
+  });
+
+  // ── Artifact serialization round-trip ─────────────────────────
+
+  test("completeWithArtifacts stores and retrieves artifacts via JSON round-trip", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "working");
+
+    const artifacts: Artifact[] = [
+      {
+        artifact_id: "art-1",
+        parts: [{ kind: "text", text: "Result data" }],
+        metadata: { score: 0.95 },
+      },
+      {
+        artifact_id: "art-2",
+        parts: [
+          { kind: "data", data: { key: "value" } },
+          {
+            kind: "file",
+            url: "https://example.com/file.txt",
+            filename: "file.txt",
+          },
+        ],
+      },
+    ];
+
+    const completed = completeWithArtifacts(task.id, artifacts);
+    expect(completed.status.state).toBe("completed");
+    expect(completed.artifacts).toHaveLength(2);
+    expect(completed.artifacts![0].artifact_id).toBe("art-1");
+    expect(completed.artifacts![0].metadata).toEqual({ score: 0.95 });
+    expect(completed.artifacts![1].parts).toHaveLength(2);
+
+    // Verify round-trip via fresh getTask
+    const fetched = getTask(task.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.artifacts).toEqual(completed.artifacts);
+  });
+
+  test("completeWithArtifacts rejects terminal task", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    updateState(task.id, "completed");
+
+    expect(() =>
+      completeWithArtifacts(task.id, [
+        { artifact_id: "art-1", parts: [{ kind: "text", text: "late" }] },
+      ]),
+    ).toThrow(/terminal state/);
+  });
+
+  // ── Push URL storage and retrieval ────────────────────────────
+
+  test("push URL is stored and retrieved", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+      pushUrl: "https://example.com/push",
+    });
+
+    const url = getPushUrl(task.id);
+    expect(url).toBe("https://example.com/push");
+  });
+
+  test("getPushUrl returns null when no push URL set", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    const url = getPushUrl(task.id);
+    expect(url).toBeNull();
+  });
+
+  test("getPushUrl returns null for unknown task ID", () => {
+    const url = getPushUrl("nonexistent-id");
+    expect(url).toBeNull();
+  });
+
+  // ── getTask ───────────────────────────────────────────────────
+
+  test("getTask returns null for unknown ID", () => {
+    const result = getTask("nonexistent-id");
+    expect(result).toBeNull();
+  });
+
+  test("getTask returns task with context_id when provided", () => {
+    const task = createTask({
+      contextId: "ctx-456",
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    const fetched = getTask(task.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.context_id).toBe("ctx-456");
+  });
+
+  // ── linkConversation ──────────────────────────────────────────
+
+  test("linkConversation associates a conversation ID", () => {
+    const task = createTask({
+      senderAssistantId: "assistant-123",
+      requestMessage: makeRequestMessage(),
+    });
+
+    linkConversation(task.id, "conv-789");
+
+    // Verify via raw DB since getTask doesn't expose conversationId
+    const raw = getSqliteFrom(getDb());
+    const row = raw
+      .prepare("SELECT conversation_id FROM a2a_tasks WHERE id = ?")
+      .get(task.id) as { conversation_id: string };
+    expect(row.conversation_id).toBe("conv-789");
+  });
+
+  test("linkConversation throws for unknown task ID", () => {
+    expect(() => linkConversation("nonexistent-id", "conv-123")).toThrow(
+      /not found/,
+    );
+  });
+
+  // ── updateState error cases ───────────────────────────────────
+
+  test("updateState throws for unknown task ID", () => {
+    expect(() => updateState("nonexistent-id", "working")).toThrow(/not found/);
+  });
+});

package/src/a2a/agent-card.ts

@@ -0,0 +1,58 @@
+/**
+ * A2A v1.0 agent card builder.
+ *
+ * `buildAgentCard()` constructs a spec-compliant agent card from explicit
+ * parameters. `getAgentCard()` is a convenience wrapper that reads the
+ * assistant name and public base URL from workspace config.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { getAssistantName } from "../daemon/identity-helpers.js";
+import { getPublicBaseUrl } from "../inbound/public-ingress-urls.js";
+import type { AgentCard } from "./protocol-types.js";
+
+export interface BuildAgentCardParams {
+  assistantName: string;
+  assistantDescription?: string;
+  baseUrl: string;
+}
+
+export function buildAgentCard(params: BuildAgentCardParams): AgentCard {
+  return {
+    name: params.assistantName,
+    description:
+      params.assistantDescription ??
+      `${params.assistantName} — a Vellum AI assistant`,
+    version: "1.0.0",
+    supported_interfaces: [
+      {
+        url: `${params.baseUrl}/a2a/message:send`,
+        protocol_binding: "JSONRPC",
+        protocol_version: "1.0",
+      },
+    ],
+    capabilities: {
+      streaming: false,
+      push_notifications: true,
+      extended_agent_card: false,
+    },
+    default_input_modes: ["text/plain"],
+    default_output_modes: ["text/plain"],
+    skills: [
+      {
+        id: "conversation",
+        name: "General conversation",
+        description: "Send a message and receive a response",
+        tags: ["chat"],
+      },
+    ],
+  };
+}
+
+export function getAgentCard(): AgentCard {
+  const config = getConfig();
+  const assistantName = getAssistantName() ?? "Vellum Assistant";
+  const baseUrl = getPublicBaseUrl(config);
+
+  return buildAgentCard({ assistantName, baseUrl });
+}

package/src/a2a/feature-gate.ts

@@ -0,0 +1,8 @@
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../config/schema.js";
+
+const A2A_FLAG_KEY = "a2a-channel" as const;
+
+export function isA2AEnabled(config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(A2A_FLAG_KEY, config);
+}

package/src/a2a/protocol-constants.ts

@@ -0,0 +1,21 @@
+/**
+ * A2A v1.0 protocol constants.
+ */
+
+import type { TaskState } from "./protocol-types.js";
+
+export const A2A_VERSION = "1.0";
+export const A2A_CONTENT_TYPE = "application/a2a+json";
+export const A2A_VERSION_HEADER = "A2A-Version";
+export const AGENT_CARD_PATH = "/.well-known/agent-card.json";
+
+/**
+ * Task states that represent a terminal (final) condition.
+ * Once a task reaches one of these states it will not transition further.
+ */
+export const TERMINAL_TASK_STATES: ReadonlySet<TaskState> = new Set([
+  "completed",
+  "failed",
+  "canceled",
+  "rejected",
+]);

package/src/a2a/protocol-errors.ts

@@ -0,0 +1,50 @@
+/**
+ * A2A JSON-RPC error codes and helper functions.
+ */
+
+import type { JsonRpcResponse } from "./protocol-types.js";
+
+// ── Standard JSON-RPC error codes ───────────────────────────────────
+
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+
+// ── A2A-specific error codes ────────────────────────────────────────
+
+export const TASK_NOT_FOUND = -32001;
+export const TASK_NOT_CANCELABLE = -32002;
+export const PUSH_NOTIFICATION_NOT_SUPPORTED = -32003;
+export const UNSUPPORTED_OPERATION = -32004;
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+export function makeJsonRpcError(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code,
+      message,
+      ...(data !== undefined && { data }),
+    },
+  };
+}
+
+export function makeJsonRpcSuccess(
+  id: string | number | null,
+  result: unknown,
+): JsonRpcResponse {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result,
+  };
+}

package/src/a2a/protocol-types.ts

@@ -0,0 +1,162 @@
+/**
+ * A2A v1.0 protocol type definitions.
+ *
+ * Implemented directly from the A2A spec — no SDK dependency.
+ * See https://google.github.io/A2A/
+ */
+
+// ── Agent Card ──────────────────────────────────────────────────────
+
+export interface AgentCard {
+  name: string;
+  description: string;
+  version: string;
+  supported_interfaces: AgentInterface[];
+  capabilities: AgentCapabilities;
+  default_input_modes: string[];
+  default_output_modes: string[];
+  skills: AgentSkill[];
+  security_schemes?: Record<string, unknown>;
+  security_requirements?: Record<string, string[]>[];
+}
+
+export interface AgentInterface {
+  url: string;
+  protocol_binding: string;
+  protocol_version: string;
+}
+
+export interface AgentSkill {
+  id: string;
+  name: string;
+  description: string;
+  tags: string[];
+}
+
+export interface AgentCapabilities {
+  streaming: boolean;
+  push_notifications: boolean;
+  extended_agent_card: boolean;
+}
+
+// ── Messages ────────────────────────────────────────────────────────
+
+export interface A2AMessage {
+  message_id: string;
+  context_id?: string;
+  task_id?: string;
+  role: "user" | "agent";
+  parts: Part[];
+  metadata?: Record<string, unknown>;
+}
+
+export type Part = TextPart | DataPart | FilePart;
+
+export interface TextPart {
+  kind: "text";
+  text: string;
+}
+
+export interface DataPart {
+  kind: "data";
+  data: Record<string, unknown>;
+  media_type?: string;
+}
+
+export interface FilePart {
+  kind: "file";
+  url?: string;
+  raw?: string;
+  filename?: string;
+  media_type?: string;
+}
+
+// ── Tasks ───────────────────────────────────────────────────────────
+
+export type TaskState =
+  | "submitted"
+  | "working"
+  | "completed"
+  | "failed"
+  | "canceled"
+  | "input_required"
+  | "rejected";
+
+export interface TaskStatus {
+  state: TaskState;
+  message?: A2AMessage;
+  timestamp: string;
+}
+
+export interface A2ATask {
+  id: string;
+  context_id?: string;
+  status: TaskStatus;
+  artifacts?: Artifact[];
+  history?: A2AMessage[];
+  metadata?: Record<string, unknown>;
+}
+
+// ── Artifacts ───────────────────────────────────────────────────────
+
+export interface Artifact {
+  artifact_id: string;
+  parts: Part[];
+  metadata?: Record<string, unknown>;
+}
+
+// ── Requests / Responses ────────────────────────────────────────────
+
+export interface TaskPushNotificationConfig {
+  url: string;
+  authentication?: Record<string, unknown>;
+}
+
+export interface SendMessageConfiguration {
+  accepted_output_modes?: string[];
+  history_length?: number;
+  return_immediately?: boolean;
+  task_push_notification_config?: TaskPushNotificationConfig;
+}
+
+export interface SendMessageRequest {
+  message: A2AMessage;
+  configuration?: SendMessageConfiguration;
+}
+
+export type SendMessageResponse = { task: A2ATask } | { message: A2AMessage };
+
+// ── Push Events ─────────────────────────────────────────────────────
+
+export interface TaskStatusUpdateEvent {
+  task_id: string;
+  status: TaskStatus;
+  final: boolean;
+}
+
+export interface TaskArtifactUpdateEvent {
+  task_id: string;
+  artifact: Artifact;
+}
+
+// ── JSON-RPC ────────────────────────────────────────────────────────
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: unknown;
+  error?: JsonRpcError;
+}