@vellumai/assistant 0.6.6 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.6.6",
+  "version": "0.7.1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,6 +19,8 @@
     "format:check": "prettier --check .",
     "lint": "eslint",
     "lint:unused": "knip --include files,dependencies,unlisted",
+    "lint:circular": "bun run scripts/check-circular-deps.ts",
+    "lint:unused:production": "knip --production --include exports",
     "typecheck": "bunx tsc --noEmit",
     "test": "bash scripts/test.sh",
     "test:coverage": "COVERAGE=true bash scripts/test.sh",
@@ -38,9 +40,13 @@
     "@resvg/resvg-js-darwin-arm64": "2.6.2",
     "@resvg/resvg-js-darwin-x64": "2.6.2",
     "@sentry/node": "10.43.0",
-    "@vellumai/ces-contracts": "file:../packages/ces-contracts",
+    "@vellumai/ces-client": "file:../packages/ces-client",
     "@vellumai/credential-storage": "file:../packages/credential-storage",
+    "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+    "@vellumai/gateway-client": "file:../packages/gateway-client",
+    "@vellumai/skill-host-contracts": "file:../packages/skill-host-contracts",
+    "@vellumai/slack-text": "file:../packages/slack-text",
     "archiver": "7.0.1",
     "commander": "13.1.0",
     "croner": "10.0.1",
@@ -54,13 +60,10 @@
     "pino-pretty": "13.1.3",
     "playwright": "1.58.2",
     "postgres": "3.4.8",
-    "qrcode": "1.5.4",
     "rrule": "2.8.1",
     "tar-stream": "3.1.7",
     "tldts": "7.0.25",
-    "tree-sitter-bash": "0.25.1",
     "uuid": "11.1.0",
-    "web-tree-sitter": "0.26.5",
     "yaml": "2.8.2",
     "zod": "4.3.6"
   },
@@ -68,9 +71,13 @@
     "node": ">=20.12.0"
   },
   "bundledDependencies": [
-    "@vellumai/ces-contracts",
+    "@vellumai/ces-client",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/service-contracts",
+    "@vellumai/egress-proxy",
+    "@vellumai/gateway-client",
+    "@vellumai/skill-host-contracts",
+    "@vellumai/slack-text"
   ],
   "overrides": {
     "lodash": "4.18.1",
@@ -86,6 +93,7 @@
     "eslint-plugin-simple-import-sort": "12.1.1",
     "fast-check": "4.6.0",
     "knip": "5.86.0",
+    "madge": "8.0.0",
     "prettier": "3.8.1",
     "typescript": "5.9.3",
     "typescript-eslint": "8.57.0"

package/scripts/check-circular-deps.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+/**
+ * Detect circular dependencies in the assistant package using madge.
+ *
+ * Usage:
+ *   bun run lint:circular            # exits 1 when cycles exist
+ *   bun run lint:circular -- --json  # machine-readable output
+ */
+
+import { execSync } from "node:child_process";
+import { resolve } from "node:path";
+
+const assistantRoot = resolve(import.meta.dirname, "..");
+const tsConfig = resolve(assistantRoot, "tsconfig.json");
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes("--json");
+
+const cmd = [
+  "bunx",
+  "madge",
+  "--circular",
+  "--extensions",
+  "ts,tsx",
+  "--ts-config",
+  tsConfig,
+  jsonMode ? "--json" : "",
+  resolve(assistantRoot, "src"),
+]
+  .filter(Boolean)
+  .join(" ");
+
+try {
+  const output = execSync(cmd, {
+    cwd: assistantRoot,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  if (jsonMode) {
+    const cycles: string[][] = JSON.parse(output);
+    if (cycles.length > 0) {
+      console.log(JSON.stringify(cycles, null, 2));
+      console.error(`\n✗ Found ${cycles.length} circular dependency chain(s)`);
+      process.exit(1);
+    }
+  }
+
+  console.log("✓ No circular dependencies detected");
+  process.exit(0);
+} catch (error: unknown) {
+  const execError = error as {
+    stdout?: string;
+    stderr?: string;
+    status?: number;
+  };
+
+  // madge exits non-zero when it finds cycles
+  if (execError.stdout) {
+    if (jsonMode) {
+      try {
+        const cycles: string[][] = JSON.parse(execError.stdout);
+        console.log(JSON.stringify(cycles, null, 2));
+        console.error(
+          `\n✗ Found ${cycles.length} circular dependency chain(s)`,
+        );
+      } catch {
+        process.stdout.write(execError.stdout);
+      }
+    } else {
+      process.stdout.write(execError.stdout);
+    }
+  }
+
+  if (execError.stderr) {
+    process.stderr.write(execError.stderr);
+  }
+
+  process.exit(execError.status ?? 1);
+}

package/scripts/generate-openapi.ts

@@ -4,10 +4,9 @@
  * HTTP route definitions.
  *
  * Pipeline:
- *   1. Programmatically import and invoke all *RouteDefinitions() exports
- *      from src/runtime/routes/ — no regex, no source-text parsing.
- *   2. Combine with inline routes (defined in buildRouteTable()) and
- *      pre-auth / non-v1 routes.
+ *   1. Programmatically import every route module under src/runtime/routes/
+ *      and collect all exported ROUTES arrays — no regex, no source-text parsing.
+ *   2. Combine with pre-auth / non-v1 routes.
  *   3. Convert to OpenAPI path items.
  *   4. Write to openapi.yaml.
  *
@@ -83,9 +82,15 @@ const RouteEntrySchema = z.object({
   requestBody: RouteBodySchemaSchema.optional(),
   /** Multi-content-type request body variants (overrides `requestBody` when present). */
   requestBodies: z.array(RouteRequestBodyVariantSchema).optional(),
-  /** JSON Schema for the 200 response body. */
+  /** JSON Schema for the success response body. */
   responseBody: RouteBodySchemaSchema.optional(),
-  /** Extra non-200 responses documented in the spec. */
+  /** HTTP status code for the success response. Defaults to "200".
+   * Callable responseStatus values (used at runtime) are ignored here. */
+  responseStatus: z.preprocess(
+    (v) => (typeof v === "string" ? v : undefined),
+    z.string().optional(),
+  ),
+  /** Extra response codes documented in the spec. */
   additionalResponses: z
     .record(z.string(), RouteAdditionalResponseSchema)
     .optional(),
@@ -126,40 +131,12 @@ function toJSONSchemaObject(schema: unknown): JSONSchemaObject {
 // ---------------------------------------------------------------------------
 
 /**
- * Create a recursive proxy that stands in for any dependency object.
+ * Dynamically import every route module under `src/runtime/routes/`
+ * and collect all exported `ROUTES` arrays.
  *
- * Route definition functions capture deps in handler closures but never
- * access them during array construction, so this stub is never actually
- * invoked at runtime — it just needs to be truthy and not throw when
- * properties are read or the value is called as a function.
- */
-function createDeepStub(): unknown {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const stub: any = new Proxy(function () {}, {
-    get(_target, prop) {
-      // Prevent the stub from being treated as a Promise (await-able).
-      if (prop === "then") return undefined;
-      // Prevent infinite iteration.
-      if (prop === Symbol.iterator) return undefined;
-      // String coercion.
-      if (prop === Symbol.toPrimitive) return () => "";
-      return createDeepStub();
-    },
-    apply() {
-      return createDeepStub();
-    },
-  });
-  return stub;
-}
-
-/**
- * Dynamically import every route module under `src/runtime/routes/`,
- * find all exported functions whose names end with `RouteDefinitions`,
- * invoke each with a deep stub as its first argument, and collect the
- * `{ endpoint, method }` pairs from the returned arrays.
- *
- * This replaces the previous regex + balanced-brace scanning approach
- * and automatically picks up new route modules without manual updates.
+ * Each route module is expected to export a `ROUTES: RouteDefinition[]`
+ * constant. The function automatically picks up new route modules
+ * without manual updates.
  */
 async function collectRoutesFromModules(): Promise<RouteEntry[]> {
   const routes: RouteEntry[] = [];
@@ -185,30 +162,13 @@ async function collectRoutesFromModules(): Promise<RouteEntry[]> {
       continue;
     }
 
-    for (const [exportName, exportValue] of Object.entries(mod)) {
-      if (
-        !exportName.endsWith("RouteDefinitions") ||
-        typeof exportValue !== "function"
-      ) {
-        continue;
-      }
-
-      try {
-        const rawDefs = exportValue(createDeepStub());
-        if (!Array.isArray(rawDefs)) continue;
-        for (const raw of rawDefs) {
-          const result = RouteEntrySchema.safeParse({
-            ...(typeof raw === "object" && raw !== null ? raw : {}),
-            sourceModule: file,
-          });
-          if (result.success) {
-            routes.push(result.data);
-          }
-        }
-      } catch (err) {
-        console.warn(
-          `Warning: ${exportName}() in ${file} threw: ${err instanceof Error ? err.message : err}`,
-        );
+    if ("ROUTES" in mod && Array.isArray(mod.ROUTES)) {
+      for (const raw of mod.ROUTES) {
+        const result = RouteEntrySchema.safeParse({
+          ...(typeof raw === "object" && raw !== null ? raw : {}),
+          sourceModule: file,
+        });
+        if (result.success) routes.push(result.data);
       }
     }
   }
@@ -216,43 +176,6 @@ async function collectRoutesFromModules(): Promise<RouteEntry[]> {
   return routes;
 }
 
-/**
- * Routes defined inline in RuntimeHttpServer.buildRouteTable() that are
- * not exported from any route module. These are kept here because they
- * depend on cross-cutting concerns specific to the RuntimeHttpServer
- * instance (see B2 in the improvement plan for the recommendation to
- * extract these into modules).
- *
- * Whenever buildRouteTable() gains or loses an inline route, this list
- * must be updated manually. Note: `--check` only compares the generated
- * YAML against the committed YAML, so it will NOT catch a missing entry
- * here if openapi.yaml is also stale. Plan items B2/C2 address this gap.
- */
-const INLINE_ROUTES: RouteEntry[] = [
-  { endpoint: "conversations", method: "GET" },
-  { endpoint: "conversations/seen", method: "POST" },
-  { endpoint: "conversations/unread", method: "POST" },
-  { endpoint: "conversations/:id", method: "GET" },
-  { endpoint: "interfaces/:path*", method: "GET" },
-  { endpoint: "internal/twilio/voice-webhook", method: "POST" },
-  { endpoint: "internal/twilio/status", method: "POST" },
-  { endpoint: "internal/twilio/connect-action", method: "POST" },
-  { endpoint: "internal/oauth/callback", method: "POST" },
-];
-
-/**
- * Pre-auth routes handled directly in routeRequest() before the router.
- * These are a small, stable set that bypass JWT authentication and are
- * not part of the declarative route table.
- */
-const PRE_AUTH_ROUTES: RouteEntry[] = [
-  { method: "GET", endpoint: "audio/:id" },
-  { method: "POST", endpoint: "guardian/init" },
-  { method: "POST", endpoint: "guardian/refresh" },
-  { method: "POST", endpoint: "pairing/request" },
-  { method: "GET", endpoint: "pairing/status" },
-];
-
 /**
  * Top-level routes outside the /v1/ namespace.
  * These are added to the spec separately.
@@ -431,14 +354,17 @@ function buildSpec(
           ? [deriveTagFromModule(entry.sourceModule)]
           : undefined;
 
-    // Build the operation
+    // Build the operation. Default success status is 200; async endpoints
+    // that enqueue a job and return immediately set responseStatus: "202"
+    // so the generated spec matches the handler's actual response code.
+    const successStatus = entry.responseStatus ?? "200";
     const operation: OpenApiOperation = {
       operationId,
       ...(entry.summary ? { summary: entry.summary } : {}),
       ...(entry.description ? { description: entry.description } : {}),
       ...(tags ? { tags } : {}),
       responses: {
-        "200": entry.responseBody
+        [successStatus]: entry.responseBody
           ? {
               description: "Successful response",
               content: {
@@ -534,11 +460,7 @@ async function main() {
   const moduleRoutes = await collectRoutesFromModules();
 
   // Combine all route sources
-  const allRoutes: RouteEntry[] = [
-    ...PRE_AUTH_ROUTES,
-    ...INLINE_ROUTES,
-    ...moduleRoutes,
-  ];
+  const allRoutes: RouteEntry[] = moduleRoutes;
 
   // Build the spec
   const spec = buildSpec(allRoutes, version);

package/{src/memory/graph/inspect.ts → scripts/memory-inspect.ts}

@@ -2,27 +2,27 @@
 // Memory Graph — CLI inspection tool for testing
 //
 // Usage (from assistant/):
-//   bun run src/memory/graph/inspect.ts --stats
-//   bun run src/memory/graph/inspect.ts --context-load
-//   bun run src/memory/graph/inspect.ts --query "what does the user think about X"
-//   bun run src/memory/graph/inspect.ts --node <id>
-//   bun run src/memory/graph/inspect.ts --turn "user said this"
-//   bun run src/memory/graph/inspect.ts --bootstrap [--limit N] [--dry-run]
-//   bun run src/memory/graph/inspect.ts --bootstrap-journal
-//   bun run src/memory/graph/inspect.ts --decay
+//   bun run scripts/memory-inspect.ts --stats
+//   bun run scripts/memory-inspect.ts --context-load
+//   bun run scripts/memory-inspect.ts --query "what does the user think about X"
+//   bun run scripts/memory-inspect.ts --node <id>
+//   bun run scripts/memory-inspect.ts --turn "user said this"
+//   bun run scripts/memory-inspect.ts --bootstrap [--limit N] [--dry-run]
+//   bun run scripts/memory-inspect.ts --bootstrap-journal
+//   bun run scripts/memory-inspect.ts --decay
 // ---------------------------------------------------------------------------
 
-import { getConfig } from "../../config/loader.js";
-import { initializeDb } from "../db-init.js";
-import { initQdrantClient, resolveQdrantUrl } from "../qdrant-client.js";
+import { getConfig } from "../src/config/loader.js";
+import { initializeDb } from "../src/memory/db-init.js";
 import {
   countNodes,
   getEdgesForNode,
   getNode,
   getTriggersForNode,
   queryNodes,
-} from "./store.js";
-import type { ScoredNode } from "./types.js";
+} from "../src/memory/graph/store.js";
+import type { ScoredNode } from "../src/memory/graph/types.js";
+import { initQdrantClient, resolveQdrantUrl } from "../src/memory/qdrant-client.js";
 
 // Initialize DB and Qdrant before anything else
 initializeDb();
@@ -211,7 +211,7 @@ async function showStats() {
 }
 
 async function showContextLoad() {
-  const { loadContextMemory } = await import("./retriever.js");
+  const { loadContextMemory } = await import("../src/memory/graph/retriever.js");
 
   console.log("\n  Simulating context load (conversation start)...\n");
 
@@ -227,7 +227,7 @@ async function showContextLoad() {
   console.log(`  Triggered: ${result.triggeredNodes.length} triggers fired`);
 
   // Show assembled context
-  const { assembleContextBlock } = await import("./injection.js");
+  const { assembleContextBlock } = await import("../src/memory/graph/injection.js");
   const block = assembleContextBlock(result.nodes, {
     serendipityNodes: result.serendipityNodes,
   });
@@ -244,9 +244,9 @@ async function showContextLoad() {
 }
 
 async function showQuery(query: string) {
-  const { embedWithRetry } = await import("../embed.js");
-  const { searchGraphNodes } = await import("./graph-search.js");
-  const { getNodesByIds } = await import("./store.js");
+  const { embedWithRetry } = await import("../src/memory/embed.js");
+  const { searchGraphNodes } = await import("../src/memory/graph/graph-search.js");
+  const { getNodesByIds } = await import("../src/memory/graph/store.js");
 
   console.log(`\n  Searching: "${query}"\n`);
 
@@ -367,9 +367,9 @@ function showNode(nodeId: string) {
 }
 
 async function showTurn(userMessage: string) {
-  const { retrieveForTurn } = await import("./retriever.js");
-  const { InContextTracker } = await import("./injection.js");
-  const { assembleInjectionBlock } = await import("./injection.js");
+  const { retrieveForTurn } = await import("../src/memory/graph/retriever.js");
+  const { InContextTracker } = await import("../src/memory/graph/injection.js");
+  const { assembleInjectionBlock } = await import("../src/memory/graph/injection.js");
 
   const tracker = new InContextTracker();
 
@@ -399,7 +399,7 @@ async function showTurn(userMessage: string) {
 
 async function runBootstrap() {
   const { bootstrapFromHistory, resetBootstrapCheckpoint } =
-    await import("./bootstrap.js");
+    await import("../src/memory/graph/bootstrap.js");
 
   const limitIdx = args.indexOf("--limit");
   const limit = limitIdx >= 0 ? parseInt(args[limitIdx + 1], 10) : undefined;
@@ -440,7 +440,7 @@ async function runBootstrap() {
 }
 
 async function runJournalBootstrap() {
-  const { bootstrapFromJournal } = await import("./bootstrap.js");
+  const { bootstrapFromJournal } = await import("../src/memory/graph/bootstrap.js");
 
   console.log("\n  Extracting from journal files...\n");
   const result = await bootstrapFromJournal();
@@ -450,7 +450,7 @@ async function runJournalBootstrap() {
 }
 
 async function runConsolidate() {
-  const { runConsolidation } = await import("./consolidation.js");
+  const { runConsolidation } = await import("../src/memory/graph/consolidation.js");
   console.log("\n  Running consolidation...\n");
   const result = await runConsolidation("default", config);
   console.log(
@@ -469,7 +469,7 @@ async function runConsolidate() {
 }
 
 async function runPatterns() {
-  const { runPatternScan } = await import("./pattern-scan.js");
+  const { runPatternScan } = await import("../src/memory/graph/pattern-scan.js");
   console.log("\n  Running pattern scan...\n");
   const result = await runPatternScan("default", config);
   console.log(
@@ -481,7 +481,7 @@ async function runPatterns() {
 }
 
 async function runNarrative() {
-  const { runNarrativeRefinement } = await import("./narrative.js");
+  const { runNarrativeRefinement } = await import("../src/memory/graph/narrative.js");
   console.log("\n  Running narrative refinement...\n");
   const result = await runNarrativeRefinement("default", config);
   console.log(
@@ -502,7 +502,7 @@ async function runNarrative() {
 
 function runDecay() {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const { runDecayTick } = require("./decay.js") as typeof import("./decay.js");
+  const { runDecayTick } = require("../src/memory/graph/decay.js") as typeof import("../src/memory/graph/decay.js");
   console.log("\n  Running decay tick...\n");
   const result = runDecayTick("default");
   console.log(`  Nodes processed: ${result.nodesProcessed}`);

package/src/__tests__/access-request-decision.test.ts

@@ -35,7 +35,8 @@ mock.module("../runtime/gateway-client.js", () => ({
   },
 }));
 
-import { getDb, initializeDb } from "../memory/db.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
 import {
   createApprovalRequest,
   getApprovalRequestById,
@@ -218,7 +219,6 @@ describe("access request notification delivery", () => {
       requesterIdentifier: "user-unknown-456",
       verificationCode: "123456",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(result.ok).toBe(true);
@@ -240,7 +240,6 @@ describe("access request notification delivery", () => {
       requesterIdentifier: "user-unknown-456",
       verificationCode: "123456",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(result.ok).toBe(false);
@@ -256,7 +255,6 @@ describe("access request notification delivery", () => {
       replyCallbackUrl: "http://localhost:7830/deliver/telegram",
       requesterChatId: "chat-123",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -272,7 +270,6 @@ describe("access request notification delivery", () => {
       replyCallbackUrl: "http://localhost:7830/deliver/telegram",
       requesterChatId: "chat-123",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -287,7 +284,6 @@ describe("access request notification delivery", () => {
       replyCallbackUrl: "http://localhost:7830/deliver/telegram",
       requesterChatId: "chat-123",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -307,7 +303,6 @@ describe("access request notification delivery", () => {
       requesterExternalUserId: "U98765-user",
       channel: "slack",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -326,7 +321,6 @@ describe("access request notification delivery", () => {
       requesterExternalUserId: "U98765-user",
       channel: "slack",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -343,7 +337,6 @@ describe("access request notification delivery", () => {
       requesterExternalUserId: "U98765-user",
       channel: "slack",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -360,7 +353,6 @@ describe("access request notification delivery", () => {
       requesterExternalUserId: "user-456",
       channel: "telegram",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);
@@ -375,7 +367,6 @@ describe("access request notification delivery", () => {
       requesterChatId: "C12345-channel",
       channel: "slack",
       assistantId: "self",
-      bearerToken: "test-token",
     });
 
     expect(deliverReplyCalls.length).toBe(1);