Documentation
¶
Overview ¶
Package apiwire holds the daemon↔client wire contract: the request and response shapes both internal/api (server side) and internal/client + cmd (client side) encode and decode, plus the few validators that DEFINE a field's canonical form (NormalizePublicURL).
It exists to break a compile-time dependency, not to reorganize code for its own sake. internal/client imported internal/api purely for these types, and internal/api is the daemon's handler package — so the import dragged internal/dispatcher, internal/db, internal/sandbox, internal/skills and web/templates in behind it. That made the CLI unbuildable for any GOOS but linux even though nothing on the client path needs a syscall the daemon owns (docs/plans/windows-client-build.md).
The rule that keeps it working: apiwire may import internal/orchestrator (whose types appear in these payloads) and the standard library, and nothing else. TestApiwireDependencies pins it. internal/api re-exports every symbol here as an alias, so server-side code and web/templates are unaffected by the move.
Index ¶
- Constants
- func NormalizePublicURL(raw string) (string, error)
- type AckSignalsRequest
- type AckSignalsResponse
- type ActionApplication
- type AnswerTaskRequest
- type ApplyActionRequest
- type ConfigApplyResult
- type ConfigMutateOp
- type ConfigMutateRequest
- type ConfigMutateResult
- type ConnectorRef
- type CreateTaskRequest
- type DuplicateTaskRequest
- type FoldedSiblingSummary
- type ImportError
- type ImportResult
- type Job
- type JobListFilter
- type JobStatus
- type JobWithContext
- type ListSignalsResponse
- type NotifyTaskRequest
- type ReleaseResult
- type ReplayHookResult
- type RerunTaskRequest
- type ResolveOrCaptureRequest
- type ResolveOrCaptureResult
- type Signal
- type SignalSource
- type StartExecRequest
- type StartExecResult
- type StartSessionRequest
- type StartSessionResult
- type TaskDetailView
- type TaskIdentity
- type TaskIdentityRequest
- type UpdateTaskRequest
- type WorkspaceDetail
- type WorkspaceHomeSize
- type WorkspaceInitScriptResult
- type WorkspaceRemoveResponse
Constants ¶
const ( // WorkspaceInitScriptWritten: the script was persisted (created or // replaced). WorkspaceInitScriptWritten = "written" // WorkspaceInitScriptCleared: the workspace's init.sh was removed, so it // is back in the pass-through class. WorkspaceInitScriptCleared = "cleared" // WorkspaceInitScriptUnchanged: the request asked for the state the // workspace was already in. Reported rather than folded into "written" // because a re-applied backup should not read as a change — and because // the completion marker's hash is unchanged either way, so no init re-run // follows. WorkspaceInitScriptUnchanged = "unchanged" )
The three values WorkspaceInitScriptResult.Action (and orchestrator.WorkspaceApplyResult.InitScriptAction) can take.
const WorkspaceInitScriptAbsentRevision = "absent"
WorkspaceInitScriptAbsentRevision is the revision of a workspace that has NO init.sh.
A sentinel rather than the empty string, because "" already means "the caller sent no If-Match at all" (428). With a real value for the absent state, creating a workspace's first script is guarded the same way replacing one is: `boid workspace set-init-script` reads first, gets this back, sends it as If-Match, and a script that appeared in between makes the write a 412 instead of a silent overwrite.
It cannot collide with a real revision: those are 32 hex characters (workspaceInitScriptRevision).
const WorkspaceInitScriptContentType = "text/x-shellscript"
WorkspaceInitScriptContentType is the media type the init script is served with, and the canonical one to send when writing it.
text/x-shellscript rather than text/plain because the content IS a shell script and saying so costs nothing. It is not REQUIRED on the way in: the route refuses only the structured-data formats whose arrival means the caller is sending something else entirely, and accepts everything else including an absent declaration — see workspaceInitScriptMediaTypeError.
Variables ¶
This section is empty.
Functions ¶
func NormalizePublicURL ¶
NormalizePublicURL parses raw as an HTTPS origin, strips path/query/fragment, lowercases and IPv6-brackets the host, and returns the canonical `https://host[:port]` form. It exists so wire.go can validate cfg.Web.PublicURL once at daemon startup and hand the canonical form to DeviceAuthHandler.PublicURL — the value that ends up in the POST /api/auth/device response, which the CLI (PR2) will byte-compare against its saved profile URL on every subsequent request. An un-normalized value (path, trailing slash, `HOST.EXAMPLE.COM`, plain http, empty host like `https://:443`) would either fail the CLI's origin-bind check later or, worse, get accepted and silently misroute future requests.
This is also the exact same normalization applied to the request Host header fallback inside DeviceAuthHandler.canonicalURL — see the code path there for the "fallback must not bypass this validator" rule.
Empty raw is not an error (PublicURL is optional at boot — the handler falls back to the request's Host header). A non-empty raw that fails validation is returned as an error so the operator sees the misconfig at startup instead of at the first pair attempt.
Types ¶
type AckSignalsRequest ¶ added in v0.4.0
type AckSignalsRequest struct {
WorkspaceID string `json:"workspace_id,omitempty"`
IDs []string `json:"ids"`
}
AckSignalsRequest is POST /api/signals/ack's request body. WorkspaceID defaults to orchestrator.DefaultWorkspaceSlug ("default") server-side when omitted, mirroring the CLI's --workspace default (signal-ingest-detailed-design.md §3.1).
Ack is idempotent (signal-driven-review.md §14 Q14): re-acking an id that is already acked is not an error, matching orchestrator.AckSignals' own contract.
type AckSignalsResponse ¶ added in v0.4.0
type AckSignalsResponse struct {
Acked []string `json:"acked"`
}
AckSignalsResponse is POST /api/signals/ack's response body: the (de-duplicated) ids that are now acked, whether this call is what acked them or an earlier call already had.
type ActionApplication ¶
type ActionApplication struct {
Task *orchestrator.Task `json:"task"`
Action *orchestrator.Action `json:"action"`
MatchedHooks []string `json:"matched_hooks,omitempty"`
TargetTaskID string `json:"target_task_id,omitempty"`
DecisionAccepted bool `json:"decision_accepted,omitempty"`
}
type AnswerTaskRequest ¶
type ApplyActionRequest ¶
type ApplyActionRequest struct {
Type string `json:"type"`
Payload json.RawMessage `json:"payload,omitempty"`
}
type ConfigApplyResult ¶
type ConfigApplyResult struct {
// Warnings are pre-formatted, operator-facing lines (docs/plans/
// volume-only-daemon.md §論点 f's exact wording for the
// restart-required and sandbox.backend-retirement cases) — the CLI
// prints these verbatim rather than reconstructing them client-side,
// so the daemon (which alone knows exactly which leaf paths actually
// changed) is the single source of truth for when a warning fires.
Warnings []string `json:"warnings,omitempty"`
}
ConfigApplyResult is POST /api/config's response body.
type ConfigMutateOp ¶
type ConfigMutateOp string
ConfigMutateOp names a POST /api/config/mutate operation.
const ( // ConfigMutateSet sets a scalar (1 Value) or replaces an array // wholesale (multiple Values) at Key. ConfigMutateSet ConfigMutateOp = "set" // ConfigMutateUnset removes Key (Value is ignored). ConfigMutateUnset ConfigMutateOp = "unset" )
type ConfigMutateRequest ¶
type ConfigMutateRequest struct {
Op ConfigMutateOp `json:"op,omitempty"`
Key string `json:"key,omitempty"`
Value []string `json:"value,omitempty"`
// Ops, when non-empty, requests a batch of set/unset operations
// (BLOCKER, codex review round 1 on PR #831) — see this type's doc
// comment. Each element's own (nested) Ops field, if set, is ignored;
// only Op/Key/Value are read per element.
Ops []ConfigMutateRequest `json:"ops,omitempty"`
}
ConfigMutateRequest is POST /api/config/mutate's request body: either a single `boid config set <key> <value...>` / `unset <key>` operation (the Op/Key/Value fields, unchanged since BLOCKER 1 round 1), or — when Ops is non-empty — a BATCH of operations applied as one atomic read-modify-write (BLOCKER, codex review round 1 on PR #831).
The batch shape exists because a single-op call validates the FULL document after every call (MutateConfig's doc comment), which makes it impossible to create a brand-new gateway.forges.<id> entry through a sequence of single-op calls: setting just "<id>.host" leaves the document with an empty "<id>.forge", which config.ValidateYAML rejects ("unrecognized forge \"\"") before a second call ever gets a chance to set "<id>.forge" — see internal/config/config.go's resolveForgeConfig. Ops applies every listed op to the same in-memory tree first, and validates only once against the fully-mutated result, so the three leaves of a new forge (or any other structural, multi-leaf add) land together or not at all.
When Ops is non-empty, the top-level Op/Key/Value fields are ignored.
type ConfigMutateResult ¶
type ConfigMutateResult struct {
ConfigApplyResult
YAML []byte `json:"yaml"`
Revision string `json:"revision"`
}
ConfigMutateResult is POST /api/config/mutate's response body: the same Warnings ConfigApplyResult carries, plus the resulting full document and its new revision (for a caller that wants to keep editing without a follow-up GET — not currently consumed by `boid config set/unset`, which only prints Warnings, but useful to a future Web UI settings page per docs/plans/volume-only-daemon.md §論点 f).
type ConnectorRef ¶ added in v0.4.0
type ConnectorRef struct {
// Pack / ConnectorName are the "<pack>/<connector>" halves.
Pack string `json:"pack"`
ConnectorName string `json:"connector_name"`
// Service is the service instance name this connector's API gateway
// token is restricted to.
Service string `json:"service"`
// Config is the connector's own configuration (project.yaml
// signals.sources[].config), validated against the Pack manifest's
// declared configSchema at resolution time.
Config map[string]any `json:"config,omitempty"`
}
ConnectorRef identifies a signal-derived trigger's connector — the raw declaration StartExecRequest carries through from orchestrator.TriggerConnector (fireTrigger copies the 4 fields verbatim; see that type's own doc comment for why no Pack-registry resolution happens this early). sessionDispatcherAdapter.StartExec (internal/server/wire.go) resolves this against the daemon's loaded Pack registry to build the connector job's env/bind/policy/service-allowlist.
type CreateTaskRequest ¶
type CreateTaskRequest struct {
WorkspaceID string `json:"workspace_id,omitempty"`
NoProject bool `json:"no_project,omitempty"`
ID string `json:"id,omitempty"`
ProjectID string `json:"project_id"`
Title string `json:"title"`
Description string `json:"description,omitempty"`
Behavior string `json:"behavior,omitempty"`
BehaviorSpec *orchestrator.BehaviorSpec `json:"behavior_spec,omitempty"`
RemoteID string `json:"remote_id,omitempty"`
Payload json.RawMessage `json:"payload,omitempty"`
Instructions json.RawMessage `json:"instructions,omitempty"`
AutoStart bool `json:"auto_start,omitempty"`
Traits []string `json:"traits,omitempty"`
Ref string `json:"ref,omitempty"`
ParentID string `json:"parent_id,omitempty"`
Readonly *bool `json:"readonly,omitempty"`
// InitialStatus lets a caller create a task directly in a pre-execution
// status (docs/plans/cross-project-issue-triage.md Phase 1 PR-1) instead
// of the default "pending". Empty means "pending" (unchanged behavior).
// Only "", "pending", "parked" are accepted — validated in
// internal/api/task_create.go, not here (apiwire is a pure wire struct).
// ("captured"/"triaged" were accepted pre-card-model-cleanup PR-2; card
// machine v2 has no such statuses, a card is now born directly into
// "parked" — see task_create.go's allowedCreateInitialStatuses.)
InitialStatus string `json:"initial_status,omitempty"`
// IdempotencyKey (docs/plans/signal-ingest-detailed-design.md §8): a
// caller-supplied stable key, scoped by (ProjectID, ParentID), that makes
// a create call safe to retry — a second call with the same (ProjectID,
// ParentID, IdempotencyKey) returns the existing task instead of creating
// a duplicate (exit 0, not an error). See migration 0047 and
// orchestrator.Task.IdempotencyKey's doc comment for why ParentID is part
// of the scope (a same-project, different-parent key collision must not
// silently hand back the WRONG parent's child).
//
// Reachable via all three of:
// - the host CLI: `boid task create --idempotency-key <key>`
// (cmd/task.go's runTaskCreate)
// - this JSON field on POST /api/tasks directly
// - the sandboxed `task_create` builtin op, via EITHER `idempotency_key:`
// in the YAML spec (forwarded wholesale, no special-casing needed) OR
// its own `--idempotency-key` flag (internal/sandbox/boid_shim.go's
// parseBoidTaskCreate — this is the primary intended call site: a
// judgment task minting a child task runs inside the sandbox, so this
// flag form was NOT optional plumbing)
//
// See orchestrator.Task.IdempotencyKey's doc comment for the distinction
// from task_identities/Ref (no external-identity or link/drop semantics
// here — purely an internal dedup key).
IdempotencyKey string `json:"idempotency_key,omitempty"`
// CardRequestID is never client-settable (json:"-") — only
// BoidOpTaskCreate sets it, after verifying the calling job owns that
// request (LauncherJobID matches, status is launching).
CardRequestID string `json:"-"`
// CardRequestOwnerJobID travels with CardRequestID (same json:"-"
// reasoning) so the eventual attach can re-assert ownership in its own write.
CardRequestOwnerJobID string `json:"-"`
}
type DuplicateTaskRequest ¶
type DuplicateTaskRequest struct {
AutoStart bool `json:"auto_start"`
}
type FoldedSiblingSummary ¶ added in v0.5.0
type FoldedSiblingSummary struct {
ID string `json:"id"`
CommandKey string `json:"command_key,omitempty"`
}
FoldedSiblingSummary is one row FoldedSiblingsFailed reports.
type ImportError ¶
type ImportResult ¶
type ImportResult struct {
Created int `json:"created"`
Skipped int `json:"skipped"`
Errors []ImportError `json:"errors"`
}
type Job ¶
type Job struct {
ID string `json:"id"`
TaskID string `json:"task_id"`
ProjectID string `json:"project_id"`
WorkspaceID string `json:"workspace_id"`
HandlerID string `json:"handler_id"`
DisplayName string `json:"display_name,omitempty"`
TerminalTitle string `json:"terminal_title,omitempty"`
DisplayNameDefault bool `json:"display_name_default,omitempty"`
Role string `json:"role"`
RuntimeID string `json:"runtime_id,omitempty"`
WorkspacePath string `json:"workspace_path,omitempty"`
Interactive bool `json:"interactive"`
TTY bool `json:"tty"`
Status JobStatus `json:"status"`
ExitCode int `json:"exit_code,omitempty"`
Output string `json:"output,omitempty"`
ExecutionState string `json:"execution_state,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
TranscriptSize int64 `json:"transcript_size,omitempty"`
TranscriptMtime *time.Time `json:"transcript_mtime,omitempty"`
TranscriptIdleSeconds int64 `json:"transcript_idle_seconds,omitempty"`
}
func (*Job) EffectiveDisplayName ¶ added in v0.5.0
EffectiveDisplayName prefers the terminal title, falling back to the configured or generated name when no terminal title is available.
type JobListFilter ¶
type JobListFilter struct {
Status string
Interactive *bool // nil = no filter
TasklessOnly bool // true = only jobs where task_id IS NULL
}
JobListFilter specifies optional filters for global job listing.
type JobWithContext ¶
type JobWithContext struct {
Job
TaskTitle string `json:"task_title"`
ProjectName string `json:"project_name"`
}
JobWithContext extends Job with task and project metadata for the TUI global view.
type ListSignalsResponse ¶ added in v0.4.0
type ListSignalsResponse struct {
Signals []Signal `json:"signals"`
}
ListSignalsResponse is GET /api/signals' response body, and also what `boid signal list`/`boid signal list --claim` reply with from inside the sandbox (PR-3) — same envelope on both surfaces (M3 above).
type NotifyTaskRequest ¶
type ReleaseResult ¶ added in v0.5.0
type ReleaseResult struct {
Status string `json:"status"`
TargetKind string `json:"target_kind,omitempty"`
TargetID string `json:"target_id,omitempty"`
// LauncherJobID is set alongside OperatorNotice for a released row that
// was still "launching" — its own launcher job, not a task/session
// continuation, is the thing that may still be running.
LauncherJobID string `json:"launcher_job_id,omitempty"`
// HadAttachedTarget reports only that the pre-release row HAD a
// target_kind/target_id recorded — not that the target is still alive.
// A task/session that already reached a terminal state and is merely
// awaiting the next reconcile tick to clear the row also sets this true.
HadAttachedTarget bool `json:"had_attached_target,omitempty"`
// FoldedSiblingsFailed lists every OTHER card_requests row this release
// also force-failed (fold is card-scoped, not this request's own
// command_key/cause_id).
FoldedSiblingsFailed []FoldedSiblingSummary `json:"folded_siblings_failed,omitempty"`
OperatorNotice string `json:"operator_notice,omitempty"`
}
ReleaseResult is the response shape for POST /api/card-requests/{id}/release: it echoes the request's pre-release target (if any) since force-release only frees the slot, not whatever continuation was still attached to it.
type ReplayHookResult ¶
type ReplayHookResult struct {
Task *orchestrator.Task `json:"task"`
FiredEvents []orchestrator.FiredEvent `json:"fired_events,omitempty"`
}
ReplayHookResult is the output of a hook replay.
type RerunTaskRequest ¶
type RerunTaskRequest struct {
AutoStart bool `json:"auto_start,omitempty"`
InstructionsOverride json.RawMessage `json:"instructions_override,omitempty"`
}
type ResolveOrCaptureRequest ¶ added in v0.6.0
type ResolveOrCaptureRequest struct {
ProjectID string `json:"project_id,omitempty"`
WorkspaceID string `json:"workspace_id,omitempty"`
Identity string `json:"identity,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
URL *string `json:"url,omitempty"`
DisplayName *string `json:"display_name,omitempty"`
}
ResolveOrCaptureRequest selects an identity scope and supplies content for a new card.
type ResolveOrCaptureResult ¶ added in v0.6.0
ResolveOrCaptureResult identifies the card and whether this call created it.
type Signal ¶ added in v0.4.0
type Signal struct {
ID string `json:"id"`
OccurredAt time.Time `json:"occurred_at"`
Source SignalSource `json:"source"`
Identity string `json:"identity"`
URL string `json:"url,omitempty"`
Author string `json:"author,omitempty"`
Title string `json:"title,omitempty"`
ReceivedAt time.Time `json:"received_at"`
Attempts int `json:"attempts"`
// AckedAt is nil while the signal is unacked.
AckedAt *time.Time `json:"acked_at,omitempty"`
}
Signal is one inbox row shaped as the v0 envelope (signal-driven-review.md §5.2: id / occurred_at / source / identity / url / author / title) plus the daemon-side bookkeeping fields (received_at / attempts / acked_at) an operator needs when listing --state dead/acked/all. This is the wire contract `GET /api/signals` and `boid signal list -o json` (host) / `boid signal list` (sandbox) are all pinned to — deliberately NOT a straight mirror of orchestrator.Signal (whose Connector field is still the raw composite, and which has no envelope concept at all).
type SignalSource ¶ added in v0.4.0
type SignalSource struct {
Pack string `json:"pack"`
Connector string `json:"connector"`
Service string `json:"service"`
}
SignalSource is the provenance block of the Signal envelope (docs/plans/signal-driven-review.md §5.2: `source.pack` / `source.connector` / `source.service`). The signals table stores pack and connector together as a single "<pack>/<connector>" composite string (signal-ingest-detailed- design.md §2's `connector` column, and orchestrator.Signal.Connector) — SignalSource is what splits that back into the envelope's separate fields for the wire response. It is NOT what `--source` filters on: the CLI flag and SignalFilter.Connector both keep the "<pack>/<connector>" composite form, matching the stored column exactly (no split needed there).
type StartExecRequest ¶
type StartExecRequest struct {
WorkspaceID string `json:"workspace_id,omitempty"`
// ProjectID is taken from the URL for the project-scoped route; there is
// no top-level /api/exec (every exec is inherently project-scoped —
// `boid exec -p <ref> -- argv...`), so the handler always fills this in
// from chi.URLParam before it reaches the dispatcher.
ProjectID string `json:"project_id"`
// Argv is the literal program + arguments to run inside the sandbox.
// Required, non-empty.
Argv []string `json:"argv"`
// Readonly, when true, mounts the project workspace read-only. Exec
// defaults to writable, matching the CLI's --readonly flag default.
Readonly bool `json:"readonly,omitempty"`
// Interactive requests a PTY-backed sandbox. The CLI computes this from
// isatty(stdin) && isatty(stdout) (see cmd/exec.go) — both, not stdin
// alone, because a PTY is only correct when the whole terminal round-trip
// is real; `boid exec -- cmd | grep pattern` must NOT get a PTY even
// though its own stdin is a real terminal, or the PTY's line-discipline
// framing would corrupt the piped bytes grep receives. false selects the
// plain-pipe transport (see runtime_local_linux.go's non-interactive
// branch and its StdinForward stdin-piping addition).
Interactive bool `json:"interactive,omitempty"`
// DisplayName is the human-readable label persisted to jobs.display_name.
// Empty falls back to argv[0] (dispatcher.BuildExecJobSpec).
DisplayName string `json:"display_name,omitempty"`
// Connector, when non-nil, marks this exec as a signal-derived trigger's
// connector run (docs/plans/signal-ingest-detailed-design.md §5.1/§5.2,
// PR-5) — fireTrigger (internal/api/trigger_loop.go) populates it from
// the firing orchestrator.Trigger's own Connector field. Every other
// StartExec caller (`boid exec`, a plain schedule trigger) leaves this
// nil, and sessionDispatcherAdapter.StartExec dispatches exactly as
// before this PR when it is nil.
Connector *ConnectorRef `json:"connector,omitempty"`
// JobID, CardID and CardRequestID are never client-settable (json:"-") —
// only internal/api's card command launcher sets them.
JobID string `json:"-"`
CardID string `json:"-"`
CardRequestID string `json:"-"`
}
StartExecRequest is the body of POST /api/projects/{id}/exec. `boid exec` used to be a client-side-only path (the CLI built its own SandboxRuntimeInfo and syscall.Exec'd straight into the sandbox launcher), which is exactly why it never picked up the git gateway cutover's Dispatch()-only wiring (registerGatewayToken / GatewayURL / GatewayCloneURL) — see docs/plans/git-gateway-cutover.md. This request type is the daemon-side entry point that routes exec through the same Runner.Dispatch() path as every session, so any future dispatch-time wiring lands on both by construction instead of needing a second, easy-to-forget call site.
Unlike sessions (fixed harness_type, agent-driven argv), exec runs an arbitrary user-supplied argv with no HarnessAdapter agent — see dispatcher.BuildExecJobSpec, which forces HarnessType="shell" underneath.
type StartExecResult ¶
StartExecResult is the response shape for POST /api/projects/{id}/exec.
type StartSessionRequest ¶
type StartSessionRequest struct {
// ProjectID names the project whose traits the session inherits. For the
// project-scoped route (`/api/projects/{id}/sessions`) it is taken from
// the URL and the body field is ignored.
ProjectID string `json:"project_id"`
// HarnessType selects the agent adapter. Must be one of "claude",
// "codex", or "opencode". The historical "shell" session variant was
// retired after the git gateway cutover — `boid exec -p <project> -- bash`
// runs the shell adapter through the same Runner.Dispatch() with an
// interactive PTY, so there is no session use case left for it.
// sessionDispatcherAdapter.StartSession rejects any other value at the
// API boundary.
HarnessType string `json:"harness_type"`
// Instruction is the optional bootstrap prompt for the first turn. Empty
// leaves the harness to pick its default (no positional for session mode
// on claude, since /boid-task is meaningless without a task.yaml).
Instruction string `json:"instruction,omitempty"`
// Readonly, when true, mounts the project workspace read-only. Sessions
// default to writable (developer ergonomics > fail-safety).
Readonly bool `json:"readonly,omitempty"`
// Model overrides the harness binary's default model selection.
Model string `json:"model,omitempty"`
// DisplayName is the human-readable session label persisted to
// jobs.display_name. Empty falls back to "<harness> session".
DisplayName string `json:"display_name,omitempty"`
// CardID / CardRequestID mark this session as a card command's
// continuation, propagated onto the resulting JobSpec/token so a
// daemon-restart recovery scan can reverse-link it to its
// card_requests row. Deliberately untagged for JSON (no external
// caller may set these on POST /api/sessions or the project-scoped
// route) — only boid_executor's BoidOpAgentStart case constructs a
// StartSessionRequest with these set, from its own token context.
CardID string `json:"-"`
CardRequestID string `json:"-"`
}
StartSessionRequest is the body of POST /api/sessions and POST /api/projects/{id}/sessions. Phase 3-d (PR1) introduced the session concept as a first-class JobKind so the WebUI [New Session] dialog and the `boid agent` CLI share one daemon entry point.
type StartSessionResult ¶
type StartSessionResult struct {
JobID string `json:"job_id"`
AttachURL string `json:"attach_url"`
}
StartSessionResult is the response shape for POST /api/sessions and the project-scoped variant.
type TaskDetailView ¶
type TaskDetailView struct {
Task *orchestrator.Task
Actions []*orchestrator.Action
Jobs []*Job
AvailableActions []string `json:"available_actions"`
Identities []TaskIdentity `json:"identities,omitempty"`
}
type TaskIdentity ¶ added in v0.5.0
type TaskIdentityRequest ¶ added in v0.6.0
type TaskIdentityRequest struct {
ProjectID string `json:"project_id,omitempty"`
WorkspaceID string `json:"workspace_id,omitempty"`
Identity string `json:"identity"`
TaskID string `json:"task_id,omitempty"`
URL *string `json:"url,omitempty"`
DisplayName *string `json:"display_name,omitempty"`
}
TaskIdentityRequest selects a repository scope or a repository-free workspace scope.
type UpdateTaskRequest ¶
type UpdateTaskRequest struct {
Title string `json:"title"`
Description string `json:"description"`
ProjectID string `json:"project_id,omitempty"`
RemoteID *string `json:"remote_id,omitempty"`
Payload json.RawMessage `json:"payload,omitempty"`
Instructions json.RawMessage `json:"instructions,omitempty"`
ParentID *string `json:"parent_id,omitempty"`
AutoStart *bool `json:"auto_start,omitempty"`
}
type WorkspaceDetail ¶
type WorkspaceDetail struct {
Slug string `json:"slug"`
Meta *orchestrator.WorkspaceMeta `json:"meta"`
Revision string `json:"revision,omitempty"`
// ProjectCount mirrors len(AssignedProjects); kept as its own field so
// callers that only need the count (e.g. a future list-style summary
// view) don't need to len() the slice themselves.
ProjectCount int `json:"project_count"`
AssignedProjects []string `json:"assigned_projects"`
// Home reports the workspace home VOLUME's size, read from the engine's
// own disk-usage accounting (docs/plans/workspace-home-volume-persistence.md
// 論点 a-2, PR7 — it was a directory-tree walk under Phase 4 PR5, before
// the home became a docker named volume). Populated only by GET
// /api/workspaces/{slug} (WorkspaceHandler.Show) — Create/Update/Import
// leave it nil, since reading it costs an engine round trip and none of
// those callers need it. nil (omitted from the JSON body) when the
// handler has no home store, i.e. no engine handle to ask.
Home *WorkspaceHomeSize `json:"home,omitempty"`
}
WorkspaceDetail is the response shape for the workspace create/show/update endpoints: the parsed meta plus enough bookkeeping (revision, assigned project ids) for a caller to display or re-PUT it with the correct If-Match header. docs/plans/workspace-db-consolidation.md Step C/D/E.
type WorkspaceHomeSize ¶
type WorkspaceHomeSize struct {
Slug string `json:"slug"`
// Volume is the engine-side name of the workspace's HOME volume,
// dockerres.WorkspaceHomeVolumeName(installID, slug) — the same name the
// dispatcher mounts as the harness's $HOME, and the name to pass to
// `docker volume rm` for manual cleanup. Always set, whether or not the
// volume currently exists.
//
// It REPLACES the `path` field this struct carried through PR6, rather
// than joining it (論点 a-2, D4). A volume name is not a path, and the
// only consumers are boid's own CLI renderers (cmd/workspace.go's
// formatWorkspaceHomeSize / formatWorkspaceRemoveResult, cmd/gc.go's
// printWorkspaceHomes), which this PR updates in lockstep. Keeping a
// `path` key alive with a volume name in it would have made every one of
// them print a lie that reads like a path; keeping BOTH would have meant
// emitting a legacy field describing a directory the daemon stopped
// using two PRs ago.
//
// On CLI/daemon version skew: this repo has no API versioning and no
// compatibility shim — a field the peer does not know decodes to its zero
// value, which is precisely how `boid gc`'s listing already documents its
// own old-daemon behavior ("either the daemon was too old to report it,
// or no workspace has ever been dispatched into yet", cmd/gc.go's
// printWorkspaceHomes). Skew is reachable since Phase 3 made the CLI able
// to talk to a remote daemon, so the renderers updated by this PR treat
// an empty identifier as "not reported" and omit the parenthetical
// instead of printing an empty one. That is the whole cost in both
// directions: a size still renders, only unattributed.
Volume string `json:"volume"`
// Exists reports whether the volume is currently on the engine. false
// means the workspace has never been dispatched into (docs/plans/
// home-workspace-volume.md's init-on-first-dispatch contract) — not an
// error.
Exists bool `json:"exists"`
// Bytes is the volume's size as the engine's GET /system/df reports it,
// meaningful only when Exists is true and SizeError is empty. See
// dispatcher.WorkspaceHomeVolumeStore's doc comment for what that number
// means (du --apparent-size semantics) and why that endpoint is the only
// one that can produce it.
Bytes int64 `json:"bytes"`
// Orphan is true when a workspace HOME volume exists but Slug has no
// corresponding workspace row — a workspace removed (or never
// assign/create'd) while its home volume survived. Only ever set by the
// GC listing (ListWorkspaceHomeSizes); the single-slug lookup used by
// GET /api/workspaces/{slug} always has a live workspace row (it is 404
// otherwise), so it never carries Orphan=true.
Orphan bool `json:"orphan"`
// SizeError is non-empty when the size could not be determined — the
// engine's disk-usage call failed, or it listed the volume without usage
// data. Bytes is 0 and must not be trusted when this is set; callers
// render "?" instead (docs/plans/home-workspace-volume.md PR5: "エラー時は
// エラーにせず「?」表示"). A non-empty SizeError does *not* imply the
// volume is gone or undeletable — deleteWorkspaceHome treats sizing as
// best-effort and still attempts deletion regardless (codex PR #791
// review, Should-fix #2).
SizeError string `json:"size_error,omitempty"`
}
WorkspaceHomeSize describes one workspace home's footprint: used both by GET /api/workspaces/{slug} (a single entry, WorkspaceDetail.Home) and by POST /api/gc's workspace_homes listing (one entry per workspace home volume this install has).
type WorkspaceInitScriptResult ¶
type WorkspaceInitScriptResult struct {
Slug string `json:"slug"`
// Action is one of WorkspaceInitScriptWritten / Cleared / Unchanged.
Action string `json:"action"`
// Revision is the state AFTER the call — a content hash, or the absent
// sentinel when the script was cleared. A caller editing in a loop can
// carry it straight into the next If-Match.
Revision string `json:"revision"`
// Bytes is the persisted size, 0 when cleared.
Bytes int `json:"bytes"`
// Path is the daemon-side location, reported so an operator is never left
// guessing which filesystem the answer refers to.
Path string `json:"path,omitempty"`
}
WorkspaceInitScriptResult is PUT /api/workspaces/{slug}/init-script's response body.
type WorkspaceRemoveResponse ¶
type WorkspaceRemoveResponse struct {
Status string `json:"status"`
// HomeVolume/HomeBytes describe the workspace's HOME volume as it was
// found right before the deletion attempt (empty/0 when no docker client
// was wired into the handler, or slug is the reserved default workspace).
// HomeBytes is only trustworthy when HomeSizeError is empty.
//
// HomeVolume replaces the `home_path` field this struct carried through
// PR6 — see WorkspaceHomeSize.Volume for the reasoning and for the
// CLI/daemon-skew consequences.
HomeVolume string `json:"home_volume,omitempty"`
HomeBytes int64 `json:"home_bytes,omitempty"`
// HomeSizeError is non-empty when the daemon could not determine
// HomeVolume's size before attempting deletion (mirrors
// WorkspaceHomeSize.SizeError) — independent of whether the deletion
// itself subsequently succeeded. Split out from HomeDeleteError (codex
// PR #791 review, Should-fix #2): the two used to be conflated into a
// single field, so a caller could not tell "we don't know the size" (a
// diagnostic-only hiccup) apart from "the volume is still there and
// undeletable" (a real part-completed-remove problem worth
// investigating).
HomeSizeError string `json:"home_size_error,omitempty"`
// HomeDeleted is true only when a home volume existed and the engine
// removed it. false covers every other case: no docker client wired, the
// default workspace's protected home, no volume to begin with, or a
// deletion failure (see HomeDeleteError for that last one). Sizing is
// best-effort (see HomeSizeError) and never gates whether deletion is
// attempted — HomeDeleted can be true even when HomeSizeError is also
// non-empty.
HomeDeleted bool `json:"home_deleted"`
// HomeDeleteError is non-empty only when the engine's VolumeRemove
// failed. Never populated merely because sizing failed (see
// HomeSizeError for that).
//
// The case worth naming: removing a workspace while a job is still
// running in it. The engine answers 409 ("volume is being used by the
// following container(s): <id>") and — measured against podman 4.9.3,
// 2026-07-27 — keeps answering 409 with force set, so there is nothing
// boid can do about it beyond reporting it. The row is gone and the
// volume is not; re-running `boid workspace remove` is not an option
// (the row is already removed, so it 404s), which makes
// `docker volume rm <home_volume>` the follow-up. See
// docs/{ja,en}/guide/workspace-home.md.
HomeDeleteError string `json:"home_delete_error,omitempty"`
// InitScriptDeleted is true only when the workspace HAD an init.sh and it
// was removed (PR9 codex round 2, Major 1). false covers a workspace that
// never had one, the reserved default workspace, a daemon with no init
// script store wired, and a failed deletion — see InitScriptDeleteError
// for that last one.
//
// Reported at all because leaving a workspace's init.sh behind is not a
// harmless leftover: dispatch resolves the script from the SLUG, so the
// next workspace created with the same name inherits it and runs it
// against a brand-new, empty HOME volume. The row is gone by then, which
// also means `boid workspace unset-init-script` can no longer reach it.
InitScriptDeleted bool `json:"init_script_deleted"`
// InitScriptDeleteError is non-empty only when the daemon tried to delete
// the workspace's init.sh and could not. Best-effort, exactly like
// HomeDeleteError and for the same reason: the row removal has already
// committed, so failing the whole request would report a failure over an
// irreversible success — and re-running `boid workspace remove` is not
// available, since it 404s on the row that is already gone.
//
// The message carries the daemon-side path (WorkspaceInitScriptStore.
// Remove wraps it in), which is what an operator needs to delete the
// leftover by hand — and, under the container deploy, to know which
// filesystem it is on.
InitScriptDeleteError string `json:"init_script_delete_error,omitempty"`
}
WorkspaceRemoveResponse is the response body for DELETE /api/workspaces/{slug} (docs/plans/home-workspace-volume.md Phase 4 PR5). The workspace row is always removed before any home deletion is attempted (WorkspaceHandler.Remove calls Service.RemoveWorkspace first), so a non-empty HomeDeleteError (or HomeSizeError) reports a *partially* completed remove — deliberately allowed per the plan doc ("削除失敗... workspace 設定 (DB) の削除は先に完了させる (part-completed 状態を許容...)") rather than treated as a request failure: the response status stays 200.