chunkd

package
v0.7.204 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 9, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package chunkd implements the chunk watch background daemon and its client.

Index

Constants

View Source 
const (
	EnvDir        = "CHUNK_DAEMON_DIR"
	EnvTCPAddr    = "CHUNK_DAEMON_TCP_ADDR"
	EnvRemoteAddr = "CHUNK_DAEMON_REMOTE_ADDR"
	EnvTCPToken   = "CHUNK_DAEMON_TCP_TOKEN" //nolint:gosec // the variable's name, not a credential
)

The variables that say where the daemon is and how to reach it.

View Source 
const (
	// SampleInterval is how often the remote sampler emits a reading.
	SampleInterval = 2 * time.Second

	// StaleSamples is how many intervals a sample may age before the dashboard
	// should treat it as stale. A sampler that dies must look stalled rather than
	// look like an idle sidecar, so the last value is kept and marked, not
	// discarded.
	//
	// The budget has to cover more than SampleInterval: the reading crosses an SSH
	// connection before the daemon sees it, and the dashboard then renders that
	// same snapshot until its next 5s poll while re-evaluating the age every
	// frame. Measured against real sidecars, a healthy sampler reaches ~10s of
	// apparent age just before a poll lands, so a tighter bound flags working
	// samplers as stale for part of every cycle. Twelve seconds clears that and
	// still catches a dead sampler within two polls.
	StaleSamples = 6
)

Resource sampling, as a client needs to judge a sample's age.

View Source 
const (
	BandLow    = "low"
	BandMedium = "medium"
	BandHigh   = "high"
)

Risk score bands. They exist so a caller can act on the score without hard-coding a number, and so the number itself stays arguable: a band is a claim about caution, not a probability of failure.

View Source 
const (
	// ResultPassed means every check passed.
	ResultPassed = "passed"
	// ResultExhausted means checks still failed when attempts ran out.
	ResultExhausted = "exhausted"
	// ResultStuck means the implementer stopped changing the code with checks
	// still failing.
	ResultStuck = "stuck"
	// ResultNoChange means the implementer's work is empty.
	ResultNoChange = "no_change"
)

Why a factory run's loop stopped, as FactoryRun.Result.

View Source 
const (
	// CheckPassed means the check ran and found nothing to fix.
	CheckPassed = "passed"
	// CheckFailed means the check ran and found something to fix.
	CheckFailed = "failed"
	// CheckErrored means the check could not run.
	CheckErrored = "errored"
)

How a check came out, as ReviewResult.Status and RoundCheck.Status.

View Source 
const DaemonSubcommand = "_daemon"

DaemonSubcommand is the hidden command the daemon runs as. Starting the daemon is re-executing this binary with it, so the command that registers it and the code that launches it share this one name.

Variables

View Source 
var ErrAsyncRefused = errors.New("async validation refused")

ErrAsyncRefused is returned by StartAsyncValidate when the daemon will not take this run asynchronously: the tree could not be fingerprinted, so a stale result would be undetectable, or the project already has its cap of runs in flight. Callers fall back to running inline, where the answer reaches whoever asked for it while it is still true. The daemon's reason is wrapped alongside the sentinel.

View Source 
var ErrDaemonPermission = errors.New("the chunk daemon socket is not accessible to this user")

ErrDaemonPermission reports that the socket is there but this user cannot open it — a daemon running as somebody else, or a directory whose mode has been changed.

Kept apart from ErrDaemonUnreachable for the same reason ErrDaemonTimeout is: the advice differs. Starting a second daemon leaves the same socket just as unreadable, so "run chunk watch" is the one thing that cannot help here.

View Source 
var ErrDaemonTimeout = errors.New("the chunk daemon did not answer in time")

ErrDaemonTimeout reports that a daemon was there but did not answer within conflictTimeout.

Kept apart from ErrDaemonUnreachable because the two call for different advice: one means start the daemon, the other means it is already running and busy, so asking again is what helps. Collapsing them told people with a working daemon to go start one.

View Source 
var ErrDaemonUnavailable = errors.New("daemon unavailable")

ErrDaemonUnavailable is returned by RunValidate when the daemon socket is unreachable, so callers can distinguish a transient connectivity failure from a real validation error and fall back to inline execution.

View Source 
var ErrDaemonUnreachable = errors.New("no chunk daemon is running")

ErrDaemonUnreachable reports that no chunk daemon answered.

Callers on the hook path are expected to treat this as "nothing to say" and carry on. The daemon is optional — it runs when the developer has `chunk watch` open — and a hook that complains about its absence would fire on every session end for everyone who does not.

View Source 
var ErrUnauthorized = errors.New("the remote chunk daemon rejected the token (check CHUNK_DAEMON_TCP_TOKEN)")

ErrUnauthorized reports that a remote daemon rejected the bearer token. It is its own sentinel because the fix (set CHUNK_DAEMON_TCP_TOKEN to the daemon's value) has nothing in common with the fix for an unreachable daemon.

Functions

func BuildID 

func BuildID() string

BuildID identifies the binary this process was started from.

The daemon serves snapshots shaped by the code it was started from: a field added to SidecarState since then is absent rather than wrong, so a newer client renders a well-formed view of stale data with nothing to say why. A sidecar owned by a session, for instance, arrives from a pre-session daemon looking like a sidecar nobody owns. Comparing this on every ping is what makes that visible instead of silent.

The version is read per call rather than frozen alongside the file, because main sets it after package initialisation has run.

func CancelSession 

func CancelSession(id string) error

CancelSession stops a session. It is the only thing that does: a viewer that quits merely detaches.

func ClaimNotice 

func ClaimNotice(overlaps []ClaimState) string

ClaimNotice renders the advisory an agent should be told about when another session is actively validating overlapping paths. Returns "" when there are no overlaps — the common case — so an agent that checks this field sees nothing in the vast majority of turns and is not trained to skip it.

The wording states plainly that this is informational and must not divert the agent from its current task.

func ConflictNotice 

func ConflictNotice(rep ConflictReport) string

ConflictNotice renders the advisory an agent should be told about, or "" when there is nothing to advise.

Empty is the common case and the important one: no conflict, no answer yet, no daemon, a branch that is itself the merge target — all of them produce no text at all. An advisory that speaks when it has nothing to say trains the reader to skip it, which costs it the one time it matters.

The wording states plainly that this is not a gate. The agent reading it is the same one that treats a failed `chunk validate` as work to do before it can continue, and a notice that reads like a check would divert it into a rebase in the middle of an unrelated task.

func ConflictStatus 

func ConflictStatus(rep ConflictReport) string

ConflictStatus renders the full state for someone who ran the command by hand, including every reason ConflictNotice stays silent about.

The two differ on purpose. A person typing `chunk conflicts` and getting no output cannot tell a clean merge from a daemon that is not running, and both answers change what they do next; an agent being handed the same distinction mid-task gains nothing from it.

func EnsureDir 

func EnsureDir() (string, error)

EnsureDir creates the daemon's directory if it doesn't exist and returns the path. That is ~/.chunk/daemon/ unless CHUNK_DAEMON_DIR overrides it.

func EnsureLaunched 

func EnsureLaunched() error

EnsureLaunched starts the daemon when nothing is answering and otherwise leaves whatever is there alone.

Unlike EnsureRunning it never replaces a daemon from another build. It is called when a poll fails mid-session, and a dashboard that has been open for a while has no business restarting a daemon another one is using: the build check is a startup decision, made once, where the cost of being wrong is one restart rather than a restart per poll for as long as two dashboards are open.

func EnsureRunning 

func EnsureRunning() error

EnsureRunning checks whether the chunk daemon is running and serving, and launches it if not.

func IsDaemonCompatible 

func IsDaemonCompatible() bool

IsDaemonCompatible reports whether the chunk daemon is reachable and suitable for delegation. For a local daemon that means matching the current build (a build mismatch means it may not support all API endpoints). For a remote daemon the build ID can never match — the binary lives on a different host with a different path and mtime — so reachability is the meaningful check.

func IsDaemonRunning 

func IsDaemonRunning() bool

IsDaemonRunning reports whether the chunk daemon is reachable. Use IsDaemonCompatible when the caller needs to confirm the build identity too.

func IsRunning 

func IsRunning(path string) (bool, int, error)

IsRunning reports whether the process whose PID is stored in path is alive. Returns (false, 0, nil) when the file doesn't exist.

func LogPath 

func LogPath() (string, error)

LogPath returns the path to the daemon log file.

func PIDPath 

func PIDPath() (string, error)

PIDPath returns the path to the daemon PID file.

func ReadPID 

func ReadPID(path string) (int, error)

ReadPID returns the pid recorded in the pid file at path.

func RegisterCommand 

func RegisterCommand(reg CommandReg)

RegisterCommand tells the running chunk daemon to stream and buffer a command's output.

It is best-effort by design and reports no error. If the daemon is not running, the command still runs and still streams to the caller's own stdout; the only thing lost is the buffered copy. Notably this does not start the daemon: spawning a background process as a side effect of a hook firing is intrusive, and a hook that hangs waiting for a daemon launch is a far worse failure than a missing logs pane.

func SocketPath 

func SocketPath() (string, error)

SocketPath returns the path to the daemon Unix socket.

func StartAsyncValidate 

func StartAsyncValidate(projectRoot string, args []string, circleCIToken string) (string, error)

StartAsyncValidate asks the daemon to validate projectRoot in the background and returns the new task's ID without waiting for the run.

func StartFactory 

func StartFactory(req FactoryRequest) (string, error)

StartFactory asks the daemon to start a factory session and returns its ID without waiting for it. It is followed and cancelled like any other session.

func StopForCredentialChange 

func StopForCredentialChange()

StopForCredentialChange stops a running chunk daemon so that the next launch picks up newly stored credentials.

The daemon resolves its CircleCI client once, at startup, so one that started before a login holds a nil client for the rest of its life and streams no output however many times the developer retries. Stopping it here is what makes `chunk auth login` take effect: a `chunk watch` already on screen relaunches it through EnsureLaunched on its next poll, and otherwise the next `chunk watch` starts a daemon that can authenticate.

Best-effort and silent, like RegisterCommand. Failing to stop the daemon must not fail a login that has otherwise succeeded, and the cost of not stopping it is the buffered output of a daemon that was not streaming anything anyway.

func TCPListenAddr 

func TCPListenAddr() string

TCPListenAddr returns the TCP address the daemon should bind, read from CHUNK_DAEMON_TCP_ADDR (e.g. "0.0.0.0:7777"). Empty means TCP is disabled.

func TCPRemoteAddr 

func TCPRemoteAddr() string

TCPRemoteAddr returns the address of a remote daemon to connect to, read from CHUNK_DAEMON_REMOTE_ADDR (e.g. "sandbox-host:7777"). Empty means clients use the local Unix socket.

func TCPToken 

func TCPToken() string

TCPToken returns the bearer token required for TCP connections, read from CHUNK_DAEMON_TCP_TOKEN. When set, the daemon requires this token on every TCP request and clients include it in every request header.

func WritePID 

func WritePID(path string, p int) error

WritePID records p as the daemon holding the pid file at path.

Types

type AsyncValidateResponse 

type AsyncValidateResponse struct {
	TaskID string `json:"task_id"`
	// ClaimWarning is an advisory when another session is actively validating
	// overlapping paths. Empty in the common case (no overlap). Never a gate.
	ClaimWarning string `json:"claim_warning,omitempty"`
}

AsyncValidateResponse acknowledges an accepted async run.

type ClaimState 

type ClaimState struct {
	SessionID   string `json:"session_id"`
	ProjectRoot string `json:"project_root"`
	// Paths are the repo-relative paths changed in this session's working tree,
	// captured at claim registration time. Nil means the change could not be
	// measured; treat as potentially overlapping anything in the project.
	Paths     []string  `json:"paths,omitempty"`
	ClaimedAt time.Time `json:"claimed_at"`
	ExpiresAt time.Time `json:"expires_at"`
}

ClaimState describes one active validate claim held by a session. It is advisory — no blocking is done based on it.

type CollectResponse 

type CollectResponse struct {
	Tasks []TaskState `json:"tasks"`
}

CollectResponse carries the finished results for a project.

type CommandReg 

type CommandReg struct {
	CommandID   string    `json:"command_id"`
	SidecarID   string    `json:"sidecar_id"`
	ProjectRoot string    `json:"project_root"`
	Op          string    `json:"op"`
	Name        string    `json:"name"`
	SubmittedAt time.Time `json:"submitted_at"`
}

CommandReg is the registration a process sends after submitting a remote command, so the daemon can stream and buffer that command's output. The submitting process may exit immediately afterwards — that is the whole point, since most remote commands are run by a hook that exits as soon as the command finishes.

type CommandState 

type CommandState struct {
	CommandID   string     `json:"command_id"`
	SidecarID   string     `json:"sidecar_id"`
	Op          string     `json:"op"`
	Name        string     `json:"name"`
	SubmittedAt time.Time  `json:"submitted_at"`
	EndedAt     *time.Time `json:"ended_at,omitempty"`
	ExitCode    *int       `json:"exit_code,omitempty"`
	Running     bool       `json:"running"`
	Bytes       int64      `json:"bytes"`
	Truncated   bool       `json:"truncated"`
}

CommandState describes one remote command the daemon is buffering output for.

type ConflictReport 

type ConflictReport struct {
	Root string `json:"root"`
	// Conflict is nil when the daemon has no answer for this root — either it
	// does not know the project, or no check has run yet.
	Conflict *ConflictState `json:"conflict,omitempty"`
	// Known reports whether the daemon is tracking the root at all. Without it
	// "unknown project" and "checked, nothing to report" are the same response.
	Known bool `json:"known"`
}

ConflictReport is the response to a conflict query for one project root.

func FetchConflicts 

func FetchConflicts(root string) (ConflictReport, error)

FetchConflicts asks the running daemon whether root's branch still merges cleanly into its merge target.

Unlike RegisterCommand this reports its errors, because the caller decides how loudly to fail: a hook stays quiet, a person running the command by hand gets told why there is no answer.

type ConflictState 

type ConflictState struct {
	// Branch is the branch that was compared, empty when there was none.
	Branch string `json:"branch,omitempty"`
	// Target is the merge target, qualified as the remote names it —
	// "origin/main".
	Target string `json:"target,omitempty"`
	// HeadSHA and TargetSHA are the two commits actually merged. They are what
	// makes a result reusable: neither side moving means the merge would
	// resolve identically.
	HeadSHA   string `json:"head_sha,omitempty"`
	TargetSHA string `json:"target_sha,omitempty"`
	// Conflicted reports that the merge does not resolve automatically. False
	// with an empty Unavailable is a real all-clear; false with Unavailable set
	// means no merge was attempted.
	Conflicted bool `json:"conflicted"`
	// Paths lists the conflicted paths, capped at MaxConflictPaths.
	Paths []string `json:"paths,omitempty"`
	// TotalPaths is how many paths conflicted in total, which exceeds len(Paths)
	// when the list was cut.
	TotalPaths int `json:"total_paths,omitempty"`
	// CheckedAt is when the answer was produced, TargetFetchedAt when the
	// target's remote-tracking ref was last refreshed. The second is the one
	// that decides how much the answer is worth.
	CheckedAt       time.Time `json:"checked_at"`
	TargetFetchedAt time.Time `json:"target_fetched_at"`
	// TargetStale reports that the last refresh of the target ref failed, so
	// the comparison ran against whatever was already on disk. The answer may
	// simply be out of date, which is worth saying rather than implying.
	TargetStale bool `json:"target_stale,omitempty"`
	// Unavailable explains why there is no answer, and is empty when there is
	// one. A detached HEAD, a repo with no recorded default branch, and a
	// branch that is itself the merge target all land here — none of them are
	// faults, and all of them would otherwise look like "no conflicts".
	Unavailable string `json:"unavailable,omitempty"`
}

ConflictState is the daemon's answer to whether one project's branch still merges cleanly into its merge target.

It describes committed history only. The preview merges HEAD against the target, so uncommitted work in the tree is invisible to it: a conflict that exists solely in unstaged edits is not reported here, and anything presenting this to a person has to say so rather than let the silence read as an all-clear.

type Connection 

type Connection struct {
	// Remote is the TCP address of a remote daemon, empty for the local socket.
	Remote string
}

Connection describes which daemon this process talks to.

func CurrentConnection 

func CurrentConnection() Connection

CurrentConnection reports the daemon this process is configured to use.

func (Connection) Label 

func (c Connection) Label() string

Label is the short human-readable form: "local", or "remote host:port".

type FactoryRequest 

type FactoryRequest struct {
	// ProjectRoot is a project the daemon tracks. Required.
	ProjectRoot string `json:"project_root"`
	// Prompt is what the implementer is asked to do. Required unless Continue
	// is set, when it is optional guidance added to the earlier run's request.
	Prompt string `json:"prompt"`
	// Continue is the ID of an earlier run to pick up the work of, or empty to
	// start from the project's files.
	Continue string `json:"continue,omitempty"`
	// ReviewsDir is a directory of review prompts relative to the project
	// root; empty means .chunk/reviews, which may be missing when validation
	// commands are enough.
	ReviewsDir string `json:"reviews_dir,omitempty"`
	NoValidate bool   `json:"no_validate,omitempty"`
	// Attempts is the most rounds to check; zero means DefaultAttempts.
	Attempts int `json:"attempts,omitempty"`
	// Reviewers is how many reviewer sidecars to run; zero means one per
	// review prompt.
	Reviewers               int    `json:"reviewers,omitempty"`
	Model                   string `json:"model,omitempty"`
	ImplementerInstructions string `json:"implementer_instructions,omitempty"`
	// Zero timeouts mean the factory's defaults.
	ImplementTimeoutSeconds int  `json:"implement_timeout_seconds,omitempty"`
	ReviewTimeoutSeconds    int  `json:"review_timeout_seconds,omitempty"`
	KeepSidecars            bool `json:"keep_sidecars,omitempty"`
	// OrgID and Image override the project's configured ones.
	OrgID string `json:"org_id,omitempty"`
	Image string `json:"image,omitempty"`
	// Log is where the run keeps a plain-text log of its full context: an
	// absolute path, factory.LogDefault, or empty for none. Verbose adds more
	// to it and implies it; see factory.RunOptions.
	Log     string `json:"log,omitempty"`
	Verbose bool   `json:"verbose,omitempty"`
}

FactoryRequest starts a factory session.

type FactoryRun 

type FactoryRun struct {
	// Prompt is the request. A continued run's is the earlier run's, and
	// Guidance is what the user added to it, if anything.
	Prompt   string `json:"prompt"`
	Guidance string `json:"guidance,omitempty"`
	// ContinuesRunID is the run whose work this one picked up, if it did.
	ContinuesRunID string `json:"continues_run_id,omitempty"`
	// Attempts is the most rounds the run checks.
	Attempts int    `json:"attempts,omitempty"`
	RunID    string `json:"run_id,omitempty"`
	// SidecarIDs are the live or retained members of this run's pool. The
	// daemon derives ownership from its pool state so clients do not have to
	// reconstruct it from sidecar names.
	SidecarIDs []string `json:"sidecar_ids,omitempty"`
	// Worktree is where the work is, on Branch. Baseline is the commit the
	// branch starts from and Head the user's HEAD when the run started; they
	// differ when the user's uncommitted work was committed as the baseline.
	Worktree string `json:"worktree,omitempty"`
	Branch   string `json:"branch,omitempty"`
	Baseline string `json:"baseline,omitempty"`
	Head     string `json:"head,omitempty"`
	// Result is why the loop stopped, one of the Result values, once it has,
	// and Rounds how many rounds were checked.
	Result string `json:"result,omitempty"`
	Rounds int    `json:"rounds,omitempty"`
	// Committed reports whether the work was committed on Branch.
	Committed bool `json:"committed,omitempty"`
	// Stat is the committed work's diff stat against Baseline, "" when there
	// were no changes. StatError says why it could not be worked out instead.
	Stat      string `json:"stat,omitempty"`
	StatError string `json:"stat_error,omitempty"`
	// WorktreeRemoved reports that the run ended before the implementer started
	// and its worktree, holding nothing, was removed.
	WorktreeRemoved bool `json:"worktree_removed,omitempty"`
	// KeptSidecars are the sidecars left running at the user's request.
	KeptSidecars []string `json:"kept_sidecars,omitempty"`
	// Log is the path of the run's log, once the run has ended, if it kept one.
	Log string `json:"log,omitempty"`
	// Progress is what the run said as it went: its sidecars being made
	// ready and synced, and anything that went wrong cleaning up.
	Progress Feed `json:"progress,omitzero"`
}

FactoryRun is what a factory session works on and where its work is.

type Feed 

type Feed struct {
	Lines []FeedLine `json:"lines,omitempty"`
	Total int        `json:"total,omitempty"`
}

Feed is the latest lines of a stream that can run long, such as a run's progress, and how many lines there have been, so a follower can tell which it has not seen. Only the latest lines are kept.

func (Feed) Since 

func (f Feed) Since(seen int) []FeedLine

Since returns the lines added after the first seen, as many as are still kept.

type FeedLevel 

type FeedLevel string

FeedLevel is how a feed line reads, as iostream.Level, spelled out so it reads in JSON. 

const (
	FeedStep  FeedLevel = "step"
	FeedInfo  FeedLevel = "info"
	FeedWarn  FeedLevel = "warn"
	FeedDone  FeedLevel = "done"
	FeedError FeedLevel = "error"
)

Feed levels.

func (FeedLevel) Level 

func (l FeedLevel) Level() iostream.Level

Level is the line's iostream level. An unknown value reads as info: it comes from a daemon that may be newer than this client.

type FeedLine 

type FeedLine struct {
	Level FeedLevel `json:"level"`
	Text  string    `json:"text"`
}

FeedLine is one line of a Feed.

type Finding 

type Finding struct {
	// ID is unique within a round.
	ID string `json:"id,omitempty"`
	// Prompt names the review that reported it.
	Prompt string `json:"prompt,omitempty"`
	// File is a repository-relative path with forward slashes.
	File string `json:"file"`
	// Line is the 1-based line the finding is about; zero means the file as a
	// whole or a line the reviewer did not give.
	Line     int    `json:"line,omitempty"`
	Severity string `json:"severity"`
	Body     string `json:"body"`
	// Patch is an optional unified diff that would fix the finding.
	Patch string `json:"patch,omitempty"`
}

Finding is one problem a review reported.

func (Finding) Location 

func (f Finding) Location() string

Location is where the finding is, as file:line, or the file alone when the finding has no line.

type ImplementState 

type ImplementState string

ImplementState is where a factory round's implementer turn stands. 

const (
	ImplementRunning ImplementState = "running"
	ImplementApplied ImplementState = "applied"
	// ImplementEmpty means the agent made no changes.
	ImplementEmpty  ImplementState = "empty"
	ImplementFailed ImplementState = "failed"
)

Implement states.

type OutputChunk 

type OutputChunk struct {
	// Data is raw command output, exactly as the remote command wrote it —
	// interleaved stdout and stderr, ANSI and carriage returns intact.
	Data []byte `json:"data"`
	// NextOffset is the offset to pass on the following read.
	NextOffset int64 `json:"next_offset"`
	Running    bool  `json:"running"`
	ExitCode   *int  `json:"exit_code,omitempty"`
	// Truncated reports that output before the returned data was evicted and is
	// gone. Saying so is the difference between showing a partial run and
	// showing a partial run that looks whole.
	Truncated bool `json:"truncated"`
	// Found is false when the daemon knows nothing about the command.
	Found bool `json:"found"`
	// Error explains why streaming stopped early, when it did. Without it a
	// failed stream is indistinguishable from a command that produced no output,
	// which sends the reader looking for a bug in their own command.
	Error string `json:"error,omitempty"`
}

OutputChunk is one response to an output read.

func FetchOutput 

func FetchOutput(commandID string, offset int64) (OutputChunk, error)

FetchOutput reads buffered output for a command starting at offset.

type PRCheck 

type PRCheck struct {
	Name       string `json:"name"`
	Status     string `json:"status"`     // QUEUED, IN_PROGRESS, COMPLETED
	Conclusion string `json:"conclusion"` // SUCCESS, FAILURE, NEUTRAL, CANCELLED, etc.
}

PRCheck is one CI check on a PR's latest commit.

type PRComment 

type PRComment struct {
	Author    string    `json:"author"`
	Body      string    `json:"body"`
	CreatedAt time.Time `json:"created_at"`
	Resolved  bool      `json:"resolved,omitempty"`
}

PRComment is one review thread comment on a PR.

type PRState 

type PRState struct {
	Number           int         `json:"number"`
	Title            string      `json:"title"`
	URL              string      `json:"url"`
	UpdatedAt        time.Time   `json:"updated_at,omitempty"`
	CheckState       string      `json:"check_state,omitempty"` // rollup: SUCCESS, FAILURE, PENDING, ERROR, EXPECTED
	Checks           []PRCheck   `json:"checks,omitempty"`
	Comments         []PRComment `json:"comments,omitempty"`
	ChangesRequested bool        `json:"changes_requested,omitempty"`
	FetchedAt        time.Time   `json:"fetched_at"`
}

PRState is the daemon's advisory view of the open PR for a project's current branch. It is nil when no open PR exists for the branch or when GitHub credentials are absent.

type ProjectSnapshot 

type ProjectSnapshot struct {
	Root     string           `json:"root"`
	Branch   string           `json:"branch"`
	HeadRef  string           `json:"head_ref"`
	RepoName string           `json:"repo_name"`
	Sidecars []SidecarState   `json:"sidecars"`
	Events   []eventlog.Event `json:"events"`
	Commands []CommandState   `json:"commands,omitempty"`
	// Conflict is nil until the first conflict check for this project has run.
	// Nil is "not known yet", distinct from a ConflictState reporting no
	// conflict, and the two must not be collapsed by a reader.
	Conflict *ConflictState `json:"conflict,omitempty"`
	// PR is the advisory PR state for the current branch. Nil when no open PR
	// exists, or when GitHub credentials are not configured.
	PR *PRState `json:"pr,omitempty"`
	// ActiveClaims lists validate claims from all sessions currently active for
	// this project. Nil when no sessions are validating.
	ActiveClaims []ClaimState `json:"active_claims,omitempty"`
	// Sessions lists this project's pre-PR sessions, newest first. State only:
	// the text of a review is fetched on demand through GET /factory/{id}.
	Sessions []Session `json:"sessions,omitempty"`
}

ProjectSnapshot is the daemon's view of one project at a point in time.

type PromptRunState 

type PromptRunState string

PromptRunState is where one review of a round stands. The values are spelled out so they read in JSON and survive the daemon's own enum being reordered. 

const (
	PromptQueued  PromptRunState = "queued"
	PromptRunning PromptRunState = "running"
	PromptDone    PromptRunState = "done"
	PromptFailed  PromptRunState = "failed"
)

Review states.

type ProvisionRequest 

type ProvisionRequest struct {
	OrgID string `json:"org_id"`
	Name  string `json:"name"`
	Image string `json:"image,omitempty"`
}

ProvisionRequest is sent to POST /sidecar.

type ProvisionResponse 

type ProvisionResponse struct {
	SidecarID string `json:"sidecar_id"`
}

ProvisionResponse is returned from POST /sidecar.

type Resources 

type Resources struct {
	CPUPercent     float64   `json:"cpu_percent"`
	MemUsedBytes   int64     `json:"mem_used_bytes"`
	MemLimitBytes  int64     `json:"mem_limit_bytes"`
	DiskUsedBytes  int64     `json:"disk_used_bytes"`
	DiskTotalBytes int64     `json:"disk_total_bytes"`
	SampledAt      time.Time `json:"sampled_at"`
}

Resources is one sample of a sidecar's resource usage.

Memory is reported as used-of-limit rather than a percentage so the display can show both, and because a limit of zero (unknown) has to be distinguishable from a usage of zero.

type ReviewPrompt 

type ReviewPrompt struct {
	Name      string         `json:"name"`
	State     PromptRunState `json:"state"`
	SidecarID string         `json:"sidecar_id,omitempty"`
	// CommandID names the buffered output of this review's Claude run, readable
	// through /output while it runs and after.
	CommandID  string `json:"command_id,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	Error      string `json:"error,omitempty"`
	// Findings counts the structured findings parsed from this review's output,
	// and Worth the ones worth changing (severity high or medium).
	Findings int `json:"findings,omitempty"`
	Worth    int `json:"worth,omitempty"`
	// Status is how the review came out as a check, one of the Check values:
	// passed unless it found something worth changing, failed if it did,
	// errored if it could not run. Empty until it is known.
	Status string `json:"status,omitempty"`
}

ReviewPrompt is one review's progress inside a round. It carries state only: what the review said is fetched on demand through SessionDetail, the way command output is fetched through /output, so a snapshot stays small however much Claude wrote.

type ReviewResult 

type ReviewResult struct {
	Prompt     string `json:"prompt"`
	SidecarID  string `json:"sidecar_id,omitempty"`
	Error      string `json:"error,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	// Findings are the structured findings the review gave, each with an ID
	// unique within the round. Empty when it gave none or failed; Error tells
	// the two apart.
	Findings []Finding `json:"findings,omitempty"`
	// Status is how a factory review came out as a check, one of the Check
	// values.
	Status string `json:"status,omitempty"`
}

ReviewResult is what one review found.

type RiskSummary 

type RiskSummary struct {
	// Score is 0–100. Higher means more caution: bigger, broader, or already
	// failing. It does not decide anything on its own; see decideRisk.
	Score int `json:"score"`
	// Lines and Files are what was measured, kept apart from the score so a
	// caller can compare two changes without unpicking one.
	Lines int `json:"lines"`
	Files int `json:"files"`
	// Inert reports that every changed path was docs or text.
	Inert bool `json:"inert,omitempty"`
	// Band is Score bucketed into BandLow, BandMedium or BandHigh.
	Band string `json:"band"`
	// Parts are the facts behind the score, each with what it contributed.
	Parts []string `json:"parts,omitempty"`
	// Advice is what a developer or agent could do about it, or "" when there is
	// nothing useful to say.
	Advice string `json:"advice,omitempty"`
}

RiskSummary is what the daemon made of a change, as reported to a caller.

It is deliberately not just a number. A score on its own cannot be argued with — "risk 62" invites either trust or dismissal and supports neither — so the facts it was built from travel with it, and the advice that follows from them is spelled out rather than left to be inferred.

func (RiskSummary) String 

func (r RiskSummary) String() string

String renders a summary as one line of terminal output.

type Round 

type Round struct {
	Number  int            `json:"number"`
	State   RoundState     `json:"state"`
	Reviews []ReviewPrompt `json:"reviews"`
	// Findings counts every finding the round's reviews reported; Worth counts
	// the ones worth changing (severity high or medium).
	Findings int `json:"findings"`
	Worth    int `json:"worth"`
	// Implement and Checks are a factory round's implementer turn and
	// validation commands. Its reviews are in Reviews.
	Implement *RoundImplement `json:"implement,omitempty"`
	Checks    []RoundCheck    `json:"checks,omitempty"`
	// Note says why the round ended the way it did, such as why the loop stopped.
	Note      string     `json:"note,omitempty"`
	StartedAt time.Time  `json:"started_at"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

Round is one pass of implementing the work and checking it.

type RoundCheck 

type RoundCheck struct {
	Name string `json:"name"`
	// Status is one of the Check values.
	Status     string `json:"status"`
	SidecarID  string `json:"sidecar_id,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	Error      string `json:"error,omitempty"`
	// Output is the end of a failed command's output.
	Output string `json:"output,omitempty"`
}

RoundCheck is one validation command a factory round ran.

type RoundDetail 

type RoundDetail struct {
	Number  int            `json:"number"`
	Results []ReviewResult `json:"results,omitempty"`
}

RoundDetail is the text of one round.

type RoundImplement 

type RoundImplement struct {
	State      ImplementState `json:"state"`
	DurationMS int64          `json:"duration_ms,omitempty"`
	CostUSD    float64        `json:"cost_usd,omitempty"`
	// Summary is the implementer's own account of the turn.
	Summary string `json:"summary,omitempty"`
	// Stat summarizes the work so far against the run's baseline.
	Stat  string `json:"stat,omitempty"`
	Error string `json:"error,omitempty"`
}

RoundImplement is a factory round's implementer turn.

type RoundState 

type RoundState string

RoundState is where one round stands. 

const (
	// RoundStarted is a round that has begun and not yet said which half it
	// is in.
	RoundStarted RoundState = "started"
	// RoundImplementing and RoundChecking are a factory round's halves: the
	// implementer's turn, then the reviews and validation commands.
	RoundImplementing RoundState = "implementing"
	RoundChecking     RoundState = "checking"
	RoundDone         RoundState = "done"
	RoundFailed       RoundState = "failed"
)

Round states.

type Session 

type Session struct {
	ID          string `json:"id"`
	ProjectRoot string `json:"project_root"`
	Branch      string `json:"branch,omitempty"`
	HeadSHA     string `json:"head_sha,omitempty"`

	State SessionState `json:"state"`
	Error string       `json:"error,omitempty"`

	// Stages is the session's stages, in order. The only one is its factory loop.
	Stages []Stage `json:"stages"`
	Rounds []Round `json:"rounds"`
	// Factory is what the run works on and where its work is.
	Factory *FactoryRun `json:"factory,omitempty"`

	StartedAt time.Time  `json:"started_at"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

Session is the record of one factory run. It holds state only; text is in SessionDetail.

func ListSessions 

func ListSessions(root string) ([]Session, error)

ListSessions returns the daemon's sessions, newest first per project. An empty root lists every project's.

type SessionDetail 

type SessionDetail struct {
	Session
	Details []RoundDetail `json:"details,omitempty"`
}

SessionDetail is a session plus the text of its reviews.

func FetchSession 

func FetchSession(id string) (SessionDetail, error)

FetchSession returns one session with the text of its reviews.

type SessionList 

type SessionList struct {
	Sessions []Session `json:"sessions"`
}

SessionList answers GET /factory.

type SessionRefused 

type SessionRefused struct {
	Status  int
	Message string
}

SessionRefused is the daemon's refusal of a session request: it was reachable and understood the request, and said no. The message is the daemon's own and is meant to be shown as is; Status tells a caller which kind of no it was (409 a session is already active, 503 the daemon lacks a credential, ...).

func (*SessionRefused) Error 

func (e *SessionRefused) Error() string

type SessionStartResponse 

type SessionStartResponse struct {
	ID string `json:"id"`
}

SessionStartResponse answers an accepted POST /factory.

type SessionState 

type SessionState string

SessionState is where a whole session stands. 

const (
	SessionRunning   SessionState = "running"
	SessionDone      SessionState = "done"
	SessionFailed    SessionState = "failed"
	SessionCancelled SessionState = "cancelled"
)

Session states.

func (SessionState) Finished 

func (s SessionState) Finished() bool

Finished reports whether the session has ended for good.

type SidecarState 

type SidecarState struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// SessionID is the agent session that owns this sidecar, empty for state
	// written outside a session or before sessions existed. Sidecars are
	// isolated per session, so two entries for one project and branch are two
	// sessions working in the same tree — this is what tells them apart.
	SessionID    string    `json:"session_id,omitempty"`
	ProjectName  string    `json:"project_name"`
	RepoName     string    `json:"repo_name"`
	SnapshotName string    `json:"snapshot_name"`
	FileMtime    time.Time `json:"file_mtime"`
	// Workspace is the sidecar-side repo path, used to sample disk usage where
	// the work actually happens rather than wherever a shell starts.
	Workspace string `json:"workspace,omitempty"`
	// OrgID is the org the sidecar lives in: the one its state file records, or
	// the project's org for state written before that was recorded.
	OrgID string `json:"org_id,omitempty"`
	// Verified reports that the API's sidecar list confirmed this sidecar
	// exists. Sidecars the list has confirmed gone never reach a snapshot, so
	// false means only that nothing has confirmed it yet.
	Verified     bool        `json:"verified,omitempty"`
	LastActivity time.Time   `json:"last_activity"`
	LastOp       eventlog.Op `json:"last_op"`
	Running      bool        `json:"running"`
	// Resources is the most recent resource sample, or nil when none has
	// arrived — sampling only runs while a dashboard is attached.
	Resources *Resources `json:"resources,omitempty"`
}

SidecarState describes one active sidecar as maintained by the daemon.

type Snapshot 

type Snapshot struct {
	Projects []ProjectSnapshot `json:"projects"`
	// AuthError explains why output streaming is unavailable, when it is. An
	// empty logs pane with no explanation sends people hunting the wrong fault,
	// so the daemon reports this rather than silently serving nothing.
	AuthError string `json:"auth_error,omitempty"`
	// ReviewAuthError explains why the daemon cannot run sessions (no Claude
	// credential, or no CircleCI login), empty when it can. It never contains
	// the credential itself.
	ReviewAuthError string `json:"review_auth_error,omitempty"`
}

Snapshot is a point-in-time view of all watched projects.

func FetchSnapshot 

func FetchSnapshot(roots []string) (Snapshot, error)

FetchSnapshot connects to the running chunk daemon and returns the current snapshot for the given project roots. If roots is empty all known projects are returned.

func FetchSnapshotRelaunching 

func FetchSnapshotRelaunching(roots []string) (Snapshot, error)

FetchSnapshotRelaunching is FetchSnapshot for a caller that keeps polling. If the local daemon has gone away it starts one and asks again, once.

Starting one at startup is not enough on its own: the daemon can exit while a dashboard is open — it crashes, someone kills it, or a chunk from another build replaces it (see BuildID) — and the dashboard would then hold whatever it last saw, which reads as a quiet dashboard rather than a broken one.

It relaunches with EnsureLaunched rather than EnsureRunning on purpose: a failed poll should start a daemon if none is answering, not replace one that is. A remote daemon is managed elsewhere, so it is never relaunched.

type Stage 

type Stage struct {
	ID    StageID    `json:"id"`
	State StageState `json:"state"`
	// Note says more about the state: why a loop ended, what failed.
	Note string `json:"note,omitempty"`
}

Stage is one stage of a session and how it is going.

type StageID 

type StageID string

StageID names one stage of a session. 

const (
	// StageFactoryLoop is a factory run's loop: implement, then review and
	// validate until the checks pass.
	StageFactoryLoop StageID = "factory_loop"
)

The stages.

type StageState 

type StageState string

StageState is where one stage stands. 

const (
	StageRunning StageState = "running"
	StageDone    StageState = "done"
	StageFailed  StageState = "failed"
)

Stage states.

type TaskState 

type TaskState struct {
	ID string `json:"id"`
	// ProjectRoot is the key the task is filed under — the root of the repo,
	// which may sit above the directory the run was actually asked for. See
	// taskStore.projectKey.
	ProjectRoot string    `json:"project_root"`
	StartedAt   time.Time `json:"started_at"`
	FinishedAt  time.Time `json:"finished_at,omitempty"`
	Running     bool      `json:"running"`
	// ExitCode is the validate run's exit status. Meaningful only once the task
	// has finished.
	ExitCode int `json:"exit_code"`
	// Output is what the run printed, held for whoever collects the result.
	// Capped at maxTaskOutput, keeping the tail.
	Output string `json:"output,omitempty"`
	// Stale reports that the working tree changed between the run starting and
	// its result being read, so the result describes code that is no longer on
	// disk. For a live-tree run ExitCode and Output are cleared when it is set: a
	// stale task is reported so that the discard is visible, and carrying the
	// verdict would invite it to be read as one. For a snapshot run they are
	// kept — see Snapshot, where the verdict outlives the tree moving.
	//
	// The tree most often moved because of the run itself — output written,
	// goldens regenerated, a lockfile touched. Reporting the discard is what
	// lets that be diagnosed instead of looking like no run happened.
	//
	// It is not a fix for the cause. A mid-run edit by the developer and a file
	// written by the run are the same event as far as a content digest is
	// concerned, so nothing here can tell them apart, and relaxing the
	// comparison to let artifacts through would let a real edit through with
	// them — trading a silence for a false pass, which is the one direction this
	// store must not fail in. Actually keeping the result means stopping the
	// tree from moving under the run, which is a matter of where the run
	// happens rather than how its result is judged.
	Stale bool `json:"stale"`
	// Snapshot reports that the run validated a checked-out copy of the tree
	// rather than the tree itself. Such a result is exact about the state it
	// ran against whatever happened afterwards, so it is reported even when
	// stale — qualified rather than thrown away.
	Snapshot bool `json:"snapshot,omitempty"`
	// DeliveredAt records when this result was handed to a caller. A stamped
	// task is never reported again; an unstamped one is still owed to somebody.
	//
	// It exists so that handing a result over and forgetting it are two steps
	// rather than one. See taskStore.collect.
	DeliveredAt time.Time `json:"delivered_at,omitempty"`
}

TaskState is a validation task as reported to a caller.

func CollectValidateResults 

func CollectValidateResults(projectRoot string) ([]TaskState, error)

CollectValidateResults returns the finished async results for projectRoot and clears them from the daemon, so a result is reported once and not repeated.

Best-effort: with no daemon running there is nothing to collect and nothing to report, which is not an error worth surfacing on a hook path.

func (TaskState) Passed 

func (t TaskState) Passed() bool

Passed reports whether a finished task validated the tree successfully.

A stale live-tree task never passes, whatever its exit code says. Its verdict is stripped when it is reported, which leaves ExitCode at zero — so without the Stale check a discarded run would read here as a clean pass, which is exactly the claim discarding it exists to avoid making.

A stale snapshot task can still pass. It ran against a copy that could not move, so its exit code remains exactly true about the state it was handed; what staleness says there is that the state has been overtaken, not that the verdict is unreliable. Callers are expected to report that qualification — see printResults.

type ValidateRequest 

type ValidateRequest struct {
	// Args is os.Args[1:] from the caller, e.g. ["validate", "test", "--remote"].
	Args []string `json:"args"`
	// CircleCIToken is forwarded to the subprocess as CIRCLE_TOKEN.
	CircleCIToken string `json:"circleci_token,omitempty"`
	// Env is the caller's os.Environ(), forwarded verbatim to the subprocess so
	// session-identity variables (e.g. CLAUDE_CODE_SESSION_ID) reach it intact.
	Env []string `json:"env,omitempty"`
	// ProjectRoot is the repo the run applies to, already resolved by the client
	// (so it reflects the caller's --project, or its cwd). It decides what gets
	// validated, and it is also what a task is filed and fingerprinted under,
	// what a change is measured against, and what a verdict is remembered by —
	// so anything the daemon decides on a project's behalf needs it.
	//
	// It cannot be left to the daemon to infer. The daemon's own cwd is wherever
	// it was launched from, which is one arbitrary repo out of all the repos it
	// serves, so a run that resolved the project itself would validate that one
	// and report the answer under whichever project asked. Empty is accepted on
	// the synchronous path only, for a client too old to send it; such a run is
	// simply run, with nothing judged or recorded.
	ProjectRoot string `json:"project_root,omitempty"`
	// AllowAsync says the caller will accept being released before the answer
	// exists. It is an offer, not an instruction: the daemon weighs the change
	// and may hold the caller anyway.
	//
	// Only a caller that has somewhere to hear the answer later should set it.
	// A hook does — the next turn collects background results — while a developer
	// watching a terminal does not, and releasing them would leave the run's
	// output going nowhere they are looking.
	AllowAsync bool `json:"allow_async,omitempty"`
	// OrgID is the CircleCI org UUID for this project. When set and the daemon
	// has credentials, the daemon provisions a fresh sidecar for the run rather
	// than expecting one to already be registered on its filesystem.
	OrgID string `json:"org_id,omitempty"`
	// HookCodex says the run is a hook invocation from Codex, and the daemon
	// passes it on to the run as --hook-codex.
	//
	// It travels as a field rather than in Args because a remote daemon's build
	// cannot be checked, and one that predates the flag would reject the whole
	// run with a non-blocking exit — a commit gate would pass having checked
	// nothing. A daemon that predates this field ignores it instead, and the run
	// goes ahead, just without Codex's quieter output.
	HookCodex bool `json:"hook_codex,omitempty"`
	// WorkDir is the caller's working directory, which the daemon passes to the
	// subprocess as --project so it can load .chunk/config.json from the right
	// location. It equals ProjectRoot for callers whose working directory is the
	// git top-level; it differs when the .chunk directory sits below the git root.
	//
	// A daemon that predates this field ignores it and falls back to ProjectRoot,
	// which is the caller's cwd and therefore also correct in the common case.
	WorkDir string `json:"work_dir,omitempty"`
	// SidecarImage is the image the caller resolved for this run from its own
	// config, per-command override included. The daemon boots the sidecar it
	// provisions from it, since the subprocess is handed that sidecar by ID and
	// never picks an image itself. A remote daemon may not have the checkout to
	// read the config from, so the client resolving it is what makes the image
	// right there.
	//
	// Empty means the caller configured none, or predates this field; the daemon
	// then reads validation.sidecarImage from the project's config itself.
	SidecarImage string `json:"sidecar_image,omitempty"`
}

ValidateRequest is the payload sent to POST /validate and POST /validate/async.

type ValidateResponse 

type ValidateResponse struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	// TaskID is set when the daemon took the run into the background rather than
	// running it here. Nothing has run yet: ExitCode is zero because there is no
	// exit code, and the result is collected on a later turn.
	TaskID string `json:"task_id,omitempty"`
	// Risk is what the daemon made of the change: a score, the facts behind it,
	// and any advice. Nil when the caller never offered to be released, since
	// then no change was judged.
	Risk *RiskSummary `json:"risk,omitempty"`
	// Reason says why the run was released or held, in words a caller can print
	// as one line. Empty when the caller never offered to be released, since
	// then there was no decision to explain.
	Reason string `json:"reason,omitempty"`
	// ClaimWarning is an advisory when another session is actively validating
	// overlapping paths. Empty in the common case (no overlap). Never a gate.
	ClaimWarning string `json:"claim_warning,omitempty"`
}

ValidateResponse is the response from POST /validate.

func RunValidate 

func RunValidate(req ValidateRequest) (ValidateResponse, error)

RunValidate delegates a validate run to the daemon. req.ProjectRoot is the repo to validate, already resolved by the caller.

The caller is responsible for deciding which fields to populate: req.Env and req.CircleCIToken should only be set when using the local Unix socket — over TCP the remote daemon uses its own credentials and environment. See runValidateViaDaemon in cmd/ for the canonical call site.

Set req.AllowAsync to offer the daemon the option of releasing this caller and reporting later; a response carrying a TaskID is that offer taken, and means nothing has run yet.

It takes the request type rather than a list of arguments because what the daemon needs to know about a run keeps growing, and every addition would otherwise be another positional parameter at two call sites.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.