Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

7.1 KB
Raw Blame
import { describe, it, expect } from 'vitest';
const { buildToolResource, TOOL_RESOURCE_TYPE } = await import('./apiToolResource.js');
const { API_OPERATION_CONTRACTS } = await import('./apiOperationContracts.js');
const { ERROR_CODES_BY_STATUS } = await import('./errorHandler.js');

const resource = buildToolResource({ version: '9.9.9' });
const byName = (name) => resource.tools.find((tool) => tool.name === name);

describe('buildToolResource', () => {
  it('declares the resource envelope and the source document version', () => {
    expect(resource.type).toBe(TOOL_RESOURCE_TYPE);
    expect(resource.schemaVersion).toBe(1);
    expect(resource.portosVersion).toBe('9.9.9');
    expect(resource.source).toEqual({ document: 'openapi', version: '3.0.3' });
  });

  it('publishes JSON Schema, not the 3.0.3 dialect, so the schemas work as provider tool definitions', () => {
    expect(resource.schemaDialect).toBe('https://json-schema.org/draft/2020-12/schema');
    // A 3.0.3 `nullable: true` is not a JSON Schema keyword — converting here
    // would DROP the null branch and make a legal `null` argument invalid.
    expect(byName('image.generate').input_schema.properties.negative_prompt)
      .toEqual({ anyOf: [{ type: 'string', maxLength: 8000 }, { type: 'null' }] });
  });

  it('includes exactly the operations carrying an x-portos-tool annotation', () => {
    const annotated = Object.values(API_OPERATION_CONTRACTS)
      .flatMap((pathItem) => Object.values(pathItem))
      .filter((operation) => operation['x-portos-tool']);
    expect(resource.tools).toHaveLength(annotated.length);
    expect(resource.tools.map((tool) => tool.name).sort())
      .toEqual(annotated.map((operation) => operation['x-portos-tool'].name).sort());
  });

  it('is not filtered by API exposure settings', () => {
    // The registry enforces reachability at call time; hiding a tool here would
    // leave an agent unable to learn why its call was refused.
    expect(buildToolResource().tools).toHaveLength(resource.tools.length);
  });

  it('binds each tool to its HTTP method and path', () => {
    expect(byName('voice.synthesize').binding)
      .toEqual({ protocol: 'http', method: 'POST', path: '/api/voice/public/synthesize' });
    expect(byName('image.list-models').binding)
      .toEqual({ protocol: 'http', method: 'GET', path: '/sdapi/v1/sd-models' });
  });

  it('derives a snake_case provider name from the dotted canonical name', () => {
    expect(byName('image.list-models').providerName).toBe('image_list_models');
    expect(byName('voice.synthesize').providerName).toBe('voice_synthesize');
  });

  it('flattens an object request body into the argument schema and keeps property descriptions', () => {
    const input = byName('voice.synthesize').input_schema;
    expect(input.required).toEqual(['text']);
    expect(input.properties.engine.enum).toEqual(['auk', 'piper', 'qwen3-tts']);
    // The description is what lets a model pick a valid rate — minimization must not strip it.
    expect(input.properties.rate.description).toMatch(/Speech rate/);
    expect(input.additionalProperties).toBe(false);
  });

  it('turns query parameters into input properties', () => {
    const input = byName('voice.list-voices').input_schema;
    expect(input.properties.engine).toEqual({ type: 'string', enum: ['auk', 'piper', 'qwen3-tts'] });
    expect(input.required).toBeUndefined(); // the engine param is optional
  });

  it('preserves an open body contract rather than closing it', () => {
    // sdapiTxt2imgBodySchema is .passthrough() for A1111 compatibility.
    expect(byName('image.generate').input_schema.additionalProperties).not.toBe(false);
  });

  it('reports a non-JSON success payload by media type instead of claiming JSON', () => {
    expect(byName('voice.synthesize').output_schema)
      .toEqual({ type: 'string', format: 'binary', 'x-portos-media-type': 'audio/wav' });
  });

  it('uses the modeled JSON response schema when the contract has one', () => {
    expect(byName('image.list-models').output_schema).toEqual({ type: 'array', items: { type: 'object' } });
  });

  it('falls back to an open object when no success payload is modeled', () => {
    expect(byName('image.generate').output_schema).toEqual({ type: 'object', additionalProperties: true });
  });

  it('publishes the error code a route actually throws, not one derived from the status', () => {
    // errorHandler resolves `err.code || getErrorCode(status)`, and both write
    // routes pass an explicit code — so a status-derived guess would publish
    // BAD_REQUEST for a 400 that really reports VALIDATION_ERROR. One status can
    // carry several codes: a schema-valid request naming an unknown voice is a
    // 400 UNKNOWN_VOICE (see routes/voicePublic.test.js).
    expect(byName('voice.synthesize').failures).toEqual([
      { status: 400, code: 'VALIDATION_ERROR' },
      { status: 400, code: 'UNKNOWN_VOICE' },
    ]);
  });

  it('declares the router-wide exposure gate on every sdapi tool, not just the write one', () => {
    // routes/sdapi.js gates the WHOLE router with `router.use(...)`, so a read
    // tool returns 403 too when A1111 exposure is off. An agent that never saw
    // that failure has no way to explain the refusal.
    for (const name of ['image.list-models', 'image.list-samplers', 'image.get-options', 'image.get-progress']) {
      expect(byName(name).failures).toEqual([{ status: 403, code: 'FORBIDDEN' }]);
    }
  });

  it('emits one entry per code when a status carries several', () => {
    expect(byName('image.generate').failures).toEqual([
      { status: 400, code: 'VALIDATION_ERROR' },
      { status: 403, code: 'FORBIDDEN' }, // undeclared: falls back to the status map
      { status: 500, code: 'GEN_FAILED' },
      { status: 500, code: 'GEN_OUTPUT_MISSING' },
      { status: 504, code: 'GEN_TIMEOUT' },
    ]);
  });

  it('omits failures entirely for a tool that declares no error responses', () => {
    expect(byName('voice.list-voices').failures).toBeUndefined();
  });

  it('marks read tools idempotent and side-effecting tools not', () => {
    expect(byName('image.list-models').policy).toMatchObject({ sideEffect: 'read', idempotent: true });
    expect(byName('image.generate').policy).toMatchObject({ sideEffect: 'local-compute', idempotent: false, async: true });
  });

  it('publishes the full error vocabulary from the shared status map', () => {
    expect(resource.errors).toEqual(
      Object.entries(ERROR_CODES_BY_STATUS).map(([status, code]) => ({ status: Number(status), code })),
    );
    expect(resource.errors.some((error) => error.code === 'VALIDATION_ERROR')).toBe(true);
  });

  it('counts read versus side-effecting tools', () => {
    expect(resource.stats.total).toBe(resource.tools.length);
    expect(resource.stats.read + resource.stats.write).toBe(resource.tools.length);
  });

  it('stays smaller than the OpenAPI document it is derived from', async () => {
    // The point of the resource is that an agent can read it whole.
    const { buildInternalOpenApiSpec } = await import('./openapiSpec.js');
    const internal = JSON.stringify(buildInternalOpenApiSpec({}, { version: '9.9.9' }));
    expect(JSON.stringify(resource).length).toBeLessThan(internal.length / 100);
  });
});