Skip to main content
Package 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.Context first. What it acts on and a value to store are plain arguments, as in Get(ctx, id), Send(ctx, text), and Update(ctx, name, entry); options and filters are one struct named resource then verb, as in paddock.SessionCreate and paddock.EventList.
  • List of a paged collection returns an iter.Seq2[T, error] over every item, fetching pages as you go; ListPage returns one page with Data and NextCursor. Models.List takes no parameters and is one page. Three lists are not paged this way: Events.List returns one *EventPage with Data and HasMore, paged by After and Before, and Files.List and Memory.List return a []FileEntry.
  • Agent and Session are 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.ShellInput from a remote message is a *cloudagent.ShellInput.

The main flow

A 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.