Skip to content

API contract

The backend is Go. The surfaces that call it (the web console, a Slack app, later a GitHub app) may be TypeScript. They share one contract: api/openapi.yaml, an OpenAPI 3.2 description of every route internal/httpapi serves. The TypeScript client in packages/client is generated from it.

How the contract stays true

The spec is written by hand, from the code. The tests in internal/httpapi/openapi_test.go run with go test ./... and fail when the two disagree:

Test Fails when
TestSpecListsExactlyTheRegisteredRoutes A route is registered and not in the spec, or the reverse. An operation has no operationId or tag, or its x-permission is not the permission Server.Handler names for the route. Routes are read with go/types, so any call of (*http.ServeMux).Handle or HandleFunc counts, whatever its receiver is called, and one the reader cannot resolve to a constant pattern and permission fails the test.
TestSpecPermissionsAreTheOnesTheServerEnforces The running server enforces a different permission than x-permission says.
TestSpecSchemasHaveTheFieldsTheGoTypesMarshal For the named Go types it lists (about 75), the type marshals a field the schema lacks, or the schema has one the type lacks, or required disagrees with omitempty. The event union is not the catalog: EventType is not exactly event.Types(), or RunEvent's type mapping lacks a type, has one more, or maps a type to a variant whose data is not the body that type decodes to. TestEventUnionParityCatchesAMissingVariant proves a missing mapping entry fails.
TestResponsesMatchTheSpec, TestEventStreamMatchesTheSpec A real response, including 4xx and the event stream, does not validate against its schema, or answers with a status the spec does not list. Every JSON operation must be exercised.
TestResponsesMatchTheSpec A documented status code is never produced by a test, unless it is in unexercised with the reason. 401, 403, 413 and 500 are covered once for every route.

Validation in these tests is stricter than the published spec: every object schema refuses properties it does not name. So a key added to a response built from a map or an inline struct (getMe, getStorage, a refusal, a manifest) fails as soon as a test sees it. What is not guaranteed: a property that is optional in the spec and that no test makes the server send can drift without notice, and so can a field of a response shape no test reaches.

An operation that is offered as a tool over the humagen MCP (POST /api/mcp) says what a call does with three markers beside x-permission: x-readonly: true for a call that changes nothing, x-destructive: true for one that removes something, and x-idempotent: true for a change that is safe to repeat. An MCP client is given them as the tool's hints. They are read from the contract and never from the HTTP verb: getMessageContext is a POST because it takes a body, and it is a read. An unmarked operation is listed as a change that is neither destructive nor safe to repeat, and TestAnOperationsHintsComeFromTheContract fails for a GET that is offered as a tool and not marked x-readonly. TestTheMCPListsExactlyItsTools pins the tools the MCP lists.

So a change to a route, a handler's answer or a type's JSON fields is a change to api/openapi.yaml in the same commit, followed by make client. A new event type registered in fiber's catalog needs its variant in RunEvent and EventType too.

Events

Every event is one envelope (EventEnvelope: id, source, type, subject, channel, time, hops, and on run events tenant, run, seq, agent, version, digest) with data, the body for its type, as inline JSON. type is the only discriminator and carries the version, such as run.completed.v1. RunEvent is the union, one variant per type in the catalog. A type not in its mapping is an UnknownEvent: a reader passes over it and never guesses its shape. The API sends run events only (run.*).

type data Was
run.accepted.v1, run.started.v1, run.resumed.v1 RunAcceptedEvent, RunStartedEvent, RunResumedEvent lifecycle.accepted, .started, .resumed
run.parked.v1, run.child.parked.v1 the question (question, and questions with every one when a batch of tool calls parked the run on several; run.resumed.v1 then carries answers), the child's question lifecycle.parked, lifecycle.child.parked
run.delta.tool.marker.v1 ToolMarkerEvent: a tool call that waits for a decision, such as an approval. The question a person answers is on run.parked.v1 none
run.completed.v1, run.failed.v1, run.stopped.v1 the answer and usage, the error and terminal, the reason and partial answer lifecycle.completed, .failed, .stopped
run.delta.text.v1, run.delta.thinking.v1, run.delta.tool.call.v1, run.delta.tool.done.v1, run.delta.citation.v1 one fragment each delta.*
run.action.taken.v1 the action and its summary action.taken
run.usage.v1, run.usage.child.v1 (opt-in) one model call, a child's total usage.call, usage.child
run.context.compacted.v1 (opt-in) the compaction context.compacted

The schema names are in RunEvent's mapping in api/openapi.yaml. UnknownEvent is any other type, with data left as the server sent it: a newer server can add a type without breaking an older client.

GET /api/events takes channel (a channel prefix), type (type prefixes, repeated) and run, and from to resume. With none it sends every run event the caller may read, run.usage and run.context included. The workspace is always the caller's. The old topic is deprecated. It still works and cannot be combined with the others: agent:<name>:<run> is read as run=<run> (internal/legacy.Topic). inbox=true sends inbox and thread notices alone, with no run event, and takes no other filter. GET /api/journal filters by type, repeated for more than one; the old kind is still read when no type is given.

Breaking change. This replaced kind and a base64 payload on every event. A client generated before it reads neither type nor data: regenerate it (make client) and switch on type. Each old kind maps to one type in the table above; lifecycle.* became one type per ending, and control.created, control.revised and control.deleted are gone.

Validation uses santhosh-tekuri/jsonschema, a JSON Schema 2020-12 validator with no dependencies of its own, which is the schema dialect of OpenAPI 3.1 and 3.2. The spec is read with go.yaml.in/yaml/v4, which was already in the module graph.

Commands

Task Command
Regenerate the client after changing the spec make client
Build, typecheck and test the client make client-check
Lint the spec with Redocly make spec-lint
Check the spec against the server go test ./internal/httpapi

make client needs oag at the version pinned in the Makefile. make oag-install downloads that release for this machine into ~/.local/bin (or OAG_DIR) and refuses it unless its sha256 matches the one pinned beside the version, because oag publishes no checksums of its own.

CI installs oag the same way, regenerates the client and fails if the result differs from what is committed.

The generated client

packages/client is @humagen/client: private, ESM, typed, no runtime dependencies, for Node 22.12 or later and browsers. Consumers in this repository depend on it with "@humagen/client": "link:../../packages/client" and run pnpm build in packages/client first, because the package exports its built dist/.

Path What it is
packages/client/oag.yaml The generator's configuration.
packages/client/.oag/packs/node-client oag's node-client template pack, copied unchanged from oag v0.20.6. Without it oag fetches the pack from oag's main branch.
packages/client/src/generated/ oag's output. Committed, never edited.
packages/client/src/humagen.ts The hand-written layer over it.

The generated output is committed, as fiber commits gen/: a change to the contract shows up as a reviewable diff in the client, consumers need no generator to build, and CI can prove the two match.

One method per operation, named by its operationId. Path parameters come first, then the body, then query and header parameters in the order the spec lists them, then RequestOptions (signal, headers, timeout, retry). Each also has a ...Raw form that returns the status and headers.

The layer in humagen.ts adds what the generator does not do:

  • createClient({ baseUrl, token, credentials }): token is a string or a function that returns one, sent as a bearer. credentials: "include" uses a browser's session cookie instead. Retries are off unless asked for.
  • events({ channel, type, run, from }): the event stream as typed items, told apart by item: event carries a RunEvent, inbox an InboxNotice. A RunEvent is an envelope whose data is the inline JSON body for its type, so a switch on event.type narrows event.data. Leaving the loop by break, return or a throw, or the stream ending, closes the connection.
  • runFilter(run, type?): the filter for one run's events.
  • endsRun(event): whether an event ends its run on the stream: run.completed.v1, run.stopped.v1, or run.failed.v1 with data.terminal.
  • runEvents(run): one run's events, to the one that completes it, stops it or fails it for good. If the stream drops first, it reads the run's record and resumes after the last seq, with backoff. It never ends quietly before the run's last event: it throws StreamEndedError with reason stopped (the record says stopped and its run.stopped.v1 was no longer on the stream), ended (the record says completed or failed and no ending event was found) or gave-up (it could not resume). The last read of a run that has ended waits at most resume.drainMs (2 s by default) for that event.
  • failureOf(error): the status and the API's error body from any error the client throws, and refusal when a limit refused a run.
  • getArtifactContent and getPreferencesPhoto return the file's bytes. The generated versions read the body as text.

Authenticating a machine

A machine sends an OIDC access token issued for the API audience by client credentials: Authorization: Bearer <token>. It has no role. It may do exactly what the humagen:<permission> scopes on its token allow, and its workspace comes from the token's tenant claim. Each operation's x-permission names the scope it needs. A Slack surface needs at least humagen:agents:read, humagen:runs:read, humagen:runs:write and humagen:billing:read, plus the write scope for each inbox action it offers. The Slack app's Home lists a mapped person's projects, which takes humagen:projects:read too. An app run as a client (HUMAGEN_CLIENT) reads its client and its bindings, which takes humagen:clients:read, and catches up on each bound project's announcements in the project's inbox, which takes humagen:projects:read: without it, release notes, and announcements made while the app was away, never reach Slack. See security for setting up the identity provider.

Under make dev the server runs with development auth: every request is the same admin, and no token is needed.

Example

Start a run under the caller's own idempotency key, stream its answer, and stop it if it takes longer than a minute:

import { createClient, failureOf, StreamEndedError } from "@humagen/client";

const client = createClient({ baseUrl: "http://127.0.0.1:8080", token: process.env.HUMAGEN_TOKEN });
const run = await client.createRun({ agent: "helper", text: "Say hello" }, "slack-event-Ev01");
const giveUp = AbortSignal.timeout(60_000);
try {
  for await (const event of client.runEvents(run, {}, { signal: giveUp })) {
    if (event.type === "run.delta.text.v1") process.stdout.write(event.data.text);
    if (event.type === "run.action.taken.v1") console.log(`\n${event.data.summary ?? ""}`);
  }
} catch (error) {
  if (giveUp.aborted) await client.stopRun(run.id);
  else if (error instanceof StreamEndedError) console.log(`\nended: ${error.reason}`);
  else throw new Error(failureOf(error)?.message ?? String(error));
}

runEvents returns after the event that completes the run, or fails it for good, and closes its connection however the loop is left. It also yields run.usage.v1, one per model call, and run.usage.child.v1; a reader that does not count usage passes over them, and getRun has the run's total in usage. A type the client does not know (UnknownEvent) is passed over the same way. A dropped stream is resumed. A run stopped elsewhere ends it with StreamEndedError and reason stopped. getRun is the authority on whether a run is over. A refusal by a limit throws from createRun: failureOf(error).refusal names the limit, the policy and when the count resets.

Agent sessions

POST /api/sessions starts or continues one agent's session. The list and detail routes return its real conversation metadata, messages, children, evidence links, and usage. Post to /api/sessions/{id}/messages to continue it, or select an agent and fresh to start an independent child. People, links, stop, and feedback routes share the same ancestor-aware access checks as transcript reads.

GET /api/sessions/{id}/stream supports Last-Event-ID with one cursor per run. A session-reset event supplies the authoritative snapshot when completed run cursors are compacted; clients replace transient stream state with that snapshot.

Messages while an agent works

A message posted to /api/threads/{id}/messages or /api/sessions/{id}/messages that would start agent work, while a top-level run its poster may stop is working in the conversation, is a follow-up. It starts nothing at once. Posting answers with rule followup, and the message carries followup:

Outcome What happens
queue The message waits. Once every run in waiting has ended, and no run answering an earlier message is working, what it calls for starts. Queued messages start in the order they were posted.
replace The runs in waiting are asked to stop with the cause replace: <reason>, keeping what they have said. The message starts once they have ended.
stop The runs in waiting are asked to stop with the cause stop: <reason>. Nothing starts, and the reason stays on the message.

The first word after any leading mentions forces the outcome: queue, replace or stop, in any case, with an optional colon. After stop the rest is the reason; after queue or replace the rest is what runs, with the leading mentions kept. A message that starts with stop is a follow-up even when it would start no work itself. Otherwise the workspace's router model decides, given both texts as data. No model, a timeout, an error or an answer that is not exactly one JSON object with a known outcome and a reason all queue.

handled is set once a follow-up was carried out. Release is a completion step of each run, retried until it succeeds, so it survives a worker restart. It reads the poster's access as it stands then, not as it stood when they posted: someone no longer allowed to post there starts nothing. The runs a released message starts are named by the message, so a retried release joins them instead of starting them again. The poster's model and effort choice is kept for them.

A run the poster may not stop is neither waited on nor interrupted. A post with post_only, an answer to a question and a reply are never follow-ups. The console's composer still queues its own messages before sending them.