HTTP and OpenAPI adapter

Import the HTTP adapter from its separate package entrypoint:

import { createHttpHandler } from '@uppercut-labs/agent-native/http';

createHttpHandler(registry, options) returns a handler from the standard Web Request API to Response. Mount that function in a framework or server of your choice. The core contract and executor remain independent of HTTP, Node, and framework modules.

The default base path is /agent-native/v1. Public, read-only capabilities receive a deterministic POST /agent-native/v1/capabilities/{namespace}/{name}/v{major}/invoke route. The endpoint is a generic capability invocation, not a generated REST resource API. By default there is no GET invocation route; a GET to a visible invocation path receives 405 with Allow: POST.

A definition may preserve an established read route with a contract-level override:

E10 keeps its existing search route with this override in the tested capability definition:

http: {
  path: '/api/content/search',
  method: 'GET',
  query: { query: 'q' },
},

View tested source

The query map runs from input property to query parameter. GET conversion supports string, number, integer, boolean, string enum, and arrays of those scalar values; nested objects and other lossy conversions fail when the HTTP adapter is created. GET overrides are rejected for write or destructive capabilities. Paths must be absolute and unique across visible definitions. The same override drives routing and OpenAPI parameters.

The adapter uses the shared executor for schema validation, authorization, binding selection, and output validation. Its default authorization policy permits only definitions explicitly marked as public reads. Supply resolveExecutionContext to adapt a trusted authentication boundary; this does not replace authorization in the executor. Hidden/protected definitions are omitted from the public OpenAPI document and route map, and unknown paths return the same 404 shape.

OpenAPI 3.1 is generated directly from the public definitions' input/output SchemaPort values. The same document is available at GET /agent-native/v1/openapi.json. A health observation at GET /agent-native/v1/health records an actual protocol request as UAN-003.http-protocol.

The default request body limit is 32 KiB and can be set from 1 byte to 1 MiB with maxRequestBytes. The default execution deadline is 10 seconds and the configurable maximum is 300 seconds. At a deadline the handler returns 504 and sets context.signal.aborted. Bindings must observe that signal to stop their work; JavaScript cannot forcibly stop a handler that ignores cooperative cancellation.

This slice has no framework-specific route installer or authenticated OpenAPI projection, rate limiter, or provider deployment integration. A host remains responsible for transport security, authentication, rate limiting, and deployment.

Reproduce the GET override

With Node.js 22 or newer, run npm ci and npm run example:e10 at the root. In the exported E10 project, start npm start, then request http://127.0.0.1:8788/api/content/search?q=night&limit=1; the response contains the existing first search match. Missing q or a fractional limit returns invalid_input without invoking the source function. Supply a valid query and integer limit, then retry. See E10 setup.