paddock is the Go client of paddock’s API, for your backend. It needs Go 1.24 or later. Outside the standard library and its own module, it depends only on github.com/google/uuid and google.golang.org/protobuf.
Install
The SDK lives in the
github.com/wenfengwang/paddock module, beside cloudagent, the local runtime that runs Claude Code and Codex on your own machine. Package paddock never starts a harness; it only calls the hosted API.Create a client
A
Client is safe for concurrent use.
Conventions
- Every method takes a
context.Contextfirst. What it acts on and a value to store are plain arguments, as inGet(ctx, id),Send(ctx, text), andUpdate(ctx, name, entry); options and filters are one struct named resource then verb, as inpaddock.SessionCreateandpaddock.EventList. Listof a paged collection returns aniter.Seq2[T, error]over every item, fetching pages as you go;ListPagereturns one page withDataandNextCursor.Models.Listtakes no parameters and is one page. Three lists are not paged this way:Events.Listreturns one*EventPagewithDataandHasMore, paged byAfterandBefore, andFiles.ListandMemory.Listreturn a[]FileEntry.AgentandSessionare data structs that also carry their sub-resources:agent.MCP,agent.Sessions,agent.Files,session.Events,session.Turns.- Optional and nullable fields are pointers;
paddock.Ptr(v)makes one. - Message and tool types are the same types as package
cloudagent’s: a*paddock.ShellInputfrom a remote message is a*cloudagent.ShellInput.
The main flow
StreamEvent has exactly one of Session and Event set. An Event carries its envelope (Seq, AgentID, SessionID, TurnID, CreatedAt, Type) and one pointer field per event type: Message, TurnStarted, TurnEnded, AgentUnavailable, DaemonOutdated, SessionStatus, ConfigApplied, and StatusUpdate. A Message has a Kind and one non-nil payload: User, Assistant, Reasoning, Streaming, ToolCall, ToolResult, or Unknown. Cancel the context to close a stream.
Operations
What each operation does is in the guides: Templates, Agents and sessions, Capabilities, Configuration, Models, Triggers, and Files.
Errors
A non-2xx answer is a*paddock.Error with Status, Code, Message, Details, and RequestID; codes are constants such as paddock.CodeNotFound. A request that got no answer is a *paddock.ConnectionError wrapping the cause, context.DeadlineExceeded on a timeout. Inspect both with errors.As. Idempotent requests are retried after a connection error, a timeout, or a 5xx; a POST never is. See Errors.