Decisions

Why connections pair an owner, isolate conversations and delegate delivery through a bridge.

Connections

How a connection is set up, shared, carried for a harness that speaks none, and how an agent's webhooks take their posts.

Connecting a connection

Where a connection's setup lives, which a harness speaks, and who a connection answers.

Where does a connection's setup live?

In a module per connection (lnk-telegram, lnk-slack, lnk-discord, lnk-signal), installed the first time you connect it, rather than in the harness module. You install only the connections you use, with what each needs, such as Discord's Gateway client, and adding one doesn't grow the harness module. The harness module keeps what's the same for every connection: its settings, stopping the agent while it pairs, disconnect, switching and moving.

Which connections does a harness speak?

Its adapter says, with lnk-<name> connections, so connect refuses one it lacks and use says which stop answering. A connection stays in the settings when the harness changes, so switching back brings it back. An adapter that doesn't answer it speaks Telegram. An adapter with an endpoint also speaks the connections Link carries.

Why does the harness module know no connection by name?

So a connection is a module like a harness: lnk-matrix on the PATH plugs in, and adding one of Link's own touches only its module and the core's list.

One map

An agent keeps one map of connections, each as its module's connect made it and describe said of it (its title, which fields are secret, whether it's linked as a device, its hosts), and hands each section to the adapter under the connection's name. The typed sections of Link's own connections stay in link_harness_contract::harness, the contract the adapters read, and a connection from outside Link sits beside them.

One map for every connection

Settings and moves hold connections in one map, bots, and lnk agent list --json prints it as bots. A Telegram token keeps its Keychain name, bot-token, so no Mac asks for it again.

Who does a connection answer?

Whoever sends the one-time code printed in your terminal, in a private chat or direct message (Telegram, Slack, Discord), or the number you type (Signal), as its owner, and no one else as its owner: a chat you share it with is answered as its members. Knowing the bot, or being in the workspace, isn't enough. Slack's allowlist is by member id: the harness's own for one that speaks Slack, the bridge's for one Link carries.

Shared chats

Why the owner shares a chat, and who in it may do what.

Why share a chat rather than a workspace?

The owner shares individual Slack connections, Telegram groups and Discord connections. A member's direct message stays private to the owner, and bots are refused. Each agent is the cordon: everyone in a shared chat can use all its tools, files and memory. Separate files belong to separate agents. The owner pays for every turn, with no cap per chat.

Why keep the audience in access?

[access] message lists chats, each a group a connection keeps, never a principal: link-agent-identity's Chat, chat:<connection>:<id>. A connection names a person as member:<connection>:<id>, including the workspace when its user IDs are workspace-scoped. The harness keeps the person's identity and name beside their message, never treating them as the owner. Sharing requires a harness that supports these senders.

Who may approve a shared agent's actions?

The owner alone shares, unshares and approves sandbox requests. An admitted member can use the agent's tools. A stranger receives only the tools the spec gives strangers, on a harness that can narrow a conversation's tools. The agent's own schedules, subagents and background commands act for its owner.

Why does sharing stop the agent?

The connection module takes a paired user's mention with a one-time code, within ten minutes, while the bridge is stopped. It never writes the spec. The command atomically edits only [access] message, preserving comments, then restarts the agent. Sharing is done on its machine before a move to a cloud. The three connections use the same contract and are released together.

Carrying a connection

How Link carries the connections of a harness that speaks none, and where that runs.

The connection modules already make the bot and pair its owner; for a harness that speaks the Agent Client Protocol (ACP) at its endpoint instead of speaking connections (lnk-<name> endpoint), the module carries the messages too: lnk-<connection> bridge sends each message from the owner there and the answer back, streamed while it's written.

ACP

Any harness that answers one local endpoint gets every connection Link carries, and a new connection reaches every such harness at once. ACP, is the shape, as every harness is driven the same way so they differ as little as possible, a harness on stdio through the hub; only the new message is sent, never the thread's history, since remembering is the harness's.

Where does the thread go in the request?

In the session's ID, <connection>:<chat id>: each thread is an ACP session of its own.

Where does the carrying run?

In each connection module, outside the harness's sandbox, beside the agent while it runs: a background service of its own (lnk agent bridge, which runs lnk-<connection> bridge per connection), stopped with the agent, or a thread of lnk agent start --foreground; or, where the machine says so, one bridge for every agent (lnk agent bridges).

What the bridge holds

The harness never holds the connection's token, and the bridge holds no state but what the connection needs, so a harness answering elsewhere sees no difference. The harness's endpoint takes a key Link makes at each start, since other users of the machine can reach its loopback.

Endpoint Identity

Why the bridge verifies a harness before sending credentials, and how that proof works while connections start, wake, and move.

How does a bridge know the harness answers on its port?

The endpoint proves it: each message goes on a connection of its own, which first answers a random challenge with an HMAC of it made with the endpoint's key, and only then gets the key and the message.

Why a proof

A start checks the agent's ports are free, but another program can take one in the moment after, or while the harness's service restarts, and a bridge would hand it the key. The other way, the endpoint on a unix socket in a 700 folder, keeps everyone else off it, but a harness's endpoint is an address on the loopback in the contract, which an adapter released earlier can't change, and an adapter can't always make its harness listen elsewhere.

Additive

A challenge needs only a route and a function in the adapter, so it's in the contract as proof, a field with no new version, which an adapter says it answers: older ones keep working, unchecked. The proof is on the same connection as the message, so the port can't change hands between them, and it's a signature of the challenge, never the key, so asking for one gives nothing away.

Waiting through a wake

An agent asleep for being idle is reached through its door, which holds the connection while it wakes the agent and closes it if the agent doesn't answer within two minutes. The bridge waits as long for the proof. A wake that takes longer than a moment, on a busy machine, is then answered by the harness, never taken for another program's answer and the message dropped.

Telegram, Slack, Discord and Signal, where people already chat: all four for any harness, so any harness can answer anywhere Link connects. How a long answer is split, and showing the agent typing, are each connection module's, as their limits differ:

  • Telegram's answer is edited in place about once a second and split past 4,096 characters.
  • Slack's is the same, split past the 4,000 characters Slack recommends; Slack shows no bot typing, so 👀 goes on the owner's message while it's answered.
  • Discord's is the same, split past 2,000 characters.
  • Signal caps how often a message can be edited, so it shows typing and sends the whole answer, split past 2,000 characters.

Where does a linked connection's device live?

In a folder of the agent's for that connection, ~/.lnk/safe/agents/<agent>/connections/<connection>, which the connection's module links into (lnk-<connection> link) and carries from. A linked device's keys read and send as the account, like a token, so they stay out of the harness's home, as tokens stay out of its settings.

When it moves

A move carries what the module names as the link (lnk-<connection> state), never a program it installed, which differs between a Mac and Linux: the machine the agent left deletes its copy, so one device holds the account. It's decided when the agent is sent, from its harness: one that speaks the connection itself keeps the link in its own state, which moves as it always has.

Webhooks

Where an agent's webhook listens, whose its post is, and how long a post's id and a rolled secret are kept.

Where does an agent's webhook listen?

On 127.0.0.1 alone, in the agent's bridge, which already runs outside its sandbox beside it and holds its endpoint's key. Anything public in front of it is a tunnel you open (a relay client), so the address a stranger can reach is always one you chose, and add never opens one.

Its port

The port is chosen once and kept with the agent's settings, so a tunnel to it keeps working after every restart. The listener names no connection: each hook says which module checks its posts (sift), as on a machine that packs agents, where the same module answers the same sift.

Who hands it over

The bridge, not the module, hands a post to the agent, through the way in every message from others takes: who it's from is the webhook's own, so a module can't send a post as the owner's, and its tools are a stranger's.

Why is a webhook's post a stranger's message?

Anyone who holds the secret can post, and a service that signs (GitHub) passes on what other people wrote. So the post reaches the agent from webhook:<name>, quoted, never as its owner, with only the tools its spec gives strangers, none unless it says, and only a harness that can say who a message is from, and keep a conversation's tools, gets a webhook. No answer goes back to the poster: 202 says it was taken, and nothing the agent says leaks to whoever sent it.

How long is a post's id kept, and a rolled secret?

A post's id is kept 30 days, the longest any sender Link knows keeps its own (GitHub's, whose posts sign no time), so one keep covers every scheme. It's kept only once the agent's harness has taken the post, when it answers the way in, before its turn ends: a sender gives up long before a turn might, and waiting would hold the post's place for the whole turn. One the harness refused, or that couldn't reach it (its harness down), is answered 503 and let go, so the sender's redelivery is taken rather than refused as a repeat.

A rolled secret

A rolled secret's previous one is taken for 24 hours, its expiry kept beside it, or until lnk agent webhook rotate <name> --done: Link can't see when the sender switched without carrying which secret matched through sift, and a day is enough to paste the new one in.

What does a mention in a group get?

An answer, there, on every harness and connection: the owner mentioning their agent in a group, connection or server gets it answering, as in a direct message, since silence looks broken. Only the owner's mention is answered; anyone else's, and a message that doesn't mention it, get nothing. Link sets it in each harness's settings (OpenClaw's and Hermes's group policies), and Link Harness's bridges carry the mention, each group a conversation of its own (<connection>:<group id>), so switching harness doesn't change it.