Ports

Ports is the programmatic surface for durable agent runs. You POST a task to an agent by slug and get a run id back immediately; a worker executes the run independently of your request, and you reattach to a database-backed event stream to watch model calls, tool calls, human-approval pauses, and the final cited answer. Because every step is persisted, a client can disconnect, redeploy, or reconnect from a different machine without losing or restarting the run.

The same workspace is also exposed to third-party agents and IDEs through a native Model Context Protocol endpoint at /api/mcp, authenticated with the same bearer keys. MCP is a read-and-ask surface: it does not start or manage runs.

Use it standalone

Ports needs two API-key scopes and nothing else from the platform. agents:run starts, cancels, approves, and records feedback on runs; runs:read reads a run, its steps, and its stream. Both are in the default scope set for a new key, so a freshly issued key usually already has them.

What Ports does not require

No kb:read, kb:write, data:read, data:run, or reports:* scope is involved in any of the seven run operations. The run lifecycle — queue, stream, cancel, approve, feedback, steps — is complete without a single document, entity, or data connector in the workspace. What an agent can usefully do depends on the tools its version enables, which is where the other modules enter; see how it composes.

React components

@eli-ai/react/agents exports two components. Both are client components, both require an EliProvider above them, and both build their own agents client from the provider's transport — they import no other capability module. EliAgents is an alias export for EliAgentRunner (the same function, re-exported under a shorter name).

EliAgentRunner

A complete run surface: a form (agent picker or free-text slug input, plus a task textarea), a Run agent submit button, a Cancel run button that appears while a run is in flight or suspended, a live-region list of run events, and an Allow / Deny panel when the run suspends on a tool that needs a human. Starting a run calls createRun then streamRun; resolving an approval calls resolveApproval and then reattaches to the stream, skipping the replayed model_call and tool_call frames it has already rendered. Cancelling aborts the local reader and calls cancelRun.

EliRunDetail

A read-only trace of one run by id, with an optional cancel action in the header. It fetches getRun once (and refetches after a successful cancel) and renders three KPI tiles — Status, Tokens (the sum of tokensIn and tokensOut), and Cost (costUsd to four decimals) — above an ordered list of steps. Each step card shows its index, its name falling back to its kind, a status badge, a formatted timestamp, and the step output as pretty-printed JSON when present. The cancel button only renders while the run status is queued, running, or suspended.

Headless, with your own markup

Every component is a thin shell over createAgentsClient and the two generic hooks from @eli-ai/react/hooks. If the built-in eli-* markup does not fit, use the client directly and keep the provider for transport and workspace resolution.

HTTP API

Seven operations, all bearer-authenticated with Authorization: Bearer eli_sk_… or eli_uk_…. A user key that can reach several workspaces must also send X-Workspace-Id. A run that belongs to another workspace is invisible under row-level security and returns 404 rather than 403 — the distinction is deliberately hidden.

The curl examples below use -L on non-GET calls because the apex host issues a 308 redirect, which preserves the method and body.

Five frame types are emitted, each as one data: line of JSON. guardrail, approval, and retry steps have no stream equivalent and are skipped during replay — read them from /runs/{id}/steps instead.

MCP endpoint

/api/mcp is a stateless Streamable-HTTP Model Context Protocol server. Every request builds a fresh server bound to the workspace resolved from the bearer key — the remote model never supplies the workspace. POST, GET, and DELETE are all handled by the transport per the MCP spec; POST responses are plain JSON, so clients must send Accept: application/json, text/event-stream.

Data elements

Every table below carries a workspace_id column and a workspace row-level security policy; all reads and writes run inside a workspace-scoped transaction with FORCE RLS, which is why a cross-workspace run id is invisible rather than forbidden. Note the naming: the run table is agent_runs, even though the API path and the TypeScript contract call it a Run.

Feature map

Six feature areas cover the module: how a run is admitted and made durable, what bounds it, how a human enters the loop, how a client watches it, what an agent is allowed to reach, and how the same workspace is served to external harnesses over MCP.

System architecture

The web process and the worker are decoupled by the database. Routes admit, enqueue, read, and resolve; the worker owns the model loop; both sides meet only in the workspace tables. The MCP endpoint is a parallel front door onto the same governed tools, never a second execution engine.

Where the logic lives

The code map locates each component. Table names stay in the notes; all are defined in the schema module with workspace row-level security.

Primary runtime flow

The highest-value path is one durable run end to end: createAgentRun through admission and the queue, the worker loop stepping the model under its locked toolset, a human gate in the middle, and streamRun replaying the trace for whoever is watching.

Internals and invariants

Durable run lifecycle

The loop is hand-rolled around single-step generation: the harness owns the messages array, persists a resume cursor and every step as it advances, and treats the database as the only source of truth. That is what lets a run survive hours-long suspensions, process restarts, and worker crashes without replaying model calls.

• Invariant — a run can resume from Postgres alone: everything needed to continue — system prompt, messages, step index, budgets — persists as the loop advances, and no resume path reads worker memory. Enforced in src/server/agents/runner.ts.
• Invariant — the queued run row commits before the job is sent, so a crash between commit and send is reconstructed from tenant state instead of losing the run. Enforced in src/server/agents/starts.ts.

Admission and budgets

Admission is checked in the web process before the executor pre-creates the run row: first the per-workspace cap on non-terminal runs, then the monthly spend cap. Once running, the per-agent budgets from the pinned config bound steps, tokens, cost, and wall-clock, and exhaustion is a terminal status, not an error.

• Invariant — admission precedes row creation, so a run never counts against its own concurrency cap and a rejected request creates no state. Enforced in src/server/agents/admission.ts.

Human-in-the-loop approvals

A tool that requires review raises a suspend signal from inside the loop; the runner writes the pending gate with the tool name and input, flips the run to suspended, and stops. The decision and the suspended-to-queued transition commit together, and the continuation carries the decided approval back into the loop.

• Invariant — a gate is decided exactly once: the approve path claims the pending row with a conditional update, so a second reviewer sees a 404 rather than a double decision. Enforced by the approve handler in src/app/api/v1/runs with queued continuations reconciled in src/server/agents/continuations.ts.

Streaming and reattach

The stream is a database tail, not a worker attachment: persisted steps replay oldest-first mapped to the same frame types the interactive path emits, then the tail polls for new steps and the run's status, closing on suspended or terminal frames.

• Invariant — the tail performs pure reads, which is why any web replica can serve it and why closing and reopening a stream can never affect the run. Enforced in src/server/agents/reattach.ts.

Agent versions and capability locks

Configuration is immutable-by-version: publishing appends a new version, in-flight runs keep the one they pinned, and the capability lock names the platform areas the agent may reach. The lock is enforced three times — a version outside its own lock cannot be saved, the runner filters the assembled toolset at run time, and the agent's MCP mount projects the same lock outward.

• Invariant— the lock never widens: a legacy version predating its agent's lock degrades to the locked subset at run time rather than escaping it. Enforced in src/server/agents/capability-lock.ts and applied in src/server/agents/runner.ts.
• Invariant — a run pins exactly one immutable version, so editing an agent never rewrites the config a historical run executed under. Enforced by version resolution in src/server/agents/config.ts.

Native MCP surface

Every MCP request builds a fresh server bound to the workspace resolved from the bearer key. Each tool closure re-checks its own scopes before doing work, mirroring the REST scope map, and the per-agent mounts register only the tools the agent's locked toolset maps to — resolved per request, so publishing a new version takes effect without remounting.

• Invariant — the remote model never supplies workspace scope, and the transport is never a scope bypass: workspace binding happens at server construction and scopes re-check per tool call. Enforced in src/server/mcp/server.ts.

For a self-hosting team the supported extension points are the tool and job seams: a plugin tool registers once and appears as both an agent-harness tool and an MCP tool behind the same scope guard, background jobs get namespaced queues, and custom run consoles build cleanly on the headless agents client and the frame types. Admission, budgets, the capability lock, and the durable suspend/resume contract are host-owned and not designed to be replaced.

How it composes

Ports on its own gives you the whole run lifecycle: queue, stream, inspect steps, cancel, approve or deny a gate, and record feedback — under per-workspace concurrency and monthly spend admission, and per-agent step, token, cost, and wall-clock budgets. What it gains from the other seven modules is what the agent can reach, because an agent version's tool allowlist is what wires them in.

• Intake and Atlas — the default tool allowlist is kb_search, kb_doc_read, kb_list_docs, kb_entity_lookup, and kb_graph_query. Those tools are always registered, so a run never fails for their absence — but against an empty corpus or an empty graph they return nothing useful, and the agent answers without evidence. This is the one pairing most agents genuinely want.
• Lens — the final frame's citations array is a list of docId (and optional chunkId) pairs produced by the retrieval and answer path. Without Lens the field is still present and simply empty. The MCP eli_query tool is Lens's structured answer surfaced over MCP.
• Conduit — an agent version with dataEnabled (or a kb_data entry in tools) can look up live rows through governed entity bindings. This genuinely requires Conduit: connectors and named queries must exist, and an MCP caller additionally needs the data:read / data:run scopes. Runs work fine without it.
• Warrant — the per-agent guardrail citations.required and the authority and lifecycle labels returned by the graph tools come from governance. Ports enforces the run-level budgets and the approval gate on its own; certification semantics come from Warrant.
• Lineage — run_steps is already an append-only per-run audit trail, and run_approvals records who decided what and when. Tracing a cited document back to its origin, and forward to everything it affected, is the kb_document_lineage MCP tool and needs Lineage.
• Crucible — the eval trigger value and the five feedback kinds exist so runs can be replayed against a golden set and so human signals feed the improvement loop. You can post feedback with Ports alone; interpreting it as a metric is Crucible.

Wiring an agent's tools, model slot, budgets, and approval requirements is a workspace-application task, not an API one — see Creating agents and Approvals & feedback. For the wire contract in full, read Agents and durable run streams, Authentication and scopes, and Errors.