Harness Hub

link-harness-hub serves a harness that speaks the Agent Client Protocol (ACP) over stdio to Link's bridges, as Link Harness serves its own: ACP over a WebSocket at the endpoint's /acp, opened with the agent's headers and its endpoint key. It's a package each adapter's relay is built on, in the adapter's own serve, never a process of its own.

Native Lifecycle

Launcher resources stay alive until their native ACP child has been stopped and reaped, even when a connection outlives its hub or initialization fails. A gateway captured by an adapter's launcher therefore closes after its ACP client, so native cleanup can release the client's sessions and leases. On Unix the ACP launcher has an owned process group. Cleanup stops that group before reaping its leader, including native clients a launcher respawned. A naturally exited launcher retains its wait ownership until cleanup, so its remaining descendants cannot outlive the ACP owner.

The harness behind it

One harness runs behind the hub, started by the adapter's Start on the first message and again whenever its output ends. It answers /health once the harness has agreed on ACP, waiting a little for one still starting. A permission the harness asks for is given with the first option that allows, since Link's sandbox is what confines it.

A harness that can't start

A start that fails, or never agrees on ACP, is tried again only after a wait: 1 s after the first failure, doubling with each one in a row, at most a minute. Until then /health and every message are refused with the last failure's reason, so health checks can't restart a broken harness every second. A harness that answered once and then stopped starts again at the next message, with no wait.

A harness that keeps failing

A harness that ended within a minute of agreeing on ACP counts as a failure too, and one that has run a minute clears the count. After five in a row (restarts.toml) the hub stops starting it: it warns once on its log, naming the last reason, and refuses /health and every message with that reason until the agent is started again. A harness that refuses to run past its start, such as one waiting on a migration of its own, is then never restarted forever.

Threads and sessions

A bridge names a session by its thread (telegram:42), as Link Harness does; the harness makes sessions of its own. The hub keeps which session is each thread's in a file, so a thread goes on where it was after a restart. It uses the harness's session/resume, or session/load when that's all it has. Explicit new and resume requests answer only after opening and saving the native binding, even before the first prompt. Unaddressed new sessions receive random IDs; repeating an addressed open keeps the existing binding.

Operation ownership

A thread's opens, loads and prompts run one at a time. Each session's updates go back under its thread's name. Adapters using Hub::single_session serialize these foreground operations across all threads while keeping inactive bindings. Other adapters can run different threads concurrently. Native background jobs and children need their own runtime confinement and settlement.

Cancellation

Cancellation reaches only a session opened in the existing live runtime. It never starts or reconnects a process to cancel saved work. Native cancellation remains scoped by the protocol's session ID.

Failed recovery

A saved session that cannot resume returns an error and keeps its binding. The hub never substitutes an empty session after refused recovery or when the runtime supports neither resume nor load. A later compatible runtime can still take up the original session. A thread with no saved binding creates a new session.

Binding integrity

Only a missing binding file means no saved sessions. Unreadable or invalid metadata refuses health checks and runtime startup until repaired. Empty native IDs and a native session assigned to several threads are refused. New bindings become visible in memory only after their atomic file write succeeds, so a failed write cannot change routing for a later prompt.

What a prompt carries

A prompt is told taken (_link/taken) as it's forwarded, so a webhook's sender is answered then. When its _meta.link says it's from someone other than the owner, the hub writes who into its text, a line of its own with their name and hops, each of their lines quoted, so a harness that reads no _meta still knows; a sender that isn't one is refused before the harness sees it. The _meta goes on to the harness as it came.

A command by another name

The owner's command goes to the harness by a name it offers, as its session's latest available_commands_update lists them. A prompt that is one command, an action of Link's namespaces or one of its aliases (/chat:create, /new), goes as the first of the action's names the harness offers; one it offers, or one no action has, goes as it came. The names are the namespaces' modules' actions.toml's.

The first command

A known command waits for its session's command list, including a list published after session/new answers. If no list arrives within the harness call timeout, the command fails before forwarding. Normal messages do not wait for command discovery.

Link's tools and memory go with each session the hub makes, resumes or loads, as its mcpServers: each an MCP server over HTTP at its address on Link's proxy. An adapter's configure keeps them (Tools::keep) and its serve hands them to the hub. A harness that says it takes no MCP server over HTTP (mcpCapabilities.http) is given none, and its adapter writes Link's tools into the harness's own settings instead.

Agent state

The hub answers the agent state of Agent State Protocol (ASP) for the harness behind it, each session named by its thread both ways. A harness that advertises agent state answers it itself. Otherwise the adapter's Store reads and writes the harness's own files, and the sessions a store doesn't give are replayed through the harness's own session/list and session/load, when it has them. Temporary replay routes restore the preceding destination even when a load fails.

The capture boundary

Describe, export and import wait up to two minutes for admitted session operations to finish. Once queued, capture excludes later admissions through its native calls, file operations and routing commit. A blocking store retains that exclusion even if its waiting caller is cancelled. This barrier covers hub foreground operations; adapters still own native background settlement and the consistency of their own file stores.

Portable Personal History

Personal adapters opt into an append-only archive under .lnk/data/agents/context/. Admitted prompts and native updates are synced before forwarding or acknowledgement. Imported updates remain exact, separately from native model input. Unmapped native histories receive stable archival thread IDs that never guess a channel, account, group or topic destination.

Continuation Without Native Import

When native import is unavailable, the hub retains the portable session and supplies bounded historical context with its next prompt. Existing native bindings remain available. The context contains current sourced memory, including deletions, all user text, and recent replies and tool evidence that fit. Required material that exceeds the budget refuses continuation. Historical tools are data and are never executed by import.

Capture Recovery

Each capture record is written privately, synced, renamed and its directory synced before admission succeeds. Reopening replays the records in order. Unknown, incomplete or foreign records refuse continuation and retain their originals. Repeated imports of an already retained prefix do not append it again. A repeated transport delivery requires outcome reconciliation before the hub will forward it again.

Identity and Interrupted Writes

Records bind to the immutable agent, owner and adapter. A complete pending record is committed once on reopening. A partial record refuses startup. Imports validate every routing identity and native source correlation before committing the group. Reusing a native record ID with changed content is an error. Archive files are limited to 48 MiB each, with oversized capture refused before forwarding.

Context Budget

The shared selector reserves at most one quarter of the model's window, counted conservatively as UTF-8 bytes, capped at 32 KiB. An unknown window uses 8,192 as its input limit. The supplied record keeps its thread, archive position and selected and omitted indices. Native context limits still apply to instructions, cached history and tools together.

What comes in

An import's sessions each become a thread: under its old name when that's a valid thread name, else a new one. All returned bindings are validated and saved together, including swaps between existing threads; invalid or unwritable routing publishes none of the group. Successful restore clears the loaded-session and command caches, so the next open takes up the restored native session. A harness with neither state source answers that it takes none, kind by kind.

Its endpoint

The hub refuses a connection without the key, or naming an agent that isn't its own, and proves it holds the key before it's sent it, as the contract asks; Hub::serve sets TCP_NODELAY on each connection it takes.

Why it works this way

The hub's decisions explain its thread mapping, native state boundary and why it shares code inside each adapter's endpoint.

Kept tool delivery also holds the agent's proved action endpoints and names. The hub runs these owner commands through their routes before forwarding a prompt to the native harness, and returns the typed answer through ACP. It adds them to the harness's advertised command list. A message from another sender cannot invoke them. Per-harness conversation commands continue to use the native session's advertised names and aliases.