@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/mcp/mcp-session-store.ts

@@ -1,162 +0,0 @@
-/**
- * In-memory mapping from MCP session id → { userId, tokenId }. Each entry
- * represents one MCP client connection's worth of state: the Bevel user the
- * Bearer token resolved to at `initialize`, and the connection-key id for
- * metering. Conversation continuity is the caller's own (a continuity-aware
- * tool like `ask` returns its `sessionId` in the result and the caller echoes
- * it back); thread/workspace bookkeeping lives on the REST tool surface.
- *
- * Eviction is lazy: each `get` / `touch` sweeps idle entries before the
- * lookup, and `put` enforces the size cap before insert. No background
- * timer — keeps the store cheap to construct and avoids leaking a setInterval
- * handle in tests.
- *
- * Single-replica only. If we add a second backend instance later, sessions
- * need to be persisted (see docs/mcp-remote-access.md → "Out of scope"). The
- * MCP protocol tolerates this — a 404 on an unknown session id is a defined
- * response, and clients re-initialize.
- */
-
-export interface McpSession {
-  sessionId: string;
-  userId: string;
-  /**
-   * The connection-key id this session authenticated with, or null when the
-   * session was opened with a browser JWT (no connection key). Captured at
-   * `initialize` so every `ask_bevel_agent` call in the session can be metered
-   * against that key's daily token cap.
-   */
-  tokenId: string | null;
-  createdAt: number;
-  lastTouchedAt: number;
-}
-
-export interface McpSessionStoreOptions {
-  /** Drop sessions idle for longer than this. Default: 4 hours. */
-  idleTtlMs?: number;
-  /** Hard cap on simultaneous live sessions. Oldest-touched evicted first. */
-  maxSessions?: number;
-  /** Override `Date.now` — injected only by tests. */
-  now?: () => number;
-}
-
-const DEFAULT_IDLE_TTL_MS = 4 * 60 * 60 * 1000;
-const DEFAULT_MAX_SESSIONS = 5000;
-
-export class McpSessionStore {
-  private readonly sessions = new Map<string, McpSession>();
-  private readonly idleTtlMs: number;
-  private readonly maxSessions: number;
-  private readonly now: () => number;
-  // Subscribers notified whenever a session is dropped by the store itself
-  // (idle TTL sweep or size-cap eviction). NOT fired by explicit `delete()` —
-  // the caller of `delete` already knows the session is gone, and the route
-  // layer uses `delete` *because* it's already cleaning up.
-  //
-  // Callbacks are invoked synchronously; long-running cleanup (e.g.
-  // `transport.close()`) should be fire-and-forget so a slow listener can't
-  // block the next eviction.
-  private readonly evictListeners = new Set<(sessionId: string) => void>();
-
-  constructor(opts: McpSessionStoreOptions = {}) {
-    this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
-    this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
-    this.now = opts.now ?? Date.now;
-  }
-
-  /**
-   * Subscribe to eviction events. Returns an unsubscribe function so callers
-   * can clean up in test teardown. The route layer uses this to drop the
-   * transport-state entry in its `active` map and close the underlying SDK
-   * transport when the store decides a session has aged out.
-   */
-  onEvict(listener: (sessionId: string) => void): () => void {
-    this.evictListeners.add(listener);
-    return () => {
-      this.evictListeners.delete(listener);
-    };
-  }
-
-  /**
-   * Register a fresh MCP session. Caller supplies the id (generated by the
-   * SDK's transport). Evicts the oldest-touched session if the cap is hit
-   * — better than refusing the connection, since a wedged old session is
-   * the most likely cause of a full table.
-   */
-  create(sessionId: string, userId: string, tokenId: string | null = null): McpSession {
-    this.sweep();
-    if (this.sessions.size >= this.maxSessions) {
-      this.evictOldest();
-    }
-    const now = this.now();
-    const session: McpSession = {
-      sessionId,
-      userId,
-      tokenId,
-      createdAt: now,
-      lastTouchedAt: now,
-    };
-    this.sessions.set(sessionId, session);
-    return session;
-  }
-
-  /**
-   * Look up a session and bump its `lastTouchedAt`. Returns null when the
-   * session is unknown or has aged out. Sweep runs first so an aged entry
-   * is collected, not silently revived.
-   */
-  get(sessionId: string): McpSession | null {
-    this.sweep();
-    const session = this.sessions.get(sessionId);
-    if (!session) return null;
-    session.lastTouchedAt = this.now();
-    return session;
-  }
-
-  delete(sessionId: string): void {
-    this.sessions.delete(sessionId);
-  }
-
-  /** Visible size; useful for diagnostics. Does not sweep. */
-  size(): number {
-    return this.sessions.size;
-  }
-
-  private sweep(): void {
-    const cutoff = this.now() - this.idleTtlMs;
-    for (const [id, s] of this.sessions) {
-      if (s.lastTouchedAt < cutoff) {
-        this.sessions.delete(id);
-        this.emitEviction(id);
-      }
-    }
-  }
-
-  private evictOldest(): void {
-    let oldestId: string | null = null;
-    let oldestTouched = Infinity;
-    for (const [id, s] of this.sessions) {
-      if (s.lastTouchedAt < oldestTouched) {
-        oldestTouched = s.lastTouchedAt;
-        oldestId = id;
-      }
-    }
-    if (oldestId) {
-      this.sessions.delete(oldestId);
-      this.emitEviction(oldestId);
-    }
-  }
-
-  private emitEviction(sessionId: string): void {
-    for (const listener of this.evictListeners) {
-      try {
-        listener(sessionId);
-      } catch (err) {
-        // A misbehaving listener must not stop the sweep from finishing —
-        // otherwise one bad subscriber would block the rest of the eviction
-        // pass and leak more sessions.
-        console.warn('[mcp-session-store] eviction listener threw:', err);
-      }
-    }
-  }
-}

package/src/shared/__tests__/fs-walk.test.ts

@@ -1,63 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import os from 'node:os';
-import { walkFiles } from '../fs-walk.js';
-
-describe('walkFiles', () => {
-  let root: string;
-
-  beforeEach(async () => {
-    root = await fs.mkdtemp(path.join(os.tmpdir(), 'fs-walk-'));
-  });
-  afterEach(async () => {
-    await fs.rm(root, { recursive: true, force: true });
-  });
-
-  it('returns [] for a missing root', async () => {
-    expect(await walkFiles(path.join(root, 'nope'), () => true)).toEqual([]);
-  });
-
-  it('walks nested directories, filters by basename, and sorts the result', async () => {
-    await fs.mkdir(path.join(root, 'b/deep'), { recursive: true });
-    await fs.mkdir(path.join(root, 'a'), { recursive: true });
-    await fs.writeFile(path.join(root, 'b/deep/z.tool'), '');
-    await fs.writeFile(path.join(root, 'a/y.tool'), '');
-    await fs.writeFile(path.join(root, 'a/skip.md'), '');
-    await fs.writeFile(path.join(root, 'x.tool'), '');
-
-    const found = await walkFiles(root, (n) => n.endsWith('.tool'));
-    // Relative `/`-separated paths, sorted, only matching basenames.
-    expect(found).toEqual(['a/y.tool', 'b/deep/z.tool', 'x.tool']);
-  });
-
-  it('skips dot-prefixed entries — files AND whole directories (.git)', async () => {
-    await fs.mkdir(path.join(root, '.git/objects'), { recursive: true });
-    await fs.writeFile(path.join(root, '.git/objects/a.tool'), '');
-    await fs.writeFile(path.join(root, '.hidden.tool'), '');
-    await fs.writeFile(path.join(root, 'visible.tool'), '');
-
-    expect(await walkFiles(root, (n) => n.endsWith('.tool'))).toEqual(['visible.tool']);
-  });
-
-  it('skips a directory it cannot list by default, and throws for a strict caller', async () => {
-    await fs.mkdir(path.join(root, 'locked'), { recursive: true });
-    await fs.writeFile(path.join(root, 'locked/a.tool'), '');
-    await fs.writeFile(path.join(root, 'b.tool'), '');
-    const real = fs.readdir;
-    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) => {
-      if (String(dir).endsWith('locked')) {
-        return Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }));
-      }
-      return (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts);
-    }) as never);
-    try {
-      // A catalog shows what it can…
-      expect(await walkFiles(root, (n) => n.endsWith('.tool'))).toEqual(['b.tool']);
-      // …a caller that must see everything gets the error, not a list with a hole.
-      await expect(walkFiles(root, (n) => n.endsWith('.tool'), { strict: true })).rejects.toThrow('EACCES');
-    } finally {
-      spy.mockRestore();
-    }
-  });
-});

package/src/shared/__tests__/kb-walk.test.ts

@@ -1,107 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import os from 'node:os';
-import { walkKb, type KbWalkListener } from '../kb-walk.js';
-
-/**
- * The one walk: what it skips, in what order it visits, what it calls a hole
- * — and that every listener on it is told exactly the same things.
- */
-describe('walkKb', () => {
-  let root: string;
-  const write = async (rel: string, text = '') => {
-    const abs = path.join(root, rel);
-    await fs.mkdir(path.dirname(abs), { recursive: true });
-    await fs.writeFile(abs, text);
-  };
-  /** A listener that records every event it is told, in order. */
-  const recorder = () => {
-    const events: string[] = [];
-    const listener: KbWalkListener = {
-      onDir: (rel, entries) => void events.push(`dir ${rel || '.'} [${entries.map((e) => e.name).join(' ')}]`),
-      onFile: (dir, name) => void events.push(`file ${dir ? `${dir}/${name}` : name}`),
-      onHole: (rel) => void events.push(`hole ${rel || '.'}`),
-    };
-    return { events, listener };
-  };
-
-  beforeEach(async () => {
-    root = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-walk-'));
-  });
-  afterEach(() => fs.rm(root, { recursive: true, force: true }));
-
-  it('visits every folder once, in component order, skipping dot-entries and node_modules', async () => {
-    await write('Plugins/a-b/plugin.json');
-    await write('Plugins/a/b/plugin.json');
-    await write('KnowledgeBase/x.md');
-    await write('.git/HEAD');
-    await write('node_modules/dep/index.js');
-    await write('Plugins/.parked/plugin.json');
-    const { events, listener } = recorder();
-    const { holes } = await walkKb(root, [listener]);
-    expect(holes).toEqual([]);
-    expect(events).toEqual([
-      'dir . [KnowledgeBase Plugins]',
-      'dir KnowledgeBase [x.md]',
-      'file KnowledgeBase/x.md',
-      'dir Plugins [a a-b]', // "a" before "a-b": the walk order every consumer agrees on
-      'dir Plugins/a [b]',
-      'dir Plugins/a/b [plugin.json]',
-      'file Plugins/a/b/plugin.json',
-      'dir Plugins/a-b [plugin.json]',
-      'file Plugins/a-b/plugin.json',
-    ]);
-  });
-
-  it('tells every listener the same things', async () => {
-    await write('Plugins/GTM/plugin.json');
-    await write('Skills/Eng/deploy/SKILL.md');
-    const a = recorder();
-    const b = recorder();
-    await walkKb(root, [a.listener, b.listener]);
-    expect(a.events.length).toBeGreaterThan(0);
-    expect(b.events).toEqual(a.events);
-  });
-
-  it('a folder that exists but cannot be listed is a hole — reported to every listener and in the result', async () => {
-    await write('Plugins/locked/plugin.json');
-    await write('Plugins/open/plugin.json');
-    const real = fs.readdir;
-    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) =>
-      String(dir).endsWith('locked')
-        ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
-        : (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts)) as never);
-    try {
-      const { events, listener } = recorder();
-      const { holes } = await walkKb(root, [listener]);
-      expect(holes).toEqual(['Plugins/locked']);
-      expect(events).toContain('hole Plugins/locked');
-      // The rest of the tree is still walked.
-      expect(events).toContain('file Plugins/open/plugin.json');
-    } finally {
-      spy.mockRestore();
-    }
-  });
-
-  it('a missing root is an empty walk; a folder that vanished between listing and visiting is not a hole', async () => {
-    const empty = recorder();
-    expect(await walkKb(path.join(root, 'nope'), [empty.listener])).toEqual({ holes: [] });
-    expect(empty.events).toEqual([]);
-
-    await write('Plugins/gone/plugin.json');
-    const real = fs.readdir;
-    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) =>
-      String(dir).endsWith('gone')
-        ? Promise.reject(Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' }))
-        : (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts)) as never);
-    try {
-      const { events, listener } = recorder();
-      const { holes } = await walkKb(root, [listener]);
-      expect(holes).toEqual([]);
-      expect(events.some((e) => e.startsWith('hole'))).toBe(false);
-    } finally {
-      spy.mockRestore();
-    }
-  });
-});

package/src/shared/fs-errors.ts

@@ -1,10 +0,0 @@
-/**
- * Whether a filesystem error means "there is no such path" — the one failure
- * a reader may treat as an ordinary answer. Everything else (permissions,
- * I/O, a loop) is a failure to READ what is there, and a caller that folds
- * it into absence turns an outage into a wrong answer.
- */
-export function isAbsence(err: unknown): boolean {
-  const code = (err as { code?: unknown } | null)?.code;
-  return code === 'ENOENT' || code === 'ENOTDIR';
-}

package/src/shared/fs-walk.ts

@@ -1,45 +0,0 @@
-import { walkKb, isSkippedEntry } from './kb-walk.js';
-
-export { isSkippedEntry };
-
-/**
- * The file listing catalog scanners want, on top of {@link walkKb}: relative
- * (`/`-separated, sorted) paths of files under `root` whose basename matches.
- * A missing root yields `[]`; skipped entries are never entered.
- *
- * A directory that cannot be listed is SKIPPED by default — right for a
- * catalog, which shows what it can. A caller that must see EVERYTHING or
- * nothing passes `strict`, and the listing throws a {@link WalkError} naming
- * the directory instead: a list with a hole in it is not a list of every
- * file, and the caller can say WHICH hole rather than pass a raw errno up.
- */
-export async function walkFiles(
-  root: string,
-  match: (basename: string) => boolean,
-  opts: { strict?: boolean } = {},
-): Promise<string[]> {
-  const out: string[] = [];
-  await walkKb(root, [
-    {
-      onFile(dir, name) {
-        if (match(name)) out.push(dir ? `${dir}/${name}` : name);
-      },
-      onHole(rel, err) {
-        if (opts.strict) throw new WalkError(rel, err);
-      },
-    },
-  ]);
-  out.sort();
-  return out;
-}
-
-/** A strict listing's refusal: the directory (relative to the root, `''` for the root itself) it could not list. */
-export class WalkError extends Error {
-  constructor(
-    readonly relDir: string,
-    readonly cause: unknown,
-  ) {
-    super(`${relDir || '.'} could not be listed — ${cause instanceof Error ? cause.message : String(cause)}`);
-    this.name = 'WalkError';
-  }
-}

package/src/shared/hash-email.ts

@@ -1,14 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/**
- * Canonical user-identity hash: SHA-256 over the trimmed, lowercased email,
- * returned as hex. Used wherever Bevel needs a stable email-derived identifier
- * without storing the raw email — PR author-id markers, self-approval
- * detection, etc. All callers MUST use this single function; a drift in the
- * normalization (case, whitespace) would silently de-attribute every PR the
- * bot opens because the hash embedded in the PR body would no longer match
- * the hash computed at lookup time.
- */
-export function hashEmail(email: string): string {
-  return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
-}

package/src/shared/kb-walk.ts

@@ -1,95 +0,0 @@
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { isAbsence } from './fs-errors.js';
-import { comparePathComponents } from './path-order.js';
-
-/**
- * THE walk of a knowledge-base checkout.
- *
- * Every reader of the tree — the access resolver looking for rules, plugin
- * discovery looking for manifests, a rename looking for grants, the catalog
- * scanners — used to carry a recursive `readdir` loop of its own, each with
- * its own skip list, its own idea of what an unreadable folder means and its
- * own visiting order. Two loops that disagree on one of those are two
- * answers to "what is in the tree", and every such disagreement was a bug.
- *
- * So there is one loop, and it decides three things once:
- *
- *   - WHAT IS SKIPPED: {@link isSkippedEntry} — dot-entries (`.git`, a parked
- *     delete) and vendored dependencies. Nothing else is pruned; a listener
- *     that stops at a leaf of its own (a skill folder, a plugin folder)
- *     simply ignores what lies beneath it.
- *   - IN WHAT ORDER: each folder's entries in {@link comparePathComponents}
- *     order, so "first by path" means the same thing to every listener.
- *   - WHAT A HOLE IS: a folder that exists but could not be listed is
- *     reported as an event and in the result — never thrown, never silently
- *     skipped — so a reader can show what it saw and a writer can refuse.
- *     A folder that vanished between listing and visiting is not a hole.
- *
- * Listeners see the same events in the same order; what each makes of them
- * is its own business (`.bevelignore` included — the explorer honours it,
- * the resolver must not, so it is a listener's decision, not the walk's).
- */
-export function isSkippedEntry(name: string): boolean {
-  return name.startsWith('.') || name === 'node_modules';
-}
-
-/** A directory entry as the walk presents it: a name and what it is. */
-export interface WalkedEntry {
-  name: string;
-  isDirectory(): boolean;
-  isFile(): boolean;
-}
-
-export interface KbWalkListener {
-  /** A folder was listed. `rel` is repo-relative (`''` for the root); `entries` are its children, skipped ones removed, in walk order. */
-  onDir?(rel: string, entries: readonly WalkedEntry[]): void | Promise<void>;
-  /** A file was seen. `dir` is its folder (`''` for the root), `name` its basename. */
-  onFile?(dir: string, name: string): void | Promise<void>;
-  /** A folder that exists but could not be listed. */
-  onHole?(rel: string, err: unknown): void | Promise<void>;
-}
-
-export interface KbWalkResult {
-  /** Every folder that could not be listed, repo-relative (`''` for the root). */
-  holes: string[];
-}
-
-/**
- * Walk the checkout at `root`, driving every listener from one traversal.
- * A missing root is an empty tree. Listener errors propagate untouched.
- */
-export async function walkKb(root: string, listeners: readonly KbWalkListener[]): Promise<KbWalkResult> {
-  const holes: string[] = [];
-
-  const visit = async (abs: string, rel: string): Promise<void> => {
-    let listed: import('node:fs').Dirent[];
-    try {
-      listed = await fs.readdir(abs, { withFileTypes: true });
-    } catch (err) {
-      if (isAbsence(err)) {
-        // The root: a checkout without this tree, an empty walk. Deeper: a
-        // folder that vanished between listing and visiting — not a hole.
-        return;
-      }
-      holes.push(rel);
-      for (const l of listeners) await l.onHole?.(rel, err);
-      return;
-    }
-    const entries: WalkedEntry[] = listed
-      .filter((e) => !isSkippedEntry(e.name) && (e.isDirectory() || e.isFile()))
-      .sort((a, b) => comparePathComponents(a.name, b.name));
-    for (const l of listeners) await l.onDir?.(rel, entries);
-    for (const entry of entries) {
-      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) {
-        await visit(path.join(abs, entry.name), childRel);
-      } else {
-        for (const l of listeners) await l.onFile?.(rel, entry.name);
-      }
-    }
-  };
-
-  await visit(root, '');
-  return { holes };
-}