Protocol
First Attach
AttachSession is the bidirectional stream that chainctl develop uses for interactive terminals. The
simple SDK uses it for one thing only: completing a new sandbox’s first attach, which the service
requires before it allows Exec.
Why It’s Needed
Section titled “Why It’s Needed”A session created with a workspace environment expects the client’s files to be uploaded on the first
interactive attach (Session.workspace_pending is true until then). Until that happens:
Execis refused:FAILED_PRECONDITION“attach with a shell first to upload the workspace”.- A forwarding-only attach doesn’t count:
open.no_shellneedsopen.endpoints(“open.endpoints: required for a no_shell attach”).
So right after CreateSession (and in connect, if a sandbox still has workspace_pending), the SDK opens
one short shell attach, uploads an empty tree, and detaches. It takes about 0.2 s. A session started
from a repository (source) doesn’t need it.
The Exchange
Section titled “The Exchange”- Open: the first message must be
open. The SDK sends only the sessionnameand an emptyresume. Terminal size, working directory and the other options are left unset. - Opened: the service answers
opened. Ifworkspace_pendingisfalse, there’s nothing to upload and the SDK detaches right away. - Upload: one
workspace_chunkwith an empty tar archive (1,024 zero bytes, the tar end-of-archive marker),last = true,format = FULL_TAR. Ifopened.workspace_encodingsincludesGZIP, the SDK gzips it and setsencoding = GZIP. - Ready: the service unpacks it into
/work(nothing) and answersworkspace_ready. - Detach: the SDK cancels the RPC. The session keeps running and is now ready for
Exec.
Messages
Section titled “Messages”Only the parts of the two oneofs the SDK uses are shown:
rpc AttachSession (stream AttachRequest) returns (stream AttachResponse);
message AttachRequest { oneof input { Open open = 1; // first message WorkspaceChunk workspace_chunk = 4; // not used by the simple SDK: stdin = 2, resize = 3, forward_response = 6, // stdin_eof = 7, grant = 8, resume = 9, credentials, PTY control, sharing }
message Open { string name = 1; // required: the session Resume resume = 4; // the SDK sends an empty Resume // rows = 2, cols = 3, no_shell = 5, endpoints = 6, handoff = 7, org_consent = 8, // working_dir = 9, multi_pty = 10, end_input_at_prompt = 11: left unset }
message Resume { uint64 incarnation = 1; // all zero on a first attach int64 offset = 2; uint32 pty_id = 3; }
message WorkspaceChunk { bytes data = 1; bool last = 2; Format format = 3; Encoding encoding = 4;
enum Format { FORMAT_UNSPECIFIED = 0; FULL_TAR = 1; // what the SDK sends DELTA_TAR = 2; // git-delta uploads: not used }
enum Encoding { ENCODING_UNSPECIFIED = 0; GZIP = 1; } }}
message AttachResponse { oneof output { Opened opened = 5; WorkspaceReady workspace_ready = 6; Detached detached = 4; // another client took over // not used by the simple SDK: stdout = 1, stderr = 2, exit = 3, // forwarding, credential, PTY and sharing messages }
message Opened { int32 rows = 1; int32 cols = 2; string session_name = 3; bool workspace_pending = 4; // an upload is expected repeated AttachRequest.WorkspaceChunk.Encoding workspace_encodings = 6; }
message WorkspaceReady { int64 bytes = 1; google.protobuf.Duration elapsed = 2; }
message Detached {}}Side Effects
Section titled “Side Effects”- While the stream is open, the SDK’s attach holds the session’s lease (
shell_attach_holder), so a concurrentExecwould wait. The SDK makes no other calls until it has detached. - Right after the detach, the first
Execcan getFAILED_PRECONDITION“instance held by another controller” for a moment; the SDK retries it (see Exec).
