@lumenflow/surfaces 5.1.0

package/http/__tests__/tool-discovery.test.ts

@@ -0,0 +1,384 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { createHttpSurface } from '../index.js';
+import type { KernelRuntime } from '@lumenflow/kernel';
+
+const HTTP_METHOD = {
+  GET: 'GET',
+  POST: 'POST',
+  PUT: 'PUT',
+} as const;
+
+const HTTP_STATUS = {
+  OK: 200,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+} as const;
+
+const HEADER = {
+  CONTENT_TYPE: 'content-type',
+} as const;
+
+const CONTENT_TYPE_JSON = 'application/json; charset=utf-8';
+
+const PACK = {
+  SOFTWARE_DELIVERY: 'software-delivery',
+  SIDEKICK: 'sidekick',
+  AGENT_RUNTIME: 'agent-runtime',
+} as const;
+
+const SURFACES_VERSION = '4.23.0';
+const WORKSPACE_ID = 'workspace-discovery-1';
+
+interface RequestOptions {
+  method: string;
+  url: string;
+  body?: unknown;
+  authorization?: string;
+}
+
+class MockResponse extends EventEmitter {
+  statusCode = HTTP_STATUS.OK;
+  body = '';
+  readonly headers = new Map<string, string>();
+
+  setHeader(name: string, value: string | number | readonly string[]): this {
+    this.headers.set(name.toLowerCase(), String(value));
+    return this;
+  }
+
+  writeHead(statusCode: number, headers?: Record<string, string>): this {
+    this.statusCode = statusCode;
+    if (headers) {
+      for (const [name, value] of Object.entries(headers)) {
+        this.setHeader(name, value);
+      }
+    }
+    return this;
+  }
+
+  write(chunk: string | Buffer): boolean {
+    this.body += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : chunk;
+    return true;
+  }
+
+  end(chunk?: string | Buffer): this {
+    if (chunk !== undefined) {
+      this.write(chunk);
+    }
+    this.emit('finish');
+    return this;
+  }
+}
+
+function createRequest(options: RequestOptions): IncomingMessage {
+  const request = new PassThrough() as unknown as IncomingMessage & {
+    method: string;
+    url: string;
+    headers: IncomingHttpHeaders;
+  };
+
+  request.method = options.method;
+  request.url = options.url;
+  request.headers = {
+    [HEADER.CONTENT_TYPE]: CONTENT_TYPE_JSON,
+    ...(options.authorization ? { authorization: options.authorization } : {}),
+  };
+
+  const payload = options.body === undefined ? '' : JSON.stringify(options.body);
+  (request as unknown as PassThrough).end(payload);
+  return request;
+}
+
+function createRuntimeStub(): KernelRuntime {
+  return {
+    executeTool: vi.fn(async () => ({ success: true, data: { ok: true } })),
+  } as unknown as KernelRuntime;
+}
+
+interface ToolCatalogEntry {
+  name: string;
+  pack: string;
+  description: string;
+  input_schema: unknown;
+  output_schema: unknown;
+  requires_approval: boolean;
+  capabilities_required?: string[];
+  estimated_cost?: { tokens?: number; wall_time_ms?: number };
+}
+
+function createToolCatalog(): ToolCatalogEntry[] {
+  return [
+    {
+      name: 'software-delivery:wu.claim',
+      pack: PACK.SOFTWARE_DELIVERY,
+      description: 'Claim a WU for implementation.',
+      input_schema: {
+        type: 'object',
+        required: ['wu_id'],
+        properties: { wu_id: { type: 'string' } },
+      },
+      output_schema: {
+        type: 'object',
+        properties: { worktree_path: { type: 'string' } },
+      },
+      requires_approval: false,
+    },
+    {
+      name: 'sidekick:channel.post',
+      pack: PACK.SIDEKICK,
+      description: 'Post a message to a channel.',
+      input_schema: {
+        type: 'object',
+        required: ['channel', 'message'],
+        properties: {
+          channel: { type: 'string' },
+          message: { type: 'string' },
+        },
+      },
+      output_schema: {
+        type: 'object',
+        properties: { message_id: { type: 'string' } },
+      },
+      requires_approval: true,
+    },
+    {
+      name: 'agent-runtime:turn.execute',
+      pack: PACK.AGENT_RUNTIME,
+      description: 'Execute an agent turn.',
+      input_schema: {
+        type: 'object',
+        required: ['agent_id'],
+        properties: { agent_id: { type: 'string' } },
+      },
+      output_schema: {
+        type: 'object',
+        properties: { turn_id: { type: 'string' } },
+      },
+      requires_approval: false,
+      estimated_cost: { tokens: 2000, wall_time_ms: 5000 },
+    },
+  ];
+}
+
+function parseJson(body: string): unknown {
+  return JSON.parse(body);
+}
+
+describe('http tool discovery (GET /tools)', () => {
+  // --- AC1 + AC5: GET /tools returns 200 with tools[], surfaces_version, workspace_id ---
+
+  it('GET /tools returns 200 with tools array plus surfaces_version and workspace_id', async () => {
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: createToolCatalog().map((tool) => tool.name),
+      toolCatalog: createToolCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.OK);
+    expect(response.headers.get(HEADER.CONTENT_TYPE)).toBe(CONTENT_TYPE_JSON);
+
+    const body = parseJson(response.body) as {
+      tools: ToolCatalogEntry[];
+      surfaces_version: string;
+      workspace_id: string;
+    };
+
+    expect(body.surfaces_version).toBe(SURFACES_VERSION);
+    expect(body.workspace_id).toBe(WORKSPACE_ID);
+    expect(Array.isArray(body.tools)).toBe(true);
+    expect(body.tools).toHaveLength(createToolCatalog().length);
+  });
+
+  // --- AC1: every tool has required metadata fields ---
+
+  it('each tool entry includes name, pack, description, schemas, requires_approval and capabilities_required', async () => {
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: createToolCatalog().map((tool) => tool.name),
+      toolCatalog: createToolCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    const body = parseJson(response.body) as { tools: ToolCatalogEntry[] };
+
+    for (const tool of body.tools) {
+      expect(typeof tool.name).toBe('string');
+      expect(typeof tool.pack).toBe('string');
+      expect(typeof tool.description).toBe('string');
+      expect(tool.input_schema).toBeDefined();
+      expect(tool.output_schema).toBeDefined();
+      expect(typeof tool.requires_approval).toBe('boolean');
+      expect(Array.isArray(tool.capabilities_required)).toBe(true);
+      expect((tool.capabilities_required ?? []).length).toBeGreaterThan(0);
+    }
+  });
+
+  // --- AC2: multi-pack inventory returns full list without duplicates ---
+
+  it('returns the full inventory without duplicates when all three packs are loaded', async () => {
+    const catalog = createToolCatalog();
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: catalog.map((tool) => tool.name),
+      toolCatalog: [...catalog, catalog[0]!], // duplicate entry to prove dedup
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    const body = parseJson(response.body) as { tools: ToolCatalogEntry[] };
+    const names = body.tools.map((tool) => tool.name);
+    const uniqueNames = new Set(names);
+    expect(names).toHaveLength(uniqueNames.size);
+
+    const packs = new Set(body.tools.map((tool) => tool.pack));
+    expect(packs.has(PACK.SOFTWARE_DELIVERY)).toBe(true);
+    expect(packs.has(PACK.SIDEKICK)).toBe(true);
+    expect(packs.has(PACK.AGENT_RUNTIME)).toBe(true);
+  });
+
+  // --- AC4: capabilities_required aligns with scope grammar from ADR-058 ---
+
+  it('capabilities_required defaults to the tool:<pack>:<tool> scope grammar when omitted', async () => {
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: createToolCatalog().map((tool) => tool.name),
+      toolCatalog: createToolCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    const body = parseJson(response.body) as { tools: ToolCatalogEntry[] };
+
+    const wuClaim = body.tools.find((tool) => tool.name === 'software-delivery:wu.claim');
+    expect(wuClaim).toBeDefined();
+    expect(wuClaim?.capabilities_required).toEqual(['tool:software-delivery:wu.claim']);
+
+    const channelPost = body.tools.find((tool) => tool.name === 'sidekick:channel.post');
+    expect(channelPost?.capabilities_required).toEqual(['tool:sidekick:channel.post']);
+
+    const turnExecute = body.tools.find((tool) => tool.name === 'agent-runtime:turn.execute');
+    expect(turnExecute?.capabilities_required).toEqual(['tool:agent-runtime:turn.execute']);
+  });
+
+  it('preserves explicit capabilities_required when supplied by the catalog entry', async () => {
+    const explicit = [
+      {
+        ...createToolCatalog()[0]!,
+        capabilities_required: ['tool:software-delivery:*'],
+      },
+    ];
+
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: explicit.map((tool) => tool.name),
+      toolCatalog: explicit,
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    const body = parseJson(response.body) as { tools: ToolCatalogEntry[] };
+    expect(body.tools[0]?.capabilities_required).toEqual(['tool:software-delivery:*']);
+  });
+
+  // --- Method handling ---
+
+  it('returns 405 for non-GET methods on /tools root', async () => {
+    const surface = createHttpSurface(createRuntimeStub(), {
+      allowlistedTools: createToolCatalog().map((tool) => tool.name),
+      toolCatalog: createToolCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.PUT, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.METHOD_NOT_ALLOWED);
+  });
+
+  // --- AC6: Existing POST /tools/:name behavior unchanged ---
+
+  it('existing POST /tools/:name dispatch behavior is unchanged when discovery is enabled', async () => {
+    const runtime = {
+      executeTool: vi.fn(async () => ({ success: true, data: { status: 'ok' } })),
+    } as unknown as KernelRuntime;
+
+    const surface = createHttpSurface(runtime, {
+      allowlistedTools: ['software-delivery:wu.claim'],
+      toolCatalog: createToolCatalog(),
+      surfacesVersion: SURFACES_VERSION,
+      workspaceId: WORKSPACE_ID,
+    });
+
+    const request = createRequest({
+      method: HTTP_METHOD.POST,
+      url: '/tools/software-delivery:wu.claim',
+      // WU-2779: POST /tools/:name requires Authorization. Use legacy opaque
+      // token; this test covers discovery + dispatch, not auth.
+      authorization: 'Bearer legacy-opaque-discovery-token',
+      body: {
+        input: { wu_id: 'WU-2639' },
+        context: {
+          run_id: 'run-discovery',
+          task_id: 'WU-2639',
+          session_id: 'session-discovery',
+          allowed_scopes: [],
+        },
+      },
+    });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    expect(runtime.executeTool).toHaveBeenCalledWith(
+      'software-delivery:wu.claim',
+      { wu_id: 'WU-2639' },
+      expect.objectContaining({ run_id: 'run-discovery' }),
+    );
+    expect(response.statusCode).toBe(HTTP_STATUS.OK);
+  });
+
+  it('GET /tools returns 404 when toolCatalog is not provided', async () => {
+    const surface = createHttpSurface(createRuntimeStub(), {
+      // no toolCatalog, no allowlistedTools
+    });
+
+    const request = createRequest({ method: HTTP_METHOD.GET, url: '/tools' });
+    const response = new MockResponse();
+
+    await surface.handleRequest(request, response as unknown as ServerResponse<IncomingMessage>);
+
+    expect(response.statusCode).toBe(HTTP_STATUS.NOT_FOUND);
+  });
+});