@vellumai/assistant 0.7.0 → 0.7.2

package/src/memory/v2/edges.ts

@@ -1,217 +0,0 @@
-/**
- * Memory v2 — `memory/edges.json` read/write and neighbor resolution.
- *
- * This module is the sole owner of the `memory/edges.json` file. The edges
- * index is the source of truth for v2 graph topology — concept-page
- * frontmatter only mirrors a derived view of it.
- *
- * Edges are unweighted, undirected, and stored as canonicalized 2-tuples
- * (alphabetically-first slug first). Self-loops are rejected at write time.
- *
- * Writes are atomic (write to `<file>.tmp-<uuid>`, then `rename(2)` onto the
- * destination) so a crashed writer never leaves a torn JSON file behind —
- * readers always see either the previous or the new index.
- */
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-
-import type { EdgesIndex } from "./types.js";
-import { EdgesIndexSchema } from "./types.js";
-
-const EDGES_FILENAME = "edges.json";
-
-/** Path to `memory/edges.json` inside `workspaceDir`. */
-function edgesPath(workspaceDir: string): string {
-  return join(workspaceDir, "memory", EDGES_FILENAME);
-}
-
-/**
- * Canonicalize a single tuple so `[a, b]` and `[b, a]` collapse to the same
- * representation. Keeps writes deterministic regardless of caller order.
- */
-function canonicalTuple(a: string, b: string): [string, string] {
-  return a <= b ? [a, b] : [b, a];
-}
-
-/** Stable string key for a canonical tuple, used for de-duplication. */
-function tupleKey(t: readonly [string, string]): string {
-  return `${t[0]}\u0000${t[1]}`;
-}
-
-/**
- * Read `memory/edges.json` and validate it against `EdgesIndexSchema`.
- * Returns the canonical empty index when the file is missing.
- *
- * Any JSON parse error or schema-validation failure throws — the file should
- * never be silently quarantined, since a broken edges.json signals a bug in
- * a writer or external tampering.
- */
-export async function readEdges(workspaceDir: string): Promise<EdgesIndex> {
-  let raw: string;
-  try {
-    raw = await readFile(edgesPath(workspaceDir), "utf-8");
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      return { version: 1, edges: [] };
-    }
-    throw err;
-  }
-  const parsed = JSON.parse(raw);
-  return EdgesIndexSchema.parse(parsed);
-}
-
-/**
- * Write `memory/edges.json` atomically. The on-disk tuples are canonicalized
- * and de-duplicated before serialization, so the output is independent of
- * insertion order and free of redundant pairs.
- *
- * Atomicity: bytes are written to a sibling temp file then renamed onto the
- * destination. `rename(2)` on the same filesystem is atomic, so a reader
- * concurrent with the writer sees either the prior file or the new one in
- * full — never a partial write.
- */
-export async function writeEdges(
-  workspaceDir: string,
-  idx: EdgesIndex,
-): Promise<void> {
-  const canonical = canonicalizeIndex(idx);
-  const finalPath = edgesPath(workspaceDir);
-  await mkdir(dirname(finalPath), { recursive: true });
-  const tmpPath = `${finalPath}.tmp-${randomUUID()}`;
-  const body = `${JSON.stringify(canonical, null, 2)}\n`;
-  await writeFile(tmpPath, body, "utf-8");
-  await rename(tmpPath, finalPath);
-}
-
-/**
- * Pure helper: return a new index with `(a, b)` added (canonicalized). If the
- * edge already exists the index is returned unchanged. Self-loops are
- * rejected — concept-page graphs are simple graphs.
- */
-export function addEdge(idx: EdgesIndex, a: string, b: string): EdgesIndex {
-  if (a === b) {
-    throw new Error(`addEdge: refusing to add self-loop on slug "${a}"`);
-  }
-  const tuple = canonicalTuple(a, b);
-  const key = tupleKey(tuple);
-  for (const existing of idx.edges) {
-    if (tupleKey(canonicalTuple(existing[0], existing[1])) === key) {
-      return idx;
-    }
-  }
-  return { version: idx.version, edges: [...idx.edges, tuple] };
-}
-
-/**
- * Pure helper: return a new index with `(a, b)` removed (matched on its
- * canonical form). No-op if the edge is not present.
- */
-export function removeEdge(idx: EdgesIndex, a: string, b: string): EdgesIndex {
-  const target = tupleKey(canonicalTuple(a, b));
-  const filtered = idx.edges.filter(
-    ([x, y]) => tupleKey(canonicalTuple(x, y)) !== target,
-  );
-  if (filtered.length === idx.edges.length) return idx;
-  return { version: idx.version, edges: filtered };
-}
-
-/**
- * Iterative BFS over the undirected edge graph starting at `slug`. Returns
- * every slug reachable within `hops` edges, *excluding* the start slug. An
- * orphan node (or unknown slug) yields the empty set.
- *
- * `hops` is clamped at 0 — a non-positive value collapses to an immediate
- * empty result so callers never need to special-case it.
- */
-export function getNeighbors(
-  idx: EdgesIndex,
-  slug: string,
-  hops: number,
-): Set<string> {
-  const result = new Set<string>();
-  if (hops <= 0) return result;
-
-  const adjacency = buildAdjacency(idx);
-  const visited = new Set<string>([slug]);
-  let frontier: string[] = [slug];
-
-  for (let depth = 0; depth < hops && frontier.length > 0; depth++) {
-    const next: string[] = [];
-    for (const node of frontier) {
-      const neighbors = adjacency.get(node);
-      if (!neighbors) continue;
-      for (const neighbor of neighbors) {
-        if (visited.has(neighbor)) continue;
-        visited.add(neighbor);
-        result.add(neighbor);
-        next.push(neighbor);
-      }
-    }
-    frontier = next;
-  }
-
-  return result;
-}
-
-/**
- * Validate an edges index against a known set of concept-page slugs. Returns
- * the unique list of endpoints that are referenced by an edge but missing
- * from `knownSlugs`. `ok` mirrors `missing.length === 0` for caller
- * convenience.
- */
-export function validateEdges(
-  idx: EdgesIndex,
-  knownSlugs: Set<string>,
-): { ok: boolean; missing: string[] } {
-  const missing = new Set<string>();
-  for (const [a, b] of idx.edges) {
-    if (!knownSlugs.has(a)) missing.add(a);
-    if (!knownSlugs.has(b)) missing.add(b);
-  }
-  const list = [...missing].sort();
-  return { ok: list.length === 0, missing: list };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Canonicalize tuples + dedup, returning a deterministically-sorted index.
- * Self-loops are dropped silently here (writer-side) so a malformed in-memory
- * value can still be persisted as a clean file.
- */
-function canonicalizeIndex(idx: EdgesIndex): EdgesIndex {
-  const seen = new Map<string, [string, string]>();
-  for (const [a, b] of idx.edges) {
-    if (a === b) continue;
-    const tuple = canonicalTuple(a, b);
-    seen.set(tupleKey(tuple), tuple);
-  }
-  // Sort by canonical key (NUL-separated) — gives a lexicographic order on
-  // the (left, right) pair without a multi-clause comparator.
-  const tuples = [...seen.entries()]
-    .sort(([keyX], [keyY]) => (keyX < keyY ? -1 : keyX > keyY ? 1 : 0))
-    .map(([, tuple]) => tuple);
-  return { version: idx.version, edges: tuples };
-}
-
-/** Build slug → neighbors map from canonicalized tuples (undirected). */
-function buildAdjacency(idx: EdgesIndex): Map<string, Set<string>> {
-  const adjacency = new Map<string, Set<string>>();
-  const ensure = (slug: string): Set<string> => {
-    let set = adjacency.get(slug);
-    if (!set) {
-      set = new Set<string>();
-      adjacency.set(slug, set);
-    }
-    return set;
-  };
-  for (const [a, b] of idx.edges) {
-    if (a === b) continue;
-    ensure(a).add(b);
-    ensure(b).add(a);
-  }
-  return adjacency;
-}

package/src/outbound-proxy/config.ts

@@ -1,94 +0,0 @@
-/**
- * Configuration for the standalone proxy sidecar server.
- *
- * All values are sourced from environment variables with sensible defaults.
- * Invalid values cause the process to exit with a descriptive error so
- * misconfigurations are caught immediately at startup.
- */
-
-export interface SidecarConfig {
-  /** Port the proxy server listens on. */
-  port: number;
-  /** Host address to bind to. */
-  host: string;
-  /** Port for the health/readiness HTTP server. */
-  healthPort: number;
-  /** Optional CA directory for MITM interception (contains ca.pem / ca-key.pem). */
-  caDir: string | null;
-  /** Log level for the sidecar process. */
-  logLevel: "debug" | "info" | "warn" | "error";
-}
-
-/**
- * Parse and validate sidecar configuration from environment variables.
- *
- * Environment variables:
- *   PROXY_PORT            - Port to listen on (default: 8080)
- *   PROXY_HOST            - Host to bind to (default: "0.0.0.0")
- *   PROXY_HEALTH_PORT     - Port for health/readiness endpoints (default: 8081)
- *   PROXY_CA_DIR          - Path to CA directory for MITM (optional)
- *   PROXY_LOG_LEVEL       - Log level: debug | info | warn | error (default: "info")
- */
-export function loadConfig(
-  env: Record<string, string | undefined> = process.env,
-): SidecarConfig {
-  const port = parsePort(env.PROXY_PORT, "PROXY_PORT");
-  const defaultHealthPort = port === 8081 ? 8082 : 8081;
-  const healthPort = parsePort(
-    env.PROXY_HEALTH_PORT,
-    "PROXY_HEALTH_PORT",
-    defaultHealthPort,
-  );
-  if (healthPort === port) {
-    throw new ConfigError(
-      `PROXY_HEALTH_PORT (${healthPort}) must differ from PROXY_PORT (${port})`,
-    );
-  }
-  const host = env.PROXY_HOST ?? "0.0.0.0";
-  const caDir = env.PROXY_CA_DIR ?? null;
-  const logLevel = parseLogLevel(env.PROXY_LOG_LEVEL);
-
-  return { port, host, healthPort, caDir, logLevel };
-}
-
-function parsePort(
-  raw: string | undefined,
-  envName: string = "PROXY_PORT",
-  defaultPort: number = 8080,
-): number {
-  if (raw === undefined || raw === "") return defaultPort;
-
-  const port = Number(raw);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new ConfigError(
-      `${envName} must be an integer between 1 and 65535, got "${raw}"`,
-    );
-  }
-  return port;
-}
-
-const VALID_LOG_LEVELS = new Set(["debug", "info", "warn", "error"] as const);
-type LogLevel = "debug" | "info" | "warn" | "error";
-
-function parseLogLevel(raw: string | undefined): LogLevel {
-  if (raw === undefined || raw === "") return "info";
-
-  const lower = raw.toLowerCase();
-  if (!VALID_LOG_LEVELS.has(lower as LogLevel)) {
-    throw new ConfigError(
-      `PROXY_LOG_LEVEL must be one of debug, info, warn, error — got "${raw}"`,
-    );
-  }
-  return lower as LogLevel;
-}
-
-/**
- * Dedicated error class for configuration validation failures.
- * The entrypoint catches this to print a clean message without a stack trace.
- */
-export class ConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ConfigError";
-  }
-}

package/src/outbound-proxy/health.ts

@@ -1,62 +0,0 @@
-/**
- * Health / readiness HTTP server for the proxy sidecar.
- *
- * Exposes two endpoints on a separate control port:
- *   GET /healthz  - Liveness probe. Returns 200 whenever the process is alive.
- *   GET /readyz   - Readiness probe. Returns 200 only when the proxy server
- *                   is listening and ready to accept connections.
- *
- * All other paths return 404. Non-GET methods return 405.
- */
-
-import { createServer, type Server } from "node:http";
-
-export interface HealthServerOptions {
-  /**
-   * Callback that returns `true` when the proxy server is ready to accept
-   * connections. The readiness probe delegates to this function.
-   */
-  isReady: () => boolean;
-}
-
-/**
- * Create an HTTP server that serves health and readiness endpoints.
- *
- * The returned server is not yet listening -- the caller is responsible for
- * calling `.listen()`.
- */
-export function createHealthServer(options: HealthServerOptions): Server {
-  const { isReady } = options;
-
-  const server = createServer((req, res) => {
-    // Only support GET requests
-    if (req.method !== "GET") {
-      res.writeHead(405, { "Content-Type": "text/plain", Allow: "GET" });
-      res.end("Method Not Allowed\n");
-      return;
-    }
-
-    switch (req.url) {
-      case "/healthz": {
-        res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok" }));
-        return;
-      }
-
-      case "/readyz": {
-        const ready = isReady();
-        const statusCode = ready ? 200 : 503;
-        res.writeHead(statusCode, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: ready ? "ready" : "not_ready" }));
-        return;
-      }
-
-      default: {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("Not Found\n");
-      }
-    }
-  });
-
-  return server;
-}

package/src/outbound-proxy/types.ts

@@ -1,150 +0,0 @@
-/** How a credential value is injected into an outbound proxied request. */
-export type CredentialInjectionType = "header" | "query";
-
-/**
- * Describes where and how to inject a credential into proxied requests
- * matching a specific host pattern.
- */
-export interface CredentialInjectionTemplate {
-  /** Glob pattern for matching request hosts (e.g. "*.fal.ai"). */
-  hostPattern: string;
-  /** Where the credential value is injected. */
-  injectionType: CredentialInjectionType;
-  /** Header name when injectionType is 'header' (e.g. "Authorization"). */
-  headerName?: string;
-  /** Prefix prepended to the secret value (e.g. "Key ", "Bearer "). */
-  valuePrefix?: string;
-  /** Query parameter name when injectionType is 'query'. */
-  queryParamName?: string;
-}
-
-/** Unique identifier for a proxy session. */
-export type ProxySessionId = string;
-
-export type ProxySessionStatus = "starting" | "active" | "stopping" | "stopped";
-
-export interface ProxySession {
-  id: ProxySessionId;
-  conversationId: string;
-  credentialIds: string[];
-  status: ProxySessionStatus;
-  createdAt: Date;
-  /** Ephemeral port assigned once the session starts listening. */
-  port: number | null;
-}
-
-export interface ProxySessionConfig {
-  /** How long (ms) an idle session stays alive before auto-stopping. */
-  idleTimeoutMs: number;
-  /** Maximum concurrent sessions per conversation. */
-  maxSessionsPerConversation: number;
-}
-
-export interface ProxyEnvVars {
-  HTTP_PROXY: string;
-  HTTPS_PROXY: string;
-  NO_PROXY: string;
-  NODE_EXTRA_CA_CERTS?: string;
-  /** Combined CA bundle (system roots + proxy CA) for non-Node TLS clients (curl, Python, etc.). */
-  SSL_CERT_FILE?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Policy engine types
-// ---------------------------------------------------------------------------
-
-/** A single credential matched -- inject it. */
-export interface PolicyDecisionMatched {
-  kind: "matched";
-  credentialId: string;
-  template: CredentialInjectionTemplate;
-}
-
-/** Multiple credentials match -- caller must disambiguate. */
-export interface PolicyDecisionAmbiguous {
-  kind: "ambiguous";
-  candidates: Array<{
-    credentialId: string;
-    template: CredentialInjectionTemplate;
-  }>;
-}
-
-/** No credential matches the target host/path. */
-export interface PolicyDecisionMissing {
-  kind: "missing";
-}
-
-/** No credential_ids were requested -- pass-through. */
-export interface PolicyDecisionUnauthenticated {
-  kind: "unauthenticated";
-}
-
-// ---------------------------------------------------------------------------
-// Approval hook outcomes -- structured data for triggering permission prompts.
-// ---------------------------------------------------------------------------
-
-/** Context about the outbound request target, used to build permission prompts. */
-export interface RequestTargetContext {
-  hostname: string;
-  port: number | null;
-  path: string;
-  /** The protocol scheme of the original request ('http' or 'https'). */
-  scheme: "http" | "https";
-}
-
-/**
- * The target host matches a known credential template pattern, but the
- * session has no credential bound for it. The UI should prompt the user
- * to bind or create a credential.
- */
-export interface PolicyDecisionAskMissingCredential {
-  kind: "ask_missing_credential";
-  target: RequestTargetContext;
-  /** Host patterns from the known registry that matched the target. */
-  matchingPatterns: string[];
-}
-
-/**
- * The request doesn't match any known credential template and the session
- * has no credentials. The UI should prompt the user to allow or deny the
- * unauthenticated request.
- */
-export interface PolicyDecisionAskUnauthenticated {
-  kind: "ask_unauthenticated";
-  target: RequestTargetContext;
-}
-
-export type PolicyDecision =
-  | PolicyDecisionMatched
-  | PolicyDecisionAmbiguous
-  | PolicyDecisionMissing
-  | PolicyDecisionUnauthenticated
-  | PolicyDecisionAskMissingCredential
-  | PolicyDecisionAskUnauthenticated;
-
-// ---------------------------------------------------------------------------
-// Proxy approval callback -- wires policy "ask" decisions to the UI prompter.
-// ---------------------------------------------------------------------------
-
-/**
- * Payload passed to the approval callback when the policy engine emits an
- * `ask_missing_credential` or `ask_unauthenticated` decision. Contains
- * enough context for the prompter to build a meaningful confirmation dialog.
- */
-export interface ProxyApprovalRequest {
-  /** The policy decision that triggered the approval prompt. */
-  decision:
-    | PolicyDecisionAskMissingCredential
-    | PolicyDecisionAskUnauthenticated;
-  /** The proxy session ID that originated the request. */
-  sessionId: ProxySessionId;
-}
-
-/**
- * Callback signature for proxy approval prompts. The proxy service calls
- * this when an outbound request requires user confirmation. Returns `true`
- * if the user approves, `false` if denied.
- */
-export type ProxyApprovalCallback = (
-  request: ProxyApprovalRequest,
-) => Promise<boolean>;