@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/modules/audit/__tests__/agent-rest-audit.middleware.test.ts

@@ -1,113 +1,113 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import express from 'express';
-import type { Server } from 'node:http';
-import { createAgentRestAuditMiddleware } from '../agent-rest-audit.middleware.js';
-import type { AgentEventInput } from '../audit.contract.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-
-const KB = 'KNOWLEDGE_BASE';
-
-/**
- * The REST recorder, on a real router: a stand-in auth stamps whatever
- * `toolAuth` a test wants (the way the real gate does, per route), a couple
- * of routes answer as the platform tools do, and the recorder is watched.
- */
-function makeApp(auth: ToolAuth | null, skills: { name: string; path: string }[] = []) {
-  const events: AgentEventInput[] = [];
-  const skillFolders = vi.fn(async () => skills);
-  const app = express();
-  app.use(express.json());
-  const router = express.Router();
-  router.use(
-    '/agent/tools/:name',
-    createAgentRestAuditMiddleware({ recorder: { record: (e) => void events.push(e) }, kbManualName: KB, skillFolders }),
-  );
-  const stampAuth: express.RequestHandler = (req, res, next) => {
-    if (!auth) {
-      res.status(401).json({ error: 'nope' });
-      return;
-    }
-    req.toolAuth = auth;
-    next();
-  };
-  router.post('/agent/tools/get_skill', stampAuth, (_req, res) => res.json({ ok: true }));
-  router.post('/agent/tools/read_file', stampAuth, (_req, res) => res.json({ content: 'x' }));
-  router.post('/agent/tools/list_skills', stampAuth, (_req, res) => res.json({ skills }));
-  router.post('/agent/tools/boom', stampAuth, (_req, res) => res.status(500).json({ error: 'kaboom' }));
-  app.use('/api', router);
-  return { app, events, skillFolders };
-}
-
-let server: Server;
-afterEach(() => server?.close());
-
-async function listen(app: express.Express): Promise<string> {
-  await new Promise<void>((resolve) => {
-    server = app.listen(0, resolve);
-  });
-  const address = server.address();
-  if (typeof address === 'string' || !address) throw new Error('no port');
-  return `http://127.0.0.1:${address.port}`;
-}
-
-const post = (base: string, name: string, body: unknown) =>
-  fetch(`${base}/api/agent/tools/${name}`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  });
-
-/** Recording lands after the response; give it a turn. */
-const settle = () => new Promise((r) => setTimeout(r, 20));
-
-const EXCHANGED_GRANT: ToolAuth = { source: 'external', userId: 'u-1', connectionId: 'conn-1', scope: 'write' };
-
-describe('the REST recorder for the local server', () => {
-  it("records a skill read made with an exchanged grant as that agent's skill event, with the outcome", async () => {
-    const { app, events } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
-    const base = await listen(app);
-    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(200);
-    expect((await post(base, 'boom', {})).status).toBe(500);
-    await settle();
-    expect(events).toEqual([
-      expect.objectContaining({
-        userId: 'u-1',
-        principal: { kind: 'agent', id: 'conn-1' },
-        kind: 'skill',
-        manual: 'Plugins/Sales/rfi',
-        name: 'rfi',
-        outcome: 'ok',
-      }),
-      expect.objectContaining({ kind: 'capability', name: 'boom', outcome: 'error' }),
-    ]);
-    expect(typeof events[0]!.durationMs).toBe('number');
-  });
-
-  it('fetches the skill catalog only for a read that names a path, and classifies the read by it', async () => {
-    const { app, events, skillFolders } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
-    const base = await listen(app);
-    await post(base, 'list_skills', {});
-    await post(base, 'read_file', { path: 'Plugins/Sales/rfi/SKILL.md', branch: 'main' });
-    await settle();
-    expect(skillFolders).toHaveBeenCalledTimes(1);
-    expect(events.map((e) => `${e.kind}:${e.name}`)).toEqual(['capability:list_skills', 'skill:rfi']);
-  });
-
-  it('records nothing for a connection key, a loopback token, or a refused call — those are the proxy\'s to record, or nobody\'s', async () => {
-    const key = makeApp({ source: 'external', userId: 'u-1', tokenId: 'k-1', scope: 'write' });
-    let base = await listen(key.app);
-    await post(base, 'get_skill', { name: 'rfi' });
-    server.close();
-    const loopback = makeApp({ source: 'external', userId: 'u-1', scope: 'write' });
-    base = await listen(loopback.app);
-    await post(base, 'get_skill', { name: 'rfi' });
-    server.close();
-    const refused = makeApp(null);
-    base = await listen(refused.app);
-    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(401);
-    await settle();
-    expect(key.events).toEqual([]);
-    expect(loopback.events).toEqual([]);
-    expect(refused.events).toEqual([]);
-  });
-});
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+import type { Server } from 'node:http';
+import { createAgentRestAuditMiddleware } from '../agent-rest-audit.middleware.js';
+import type { AgentEventInput } from '../audit.contract.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+
+const KB = 'KNOWLEDGE_BASE';
+
+/**
+ * The REST recorder, on a real router: a stand-in auth stamps whatever
+ * `toolAuth` a test wants (the way the real gate does, per route), a couple
+ * of routes answer as the platform tools do, and the recorder is watched.
+ */
+function makeApp(auth: ToolAuth | null, skills: { name: string; path: string }[] = []) {
+  const events: AgentEventInput[] = [];
+  const skillFolders = vi.fn(async () => skills);
+  const app = express();
+  app.use(express.json());
+  const router = express.Router();
+  router.use(
+    '/agent/tools/:name',
+    createAgentRestAuditMiddleware({ recorder: { record: (e) => void events.push(e) }, kbManualName: KB, skillFolders }),
+  );
+  const stampAuth: express.RequestHandler = (req, res, next) => {
+    if (!auth) {
+      res.status(401).json({ error: 'nope' });
+      return;
+    }
+    req.toolAuth = auth;
+    next();
+  };
+  router.post('/agent/tools/get_skill', stampAuth, (_req, res) => res.json({ ok: true }));
+  router.post('/agent/tools/read_file', stampAuth, (_req, res) => res.json({ content: 'x' }));
+  router.post('/agent/tools/list_skills', stampAuth, (_req, res) => res.json({ skills }));
+  router.post('/agent/tools/boom', stampAuth, (_req, res) => res.status(500).json({ error: 'kaboom' }));
+  app.use('/api', router);
+  return { app, events, skillFolders };
+}
+
+let server: Server;
+afterEach(() => server?.close());
+
+async function listen(app: express.Express): Promise<string> {
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return `http://127.0.0.1:${address.port}`;
+}
+
+const post = (base: string, name: string, body: unknown) =>
+  fetch(`${base}/api/agent/tools/${name}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+/** Recording lands after the response; give it a turn. */
+const settle = () => new Promise((r) => setTimeout(r, 20));
+
+const EXCHANGED_GRANT: ToolAuth = { source: 'external', userId: 'u-1', connectionId: 'conn-1', scope: 'write' };
+
+describe('the REST recorder for the local server', () => {
+  it("records a skill read made with an exchanged grant as that agent's skill event, with the outcome", async () => {
+    const { app, events } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(200);
+    expect((await post(base, 'boom', {})).status).toBe(500);
+    await settle();
+    expect(events).toEqual([
+      expect.objectContaining({
+        userId: 'u-1',
+        principal: { kind: 'agent', id: 'conn-1' },
+        kind: 'skill',
+        manual: 'Plugins/Sales/rfi',
+        name: 'rfi',
+        outcome: 'ok',
+      }),
+      expect.objectContaining({ kind: 'capability', name: 'boom', outcome: 'error' }),
+    ]);
+    expect(typeof events[0]!.durationMs).toBe('number');
+  });
+
+  it('fetches the skill catalog only for a read that names a path, and classifies the read by it', async () => {
+    const { app, events, skillFolders } = makeApp(EXCHANGED_GRANT, [{ name: 'rfi', path: 'Plugins/Sales/rfi' }]);
+    const base = await listen(app);
+    await post(base, 'list_skills', {});
+    await post(base, 'read_file', { path: 'Plugins/Sales/rfi/SKILL.md', branch: 'main' });
+    await settle();
+    expect(skillFolders).toHaveBeenCalledTimes(1);
+    expect(events.map((e) => `${e.kind}:${e.name}`)).toEqual(['capability:list_skills', 'skill:rfi']);
+  });
+
+  it('records nothing for a connection key, a loopback token, or a refused call — those are the proxy\'s to record, or nobody\'s', async () => {
+    const key = makeApp({ source: 'external', userId: 'u-1', tokenId: 'k-1', scope: 'write' });
+    let base = await listen(key.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const loopback = makeApp({ source: 'external', userId: 'u-1', scope: 'write' });
+    base = await listen(loopback.app);
+    await post(base, 'get_skill', { name: 'rfi' });
+    server.close();
+    const refused = makeApp(null);
+    base = await listen(refused.app);
+    expect((await post(base, 'get_skill', { name: 'rfi' })).status).toBe(401);
+    await settle();
+    expect(key.events).toEqual([]);
+    expect(loopback.events).toEqual([]);
+    expect(refused.events).toEqual([]);
+  });
+});

package/src/modules/audit/__tests__/event-classifier.test.ts

@@ -1,121 +1,121 @@
-import { describe, expect, it } from 'vitest';
-import { classifyToolCall, skillContaining, skillReadPath, splitUtcpName } from '../event-classifier.js';
-
-const KB = 'KNOWLEDGE_BASE';
-const ctx = { kbManualName: KB, catalogNames: new Map([['my_server', 'my-server']]) };
-const skills = [
-  { name: 'rfi', path: 'Plugins/Sales/rfi' },
-  { name: 'deploy-checklist', path: 'Skills/Engineering/deploy-checklist' },
-  // Nested under another skill's folder: the longer match must win.
-  { name: 'rfi-followup', path: 'Plugins/Sales/rfi/followup' },
-];
-
-describe('splitUtcpName', () => {
-  it('splits on the first dot and leaves a bare name without a manual', () => {
-    expect(splitUtcpName('KNOWLEDGE_BASE.read_file')).toEqual({ manual: 'KNOWLEDGE_BASE', tool: 'read_file' });
-    expect(splitUtcpName('notion.notion-search')).toEqual({ manual: 'notion', tool: 'notion-search' });
-    expect(splitUtcpName('call_tool_chain')).toEqual({ manual: '', tool: 'call_tool_chain' });
-  });
-});
-
-describe('skillReadPath', () => {
-  it('asks for the skill catalog only for a platform read that names a path, or a get_skill with a name', () => {
-    expect(skillReadPath(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, KB)).toBe(
-      'Plugins/Sales/rfi/SKILL.md',
-    );
-    expect(skillReadPath(`${KB}.grep`, { path: 'Skills' }, KB)).toBe('Skills');
-    expect(skillReadPath(`${KB}.get_skill`, { body: { name: 'rfi' } }, KB)).toBe('');
-    // Not worth a catalog fetch: a write, a read with no path, another manual's tool, a meta-tool.
-    expect(skillReadPath(`${KB}.write_file`, { body: { path: 'Plugins/x' } }, KB)).toBeNull();
-    expect(skillReadPath(`${KB}.read_file`, { body: {} }, KB)).toBeNull();
-    expect(skillReadPath('notion.search', { body: { path: 'Plugins/x' } }, KB)).toBeNull();
-    expect(skillReadPath('call_tool_chain', { code: 'x' }, KB)).toBeNull();
-  });
-});
-
-describe('skillContaining', () => {
-  it('matches a path inside a skill folder on a segment boundary, from either root, longest folder first', () => {
-    expect(skillContaining('Plugins/Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
-    expect(skillContaining('knowledge-base/Plugins/Sales/rfi/scripts/build.py', skills)?.name).toBe('rfi');
-    expect(skillContaining('./Skills\\Engineering\\deploy-checklist\\SKILL.md', skills)?.name).toBe('deploy-checklist');
-    expect(skillContaining('Plugins/Sales/rfi/followup/SKILL.md', skills)?.name).toBe('rfi-followup');
-    // The file tools accept a doubled separator as the same path; so does this.
-    expect(skillContaining('Plugins//Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
-    // `.` and `..` are resolved before matching: a path that climbs out of a
-    // skill folder is not a read of that skill, and one that climbs above its
-    // own start is no place at all.
-    expect(skillContaining('Plugins/Sales/rfi/./SKILL.md', skills)?.name).toBe('rfi');
-    expect(skillContaining('Plugins/Sales/other/../rfi/SKILL.md', skills)?.name).toBe('rfi');
-    expect(skillContaining('Plugins/Sales/rfi/../../../KnowledgeBase/Secrets.md', skills)).toBeNull();
-    expect(skillContaining('../Plugins/Sales/rfi/SKILL.md', skills)).toBeNull();
-    // A folder that merely shares a prefix is not the skill's folder.
-    expect(skillContaining('Plugins/Sales/rfi-old/notes.md', skills)).toBeNull();
-    expect(skillContaining('KnowledgeBase/Product/roadmap.md', skills)).toBeNull();
-  });
-});
-
-describe('classifyToolCall', () => {
-  it('logs the platform manual and the meta-tools as hexis capabilities, by bare name', () => {
-    expect(classifyToolCall(`${KB}.write_file`, { body: { path: 'x' } }, ctx, null)).toEqual({
-      kind: 'capability',
-      manual: null,
-      name: 'write_file',
-    });
-    expect(classifyToolCall('call_tool_chain', { code: 'x' }, ctx, null)).toEqual({
-      kind: 'capability',
-      manual: null,
-      name: 'call_tool_chain',
-    });
-  });
-
-  it("logs another manual's tool as a tool under its catalog name", () => {
-    expect(classifyToolCall('my_server.search', { q: 'x' }, ctx, null)).toEqual({
-      kind: 'tool',
-      manual: 'my-server',
-      name: 'search',
-    });
-    // An http `.tool` manual has no rewrite, so its registered name is the catalog name.
-    expect(classifyToolCall('hubspot.search_contacts', {}, ctx, null)).toEqual({
-      kind: 'tool',
-      manual: 'hubspot',
-      name: 'search_contacts',
-    });
-  });
-
-  it('logs get_skill as a skill read, with the folder when the catalog knows it', () => {
-    expect(classifyToolCall(`${KB}.get_skill`, { body: { name: 'rfi' } }, ctx, skills)).toEqual({
-      kind: 'skill',
-      manual: 'Plugins/Sales/rfi',
-      name: 'rfi',
-    });
-    expect(classifyToolCall(`${KB}.get_skill`, { name: 'unknown' }, ctx, skills)).toEqual({
-      kind: 'skill',
-      manual: null,
-      name: 'unknown',
-    });
-  });
-
-  it('logs a platform read inside a skill folder as that skill, and elsewhere as the read', () => {
-    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, skills)).toEqual({
-      kind: 'skill',
-      manual: 'Plugins/Sales/rfi',
-      name: 'rfi',
-    });
-    expect(classifyToolCall(`${KB}.list_files`, { body: { path: 'Skills/Engineering/deploy-checklist' } }, ctx, skills)).toEqual({
-      kind: 'skill',
-      manual: 'Skills/Engineering/deploy-checklist',
-      name: 'deploy-checklist',
-    });
-    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'KnowledgeBase/Product/roadmap.md' } }, ctx, skills)).toEqual({
-      kind: 'capability',
-      manual: null,
-      name: 'read_file',
-    });
-    // No catalog (the fetch failed): the honest fallback is the read itself.
-    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, null)).toEqual({
-      kind: 'capability',
-      manual: null,
-      name: 'read_file',
-    });
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { classifyToolCall, skillContaining, skillReadPath, splitUtcpName } from '../event-classifier.js';
+
+const KB = 'KNOWLEDGE_BASE';
+const ctx = { kbManualName: KB, catalogNames: new Map([['my_server', 'my-server']]) };
+const skills = [
+  { name: 'rfi', path: 'Plugins/Sales/rfi' },
+  { name: 'deploy-checklist', path: 'Skills/Engineering/deploy-checklist' },
+  // Nested under another skill's folder: the longer match must win.
+  { name: 'rfi-followup', path: 'Plugins/Sales/rfi/followup' },
+];
+
+describe('splitUtcpName', () => {
+  it('splits on the first dot and leaves a bare name without a manual', () => {
+    expect(splitUtcpName('KNOWLEDGE_BASE.read_file')).toEqual({ manual: 'KNOWLEDGE_BASE', tool: 'read_file' });
+    expect(splitUtcpName('notion.notion-search')).toEqual({ manual: 'notion', tool: 'notion-search' });
+    expect(splitUtcpName('call_tool_chain')).toEqual({ manual: '', tool: 'call_tool_chain' });
+  });
+});
+
+describe('skillReadPath', () => {
+  it('asks for the skill catalog only for a platform read that names a path, or a get_skill with a name', () => {
+    expect(skillReadPath(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, KB)).toBe(
+      'Plugins/Sales/rfi/SKILL.md',
+    );
+    expect(skillReadPath(`${KB}.grep`, { path: 'Skills' }, KB)).toBe('Skills');
+    expect(skillReadPath(`${KB}.get_skill`, { body: { name: 'rfi' } }, KB)).toBe('');
+    // Not worth a catalog fetch: a write, a read with no path, another manual's tool, a meta-tool.
+    expect(skillReadPath(`${KB}.write_file`, { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath(`${KB}.read_file`, { body: {} }, KB)).toBeNull();
+    expect(skillReadPath('notion.search', { body: { path: 'Plugins/x' } }, KB)).toBeNull();
+    expect(skillReadPath('call_tool_chain', { code: 'x' }, KB)).toBeNull();
+  });
+});
+
+describe('skillContaining', () => {
+  it('matches a path inside a skill folder on a segment boundary, from either root, longest folder first', () => {
+    expect(skillContaining('Plugins/Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('knowledge-base/Plugins/Sales/rfi/scripts/build.py', skills)?.name).toBe('rfi');
+    expect(skillContaining('./Skills\\Engineering\\deploy-checklist\\SKILL.md', skills)?.name).toBe('deploy-checklist');
+    expect(skillContaining('Plugins/Sales/rfi/followup/SKILL.md', skills)?.name).toBe('rfi-followup');
+    // The file tools accept a doubled separator as the same path; so does this.
+    expect(skillContaining('Plugins//Sales/rfi/SKILL.md', skills)?.name).toBe('rfi');
+    // `.` and `..` are resolved before matching: a path that climbs out of a
+    // skill folder is not a read of that skill, and one that climbs above its
+    // own start is no place at all.
+    expect(skillContaining('Plugins/Sales/rfi/./SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/other/../rfi/SKILL.md', skills)?.name).toBe('rfi');
+    expect(skillContaining('Plugins/Sales/rfi/../../../KnowledgeBase/Secrets.md', skills)).toBeNull();
+    expect(skillContaining('../Plugins/Sales/rfi/SKILL.md', skills)).toBeNull();
+    // A folder that merely shares a prefix is not the skill's folder.
+    expect(skillContaining('Plugins/Sales/rfi-old/notes.md', skills)).toBeNull();
+    expect(skillContaining('KnowledgeBase/Product/roadmap.md', skills)).toBeNull();
+  });
+});
+
+describe('classifyToolCall', () => {
+  it('logs the platform manual and the meta-tools as hexis capabilities, by bare name', () => {
+    expect(classifyToolCall(`${KB}.write_file`, { body: { path: 'x' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'write_file',
+    });
+    expect(classifyToolCall('call_tool_chain', { code: 'x' }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'call_tool_chain',
+    });
+  });
+
+  it("logs another manual's tool as a tool under its catalog name", () => {
+    expect(classifyToolCall('my_server.search', { q: 'x' }, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'my-server',
+      name: 'search',
+    });
+    // An http `.tool` manual has no rewrite, so its registered name is the catalog name.
+    expect(classifyToolCall('hubspot.search_contacts', {}, ctx, null)).toEqual({
+      kind: 'tool',
+      manual: 'hubspot',
+      name: 'search_contacts',
+    });
+  });
+
+  it('logs get_skill as a skill read, with the folder when the catalog knows it', () => {
+    expect(classifyToolCall(`${KB}.get_skill`, { body: { name: 'rfi' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.get_skill`, { name: 'unknown' }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: null,
+      name: 'unknown',
+    });
+  });
+
+  it('logs a platform read inside a skill folder as that skill, and elsewhere as the read', () => {
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Plugins/Sales/rfi',
+      name: 'rfi',
+    });
+    expect(classifyToolCall(`${KB}.list_files`, { body: { path: 'Skills/Engineering/deploy-checklist' } }, ctx, skills)).toEqual({
+      kind: 'skill',
+      manual: 'Skills/Engineering/deploy-checklist',
+      name: 'deploy-checklist',
+    });
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'KnowledgeBase/Product/roadmap.md' } }, ctx, skills)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+    // No catalog (the fetch failed): the honest fallback is the read itself.
+    expect(classifyToolCall(`${KB}.read_file`, { body: { path: 'Plugins/Sales/rfi/SKILL.md' } }, ctx, null)).toEqual({
+      kind: 'capability',
+      manual: null,
+      name: 'read_file',
+    });
+  });
+});