@vellumai/assistant 0.6.6 → 0.7.0

package/src/runtime/routes/host-transfer-routes.ts

@@ -0,0 +1,220 @@
+/**
+ * Route handlers for host file transfer content streaming and result submission.
+ *
+ * - GET  /v1/transfers/:transferId/content — serve file bytes for to_host transfers
+ * - PUT  /v1/transfers/:transferId/content — receive file bytes for to_sandbox transfers
+ * - POST /v1/host-transfer-result          — resolve a pending to_host transfer
+ */
+import { z } from "zod";
+
+import * as pendingInteractions from "../pending-interactions.js";
+import {
+  BadRequestError,
+  ConflictError,
+  NotFoundError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+/**
+ * Find the HostTransferProxy that owns a given transferId by scanning
+ * all pending host_transfer interactions. Returns the proxy and the
+ * interaction entry (with its requestId) so callers can resolve the
+ * pending interaction when appropriate.
+ */
+function findProxyByTransferId(transferId: string) {
+  const interactions = pendingInteractions.getByKind("host_transfer");
+  for (const interaction of interactions) {
+    const proxy = interaction.conversation?.getHostTransferProxy();
+    if (proxy?.hasPendingTransfer(transferId)) {
+      return { proxy, interaction };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// GET /v1/transfers/:transferId/content
+// ---------------------------------------------------------------------------
+
+function handleTransferContentGet({
+  pathParams = {},
+}: RouteHandlerArgs): Uint8Array {
+  const transferId = pathParams.transferId;
+  if (!transferId) {
+    throw new BadRequestError("transferId path parameter is required");
+  }
+
+  const match = findProxyByTransferId(transferId);
+  if (!match) {
+    throw new NotFoundError("Unknown or consumed transfer");
+  }
+
+  const content = match.proxy.getTransferContent(transferId);
+  if (!content) {
+    throw new NotFoundError("Unknown or consumed transfer");
+  }
+
+  return new Uint8Array(content.buffer);
+}
+
+/**
+ * Resolve Content-Length and X-Transfer-SHA256 response headers for the
+ * GET transfer content endpoint. Called by the HTTP adapter before
+ * sending the response.
+ */
+function resolveTransferContentGetHeaders({
+  pathParams = {},
+}: {
+  pathParams?: Record<string, string>;
+}): Record<string, string> {
+  const transferId = pathParams?.transferId;
+  if (!transferId) return { "Content-Type": "application/octet-stream" };
+
+  const match = findProxyByTransferId(transferId);
+  if (!match) return { "Content-Type": "application/octet-stream" };
+
+  const content = match.proxy.getTransferContent(transferId);
+  if (!content) return { "Content-Type": "application/octet-stream" };
+
+  return {
+    "Content-Type": "application/octet-stream",
+    "Content-Length": content.sizeBytes.toString(),
+    "X-Transfer-SHA256": content.sha256,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PUT /v1/transfers/:transferId/content
+// ---------------------------------------------------------------------------
+
+async function handleTransferContentPut({
+  pathParams = {},
+  rawBody,
+  headers = {},
+}: RouteHandlerArgs) {
+  const transferId = pathParams.transferId;
+  if (!transferId) {
+    throw new BadRequestError("transferId path parameter is required");
+  }
+
+  const match = findProxyByTransferId(transferId);
+  if (!match) {
+    throw new NotFoundError("Unknown or consumed transfer");
+  }
+
+  const data = rawBody ? Buffer.from(rawBody) : Buffer.alloc(0);
+  const sha256 = headers["x-transfer-sha256"] ?? "";
+
+  const result = await match.proxy.receiveTransferContent(
+    transferId,
+    data,
+    sha256,
+  );
+
+  // For to_sandbox transfers there is no separate /v1/host-transfer-result
+  // callback — the PUT handler is the terminal event. Always clean up the
+  // pending interaction so it doesn't leak.
+  pendingInteractions.resolve(match.interaction.requestId);
+
+  if (!result.accepted) {
+    throw new BadRequestError(result.error ?? "Transfer content rejected");
+  }
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-transfer-result
+// ---------------------------------------------------------------------------
+
+function handleTransferResult({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const { requestId, isError, bytesWritten, errorMessage } = body as {
+    requestId?: string;
+    isError?: boolean;
+    bytesWritten?: number;
+    errorMessage?: string;
+  };
+
+  if (!requestId || typeof requestId !== "string") {
+    throw new BadRequestError("requestId is required");
+  }
+
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked) {
+    throw new NotFoundError(
+      "No pending interaction found for this requestId",
+    );
+  }
+
+  if (peeked.kind !== "host_transfer") {
+    throw new ConflictError(
+      `Pending interaction is of kind "${peeked.kind}", expected "host_transfer"`,
+    );
+  }
+
+  const interaction = pendingInteractions.resolve(requestId)!;
+
+  interaction.conversation!.resolveHostTransfer(requestId, {
+    isError: isError ?? false,
+    bytesWritten,
+    errorMessage,
+  });
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions (shared HTTP + IPC)
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "transfers_get_content",
+    endpoint: "transfers/:transferId/content",
+    method: "GET",
+    policyKey: "transfers/content",
+    requireGuardian: true,
+    summary: "Get transfer content",
+    description:
+      "Serve raw file bytes for a to_host transfer. Single-use: returns 404 after first consumption.",
+    tags: ["host-transfer"],
+    responseHeaders: resolveTransferContentGetHeaders,
+    handler: handleTransferContentGet,
+  },
+  {
+    operationId: "transfers_put_content",
+    endpoint: "transfers/:transferId/content",
+    method: "PUT",
+    policyKey: "transfers/content",
+    requireGuardian: true,
+    summary: "Put transfer content",
+    description:
+      "Receive raw file bytes for a to_sandbox transfer. Verifies SHA-256 integrity via the X-Transfer-SHA256 header.",
+    tags: ["host-transfer"],
+    handler: handleTransferContentPut,
+  },
+  {
+    operationId: "host_transfer_result",
+    endpoint: "host-transfer-result",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Submit host transfer result",
+    description:
+      "Resolve a pending to_host transfer after the client has downloaded and written the file.",
+    tags: ["host-transfer"],
+    requestBody: z.object({
+      requestId: z.string().describe("Pending transfer request ID"),
+      isError: z.boolean().optional(),
+      bytesWritten: z.number().optional(),
+      errorMessage: z.string().optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleTransferResult,
+  },
+];

package/src/runtime/routes/http-adapter.ts

@@ -0,0 +1,172 @@
+/**
+ * Adapts transport-agnostic RouteDefinitions into HTTPRouteDefinitions
+ * for the HTTP server's route table.
+ */
+
+import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
+import type { HttpErrorCode } from "../http-errors.js";
+import { httpError } from "../http-errors.js";
+import type { HTTPRouteDefinition } from "../http-router.js";
+import { RouteError } from "./errors.js";
+import type { ResponseHeaderArgs, RouteDefinition } from "./types.js";
+import { RouteResponse } from "./types.js";
+
+function resolveResponseHeaders(
+  spec: RouteDefinition["responseHeaders"],
+  args: ResponseHeaderArgs,
+): Record<string, string> | undefined {
+  if (!spec) return undefined;
+  if (typeof spec === "function") return spec(args);
+  return spec;
+}
+
+function resolveResponseStatus(
+  spec: RouteDefinition["responseStatus"],
+  args: ResponseHeaderArgs,
+): number {
+  if (!spec) return 200;
+  if (typeof spec === "function") return Number(spec(args));
+  return Number(spec);
+}
+
+export function routeDefinitionsToHTTPRoutes(
+  routes: RouteDefinition[],
+): HTTPRouteDefinition[] {
+  return routes.map((r) => ({
+    endpoint: r.endpoint,
+    method: r.method,
+    policyKey:
+      r.policyKey ?? r.endpoint.replace(/\/:[^/]+/g, "").replace(/^:/, ""),
+    pathParams: r.pathParams,
+    summary: r.summary,
+    description: r.description,
+    tags: r.tags,
+    queryParams: r.queryParams,
+    requestBody: r.requestBody,
+    responseBody: r.responseBody,
+    responseStatus:
+      typeof r.responseStatus === "string" ? r.responseStatus : undefined,
+    additionalResponses: r.additionalResponses,
+    handler: async ({ req, url, params, authContext }) => {
+      try {
+        if (r.requireGuardian) {
+          const guardianError = requireBoundGuardian(authContext);
+          if (guardianError) return guardianError;
+        }
+
+        const pathParams: Record<string, string> = {};
+        if (params) {
+          for (const [key, value] of Object.entries(params)) {
+            pathParams[key] = String(value);
+          }
+        }
+
+        const queryParams: Record<string, string> = {};
+        for (const [key, value] of url.searchParams.entries()) {
+          queryParams[key] = value;
+        }
+
+        const contentType = req.headers.get("content-type") ?? "";
+        let body: Record<string, unknown> | undefined;
+        let rawBody: Uint8Array | undefined;
+        if (
+          r.method === "POST" ||
+          r.method === "PUT" ||
+          r.method === "PATCH" ||
+          r.method === "DELETE"
+        ) {
+          if (contentType.includes("application/json") || contentType === "") {
+            try {
+              const parsed = (await req.json()) as Record<string, unknown>;
+              if (parsed && typeof parsed === "object") {
+                body = parsed;
+              }
+            } catch {
+              // No body or invalid JSON — handler will validate
+            }
+          } else {
+            // Binary body (e.g. application/zip, application/octet-stream)
+            rawBody = new Uint8Array(await req.arrayBuffer());
+          }
+        }
+
+        const headers: Record<string, string> = {};
+        req.headers.forEach((value, key) => {
+          headers[key] = value;
+        });
+
+        // Inject auth context fields so transport-agnostic handlers can
+        // resolve trust context without importing auth internals.
+        if (authContext?.actorPrincipalId) {
+          headers["x-vellum-actor-principal-id"] = authContext.actorPrincipalId;
+        }
+        if (authContext?.principalType) {
+          headers["x-vellum-principal-type"] = authContext.principalType;
+        }
+
+        const result = await r.handler({
+          pathParams,
+          queryParams,
+          body,
+          rawBody,
+          headers,
+          abortSignal: req.signal,
+        });
+
+        const headerArgs: ResponseHeaderArgs = {
+          pathParams,
+          queryParams,
+          headers,
+        };
+
+        const responseHeaders = resolveResponseHeaders(
+          r.responseHeaders,
+          headerArgs,
+        );
+
+        const status = resolveResponseStatus(r.responseStatus, headerArgs);
+
+        // 204 No Content — discard handler result, return empty body
+        if (status === 204) {
+          return new Response(null, { status: 204, headers: responseHeaders });
+        }
+
+        // RouteResponse — handler-supplied body + headers (e.g. binary
+        // content with dynamic Content-Type / Content-Range).
+        if (result instanceof RouteResponse) {
+          return new Response(result.body, {
+            status: result.status ?? status,
+            headers: { ...responseHeaders, ...result.headers },
+          });
+        }
+
+        // Non-JSON responses: handler returned string, Uint8Array, or ReadableStream
+        if (
+          typeof result === "string" ||
+          result instanceof Uint8Array ||
+          result instanceof ReadableStream
+        ) {
+          return new Response(result as BodyInit, {
+            status,
+            headers: responseHeaders,
+          });
+        }
+
+        // JSON responses: use responseHeaders if specified, otherwise default
+        return Response.json(result, {
+          status,
+          headers: responseHeaders,
+        });
+      } catch (err) {
+        if (err instanceof RouteError) {
+          return httpError(
+            err.code as HttpErrorCode,
+            err.message,
+            err.statusCode,
+          );
+        }
+        throw err;
+      }
+    },
+  }));
+}

package/src/runtime/routes/identity-routes.ts

@@ -18,9 +18,9 @@ import {
 import { APP_VERSION } from "../../version.js";
 import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
 import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import { NotFoundError } from "./errors.js";
 import { getCachedIntro } from "./identity-intro-cache.js";
+import type { RouteDefinition } from "./types.js";
 
 interface DiskSpaceInfo {
   path: string;
@@ -373,7 +373,7 @@ export function handleHealth(): Response {
   return Response.json({ status: "ok" });
 }
 
-export function handleDetailedHealth(): Response {
+function getDetailedHealth() {
   let profiler: ReturnType<typeof getProfilerRuntimeStatus> | undefined;
   try {
     profiler = getProfilerRuntimeStatus();
@@ -381,7 +381,7 @@ export function handleDetailedHealth(): Response {
     // Profiler status is non-critical — omit on error
   }
 
-  return Response.json({
+  return {
     status: "healthy",
     timestamp: new Date().toISOString(),
     version: APP_VERSION,
@@ -394,17 +394,21 @@ export function handleDetailedHealth(): Response {
         getLastWorkspaceMigrationId(WORKSPACE_MIGRATIONS),
     },
     ...(profiler ? { profiler } : {}),
-  });
+  };
+}
+
+export function handleDetailedHealth(): Response {
+  return Response.json(getDetailedHealth());
 }
 
 export function handleReadyz(): Response {
   return Response.json({ status: "ok" });
 }
 
-export function handleGetIdentity(): Response {
+function getIdentity() {
   const identityPath = getWorkspacePromptPath("IDENTITY.md");
   if (!existsSync(identityPath)) {
-    return httpError("NOT_FOUND", "IDENTITY.md not found", 404);
+    throw new NotFoundError("IDENTITY.md not found");
   }
 
   const content = readFileSync(identityPath, "utf-8");
@@ -412,7 +416,6 @@ export function handleGetIdentity(): Response {
 
   const version = APP_VERSION;
 
-  // Read createdAt from IDENTITY.md file birthtime
   let createdAt: string | undefined;
   try {
     const stats = statSync(identityPath);
@@ -421,7 +424,7 @@ export function handleGetIdentity(): Response {
     // ignore
   }
 
-  return Response.json({
+  return {
     name: fields.name ?? "",
     role: fields.role ?? "",
     personality: fields.personality ?? "",
@@ -429,7 +432,20 @@ export function handleGetIdentity(): Response {
     home: fields.home ?? "",
     version,
     createdAt,
-  });
+  };
+}
+
+function getIdentityIntro() {
+  const soulIntro = readSoulIdentityIntro();
+  if (soulIntro) {
+    return { text: soulIntro };
+  }
+
+  const cached = getCachedIntro();
+  if (!cached) {
+    throw new NotFoundError("No cached identity intro available");
+  }
+  return { text: cached.text };
 }
 
 // ---------------------------------------------------------------------------
@@ -463,20 +479,6 @@ function readSoulIdentityIntro(): string | null {
   return null;
 }
 
-export function handleGetIdentityIntro(): Response {
-  // Prefer SOUL.md persisted intro over LLM-generated cache
-  const soulIntro = readSoulIdentityIntro();
-  if (soulIntro) {
-    return Response.json({ text: soulIntro });
-  }
-
-  const cached = getCachedIntro();
-  if (!cached) {
-    return httpError("NOT_FOUND", "No cached identity intro available", 404);
-  }
-  return Response.json({ text: cached.text });
-}
-
 // ---------------------------------------------------------------------------
 // Zod schemas for profiler health metadata
 // ---------------------------------------------------------------------------
@@ -523,58 +525,60 @@ const detailedHealthSchema = z.object({
 // Route definitions
 // ---------------------------------------------------------------------------
 
-export function identityRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "health",
-      method: "GET",
-      handler: () => handleDetailedHealth(),
-      summary: "Detailed health check",
-      description:
-        "Returns runtime health including version, disk, memory, CPU, and migration status.",
-      tags: ["system"],
-      responseBody: detailedHealthSchema,
-    },
-    {
-      endpoint: "healthz",
-      method: "GET",
-      handler: () => handleDetailedHealth(),
-      policyKey: "health",
-      summary: "Detailed health check (alias)",
-      description:
-        "Alias for /v1/health. Returns runtime health including version, disk, memory, CPU, and migration status.",
-      tags: ["system"],
-      responseBody: detailedHealthSchema,
-    },
-    {
-      endpoint: "identity",
-      method: "GET",
-      handler: () => handleGetIdentity(),
-      summary: "Get assistant identity",
-      description:
-        "Returns the assistant's identity fields parsed from IDENTITY.md.",
-      tags: ["identity"],
-      responseBody: z.object({
-        name: z.string(),
-        role: z.string(),
-        personality: z.string(),
-        emoji: z.string(),
-        home: z.string(),
-        version: z.string(),
-        createdAt: z.string(),
-      }),
-    },
-    {
-      endpoint: "identity/intro",
-      method: "GET",
-      handler: () => handleGetIdentityIntro(),
-      summary: "Get identity intro text",
-      description:
-        "Returns the cached identity intro string, preferring SOUL.md over LLM-generated cache.",
-      tags: ["identity"],
-      responseBody: z.object({
-        text: z.string(),
-      }),
-    },
-  ];
-}
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "health",
+    endpoint: "health",
+    method: "GET",
+    handler: getDetailedHealth,
+    summary: "Detailed health check",
+    description:
+      "Returns runtime health including version, disk, memory, CPU, and migration status.",
+    tags: ["system"],
+    responseBody: detailedHealthSchema,
+  },
+  {
+    operationId: "healthz",
+    endpoint: "healthz",
+    method: "GET",
+    handler: getDetailedHealth,
+    policyKey: "health",
+    summary: "Detailed health check (alias)",
+    description:
+      "Alias for /v1/health. Returns runtime health including version, disk, memory, CPU, and migration status.",
+    tags: ["system"],
+    responseBody: detailedHealthSchema,
+  },
+  {
+    operationId: "identity",
+    endpoint: "identity",
+    method: "GET",
+    handler: getIdentity,
+    summary: "Get assistant identity",
+    description:
+      "Returns the assistant's identity fields parsed from IDENTITY.md.",
+    tags: ["identity"],
+    responseBody: z.object({
+      name: z.string(),
+      role: z.string(),
+      personality: z.string(),
+      emoji: z.string(),
+      home: z.string(),
+      version: z.string(),
+      createdAt: z.string(),
+    }),
+  },
+  {
+    operationId: "identity_intro",
+    endpoint: "identity/intro",
+    method: "GET",
+    handler: getIdentityIntro,
+    summary: "Get identity intro text",
+    description:
+      "Returns the cached identity intro string, preferring SOUL.md over LLM-generated cache.",
+    tags: ["identity"],
+    responseBody: z.object({
+      text: z.string(),
+    }),
+  },
+];

package/src/runtime/routes/inbound-conversation.ts

@@ -2,40 +2,33 @@
  * Channel conversation deletion handler.
  */
 import { deleteConversationKey } from "../../memory/conversation-key-store.js";
-import * as externalConversationStore from "../../memory/external-conversation-store.js";
+import { deleteBindingByChannelChat } from "../../memory/external-conversation-store.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
-import { httpError } from "../http-errors.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteHandlerArgs } from "./types.js";
 
-export async function handleDeleteConversation(
-  req: Request,
-  assistantId: string = DAEMON_INTERNAL_ASSISTANT_ID,
-): Promise<Response> {
-  const body = (await req.json()) as {
+export function handleDeleteConversation({ body = {} }: RouteHandlerArgs) {
+  const { sourceChannel, conversationExternalId } = body as {
     sourceChannel?: string;
     conversationExternalId?: string;
   };
 
-  const { sourceChannel, conversationExternalId } = body;
-
   if (!sourceChannel || typeof sourceChannel !== "string") {
-    return httpError("BAD_REQUEST", "sourceChannel is required", 400);
+    throw new BadRequestError("sourceChannel is required");
   }
   if (!conversationExternalId || typeof conversationExternalId !== "string") {
-    return httpError("BAD_REQUEST", "conversationExternalId is required", 400);
+    throw new BadRequestError("conversationExternalId is required");
   }
 
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+
   const scopedKey = `asst:${assistantId}:${sourceChannel}:${conversationExternalId}`;
   deleteConversationKey(scopedKey);
-  // For the canonical self-assistant, also delete the legacy unscopedkey
-  // and the external conversation binding (which is assistant-agnostic).
   if (assistantId === DAEMON_INTERNAL_ASSISTANT_ID) {
     const legacyKey = `${sourceChannel}:${conversationExternalId}`;
     deleteConversationKey(legacyKey);
-    externalConversationStore.deleteBindingByChannelChat(
-      sourceChannel,
-      conversationExternalId,
-    );
+    deleteBindingByChannelChat(sourceChannel, conversationExternalId);
   }
 
-  return Response.json({ ok: true });
+  return { ok: true };
 }