@vellumai/assistant 0.8.2 → 0.8.3

package/src/a2a/task-store.ts

@@ -0,0 +1,168 @@
+import { eq } from "drizzle-orm";
+
+import type { DrizzleDb } from "../memory/db-connection.js";
+import { getDb } from "../memory/db-connection.js";
+import { rawChanges } from "../memory/raw-query.js";
+import { a2aTasks } from "../memory/schema.js";
+import { TERMINAL_TASK_STATES } from "./protocol-constants.js";
+import type {
+  A2AMessage,
+  A2ATask,
+  Artifact,
+  TaskState,
+} from "./protocol-types.js";
+
+// ── Internal types ──────────────────────────────────────────────────
+
+/** Raw database row shape for a2a_tasks. */
+type A2ATaskRow = typeof a2aTasks.$inferSelect;
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+/** Throw if the task doesn't exist or is in a terminal state. */
+function assertNonTerminal(
+  db: DrizzleDb,
+  taskId: string,
+  targetState: TaskState,
+): void {
+  const current = db
+    .select({ state: a2aTasks.state })
+    .from(a2aTasks)
+    .where(eq(a2aTasks.id, taskId))
+    .get();
+
+  if (!current) {
+    throw new Error(`A2A task not found: ${taskId}`);
+  }
+
+  if (TERMINAL_TASK_STATES.has(current.state as TaskState)) {
+    throw new Error(
+      `Cannot transition task ${taskId} from terminal state "${current.state}" to "${targetState}"`,
+    );
+  }
+}
+
+function rowToTask(row: A2ATaskRow): A2ATask {
+  return {
+    id: row.id,
+    context_id: row.contextId ?? undefined,
+    status: {
+      state: row.state as TaskState,
+      message: row.statusMessage
+        ? {
+            message_id: crypto.randomUUID(),
+            role: "agent",
+            parts: [{ kind: "text", text: row.statusMessage }],
+          }
+        : undefined,
+      timestamp: new Date(row.updatedAt).toISOString(),
+    },
+    artifacts: row.artifactsJson
+      ? (JSON.parse(row.artifactsJson) as Artifact[])
+      : undefined,
+  };
+}
+
+// ── Store functions ─────────────────────────────────────────────────
+
+export function createTask(params: {
+  contextId?: string;
+  senderAssistantId: string;
+  requestMessage: A2AMessage;
+  pushUrl?: string;
+}): A2ATask {
+  const db = getDb();
+  const now = Date.now();
+
+  const row: A2ATaskRow = {
+    id: crypto.randomUUID(),
+    contextId: params.contextId ?? null,
+    conversationId: null,
+    state: "submitted",
+    statusMessage: null,
+    requestMessageJson: JSON.stringify(params.requestMessage),
+    artifactsJson: null,
+    pushUrl: params.pushUrl ?? null,
+    senderAssistantId: params.senderAssistantId,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(a2aTasks).values(row).run();
+
+  return rowToTask(row);
+}
+
+export function getTask(taskId: string): A2ATask | null {
+  const db = getDb();
+  const row = db.select().from(a2aTasks).where(eq(a2aTasks.id, taskId)).get();
+  return row ? rowToTask(row) : null;
+}
+
+export function updateState(
+  taskId: string,
+  state: TaskState,
+  statusMessage?: string,
+): A2ATask {
+  const db = getDb();
+  assertNonTerminal(db, taskId, state);
+
+  db.update(a2aTasks)
+    .set({
+      state,
+      statusMessage: statusMessage ?? null,
+      updatedAt: Date.now(),
+    })
+    .where(eq(a2aTasks.id, taskId))
+    .run();
+
+  return rowToTask(
+    db.select().from(a2aTasks).where(eq(a2aTasks.id, taskId)).get()!,
+  );
+}
+
+export function completeWithArtifacts(
+  taskId: string,
+  artifacts: Artifact[],
+): A2ATask {
+  const db = getDb();
+  assertNonTerminal(db, taskId, "completed");
+
+  db.update(a2aTasks)
+    .set({
+      state: "completed",
+      statusMessage: null,
+      artifactsJson: JSON.stringify(artifacts),
+      updatedAt: Date.now(),
+    })
+    .where(eq(a2aTasks.id, taskId))
+    .run();
+
+  return rowToTask(
+    db.select().from(a2aTasks).where(eq(a2aTasks.id, taskId)).get()!,
+  );
+}
+
+export function linkConversation(taskId: string, conversationId: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(a2aTasks)
+    .set({ conversationId, updatedAt: now })
+    .where(eq(a2aTasks.id, taskId))
+    .run();
+
+  if (rawChanges() === 0) {
+    throw new Error(`A2A task not found: ${taskId}`);
+  }
+}
+
+export function getPushUrl(taskId: string): string | null {
+  const db = getDb();
+  const row = db
+    .select({ pushUrl: a2aTasks.pushUrl })
+    .from(a2aTasks)
+    .where(eq(a2aTasks.id, taskId))
+    .get();
+  return row?.pushUrl ?? null;
+}

package/src/agent/loop.ts

@@ -67,6 +67,43 @@ export interface CheckpointInfo {
 
 export type CheckpointDecision = "continue" | "yield";
 
+/**
+ * Why an {@link AgentLoop.run} invocation exited its `while (true)` body.
+ *
+ * Emitted exactly once per run as part of an {@link AgentEvent} of type
+ * `agent_loop_exit`, then persisted onto the **final** `llm_request_logs`
+ * row of the run. Rows from intermediate turns keep a NULL
+ * `agent_loop_exit_reason`, which is how downstream tooling (and the LLM
+ * Context Inspector) distinguishes "loop kept going" from "loop is done".
+ *
+ * Values are stable wire/DB strings — they are written to SQLite and
+ * surfaced over the inspector wire format, so renaming any of them is a
+ * breaking change.
+ *
+ * Cardinality matches the nine `break;`/`throw` sites currently inside the
+ * loop body. Keep in sync with `emitExit` call sites in
+ * {@link AgentLoop.run}.
+ */
+export type AgentLoopExitReason =
+  /** `if (signal?.aborted) break;` at the top of the loop. */
+  | "aborted_pre_call"
+  /** Empty assistant response after the configured retry budget. */
+  | "empty_response_exhausted"
+  /** Assistant message has no tool-use blocks (or no tool executor). */
+  | "no_tool_calls"
+  /** Signal aborted while building the user-side tool-results message. */
+  | "aborted_post_response"
+  /** Signal aborted mid-tool-execution; completed results were pushed. */
+  | "aborted_during_tools"
+  /** A tool result requested handing back to the user. */
+  | "yield_to_user"
+  /** The orchestrator's `onCheckpoint` callback returned `"yield"`. */
+  | "checkpoint_yield"
+  /** Signal aborted while the catch handler was synthesizing an error turn. */
+  | "aborted_via_error"
+  /** Catch-block fallback: an unhandled error broke the loop. */
+  | "error";
+
 export type AgentEvent =
   | { type: "text_delta"; text: string }
   | { type: "thinking_delta"; thinking: string }
@@ -126,6 +163,32 @@ export type AgentEvent =
       content?: unknown[];
     }
   | { type: "error"; error: Error }
+  | {
+      /**
+       * Emitted when the `llmCall` pipeline throws — i.e. the provider
+       * rejected the request before returning a usable response. Carries
+       * the loop-level raw request we attempted to send (messages, tools,
+       * system prompt, provider-agnostic config) plus the thrown error.
+       * Consumers (`handleProviderError` in the daemon handlers, the
+       * `onEvent` in `agent-wake`) persist these as `llm_request_logs`
+       * rows so failed calls are queryable in the LLM inspector instead
+       * of only surfacing in pino logs.
+       *
+       * `rawRequest` is the loop-level abstract shape rather than the
+       * provider-specific payload (which the provider builds internally
+       * and never returns when it throws). `actualProvider` echoes the
+       * `ProviderError.provider` tag when available so the persisted row
+       * has the same `provider` column value as a successful `usage` row.
+       *
+       * Re-thrown by the inner LLM-call try/catch after emission so the
+       * outer agent-loop catch still handles abort, Sentry capture, the
+       * existing `error` event, and the loop break.
+       */
+      type: "provider_error";
+      rawRequest: unknown;
+      error: Error;
+      actualProvider?: string;
+    }
   | {
       type: "usage";
       inputTokens: number;
@@ -144,6 +207,18 @@ export type AgentEvent =
        * for this call (e.g. legacy/stubbed code paths).
        */
       estimatedInputTokens?: number;
+    }
+  | {
+      /**
+       * Emitted exactly once at the end of {@link AgentLoop.run}, after the
+       * loop body has exited (whether via `break;`, an unhandled error in
+       * the catch block, or the empty-response throw path). Consumers
+       * persist `reason` onto the final `llm_request_logs` row for the run;
+       * intermediate rows keep `agent_loop_exit_reason = NULL`, which is the
+       * canonical "loop kept going" signal.
+       */
+      type: "agent_loop_exit";
+      reason: AgentLoopExitReason;
     };
 
 const DEFAULT_CONFIG: AgentLoopConfig = {
@@ -398,8 +473,24 @@ export class AgentLoop {
     const substitutionMap = new Map<string, string>();
     let streamingPending = "";
 
+    // Idempotency guard for `emitExit`. Used so the throw path in the
+    // empty-response branch can stamp its reason ("empty_response_exhausted")
+    // before throwing — the catch handler that observes the rethrow will
+    // then attempt to stamp "error" and harmlessly no-op, preserving the
+    // more specific reason. Also defends against accidental future
+    // double-emits if a new break site is added without checking this.
+    let exitReasonEmitted = false;
+    const emitExit = async (reason: AgentLoopExitReason): Promise<void> => {
+      if (exitReasonEmitted) return;
+      exitReasonEmitted = true;
+      await onEvent({ type: "agent_loop_exit", reason });
+    };
+
     while (true) {
-      if (signal?.aborted) break;
+      if (signal?.aborted) {
+        await emitExit("aborted_pre_call");
+        break;
+      }
 
       rlog.info(
         { turn: toolUseTurns, messageCount: history.length },
@@ -618,23 +709,64 @@ export class AgentLoop {
           toolUseTurns,
         );
 
-        const response: LLMCallResult = await runPipeline<
-          LLMCallArgs,
-          LLMCallResult
-        >(
-          "llmCall",
-          getMiddlewaresFor("llmCall"),
-          (args) =>
-            args.provider.sendMessage(
-              args.messages,
-              args.tools,
-              args.systemPrompt,
-              args.options,
-            ),
-          llmCallArgs,
-          turnCtx,
-          DEFAULT_TIMEOUTS.llmCall,
-        );
+        // Inner try/catch narrows error-recording scope to the provider
+        // call itself. The outer agent-loop catch (below) wraps the entire
+        // turn body (tool execution, plugin pipelines, checkpoints), so
+        // recording there would risk mis-attributing tool/plugin throws as
+        // provider rejections. On provider failure we emit `provider_error`
+        // with the loop-level raw request so consumers can persist it as an
+        // `llm_request_logs` row, then re-throw so the existing outer catch
+        // continues to handle abort sync, Sentry capture, the `error` event,
+        // and the loop break unchanged.
+        let response: LLMCallResult;
+        try {
+          response = await runPipeline<LLMCallArgs, LLMCallResult>(
+            "llmCall",
+            getMiddlewaresFor("llmCall"),
+            (args) =>
+              args.provider.sendMessage(
+                args.messages,
+                args.tools,
+                args.systemPrompt,
+                args.options,
+              ),
+            llmCallArgs,
+            turnCtx,
+            DEFAULT_TIMEOUTS.llmCall,
+          );
+        } catch (llmCallError) {
+          // Skip recording on abort — the user cancelled the request and
+          // there's no provider rejection worth a log row. The outer catch
+          // still synthesizes cancellation tool_results.
+          if (!signal?.aborted) {
+            const errInstance =
+              llmCallError instanceof Error
+                ? llmCallError
+                : new Error(String(llmCallError));
+            // Strip non-serializable / runtime-only fields from `options`
+            // before snapshotting. `onEvent` is a closure with side effects
+            // and `signal` is an AbortSignal — neither is meaningful in a
+            // persisted log row, and `JSON.stringify` would silently drop or
+            // misrepresent both.
+            const rawRequest = {
+              provider: this.provider.name,
+              messages: llmCallArgs.messages,
+              tools: llmCallArgs.tools,
+              systemPrompt: llmCallArgs.systemPrompt,
+              config: llmCallArgs.options?.config,
+            };
+            onEvent({
+              type: "provider_error",
+              rawRequest,
+              error: errInstance,
+              actualProvider:
+                errInstance instanceof ProviderError
+                  ? errInstance.provider
+                  : this.provider.name,
+            });
+          }
+          throw llmCallError;
+        }
 
         const providerDurationMs = Date.now() - providerStart;
 
@@ -785,6 +917,11 @@ export class AgentLoop {
             { turn: toolUseTurns, retries: emptyResponseRetries },
             "emptyResponse pipeline requested error surface",
           );
+          // Stamp the specific exit reason *before* throwing. The catch
+          // handler below will see the rethrown error and attempt to stamp
+          // "error" — guarded by `exitReasonEmitted`, that becomes a no-op
+          // and the more specific reason wins.
+          await emitExit("empty_response_exhausted");
           throw new AssistantError(
             "Model returned empty response after tool results",
             ErrorCode.INTERNAL_ERROR,
@@ -811,6 +948,7 @@ export class AgentLoop {
         await onEvent({ type: "message_complete", message: assistantMessage });
 
         if (toolUseBlocks.length === 0 || !this.toolExecutor) {
+          await emitExit("no_tool_calls");
           break;
         }
 
@@ -835,6 +973,7 @@ export class AgentLoop {
             }),
           );
           history.push({ role: "user", content: cancelledBlocks });
+          await emitExit("aborted_post_response");
           break;
         }
 
@@ -1022,6 +1161,7 @@ export class AgentLoop {
         // If cancelled during execution, push completed results and stop
         if (signal?.aborted) {
           history.push({ role: "user", content: resultBlocks });
+          await emitExit("aborted_during_tools");
           break;
         }
 
@@ -1029,6 +1169,7 @@ export class AgentLoop {
         // surface awaiting a button click), push results and stop the loop.
         if (toolResults.some(({ result }) => result.yieldToUser)) {
           history.push({ role: "user", content: resultBlocks });
+          await emitExit("yield_to_user");
           break;
         }
 
@@ -1095,6 +1236,7 @@ export class AgentLoop {
             history,
           });
           if (decision === "yield") {
+            await emitExit("checkpoint_yield");
             break;
           }
         }
@@ -1114,6 +1256,7 @@ export class AgentLoop {
             );
             history.push({ role: "user", content: cancelledBlocks });
           }
+          await emitExit("aborted_via_error");
           break;
         }
         const err = error instanceof Error ? error : new Error(String(error));
@@ -1125,6 +1268,12 @@ export class AgentLoop {
           Sentry.captureException(err);
         }
         onEvent({ type: "error", error: err });
+        // Catch-block fallback. If the rethrow came from the
+        // empty-response throw path above, `emitExit("error")` no-ops
+        // because `emitExit("empty_response_exhausted")` already ran
+        // before the throw. Otherwise, this is the genuine
+        // unhandled-error exit.
+        await emitExit("error");
         break;
       }
     }

package/src/channels/config.ts

@@ -94,6 +94,15 @@ const CHANNEL_POLICIES = {
       codeRedemptionEnabled: false,
     },
   },
+  a2a: {
+    notification: {
+      deliveryEnabled: false,
+      conversationStrategy: "continue_existing_conversation",
+    },
+    invite: {
+      codeRedemptionEnabled: false,
+    },
+  },
 } as const satisfies Record<ChannelId, ChannelNotificationPolicy>;
 
 export type ChannelPolicies = typeof CHANNEL_POLICIES;

package/src/channels/types.ts

@@ -6,6 +6,7 @@ export const CHANNEL_IDS = [
   "slack",
   "email",
   "platform",
+  "a2a",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -133,6 +134,18 @@ export const CHANNEL_METADATA: Partial<Record<ChannelId, ChannelInfo>> = {
         "I'd like to verify a contact's WhatsApp identity. Can you walk me through it?",
     },
   },
+  a2a: {
+    id: "a2a",
+    label: "A2A",
+    subtitle: "Agent-to-Agent protocol",
+    icon: "bot",
+    supportsVerification: false,
+    setupMessages: {
+      guardian: "Connect with other Vellum assistants via the A2A protocol.",
+      contact:
+        "I'd like to connect with another assistant via A2A. Can you help me set that up?",
+    },
+  },
 };
 
 export const INTERFACE_IDS = [
@@ -146,6 +159,7 @@ export const INTERFACE_IDS = [
   "slack",
   "email",
   "chrome-extension",
+  "a2a",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];