runner

Documentation

Index

• func Run(ctx context.Context, ws *workspace.Workspace, sessionID, userMessage string, ...) (<-chan agentsdk.SDKMessage, error)
• type Config
• type Event
  • func ToEventPayload(msg agentsdk.SDKMessage) (Event, error)
• type Spec
  • func BuildSpec(ws *workspace.Workspace, sessionID string, cfg Config, sessionExists bool) Spec
  • func (s Spec) ToOptions() []agentsdk.QueryOption

Functions

func Run

func Run(
	ctx context.Context,
	ws *workspace.Workspace,
	sessionID, userMessage string,
	cfg Config,
	mcp *agentsdk.McpSdkServer,
) (<-chan agentsdk.SDKMessage, error)

Run starts a Claude Agent SDK session for a single turn. The returned channel emits SDKMessages until the session terminates (result message, SDK error, or ctx cancel). The output channel is closed automatically when the SDK message stream ends; the underlying CLI subprocess is closed in the same defer so callers don't need to call sess.Close().

Types

type Config

type Config struct {
	SystemPrompt             string
	MaxTurns                 int
	AnthropicAPIKey          string
	AnthropicAuthToken       string
	AnthropicBaseURL         string
	DisableFileCheckpointing bool
	AutoCompactWindow        int

	// Phase 1 Task 7: TUI metadata threading.
	SessionID           string
	TurnID              string
	ChannelType         string
	CreatorUserID       string
	PermissionMode      string
	Model               string
	PreferredExecutorID string
	TurnKind            string

	// Phase 1 Task 9: executor list for system prompt augmentation.
	Executors []tools.ExecutorInfo
}

Config holds the broker-level configuration relevant to spawning a CC worker. All fields are populated from cc-broker's process env at startup.

type Event

type Event struct {
	EventType string          // canonical short tag for our own queries
	Payload   json.RawMessage // verbatim SDK message JSON
	Ephemeral bool            // true = SSE-only, do not persist
}

Event is the cc-broker-side projection of an SDK message ready to be inserted into agent_session_events and broadcast over SSE.

func ToEventPayload

func ToEventPayload(msg agentsdk.SDKMessage) (Event, error)

ToEventPayload classifies an SDKMessage. The raw JSON is preserved as payload so frontend consumers and audit replay see exactly what the SDK produced. The EventType field is our internal tag — useful for indexed queries — and is intentionally a small enumeration so new SDK message types fall through to a generic "sdk_event" without breaking callers.

type Spec

type Spec struct {
	SessionUUID                     string // bare UUID (cse_ prefix already stripped)
	SessionExists                   bool   // true → --resume, false → --session-id
	Cwd                             string
	Env                             map[string]string
	SystemPrompt                    string
	AllowedTools                    []string
	DisallowedTools                 []string
	PermissionBypass                bool
	AllowDangerouslySkipPermissions bool
	MaxTurns                        int
	McpServer                       *agentsdk.McpSdkServer
	Model                           string
}

Spec is the SDK-agnostic projection of "everything we are about to pass to the Claude SDK for one turn." It exists so tests can assert exactly what we would have asked the SDK to do, without depending on the SDK's unexported queryConfig. ToOptions() translates a Spec into an agentsdk option slice.

Session lifecycle: the Claude CLI requires distinct flags for "create a new session with this UUID" (--session-id) versus "continue an existing session" (--resume). They are mutually exclusive: --session-id rejects IDs that already have a jsonl on disk, --resume rejects IDs that don't. runner.Run inspects ws.ClaudeDir before BuildSpec to decide.

func BuildSpec

func BuildSpec(ws *workspace.Workspace, sessionID string, cfg Config, sessionExists bool) Spec

BuildSpec composes a Spec from workspace + sessionID + config. Pure. Mirrors §2 of the design spec. sessionExists must be true iff a session jsonl for this UUID is already present in ws.ClaudeDir (caller checks via filepath.Glob before invoking).

func (Spec) ToOptions

func (s Spec) ToOptions() []agentsdk.QueryOption

ToOptions translates a Spec into the agentsdk option slice that NewClient/Query consume. The McpServer field is wired separately because callers usually build the MCP tools after BuildSpec.