agents::begin

Tag 0: the client begins its work on an agent container, once, first, and hands over the arguments and the template id; the server answers Begun, carrying the dependencies the container declared and the secrets it takes, once the container holds them and, for the life of the connection, every loop of the agent on the scope — Active, every chunk the agent says, and Inactive carrying the rotating secrets handed back; every channel of the container’s life rides this scope.

The client opens the scope with a request whose payload is the tag byte 0 followed by the request as JSON: the arguments and the id of the template the container is made from. The server answers with exactly one Begun response, carrying the dependencies the container’s program declared and the secrets it takes, once the container holds its arguments, and after it sends every loop of the agent’s conversation as responses, for as long as the connection lives; the server ends the scope by the response finish when the server ends, or after an error it sends when it cannot collect a loop’s rotating secrets. This section states what the server does. It states nothing about the client beyond the order Connection provides.

The request. Request states its form.
The response. Response states the one response and the sequence of the main stream.
The channels. The client opens the channels that Client Channels defines; the server opens the channels that Server Channels defines. Each channel is its own section. Neither party opens a channel on the scope before the Begun response.

The order#

The server reads the request. A request whose payload does not decode is answered by a response finish that no response precedes, as Container Proxy Endpoints provides. A begin on a connection that has begun is answered by exactly one response, the error, and the finish; the first begin continues.
The server hands the arguments and the template id to the container. Both are held for the life of the container. A container that refuses them is answered by exactly one response, the error in the container’s own words, and the finish; the connection has not begun.
The server answers Begun. Exactly once, and before any chunk, carrying what the container’s program answered its registration with: the dependency tool templates it declared, and the secrets it takes, each by name to its mode. The server reads neither.
The server holds delivery until the container is fed. From Begun, and from every Inactive, the server delivers no message to a program that declared one or more secrets until the client has opened a secrets channel and the server has answered it Fed. A program that declared no secret is delivered to from Begun and from every Inactive.
The server relays the conversation. A message the client sends on an enqueue channel is the only thing that starts a loop or joins its queue. The server sends Active when a loop begins, each chunk the agent produces as one response, in the order produced, and, when the loop ends, collects from the program the value of every rotating secret it declared and sends Inactive carrying them. A collect the program does not answer with every value asked for is answered by exactly one response, the error naming the secret and carrying no value, and the finish.
The scope ends with the server. The server sends the response finish when it ends, and after the error of step 5, and at no other time.

The rules that hold throughout#

One begin. The server serves exactly one begin scope per connection.
Both directions. The server opens channels on this scope for everything the container asks of the world outside it — its database connections, its tool calls outward — and the client opens channels on it for the image’s /DIVERGE.md, the queue, the feed of the secrets’ values, and its half of each database connection.
No daemon connection. An agent container holds no account and asks the daemon nothing: the server opens no daemon channel on this scope, and the client opens none.
One error after Begun. After Begun, the server sends an error response only when it cannot collect a loop’s rotating secrets, and that error ends the scope. A loop that ends in any other way is reported by Inactive and by nothing else on the scope.
No value in an error. No error the server sends carries the value of a secret.
No timeout. The server imposes no timeout on any channel or on the scope.

In this section

Request — The payload is the tag byte 0 followed by the request as JSON: the arguments, as the image defines them, and the id of the template the container is made from; no secret rides it.
Response — The server sends Begun once, carrying the dependencies the container declared and the secrets it takes, or an error and the finish; after Begun it sends Active before each loop, every chunk of that loop as a response, and Inactive carrying the rotating secrets after it, and the finish when the server ends or after the one error it sends when it cannot collect them.
Client Channels — The channels the client opens on an agent container’s begin scope, by tag: its half of a database connection, the image’s /DIVERGE.md, the two verbs of the queue, and the feed of the secrets’ values; no daemon connection, since an agent container holds no account.
Server Channels — The channels the server opens on an agent container’s begin scope, by tag: everything the container asks of the world outside it — its database connections, its tool calls outward — each relayed by the client to its client as a channel of its own; no daemon connection, since an agent container holds no account.