client

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package client is the public Go SDK for the Wardyn control plane. It uses internal/types as the shared JSON source of truth and adds exactly one non-stdlib dependency (github.com/google/uuid, for typed ids) so it can be embedded in external tooling without friction. The in-repo `wardyn` CLI uses THIS client directly (there is no second transport); it maps APIError to process exit codes and prints APIError.Error(), which unwraps the server's {"error":...} envelope into a human-readable message.

Coverage

The SDK covers these wardynd public route families (the ones external tooling automates); it is a curated subset, NOT a 1:1 mirror of every route:

  • runs (/api/v1/runs): CreateRun, Preflight, GetRun, ListRuns, ListRunsPage, ListGrants, ListGrantsPage, KillRun, SynthesizeProfile, GetRecording, RunFiles, RunEvents, RunOutput, RunSignIn, GetRunPolicy
  • approvals (/api/v1/approvals): ListApprovals, ListApprovalsPage, Approve, Deny
  • policies (/api/v1/policies): CreatePolicy, GetPolicy, GetDefaultPolicy, ListPolicies, ListPoliciesPage, UpdatePolicy, DeletePolicy
  • workspaces (/api/v1/workspaces): CreateWorkspace, GetWorkspace, ListWorkspaces, ListWorkspacesPage, UpdateWorkspace, DeleteWorkspace, ScanWorkspace, RecordWorkspaceTask, GetWorkspaceBuild, BuildWorkspace
  • sources (/api/v1/sources): ListSources, CreateSource, GetSource, ScanSource, DeleteSource
  • audit (/api/v1/audit): AuditEvents, AuditEventsPage, RecentAuditEvents, ExportAuditPartition, AuditRetention, DropAuditPartition
  • secrets (/api/v1/secrets): ListSecrets, ListSecretsPage, ListSecretsScoped, ListSecretsScopedPage, SetSecret, DeleteSecret, ListMySecrets, ListMySecretsPage, SetMySecret, DeleteMySecret
  • shared-secrets (/api/v1/shared-secrets): ListSharedSecrets, ListSharedSecretsPage, SetSharedSecret, DeleteSharedSecret
  • site-config (/api/v1/site-config): GetSiteConfig, PutSiteConfig, PutSiteConfigResult
  • model-providers (/api/v1/model-providers): GetModelProviders — the read only (admin); the PUT and the per-provider sign-in and credential doors are NOT wrapped
  • drives (/api/v1/drives): GetDrives, ApplyDrives, ApplyDrivesResult, and people's own drives: ListMemberDrives, DeleteMemberDrive (/api/v1/drives/member, super admin) and the caller's CreateMyDrive, DeleteMyDrive (/api/v1/me/drives)
  • presets (/api/v1/presets): ListPresets, GetPreset, PutPreset, DeletePreset, ApplyPresets
  • templates (/api/v1/templates): ListTemplates, GetTemplate, SaveTemplate, DeleteTemplate, CopyTemplate, ImportTemplate — and, on /api/v1/admin/template-group-admins, ListTemplateGroupAdmins, GrantTemplateGroupAdmin, RevokeTemplateGroupAdmin. The server answers 501 templates_unavailable until the template store lands
  • governance (/api/v1/governance): GetGovernance, PlanGovernance, ApplyGovernance, ApplyGovernanceResult
  • governance changes (/api/v1/governance/changes): ListGovernanceChanges, GetGovernanceChange, ApproveGovernanceChange, RejectGovernanceChange
  • setup (/api/v1/setup): SetupStatus, ConnectManagedSubscription, DisconnectManagedSubscription
  • identity (/api/v1/me): Me — and, on the same prefix, ListSSHKeys/ ListSSHKeysPage/AddSSHKey/DeleteSSHKey (/api/v1/me/ssh-keys). The rest of /api/v1/me is NOT wrapped: see below.
  • health (/healthz): Healthz
  • sessions (/api/v1/sessions): RevokeSessions
  • runners (/api/v1/runners, /api/v1/me/runners): MintRunnerToken, RegisterRunner, ClaimRunner, ListRunners, ListRunnersPage, GetRunner, ListMyRunners, GetMyRunner, SetMyRunnerLimits, ListRunnerTokens, ListRunnerTokensPage, RevokeRunnerToken, GetRunnerSettings, SetRunnersEnabled
  • runner pools (/api/v1/runner-pools, /api/v1/runner-pool-defaults; /api/v1/me/runner-pools, /api/v1/me/runner-pool-defaults): ListRunnerPools, ListRunnerPoolsFor, GetRunnerPool, CreateRunnerPool, UpdateRunnerPool, DeleteRunnerPool, CreateMyRunnerPool, UpdateMyRunnerPool, DeleteMyRunnerPool, AddMyRunnerToPool, RemoveMyRunnerFromPool, GetOrgRunnerPoolDefaults, SetOrgRunnerPoolDefaults, GetMyRunnerPoolDefaults, SetMyRunnerPoolDefaults, ClearMyRunnerPoolDefaults, AddRunnerPoolRemoteRunner, RemoveRunnerPoolRemoteRunner, AddMyPoolRemoteRunner, RemoveMyPoolRemoteRunner, ListRunnerPoolMembers, GetRunnerPoolUsePolicy, SetRunnerPoolUsePolicy, ClearRunnerPoolUsePolicy
  • remote-hosted runners (/api/v1/remote-runners, /api/v1/me/remote-runners): ListRemoteRunners, GetRemoteRunner, UpdateRemoteRunner, SetRemoteRunnerPeoplePolicy, ClearRemoteRunnerPeoplePolicy, ListMyRemoteRunners
  • devices (/api/v1/admin/devices): MintDeviceEnrolmentToken, ListDeviceEnrolmentTokens, RevokeDeviceEnrolmentToken, ListDevices, RevokeDevice
  • people (/api/v1/people): ListPeople, and ErasePerson (a person's retained records, by scope, 0.8.6); the other writes below stay unwrapped
  • invitations (/api/v1/invitations, /api/v1/people/{principal}/invitations, /api/v1/me/invitations): CreateInvitation, ListInvitations, ListPersonInvitations, ListPersonInvitationsPage, ListMyInvitations, RevokeInvitation, ClaimInvitation (a signed-in session only)
  • service identities (/api/v1/service-identities, /api/v1/me/service-identities): CreateServiceIdentity, ListServiceIdentities, ListServiceIdentitiesPage, GetServiceIdentity, UpdateServiceIdentity, RetireServiceIdentity, ListMyServiceIdentities, and the sponsor's token routes MintServiceToken (a signed-in session only), ListServiceTokens, ListServiceTokensPage, RevokeServiceToken; with MoveToken (POST /api/v1/tokens/{id}/move)
  • components (/api/v1/components): ListComponents, PutComponent, DeleteComponent (the organisation's, admin) — and, on /api/v1/me/components, the caller's own: MyComponents, SaveMyComponent, UpdateMyComponent, DeleteMyComponent

NOT covered — drive these with the CLI or raw HTTP. This half is a CENSUS of every registered route family the SDK does not wrap, not a list of highlights: it read "attach, harness-login and /internal/*" while seven whole families 0.7 added were missing from BOTH halves, so docs/sdk.md's "the exact list of what it wraps and what it does not" was exact about neither.

  • /api/v1/user-types — the org's user types (0.8)
  • /api/v1/key-domains — which declared key domain wraps a person's next principal key (0.8.6). Security tier
  • /api/v1/approval-notify — each approval notification channel's delivery health (0.8.6). Security tier, and read by the console's Settings card rather than by tooling
  • /api/v1/permissions — capability grants and per-kind enforcement (0.7)
  • /api/v1/access — directory search and group->role mappings (0.7)
  • /api/v1/tokens — admin-tier API tokens (0.7), but for MoveToken (0.9); /api/v1/me/tokens is the self-service half, also unwrapped
  • /api/v1/people — the writes: creating a person, erasing their stored credentials (0.8, offboarding); its invitations are wrapped above
  • /api/v1/scim — the Settings SCIM card's read-only status (0.8.6); the SCIM server itself is /scim/v2
  • /api/v1/workspace-providers — the org's git-provider policy (allowed base URLs, credential lanes) and storage ceilings (0.7.2). Admin-only, and authored through the console's providers page rather than by tooling
  • /api/v1/agent-providers — the org's agent roster: which coding agents this deployment offers, each one's model-access lane, and whether that credential is shared or per-person (0.7.2). Admin-only, same page
  • /api/v1/integrations — integration definitions (0.7)
  • /api/v1/base-images — the base-image library (0.7)
  • /api/v1/admin — operator maintenance (the sandbox sweep; devices is wrapped)
  • /api/v1/devices — an enrolled laptop's daemon routes (enrol, audit, heartbeat)
  • /api/v1/internal — the AGENT-facing plane (mint, decisions, groundtruth, scan-results, token renew). Deliberately unwrapped: it is the sandbox's surface, not an operator's.
  • /api/v1/me — beyond Me, ssh-keys and components: capabilities, run-layout, tokens
  • /api/v1/auth, /auth/login, /auth/callback — the browser SSO leg, plus the harness-login device flow. A redirect dance, not an API call.
  • /api/v1/scm — the per-user Azure DevOps sign-in (0.7.10): a sign-in door and its identity-provider callback. Unwrapped for the same reason the SSO leg above is — it is a browser redirect dance whose whole point is a human at a keyboard consenting, and it binds to a browser session an SDK caller does not have.
  • /api/v1/model-providers-entra — the per-row Azure Foundry sign-in door (0.8.6): a browser redirect dance whose callback is the /api/v1/scm one above. Unwrapped for the same reason.
  • /api/v1/components-entra — the Azure CLI component's sign-in door: the same redirect dance and the same callback. Unwrapped for the same reason.
  • the attach lane under /api/v1/runs/{id} — attach, attach/ticket, attach/holder, attach/takeover, resources. A WebSocket and its ticket.
  • /scim/v2/Users, /scim/v2/Users/{id}, /scim/v2/Groups, /scim/v2/Groups/{id} — the identity provider's SCIM connector (0.8.6): suspend and reactivate a person, and remove one from a group. Authenticated by its own bearer (WARDYN_SCIM_TOKEN), never by an operator's credential, so no SDK caller holds it.
  • /api/v1/branding — console branding (#1125): the sign-in page's anonymous read and logo, and the Admin view Branding card's save; a console surface
  • /metrics, /readyz — the operator's scrape and readiness probes
  • the console SPA at / — static assets

(The AI Run Composer's /runs/compose* used to be listed here; those routes were removed in 0.5, not left unwrapped.)

TestClientCoversRouteFamilies pins that every family listed above has a method, TestRouteFamiliesCoverEveryMethod pins the reverse, and TestSDKCensusNamesEveryRouteFamily (internal/api) pins the COMPLEMENT: every route family the router actually registers appears in one of the two halves above, so a new one cannot land in neither.

Pagination

The list endpoints and the audit trail accept an optional ListOpts (variadic, so existing zero-arg calls are unchanged) that sends ?limit=&offset=. A page may be truncated (the server sets X-Wardyn-Truncated); re-request with Offset advanced by len(page) to page forward.

EVERY list family surfaces that signal, through a *Page variant returning it as a bool: ListRunsPage, ListApprovalsPage, ListPoliciesPage, ListWorkspacesPage, AuditEventsPage, ListGrantsPage, ListSSHKeysPage, ListSecretsPage. The plain forms are thin wrappers that discard it, so existing callers are unchanged — but they leave the caller to infer completeness from len(page) == the limit it happened to pass, a guess that silently breaks the moment a caller omits Limit and gets the server's own default page size. This doc used to name the header as the pagination contract for the list endpoints while only the audit method honoured it: the four list families discarded the header, so `wardyn run|approvals|policy| workspace list` printed a truncated page with exit 0 and nothing on stderr.

Usage: 

c := client.New("https://wardyn.example.com", "admin-token")
run, err := c.CreateRun(ctx, client.CreateRunRequest{
    Agent: "claude-code",
    Repo:  "org/repo",
    Task:  "fix issue #42",
})

Index

Constants

View Source 
const (
	CLIStateAvailable  = "available"
	CLIStateNotGranted = "not_granted"
	CLIStateComingSoon = "coming_soon"
)

CLI card states.

View Source 
const (
	MeDriveSectionUser   = "user"
	MeDriveSectionShared = "shared"

	MeDriveSourcePersonal     = "personal"
	MeDriveSourceTeam         = "team"
	MeDriveSourceOrganisation = "organisation"

	MeDriveUnavailablePaused      = "paused"
	MeDriveUnavailableUnmountable = "unmountable"
	MeDriveUnavailableNotInPool   = "not_in_pool"
)

The closed sets of MeDrive.

View Source 
const (
	PeoplePoolsOff      = types.PeoplePoolsOff
	PeoplePoolsEveryone = types.PeoplePoolsEveryone
	PeoplePoolsListed   = types.PeoplePoolsListed
)

The people policy values.

View Source 
const (
	RunEventProvisioning = "provisioning" // PENDING -> STARTING: sandbox being created
	RunEventPulling      = "pulling"      // the substrate reported an image pull
	RunEventReady        = "ready"        // STARTING -> RUNNING
	RunEventIdleStopped  = "idle_stopped" // the idle reaper stopped the run
	RunEventFailed       = "failed"       // -> FAILED; Reason names the phase
	RunEventEnded        = "ended"        // terminal; State is the terminal state
)

The closed RunEvent.Type vocabulary, in the order a run can reach them. Every stream finishes with RunEventEnded.

View Source 
const (
	RunFailedNotStarted  = "not_started"  // failed before provisioning began
	RunFailedStartFailed = "start_failed" // failed while provisioning
	RunFailedRunFailed   = "run_failed"   // failed after it was ready
)

RunEventFailed reasons: which phase the run failed in.

View Source 
const (
	RunPolicyViewRecorded = "recorded"
	RunPolicyViewNotYet   = "not_yet"
	RunPolicyViewNever    = "never"
)

The RunPolicyView.State values.

View Source 
const (
	SignInWaiting    = "waiting"
	SignInNotWaiting = "not_waiting"
)

The two RunSignIn.State values.

View Source 
const (
	RunnerFilterActive  = types.RunnerFilterActive
	RunnerFilterRevoked = types.RunnerFilterRevoked
	RunnerFilterAll     = types.RunnerFilterAll
)

The runner state filter of ListRunners; an empty filter is RunnerFilterActive.

View Source 
const (
	RunnerPoolOrganization = types.RunnerPoolOrganization
	RunnerPoolUser         = types.RunnerPoolUser

	RunnerKindSelfHosted   = types.RunnerKindSelfHosted
	RunnerKindRemoteHosted = types.RunnerKindRemoteHosted

	RunnerPoolActive   = types.RunnerPoolActive
	RunnerPoolDisabled = types.RunnerPoolDisabled
	RunnerPoolDeleted  = types.RunnerPoolDeleted

	RunnerPoolSelectedExplicit = types.RunnerPoolSelectedExplicit
	RunnerPoolSelectedPersonal = types.RunnerPoolSelectedPersonal
	RunnerPoolSelectedOrg      = types.RunnerPoolSelectedOrg

	RunnerPoolRunBackground  = types.RunnerPoolRunBackground
	RunnerPoolRunInteractive = types.RunnerPoolRunInteractive

	LimitSourcePool       = types.LimitSourcePool
	LimitSourceGovernance = types.LimitSourceGovernance
	LimitSourceDeployment = types.LimitSourceDeployment
	LimitSourceRunner     = types.LimitSourceRunner

	// RunEndMaxLifetimeReached is the reason a run is KILLED at its maximum lifetime.
	RunEndMaxLifetimeReached = types.RunEndMaxLifetimeReached
)

The scopes, runner kinds, lifecycle states and selection provenance values.

View Source 
const (
	RunnerPoolAvailable   = "available"
	RunnerPoolUnavailable = "unavailable"
	RunnerPoolUnknown     = "unknown" // the answer could not be read; never read as available
)

Whether a permitted pool can take a run right now.

View Source 
const (
	MainDriveFilesystem MainDriveEnforcement = "filesystem"
	MainDriveEviction   MainDriveEnforcement = "eviction"
	MainDriveNone       MainDriveEnforcement = "none"
	MainDriveUnknown    MainDriveEnforcement = "unknown"

	// MainDriveCoverageAll is the sandbox's writable layer (Docker's /tmp is a separate in-memory tmpfs).
	MainDriveCoverageAll MainDriveCoverage = "all"
	// MainDriveCoverageScratch is /tmp, /home/agent/work and /home/agent/.cache only.
	MainDriveCoverageScratch MainDriveCoverage = "scratch_paths"
)
View Source 
const (
	RunTypesSourcePool = "pool"
	RunTypesSourceNone = "none"
)

Where a pool's run types come from: its own limits, or none, which takes both.

View Source 
const (
	SlotsStartsNow = "starts_now"
	SlotsWaits     = "waits"
)

The Verdict of PoolSlots: advisory, since the launch decides.

View Source 
const (
	ExperienceBackground  = types.ExperienceBackground
	ExperienceInteractive = types.ExperienceInteractive
)

The two experiences. Background is a task or a command with no interactive surface; Interactive is general sandboxed work through whatever surfaces the placement supports.

View Source 
const (
	PlacementRemote = placement.Remote
	PlacementLocal  = placement.Local
)

The placements CreateRunRequest.Placement accepts.

View Source 
const (
	LocalPlacementHost      = "host"
	LocalPlacementSource    = "source"
	LocalPlacementComponent = "component"
)

The kinds a LocalPlacementFact is about.

View Source 
const (
	ImageSourceBase       = "base"        // the agent base image, for a run with no harness CLI
	ImageSourceAgent      = "agent"       // the agent's own convention image
	ImageSourceHarnessSet = "harness_set" // an image the operator declared for several harnesses; Name is its key
	ImageSourceWorkspace  = "workspace"   // a workspace's base image; Name is the workspace
	ImageSourceBuild      = "build"       // the person's own build (a custom image or devcontainer)
	ImageSourceOrgAllowed = "org_allowed" // one of the images the organisation allows, chosen by the person
)

The kinds of source a run's resolved image comes from.

View Source 
const (
	TemplateDocumentVersion = "wardyn/v1"
	TemplateDocumentKind    = "RunTemplate"
	// RunDocumentKind is a draft of one run, not a catalogue entry: it carries
	// no name, coverage or needs_setup.
	RunDocumentKind = "Run"
)

TemplateDocumentVersion and TemplateDocumentKind identify the document schema an import or a saved template carries.

View Source 
const (
	TemplateScopePerson = types.TemplateScopePerson
	TemplateScopeOrg    = types.TemplateScopeOrg
	TemplateScopeGroup  = types.TemplateScopeGroup
)

The template scopes.

View Source 
const (
	TemplateKindTemplate = types.TemplateKindTemplate
	TemplateKindPolicy   = types.TemplateKindPolicy
)

The template kinds.

View Source 
const (
	ConfigKindString     = types.ConfigKindString
	ConfigKindBoolean    = types.ConfigKindBoolean
	ConfigKindInteger    = types.ConfigKindInteger
	ConfigKindNumber     = types.ConfigKindNumber
	ConfigKindEnum       = types.ConfigKindEnum
	ConfigKindStringList = types.ConfigKindStringList
	ConfigKindSecretRef  = types.ConfigKindSecretRef
	ConfigBindConfig     = types.ConfigBindConfig
	ConfigBindSecret     = types.ConfigBindSecret
)

The schema's closed field kinds and binding targets.

View Source 
const (
	SourceLocalDir = types.SourceLocalDir
	SourceRepo     = types.SourceRepo
)

SourceKind values (the tier-1 library's two onboardable kinds).

View Source 
const (
	ApprovalPending  = types.ApprovalPending
	ApprovalApproved = types.ApprovalApproved
	ApprovalDenied   = types.ApprovalDenied
	ApprovalExpired  = types.ApprovalExpired
	// ApprovalCancelled: the approval's RUN reached a terminal state while it was
	// still PENDING, so nobody decided it and nothing was approved or denied.
	ApprovalCancelled = types.ApprovalCancelled
)

ApprovalState values. ListApprovals accepts one of these (or "" for all states).

View Source 
const (
	ScopeOnce   = types.ScopeOnce
	ScopeRun    = types.ScopeRun
	ScopeUntil  = types.ScopeUntil
	ScopeAlways = types.ScopeAlways
)

ApprovalScope values, for DecisionOpts.Scope on Approve/Deny. Omitting Scope (or passing "") is ScopeRun — today's default, unchanged.

View Source 
const (
	RunQueued    = types.RunQueued
	RunPending   = types.RunPending
	RunStarting  = types.RunStarting
	RunRunning   = types.RunRunning
	RunWaiting   = types.RunWaiting
	RunStopped   = types.RunStopped
	RunArchived  = types.RunArchived
	RunFailed    = types.RunFailed
	RunKilled    = types.RunKilled
	RunCompleted = types.RunCompleted
)

RunState values.

View Source 
const (
	CC1 = types.CC1
	CC2 = types.CC2
	CC3 = types.CC3
)

ConfinementClass values.

View Source 
const (
	GrantGitHubToken = types.GrantGitHubToken
	GrantGitPAT      = types.GrantGitPAT
	GrantCloudSTS    = types.GrantCloudSTS
	GrantAPIKey      = types.GrantAPIKey
	GrantSSHKey      = types.GrantSSHKey
	GrantEnvSecret   = types.GrantEnvSecret
)

GrantKind values.

View Source 
const (
	ApprovalCredential   = types.ApprovalCredential
	ApprovalEgressDomain = types.ApprovalEgressDomain
	ApprovalToolCall     = types.ApprovalToolCall
	ApprovalPushContent  = types.ApprovalPushContent
)

ApprovalKind values.

View Source 
const (
	ActorHuman  = types.ActorHuman
	ActorAgent  = types.ActorAgent
	ActorSystem = types.ActorSystem
)

ActorType values.

View Source 
const (
	WorkspaceKindLocalDir  = types.WorkspaceKindLocalDir
	WorkspaceKindRepo      = types.WorkspaceKindRepo
	WorkspaceKindContainer = types.WorkspaceKindContainer
)

WorkspaceKind values (WorkspaceRequest.Kind). Deprecated: the legacy single-source shape; a new caller should build WorkspaceSource entries with a WorkspaceSourceType value instead.

View Source 
const (
	WorkspaceSourceTypeLocalDir  = types.WorkspaceSourceTypeLocalDir
	WorkspaceSourceTypeRepo      = types.WorkspaceSourceTypeRepo
	WorkspaceSourceTypeEphemeral = types.WorkspaceSourceTypeEphemeral
)

WorkspaceSourceType values (WorkspaceSource.Type).

View Source 
const (
	WorkspacePendingScan = types.WorkspacePendingScan
	WorkspaceScanning    = types.WorkspaceScanning
	WorkspaceScanned     = types.WorkspaceScanned
	WorkspaceError       = types.WorkspaceError
)

WorkspaceStatus values (Workspace.Status, Source.Status).

View Source 
const (
	DriveBackendDockerVolume = types.DriveBackendDockerVolume
	DriveBackendHostPath     = types.DriveBackendHostPath
	DriveBackendK8sPVC       = types.DriveBackendK8sPVC
	DriveBackendK8sPVCStatic = types.DriveBackendK8sPVCStatic
)

DriveBackend values.

View Source 
const (
	HomeTemplateHash       = types.HomeTemplateHash
	HomeTemplateSub        = types.HomeTemplateSub
	HomeTemplateEmailLocal = types.HomeTemplateEmailLocal
)

HomeTemplate values.

View Source 
const (
	DriveReclaimRetain = types.DriveReclaimRetain
	DriveReclaimDelete = types.DriveReclaimDelete
)

DriveReclaim values.

View Source 
const (
	CapabilitySubjectUser     = types.CapabilitySubjectUser
	CapabilitySubjectGroup    = types.CapabilitySubjectGroup
	CapabilitySubjectAll      = types.CapabilitySubjectAll
	CapabilitySubjectUserType = types.CapabilitySubjectUserType
)

CapabilitySubjectType values.

View Source 
const (
	AutonomyL0 = types.AutonomyL0
	AutonomyL1 = types.AutonomyL1
	AutonomyL2 = types.AutonomyL2
	AutonomyL3 = types.AutonomyL3
)

AutonomyLevel values.

View Source 
const (
	InvitationPending = types.InvitationPending
	InvitationClaimed = types.InvitationClaimed
	InvitationExpired = types.InvitationExpired
	InvitationRevoked = types.InvitationRevoked

	ServiceIdentityActive          = types.ServiceIdentityActive
	ServiceIdentitySuspended       = types.ServiceIdentitySuspended
	ServiceIdentityRetired         = types.ServiceIdentityRetired
	ServiceIdentitySponsorInactive = types.ServiceIdentitySponsorInactive

	TokenNeedsDecision   = types.TokenNeedsDecision
	TokenAwaitingOwner   = types.TokenAwaitingOwner
	TokenReplacedByOwner = types.TokenReplacedByOwner
	TokenLinkedToService = types.TokenLinkedToService
	TokenMovedToService  = types.TokenMovedToService
	TokenRevoked         = types.TokenRevoked
)

Invitation, service-identity and admin-minted-token states, the values of the *State and TokenDisposition fields above.

View Source 
const RunModeContractV09 = "0.9"

RunModeContractV09 is the one value of CreateRunRequest.ModeContract.

View Source 
const StartFolderDrive = "drive"

StartFolderDrive names the person's drive as a start folder attachment.

Variables

This section is empty.

Functions

This section is empty.

Types

type ADOOverrides added in v0.9.0 

type ADOOverrides struct {
	Capabilities []string `json:"capabilities"`
}

ADOOverrides is the capability set the run keeps. It must be a subset of the set the source resolved; a capability outside it is refused, never granted.

type ADOTokenMode added in v0.9.0 

type ADOTokenMode = types.ADOTokenMode

ADOTokenMode is how a run presents itself to Azure DevOps, carried in ComponentFact.TokenMode.

type APIError 

type APIError struct {
	// Status is the HTTP status code, e.g. 404.
	Status int
	// Body is the raw server response body (capped at 2048 bytes).
	Body string
	// Reason is the server's machine-readable refusal class (internal/api's
	// errorBody.Reason), "" when the route does not send one — most do not yet
	// (#204 is phasing coverage in lane by lane). A caller that needs to branch
	// on WHY a call failed reads Reason, never Error()'s prose: the human
	// sentence is free to reword without notice, the reason string is not.
	Reason string
	// Policy names the governance policy whose ceiling refused the request and
	// how to ask for a change (internal/api's errorBody.Policy), nil when the
	// refusal is not a ceiling refusal or the server sent none.
	Policy *PolicyRef
}

APIError is returned when the server responds with a non-2xx status code. Status is the HTTP status code; Body is the raw response body (trimmed to 2 KiB) for diagnostic display. Callers may use errors.As to extract it.

func NewAPIError added in v0.8.0 

func NewAPIError(status int, raw []byte) *APIError

NewAPIError builds an *APIError from a non-2xx status and its raw body, parsing the server's {"error", "reason"} envelope once so every call site — this package's own transport, and the CLI's own raw net/http calls that bypass it (WebSocket dial handshakes, an attach-ticket mint, a plain non-2xx read; #656 final review round L4) — need not repeat the parse and risk leaving Reason empty.

func (*APIError) Error 

func (e *APIError) Error() string

type APIToken added in v0.9.0 

type APIToken = types.APIToken

APIToken is one API token row. Token carries the plaintext on a create or claim answer only; Disposition says where an admin-minted token stands.

type AccessCredential added in v0.9.0 

type AccessCredential struct {
	ID          string `json:"id"`
	Row         string `json:"row"`
	Kind        string `json:"kind"`
	Owner       string `json:"owner"`
	Delivery    string `json:"delivery"`
	LifetimeSec int    `json:"lifetime_sec,omitempty"`
	Renewed     bool   `json:"renewed,omitempty"`
	AfterEnd    string `json:"after_end"`
}

AccessCredential is one credential the run is handed. Kind is model_provider, github_app, azure_arm, aws_role, secret, ado_signin, git_pat or ssh_key; Owner is own, shared or org_app; Delivery is proxy, git_broker, git_helper, sandbox_env, sandbox_file or sandbox_short_lived. LifetimeSec is a minted value's ceiling, 0 when the run's lifetime bounds it or Wardyn does not set it. AfterEnd is gone, expires or stays.

type AccessFacts added in v0.9.0 

type AccessFacts struct {
	// Rows are the things that bring access, inherited first (harness,
	// repositories, command), then the ones the person added.
	Rows []AccessRow `json:"rows"`
	// Hosts is the Network total: every destination a row or the policy brings.
	Hosts []AccessHost `json:"hosts"`
	// Credentials is the Credentials total.
	Credentials []AccessCredential `json:"credentials"`
	// Unlisted is what happens to a host nothing lists.
	Unlisted AccessUnlisted `json:"unlisted"`
	// Harnesses is the tool policy per included harness.
	Harnesses []ToolPolicyFact `json:"harnesses"`
	// Setup is what the person still has to do before launch.
	Setup []PreflightItem `json:"setup"`
}

AccessFacts is what a draft brings in, projected from what the dry-run doors decided: POST /runs/policy-preview and POST /runs/preflight answer it from one function, so the two cannot disagree about a request both of them admit. Every list is an array, never null.

type AccessHost added in v0.9.0 

type AccessHost struct {
	Host    string           `json:"host"`
	Via     string           `json:"via"`
	Rows    []string         `json:"rows"`
	Verdict string           `json:"verdict"`
	Reason  string           `json:"reason,omitempty"`
	Source  ProvenanceSource `json:"source"`
}

AccessHost is one destination as the policy spells it (a port is kept). Via is egress, git_broker, model_lane, mcp_broker or injected. Rows are the AccessRow ids that bring it, or "policy" when no row does. Verdict is allowed, needs_approval or not_allowed; Reason (not_allowed only) is clamped, denied_list, capability or always_deny.

type AccessMCP added in v0.9.0 

type AccessMCP struct {
	ServerKey string   `json:"server_key"`
	Transport string   `json:"transport"`
	Harnesses []string `json:"harnesses"`
}

AccessMCP is an MCP server row's binding: the server key in mcp__<server>__<tool>, its transport and the harnesses it is turned on for.

type AccessRow added in v0.9.0 

type AccessRow struct {
	ID          string           `json:"id"`
	Kind        string           `json:"kind"`
	From        string           `json:"from"`
	Name        string           `json:"name"`
	Status      string           `json:"status"`
	Reason      string           `json:"reason,omitempty"`
	Hosts       []string         `json:"hosts"`
	Credentials []string         `json:"credentials"`
	InImage     string           `json:"in_image,omitempty"`
	MCP         *AccessMCP       `json:"mcp,omitempty"`
	Source      ProvenanceSource `json:"source"`
}

AccessRow is one thing that brings access. Kind is harness, repository, command, secret, host or custom (drive, cli, mcp and api are reserved for the lanes that add them); From is the row's chip: harness, repository, command or added. Status is ready, needs_setup, unavailable or refused. Hosts and Credentials are keys into AccessFacts.Hosts and AccessFacts.Credentials.

type AccessUnlisted added in v0.9.0 

type AccessUnlisted struct {
	Mode     types.FirstUseMode `json:"mode"`
	AllowAll bool               `json:"allow_all"`
	HoldSec  int                `json:"hold_sec,omitempty"`
	Decider  string             `json:"decider"`
}

AccessUnlisted is the line for a host nothing lists: the effective first-use mode, whether allow-all makes it inert, the hold for wait_for_review, and who decides a request (you, admin or you_or_admin).

type ActorType 

type ActorType = types.ActorType

ActorType distinguishes who performed an audited action (AuditEvent.ActorType).

type AgentFact added in v0.9.0 

type AgentFact struct {
	Agent           string                  `json:"agent"`
	ModelProvider   *AgentModelProviderFact `json:"model_provider,omitempty"`
	Hosts           []AgentHostFact         `json:"hosts"`
	Secrets         []AgentSecretFact       `json:"secrets"`
	ManagedSettings *ManagedSettingsFact    `json:"managed_settings,omitempty"`
	Telemetry       *TelemetryFact          `json:"telemetry,omitempty"`
}

AgentFact is the agent component's fact (kind "agent"): the model provider it calls through, the destinations and secrets that lane carries, and the managed settings Wardyn writes for it.

type AgentHostFact added in v0.9.0 

type AgentHostFact struct {
	Host string `json:"host"`
	Role string `json:"role"`
}

AgentHostFact is a destination the agent reaches. Role is provider for the model provider's own lane and login for a sign-in host; the source chip comes from the response's provenance.

type AgentModelProviderFact added in v0.9.0 

type AgentModelProviderFact struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
}

AgentModelProviderFact is the model provider the agent calls through: its name and kind, never its id.

type AgentOverrides added in v0.9.0 

type AgentOverrides struct {
	// AddHosts are destinations to reach. Bare DNS names only: no wildcard, no
	// IP address, no port.
	AddHosts []string `json:"add_hosts,omitempty"`
	// RemoveHosts are destinations the source granted that this run drops.
	RemoveHosts []string `json:"remove_hosts,omitempty"`
	// AddSecrets are stored secrets of the caller's, injected as a request
	// header on a host. Request headers only.
	AddSecrets []SecretOverride `json:"add_secrets,omitempty"`
	// RemoveSecrets names secrets the source granted that this run drops.
	RemoveSecrets []string `json:"remove_secrets,omitempty"`
	// ToolRules are added tool rules. Hold and deny only: a rule that allows is
	// refused, and a rule is never removed.
	ToolRules []types.ToolRule `json:"tool_rules,omitempty"`
}

AgentOverrides are the edits on the agent component.

type AgentRun 

type AgentRun = types.AgentRun

AgentRun is one governed execution of a coding agent. Returned by CreateRun, GetRun, and ListRuns.

type AgentSecretFact added in v0.9.0 

type AgentSecretFact struct {
	// Kind is key, token, aws or subscription.
	Kind string `json:"kind"`
	// Owner is own or shared.
	Owner string `json:"owner"`
	// Residency is proxy, sandbox or resolved_at_launch.
	Residency string `json:"residency"`
	// LocalDelivery is the OD-12 mode for an organisation-held one.
	LocalDelivery placement.Mode `json:"local_delivery,omitempty"`
}

AgentSecretFact is the credential the agent's model calls carry.

type AllowedImage added in v0.9.0 

type AllowedImage struct {
	Ref  string `json:"ref"`
	Name string `json:"name,omitempty"`
}

AllowedImage is one image the organisation lets a person choose for a run (CreateRunRequest.AllowedImage). The list is empty until the image lane fills it.

type AppliedAmount added in v0.9.0 

type AppliedAmount struct {
	Requested  int         `json:"requested"` // the request's value, else its source policy's; 0 asks for the default
	Applied    int         `json:"applied"`   // what the sandbox gets
	Capped     bool        `json:"capped,omitempty"`
	Source     LimitSource `json:"source,omitempty"`
	SourceName string      `json:"source_name,omitempty"`
}

AppliedAmount is one field of AppliedResources. Source names the limit that cut an over-ask when Capped, else the one whose default an ask of 0 got; SourceName is the pool's name (pool) or the governance profile's name (governance), and empty for the deployment and the runner's capacity.

type AppliedResources added in v0.9.0 

type AppliedResources struct {
	CPUMillis AppliedAmount `json:"cpu_millis"`
	MemoryMiB AppliedAmount `json:"memory_mib"`
}

AppliedResources is what a run's CPU and memory asked for and what it gets, on preflight, the policy preview, the 201 and the run.create audit row.

type ApplyStep added in v0.9.0 

type ApplyStep struct {
	Kind        string                `json:"kind"`                   // "profile" | "assignment" | "drive" | "drive_grant"
	Op          string                `json:"op"`                     // "create" | "update" | "delete" | "upsert"
	Name        string                `json:"name,omitempty"`         // profile or drive name
	SubjectType CapabilitySubjectType `json:"subject_type,omitempty"` // assignment / drive_grant
	Subject     string                `json:"subject,omitempty"`
	Profile     string                `json:"profile,omitempty"` // an assignment's profile name; its id when no name is known
	ID          *uuid.UUID            `json:"id,omitempty"`      // the existing row an update or delete targets
	Fields      []string              `json:"fields,omitempty"`  // update: the JSON names of what changes
	Outcome     string                `json:"outcome,omitempty"` // results only: "applied" | "pending" | "failed"
	Error       string                `json:"error,omitempty"`   // with outcome "failed"
}

ApplyStep is one write a declarative apply would make (a plan) or made (an apply result).

type ApprovalKind 

type ApprovalKind = types.ApprovalKind

ApprovalKind enumerates what a human is being asked to approve (ApprovalRequest.Kind).

type ApprovalRequest 

type ApprovalRequest = types.ApprovalRequest

ApprovalRequest is a human-in-the-loop approval gate. Returned by ListApprovals, Approve, and Deny.

type ApprovalScope added in v0.5.0 

type ApprovalScope = types.ApprovalScope

ApprovalScope is how far an Approve/Deny decision reaches: once, run (the default), until, or always. Set via DecisionOpts on Approve/Deny; read back on ApprovalRequest.DecisionScope. Meaningful only for an egress_domain approval, EXCEPT "run" on a credential approval — that one is the per-run credential lease (a git_pat approved once is re-mintable for the rest of the run). A tool_call is bounded by the clamp and carries no scope.

type ApprovalState 

type ApprovalState = types.ApprovalState

ApprovalState is the approval lifecycle state; ListApprovals filters on it (ApprovalRequest.State).

type ArtifactOverride deprecated added in v0.4.4 

type ArtifactOverride = types.ArtifactOverride

ArtifactOverride is one ecosystem's artifact-registry redirect, carried in the deprecated SiteConfig.ArtifactOverrides.

Deprecated: superseded by EgressRedirect. Kept aliased so a caller that still builds the legacy shape (PutSiteConfig folds it server-side for one release) can name the element type; GetSiteConfig itself now returns this field empty.

type AuditEvent 

type AuditEvent = types.AuditEvent

AuditEvent is one append-only audit record. Returned by AuditEvents.

type AuditFilter added in v0.5.0 

type AuditFilter struct {
	Since        string // RFC3339, e.g. time.Now().UTC().Format(time.RFC3339)
	Until        string // RFC3339
	ActionPrefix string
	Actor        string // exact principal, e.g. "alice@corp.example" — "everything X did"
	ActorType    string // "human" | "agent" | "system"
	Outcome      string // "success" | "denied" | "failure"
}

AuditFilter narrows an audit query by the server's optional predicates — ?since=&until=&action_prefix=&actor_type=&outcome= (see docs/sdk.md's Raw HTTP section). The zero value applies no filter. Since/Until are RFC3339 strings; a malformed one is rejected by the server as a 400, same as the raw HTTP API — the client does not duplicate that validation.

type AutonomyLevel added in v0.8.0 

type AutonomyLevel = types.AutonomyLevel

AutonomyLevel is one rung on AutonomyRubric's ladder (see the AutonomyL0 .. AutonomyL3 values below).

type AutonomyRubric added in v0.8.0 

type AutonomyRubric = types.AutonomyRubric

AutonomyRubric is GovernanceLimits.AutonomyRubric's pointed-to type. Aliased for the same reason as ArtifactOverride: without a nameable type a caller could not author one at all.

type BarrierOption added in v0.9.0 

type BarrierOption = runnerpool.BarrierOption

BarrierOption is one barrier as a pool offers it to the caller (runnerpool.BarrierOptions).

type BaseImageEntry added in v0.5.0 

type BaseImageEntry = types.BaseImageEntry

BaseImageEntry is one tier-2 base-image catalog row: a shared, reusable image an operator saved (kind registry|custom|byo).

type BedrockSettings added in v0.8.0 

type BedrockSettings = types.BedrockSettings

Domain nouns returned or accepted by Client methods.

type CLIView added in v0.9.0 

type CLIView struct {
	Kind string `json:"kind"`
	// Azure: how many subscriptions, and read or write.
	Subscriptions int    `json:"subscriptions,omitempty"`
	Access        string `json:"access,omitempty"`
	// AWS: the pinned account, permission set and default region.
	AccountID string `json:"account_id,omitempty"`
	RoleName  string `json:"role_name,omitempty"`
	Region    string `json:"region,omitempty"`
	// GitHub: what the CLI may do.
	Capabilities []ghscope.Capability `json:"capabilities,omitempty"`
}

CLIView is the non-secret face of a CLI row: its kind and what it pins.

type CapabilitySubjectType added in v0.8.0 

type CapabilitySubjectType = types.CapabilitySubjectType

CapabilitySubjectType is the user/group/all vocabulary a drive grant's subject is drawn from (DriveGrantRequest.SubjectType, UserDriveGrant.SubjectType).

type CatalogueCLI added in v0.9.0 

type CatalogueCLI struct {
	Kind string `json:"kind"` // azure | github | aws | gcloud | kubectl
	// State is available (a granted row exists), not_granted, or coming_soon.
	State string `json:"state"`
	// Rows are the granted org rows of this kind, in the order Org lists them.
	Rows []uuid.UUID `json:"rows"`
}

CatalogueCLI is one of the five CLI cards of the catalogue.

type ClaimInvitationRequest added in v0.9.0 

type ClaimInvitationRequest struct {
	Name       string `json:"name"`
	TTLSeconds int64  `json:"ttl_seconds,omitempty"`
}

ClaimInvitationRequest is the POST /api/v1/me/invitations/{id}/claim body. An empty Name takes the invitation's token name, and a zero TTLSeconds its limit, else the deployment's rule. internal/api aliases it (claimInvitationRequest).

type Client 

type Client struct {
	// BaseURL is the wardynd root, e.g. "https://wardyn.example.com".
	// A trailing slash is stripped automatically.
	BaseURL string

	// Token is the admin bearer token configured in wardynd (AdminToken).
	Token string

	// HTTPClient, when non-nil, is used instead of the default client, and its
	// redirect policy is YOURS: the default returns a 3xx as an *APIError
	// rather than following it, but a client you supply is used as it is.
	// Following a redirect can replay a request body (a secret value) and the
	// Authorization bearer at wherever Location points, so a caller who sets
	// this should set a CheckRedirect func that returns http.ErrUseLastResponse.
	HTTPClient *http.Client

	// Principal, when non-empty, is sent as the X-Wardyn-Principal header — a
	// DEV-ONLY override for simulating different principals against a local
	// wardynd. The server honors it ONLY in local (no-auth) mode. Under
	// admin-token auth it is ignored and the action is attributed to
	// actor_type=system / principal "admin-token" (the token is an opaque shared
	// bearer, not a JWT — there is no subject to extract); under OIDC the
	// verified subject wins. Use OIDC for real per-human attribution.
	Principal string
}

Client is the Wardyn SDK client. Construct it with New or by filling the fields directly. BaseURL and Token are required; HTTPClient defaults to a client that never follows a redirect when nil.

All methods accept a context; the context controls cancellation and deadline for the underlying HTTP call.

func New 

func New(baseURL, token string) *Client

New returns a Client configured with baseURL and token.

func (*Client) AddMyPoolRemoteRunner added in v0.9.0 

func (c *Client) AddMyPoolRemoteRunner(ctx context.Context, poolID uuid.UUID, remoteRunnerID string) (RunnerPoolMember, error)

AddMyPoolRemoteRunner puts a remote-hosted runner into one of the caller's own user pools: one whose "Available to people's pools" policy admits the caller (ListMyRemoteRunners).

func (*Client) AddMyRunnerToPool added in v0.9.0 

func (c *Client) AddMyRunnerToPool(ctx context.Context, poolID, runnerID uuid.UUID) (RunnerPoolMember, error)

AddMyRunnerToPool puts the caller's own claimed self-hosted runner into one of their own user pools. Nobody adds a runner on another person's behalf.

func (*Client) AddRunnerPoolRemoteRunner added in v0.9.0 

func (c *Client) AddRunnerPoolRemoteRunner(ctx context.Context, poolID uuid.UUID, remoteRunnerID string) (RunnerPoolMember, error)

AddRunnerPoolRemoteRunner puts a remote-hosted runner this server is set up with into an organization pool (admin). It is held for a second human when another pool holds that runner under a use policy.

func (*Client) AddSSHKey added in v0.7.0 

func (c *Client) AddSSHKey(ctx context.Context, name, publicKey string) (types.SSHPublicKey, error)

AddSSHKey registers one authorized_keys line under the caller's own principal and returns the stored record (201). POST /api/v1/me/ssh-keys. Fails closed on the server: 422 for private-key material, more than one key, or an admin-token caller on an SSO deployment (such a key could never authorize a human's run); 409 when the fingerprint is already registered.

func (*Client) ApplyDrives added in v0.8.0 

func (c *Client) ApplyDrives(ctx context.Context, doc DrivesDocument) (DrivesDocument, error)

ApplyDrives is ApplyDrivesResult's document, with the same error on a failed write (and no document).

func (*Client) ApplyDrivesResult added in v0.9.0 

func (c *Client) ApplyDrivesResult(ctx context.Context, doc DrivesDocument) (DrivesApplyResult, error)

ApplyDrivesResult upserts every drive and grant doc names, over the existing POST /drives, PUT /drives/{id} and POST /drives/grants routes — there is no bulk-write route, and none is added. A drive is routed by the id doc carries: one already issued by GetDrives (non-nil) is REPLACED in place (PUT), a zero id is CREATED (POST) — which is what makes `wardyn drive get > f && wardyn drive set f` a no-op: the ids `get` wrote back are exactly what route the re-`set` to an update of the same rows, not a second copy under a fresh name. A grant carries no id of its own; every one is POSTed with Additional, so it upserts the one (subject_type, subject, drive_id) allocation it names and never replaces a subject's other drives.

Nothing doc omits is touched and nothing is deleted — neither POST nor PUT can express that, and this function does not attempt it by other means. Every write's saved row replaces the caller's copy in place, so a partial failure (returned as the second value) leaves doc's earlier entries holding what was actually persisted. On success, the returned document is a fresh GetDrives — the authoritative post-write state, including the derived fields (grant counts, deployment facts) a write response cannot carry. On a failed write the result holds the steps so far, the failed one included, alongside the error; ApplyDrives is this without the steps.

func (*Client) ApplyGovernance added in v0.8.0 

func (c *Client) ApplyGovernance(ctx context.Context, doc GovernanceDocument, prune bool) (GovernanceDocument, error)

ApplyGovernance upserts every profile and assignment doc names, over the existing POST /governance/profiles, PUT /governance/profiles/{id} and POST /governance/assignments routes — there is no bulk-write route, and none is added.

A PROFILE is routed BY NAME, not by id — the divergence from ApplyDrives, and the reason is Name's role server-side: it is the UNIQUE human handle an admin actually authors and assigns by (governance.go's own words), while a drive's id is what GetDrives/ApplyDrives round-trip on. Upserting by id would make a hand-maintained, version-controlled governance.json (written once, with no ids, and re-applied against the same install repeatedly) fail its second apply with a 409 name conflict — the exact "config lives in git next to the rest of the install" workflow #1108 exists for. So ApplyGovernance reads the CURRENT state first, and: a doc profile whose Name matches an existing one is PUT to that existing row's real id (rename is therefore not expressible through apply — Name IS the identity a file's entries are matched against); a Name with no existing match is POSTed fresh. Either way, a profile whose Ceiling and Limits are BYTE-IDENTICAL to what is already stored is skipped entirely (governanceProfileUnchanged) — the no-op contract's other half, since the server audits every profile write unconditionally.

An ASSIGNMENT carries no id on write (server-assigned, same as DriveGrantRequest), and is upserted purely by its own natural key (subject_type, subject) — skipped, the same way, when the existing row already names the same profile at the same priority. Its ProfileID is resolved against the SAME apply's own profile list before being sent: an id in doc.Assignments naming one of doc.Profiles's ORIGINAL (pre-write) ids is translated to that profile's real post-write id, so a document produced by GetGovernance against a POPULATED install reproduces both profiles and assignments when applied to an EMPTY one, even though the empty install mints entirely new profile ids. An assignment whose ProfileID names no profile in this same doc is sent exactly as given, trusting it as an already-real id on the target (the case for an assignments-only file, or one applied twice against the SAME install).

prune, when true, additionally DELETES every server-side profile or assignment doc does not name (assignments first, since a profile still referenced by a to-be-pruned assignment fails the FK restrict). Without it — the default — nothing present server-side but absent from doc is touched, matching drive set's own "nothing the file omits is touched" rule.

Every write's saved row replaces the caller's copy of doc in place, so a partial failure (returned as the second value) leaves doc's earlier entries holding what was actually persisted. On success, the returned document is a fresh GetGovernance — the authoritative post-write state.

When the deployment requires a second approver for governance writes, a write is held as a pending change instead of applied. ApplyGovernance then returns the fresh document and a *PendingApprovalError (check with errors.As) rather than reporting success: an assignment naming a profile whose write is pending is not sent, and prune does not run. Use ApplyGovernanceResult to read the pending and deferred lists as data.

func (*Client) ApplyGovernanceResult added in v0.8.6 

func (c *Client) ApplyGovernanceResult(ctx context.Context, doc GovernanceDocument, prune bool) (GovernanceApplyResult, error)

ApplyGovernanceResult is ApplyGovernance with the pending-approval outcome returned as data, not an error: a 202 pending change is an expected result under four-eyes, not a failure. See ApplyGovernance for the matching and ordering rules.

A profile or assignment write the server holds for approval is recorded in Pending. An assignment naming a profile with a pending write is recorded in Deferred and never sent (its profile id is not final). Prune runs only when no write in the apply is pending, and stops at the first pending delete; PruneSkipped says so.

func (*Client) ApplyPresets added in v0.8.0 

func (c *Client) ApplyPresets(ctx context.Context, doc PresetsDocument) (PresetsDocument, error)

ApplyPresets upserts every preset doc names, by name, over PUT /api/v1/presets/{name}, and returns a fresh ListPresets. Nothing doc omits is touched and nothing is deleted, and an unchanged preset keeps its version, so `wardyn preset get > f && wardyn preset set f` is a no-op.

func (*Client) Approve 

func (c *Client) Approve(ctx context.Context, id uuid.UUID, reason string, opts ...DecisionOpts) (types.ApprovalRequest, error)

Approve transitions an approval request to APPROVED. reason is optional; pass an empty string to omit it. opts is optional (pass at most one); omitting it keeps today's default — a run-scoped approval. See DecisionOpts for once/until/always. Returns 409/APIError when the approval has already been decided. Returns 404/APIError when the approval does not exist.

func (*Client) ApproveGovernanceChange added in v0.8.6 

func (c *Client) ApproveGovernanceChange(ctx context.Context, id uuid.UUID) (GovernanceChange, error)

ApproveGovernanceChange approves a pending change, which applies it. The caller must be a different human from the proposer; the server answers 409 when the change is no longer pending or has gone stale. POST /api/v1/governance/changes/{id}/approve.

func (*Client) AuditEvents 

func (c *Client) AuditEvents(ctx context.Context, runID uuid.UUID, opts ...ListOpts) ([]types.AuditEvent, error)

AuditEvents returns the append-only audit trail for the specified run in chronological (seq ASC) order, unfiltered. run_id is required by the server; a zero UUID is rejected with 400. Pass a ListOpts to page a long trail: a truncated page (server sets X-Wardyn-Truncated) is walked forward with Offset += len(page), which reaches the terminal run.complete event under ASC order — prefer AuditEventsPage, which returns that signal directly instead of requiring the caller to infer it.

func (*Client) AuditEventsPage added in v0.5.0 

func (c *Client) AuditEventsPage(ctx context.Context, runID uuid.UUID, filter AuditFilter, opts ...ListOpts) (events []types.AuditEvent, truncated bool, err error)

AuditEventsPage is AuditEvents plus the server's X-Wardyn-Truncated signal and the optional filter predicates (AuditFilter): truncated=true means this page did NOT reach the run's newest event (including run.complete, since the per-run trail is chronological/ASC) and the caller must page forward — Offset += len(events) — to see the rest. This is the fix for the audit-gap where a >1000-event run's newest events could silently drop with no way for a caller to even detect it: AuditEvents alone (below) cannot tell "this is everything" from "this is page 1 of more".

func (*Client) AuditRetention added in v0.8.6 

func (c *Client) AuditRetention(ctx context.Context) (types.AuditRetentionStatus, error)

AuditRetention reports the audit log's effective and pending retention policy, the cutover, every partition with its row count, state and whether a drop would take it now (and, if not, why), and how many months ahead already have a partition. Security tier only. GET /api/v1/audit/retention.

func (*Client) BuildWorkspace added in v0.9.0 

func (c *Client) BuildWorkspace(ctx context.Context, id uuid.UUID, refresh bool) (WorkspaceBuild, error)

BuildWorkspace starts the workspace's image build (202 while it runs, 200 when there is nothing to do); refresh rebuilds from fresh inputs even when an image is kept. POST /api/v1/workspaces/{id}/build.

func (*Client) ClaimInvitation added in v0.9.0 

func (c *Client) ClaimInvitation(ctx context.Context, id uuid.UUID, req ClaimInvitationRequest) (APIToken, error)

ClaimInvitation claims the caller's own invitation and returns the new token; Token holds the plaintext, which the server shows once. It needs the target's signed-in browser session, so a bearer token cannot claim: the CLI has no verb for it. POST /api/v1/me/invitations/{id}/claim.

func (*Client) ClaimRunner added in v0.9.0 

func (c *Client) ClaimRunner(ctx context.Context, id uuid.UUID, fingerprint string) (RunnerRegistration, error)

ClaimRunner confirms the locally observed fingerprint under the owner's personal session.

func (*Client) ClearMyRunnerPoolDefaults added in v0.9.0 

func (c *Client) ClearMyRunnerPoolDefaults(ctx context.Context) error

ClearMyRunnerPoolDefaults removes the caller's own default pool, so the organisation's applies again.

func (*Client) ClearRemoteRunnerPeoplePolicy added in v0.9.0 

func (c *Client) ClearRemoteRunnerPeoplePolicy(ctx context.Context, id string) error

ClearRemoteRunnerPeoplePolicy turns the people policy off: nobody may add the runner to a user pool (those already in one stop being offered to people at launch). Held like a set.

func (*Client) ClearRunnerPoolUsePolicy added in v0.9.0 

func (c *Client) ClearRunnerPoolUsePolicy(ctx context.Context, poolID uuid.UUID) error

ClearRunnerPoolUsePolicy removes the use policy, so everyone who may launch on organization pools may use the pool again. Held like a set.

func (*Client) CopyTemplate added in v0.9.0 

func (c *Client) CopyTemplate(ctx context.Context, id uuid.UUID, req TemplateCopyRequest) (Template, error)

CopyTemplate copies a template into another scope and returns the copy.

func (*Client) CreateInvitation added in v0.9.0 

func (c *Client) CreateInvitation(ctx context.Context, principal string, req CreateInvitationRequest) (Invitation, error)

CreateInvitation invites one known person to mint their own API token (security tier). The answer is metadata and holds no secret: only the target, signed in, can claim it. POST /api/v1/people/{principal}/invitations.

func (*Client) CreateMyDrive added in v0.9.0 

func (c *Client) CreateMyDrive(ctx context.Context, name string) (MeDrive, error)

CreateMyDrive creates the caller's own drive (POST /api/v1/me/drives).

func (*Client) CreateMyRunnerPool added in v0.9.0 

func (c *Client) CreateMyRunnerPool(ctx context.Context, req CreateMyRunnerPoolRequest) (RunnerPool, error)

CreateMyRunnerPool creates a user pool of the caller's own.

func (*Client) CreatePolicy 

func (c *Client) CreatePolicy(ctx context.Context, req PolicyRequest) (types.RunPolicy, error)

CreatePolicy validates and persists a new policy. Returns the created RunPolicy (status 201) on success; 400 on an invalid name or spec.

func (*Client) CreateRun 

func (c *Client) CreateRun(ctx context.Context, req CreateRunRequest) (CreateRunResult, error)

CreateRun submits a new agent run and answers once the run row exists (state PENDING, never RUNNING) plus any advisory warnings; build and dispatch continue server-side. Status 201 on success; 400 on validation failure; 422 on policy/confinement mismatch; 503 when the runner is unavailable.

func (*Client) CreateRunnerPool added in v0.9.0 

func (c *Client) CreateRunnerPool(ctx context.Context, req CreateRunnerPoolRequest) (RunnerPool, error)

CreateRunnerPool adds an organization pool to the catalogue (admin).

func (*Client) CreateServiceIdentity added in v0.9.0 

func (c *Client) CreateServiceIdentity(ctx context.Context, req CreateServiceIdentityRequest) (ServiceIdentity, error)

CreateServiceIdentity creates a named, sponsored non-human principal (security tier). With the second-human governance rule on, the create is held and the call returns a PendingApprovalError. POST /api/v1/service-identities.

func (*Client) CreateSource added in v0.5.0 

func (c *Client) CreateSource(ctx context.Context, req SourceRequest) (types.Source, error)

CreateSource upserts a library source by canonical identity (201 new, 200 existing row). POST /api/v1/sources.

func (*Client) CreateWorkspace added in v0.3.1 

func (c *Client) CreateWorkspace(ctx context.Context, req WorkspaceRequest) (types.Workspace, error)

CreateWorkspace onboards a new workspace (status pending_scan). Returns the created row (201); 400 on an invalid body/source.

func (*Client) DeleteComponent added in v0.8.9 

func (c *Client) DeleteComponent(ctx context.Context, id uuid.UUID) error

DeleteComponent removes an organisation component. Its restriction stays, so the id is never open to anyone, and runs launched with it keep their record. Admin only. DELETE /api/v1/components/{id}.

func (*Client) DeleteMemberDrive added in v0.9.0 

func (c *Client) DeleteMemberDrive(ctx context.Context, id uuid.UUID) (MemberDriveDeleteResult, error)

DeleteMemberDrive deletes one person's drive and its files (DELETE /api/v1/drives/member/{id}, super admin).

func (*Client) DeleteMyComponent added in v0.8.9 

func (c *Client) DeleteMyComponent(ctx context.Context, id uuid.UUID) error

DeleteMyComponent removes one of the caller's saved components. Runs already launched with it keep their record. 404 for an id that is not theirs. DELETE /api/v1/me/components/{id}.

func (*Client) DeleteMyDrive added in v0.9.0 

func (c *Client) DeleteMyDrive(ctx context.Context, id uuid.UUID) error

DeleteMyDrive deletes the caller's own drive and its files (DELETE /api/v1/me/drives/{id}).

func (*Client) DeleteMyRunnerPool added in v0.9.0 

func (c *Client) DeleteMyRunnerPool(ctx context.Context, id uuid.UUID) error

DeleteMyRunnerPool tombstones one of the caller's own user pools.

func (*Client) DeleteMySecret added in v0.9.0 

func (c *Client) DeleteMySecret(ctx context.Context, name string) error

DeleteMySecret removes the caller's own secret. DELETE /api/v1/me/secrets/{name}.

func (*Client) DeletePolicy 

func (c *Client) DeletePolicy(ctx context.Context, id uuid.UUID) error

DeletePolicy removes a policy by id. Returns nil on success (204); 404/APIError when the policy does not exist.

func (*Client) DeletePreset added in v0.8.0 

func (c *Client) DeletePreset(ctx context.Context, name string) error

DeletePreset removes a preset by name. Admin only.

func (*Client) DeleteRunnerPool added in v0.9.0 

func (c *Client) DeleteRunnerPool(ctx context.Context, id uuid.UUID) error

DeleteRunnerPool tombstones an organization pool (admin). Runs bound to it keep their history.

func (*Client) DeleteSSHKey added in v0.8.0 

func (c *Client) DeleteSSHKey(ctx context.Context, fp string) error

DeleteSSHKey removes one of the caller's own registered SSH gateway keys. fp is ssh.FingerprintSHA256's raw form, which routinely contains '/' — it is percent-encoded here, matching the server's decode (handleDeleteSSHKey). Deleting a fingerprint registered by someone else (or one that never existed) 404s the same way — no existence leak across principals. DELETE /api/v1/me/ssh-keys/{fingerprint}.

func (*Client) DeleteSecret 

func (c *Client) DeleteSecret(ctx context.Context, name string) error

DeleteSecret removes a named secret. DELETE /api/v1/secrets/{name}. Returns 403 for a reserved platform-internal name.

func (*Client) DeleteSharedSecret added in v0.9.0 

func (c *Client) DeleteSharedSecret(ctx context.Context, name string) error

DeleteSharedSecret removes a shared service secret. DELETE /api/v1/shared-secrets/{name}.

func (*Client) DeleteSource added in v0.5.0 

func (c *Client) DeleteSource(ctx context.Context, id uuid.UUID, force bool) (detachedFrom []string, err error)

DeleteSource removes a library source. In use → 409 APIError naming the attaching workspaces; force detaches them first — those workspaces just stop mounting this source, and their next runs succeed without it (there is no loud failure at run time: the mount gate has nothing to check for a source that used to be there). detachedFrom names whichever workspaces the delete actually detached (empty when the source wasn't attached to any), the only visibility into what changed. DELETE /api/v1/sources/{id}[?force=1].

func (*Client) DeleteTemplate added in v0.9.0 

func (c *Client) DeleteTemplate(ctx context.Context, id uuid.UUID) error

DeleteTemplate removes a template the caller may write.

func (*Client) DeleteWorkspace added in v0.3.1 

func (c *Client) DeleteWorkspace(ctx context.Context, id uuid.UUID) error

DeleteWorkspace removes a workspace by id. Returns nil (204); 404 when unknown.

func (*Client) Deny 

func (c *Client) Deny(ctx context.Context, id uuid.UUID, reason string, opts ...DecisionOpts) (types.ApprovalRequest, error)

Deny transitions an approval request to DENIED (fail closed). reason is optional; pass an empty string to omit it. opts is optional (pass at most one); omitting it keeps today's default — a run-scoped denial. See DecisionOpts for once/until/always. Returns 409/APIError when the approval has already been decided. Returns 404/APIError when the approval does not exist.

func (*Client) DropAuditPartition added in v0.8.6 

func (c *Client) DropAuditPartition(ctx context.Context, partition, digest string) (types.AuditRetentionDrop, error)

DropAuditPartition drops the oldest closed audit partition past the retention window, through the database function that checks digest (the one ExportAuditPartition's footer carries, which the operator has verified), records a chained audit.retention.partition_dropped event and an anchor, and only then drops. A refusal is a 409 APIError whose Reason is one of audit_retention_not_oldest, audit_retention_not_closed, audit_retention_inside_window, audit_retention_live_run or audit_retention_digest_mismatch; an unknown partition is 404. Security tier only. POST /api/v1/audit/retention/drop.

func (*Client) ErasePerson added in v0.8.6 

func (c *Client) ErasePerson(ctx context.Context, principal string, scopes []string) (ErasePersonResult, error)

ErasePerson erases one person's retained records by scope (mask_copies, run_outputs, recordings, run_tasks, components, audit_personal_fields, credentials) in one audited act. principal is the person's subject (or an email the deployment knows them by) and is percent-encoded here. A scope that fails part way is a 500 whose reason is erasure_incomplete: retry with the same scopes. Security tier. POST /api/v1/people/{principal}/erasure.

func (*Client) ExportAuditPartition added in v0.8.6 

func (c *Client) ExportAuditPartition(ctx context.Context, partition string, raw bool) (io.ReadCloser, error)

ExportAuditPartition streams one closed audit partition as NDJSON: a manifest line, one line per row in seq order, and a footer line carrying the partition's digest. raw selects the stored, hash-covered form an operator can re-hash independently; otherwise the readable form. The caller MUST Close the returned reader, and must treat a body that ends without the footer line as an incomplete export. Security tier only: any other caller gets an empty body. GET /api/v1/audit/export?partition=<name>[&form=raw]. Returns 404/409 APIErrors for an unknown or still-open partition.

func (*Client) GetDefaultPolicy added in v0.6.0 

func (c *Client) GetDefaultPolicy(ctx context.Context) (types.RunPolicySpec, error)

GetDefaultPolicy fetches the control plane's configured default policy spec — the ceiling every run created without a policy_id gets, and the ceiling composer.Clamp bounds a member-authored inline policy against (W14-S1-6: previously unexposed by UI, CLI or API).

func (*Client) GetDrives added in v0.8.0 

func (c *Client) GetDrives(ctx context.Context) (DrivesDocument, error)

GetDrives returns every registered drive and EVERY allocation. GET /api/v1/drives serves allocations one page at a time (X-Wardyn-Truncated), so this reads ?offset= until the flag clears, and then refuses a result whose allocation count is not the server's grant_total: a document that silently dropped allocations would, fed back to ApplyDrives, restore a partial set.

func (*Client) GetGovernance added in v0.8.0 

func (c *Client) GetGovernance(ctx context.Context) (GovernanceDocument, error)

GetGovernance returns every governance profile and assignment. GET /api/v1/governance.

func (*Client) GetGovernanceChange added in v0.8.6 

func (c *Client) GetGovernanceChange(ctx context.Context, id uuid.UUID) (GovernanceChange, error)

GetGovernanceChange returns one governance change with its diff. GET /api/v1/governance/changes/{id}.

func (*Client) GetModelProviders added in v0.9.0 

func (c *Client) GetModelProviders(ctx context.Context) (ModelProvidersRead, error)

GetModelProviders returns the org's model-provider records with, per provider id, how many people hold a credential of their own for it. Admin only. Counts and configuration, never a credential value; the writes and the per-provider sign-in and credential doors stay unwrapped (the console owns them). GET /api/v1/model-providers.

func (*Client) GetMyRunner added in v0.9.0 

func (c *Client) GetMyRunner(ctx context.Context, id uuid.UUID) (RunnerView, error)

GetMyRunner reads one of the caller's own runners; another person's answers as an absent id.

func (*Client) GetMyRunnerPoolDefaults added in v0.9.0 

func (c *Client) GetMyRunnerPoolDefaults(ctx context.Context) (RunnerPoolDefaults, error)

GetMyRunnerPoolDefaults reads the caller's own default pool; with none, a run that names no pool uses the organisation's.

func (*Client) GetOrgRunnerPoolDefaults added in v0.9.0 

func (c *Client) GetOrgRunnerPoolDefaults(ctx context.Context) (RunnerPoolDefaults, error)

GetOrgRunnerPoolDefaults reads the organisation's default pool and barrier.

func (*Client) GetPolicy 

func (c *Client) GetPolicy(ctx context.Context, id uuid.UUID) (types.RunPolicy, error)

GetPolicy fetches a single RunPolicy by its UUID. Returns 404/APIError when the policy does not exist.

func (*Client) GetPreset added in v0.8.0 

func (c *Client) GetPreset(ctx context.Context, name string) (Preset, error)

GetPreset returns one preset by name (404 when unknown, or not open to the caller's user type).

func (*Client) GetRecording added in v0.4.4 

func (c *Client) GetRecording(ctx context.Context, runID uuid.UUID, session ...string) (io.ReadCloser, error)

GetRecording streams a run's terminal recording as raw asciicast bytes (the .cast a player consumes). The caller MUST Close the returned reader. GET /api/v1/runs/{id}/recording/{key} — the id really does appear twice: the route is mounted per-run and its handler takes the recording's own CAST KEY, which defaults to the bare run id (a batch run's single recording) when session is omitted — existing zero-arg callers are unaffected. An INTERACTIVE run can carry multiple recordings, one per attach session, each keyed "<runID>~<session>" (castKey above, mirroring internal/recording's own doc comment); pass that session id as the optional session argument to fetch one of those instead of the run's own bare-id cast. At most one value is meaningful; variadic only to keep it optional without a second method name. Returns 404/APIError when the run/session has no recording.

func (*Client) GetRemoteRunner added in v0.9.0 

func (c *Client) GetRemoteRunner(ctx context.Context, id string) (RemoteRunnerView, error)

GetRemoteRunner reads one remote-hosted runner (admin or security admin).

func (*Client) GetRun 

func (c *Client) GetRun(ctx context.Context, id uuid.UUID) (types.AgentRun, error)

GetRun fetches a single AgentRun by its UUID. Returns 404/APIError when the run does not exist.

func (*Client) GetRunPolicy added in v0.8.2 

func (c *Client) GetRunPolicy(ctx context.Context, runID uuid.UUID) (RunPolicyView, error)

GetRunPolicy returns the policy a run got (owner-or-admin; a run the caller cannot read is a 404). GET /api/v1/runs/{id}/policy.

func (*Client) GetRunner added in v0.9.0 

func (c *Client) GetRunner(ctx context.Context, id uuid.UUID) (RunnerView, error)

GetRunner reads one runner, revoked included (admin or security_admin).

func (*Client) GetRunnerPool added in v0.9.0 

func (c *Client) GetRunnerPool(ctx context.Context, id uuid.UUID) (RunnerPool, error)

GetRunnerPool reads one pool the caller may use; a pool they may not use is a 404.

func (*Client) GetRunnerPoolUsePolicy added in v0.9.0 

func (c *Client) GetRunnerPoolUsePolicy(ctx context.Context, poolID uuid.UUID) (RunnerPoolUsePolicy, error)

GetRunnerPoolUsePolicy reads an organization pool's use policy (admin or security admin). A pool with no policy answers with no subjects and a zero UpdatedAt; Revision is the pool's current revision, the one a set names. A user pool has none and is refused.

func (*Client) GetRunnerSettings added in v0.9.0 

func (c *Client) GetRunnerSettings(ctx context.Context) (RunnerSettings, error)

GetRunnerSettings reads whether runners are on (admin or security_admin).

func (*Client) GetServiceIdentity added in v0.9.0 

func (c *Client) GetServiceIdentity(ctx context.Context, name string) (ServiceIdentity, error)

GetServiceIdentity reads one service identity (security tier). GET /api/v1/service-identities/{name}.

func (*Client) GetSiteConfig added in v0.3.1 

func (c *Client) GetSiteConfig(ctx context.Context) (types.SiteConfig, error)

GetSiteConfig returns the operator-wide site config. GET /api/v1/site-config.

func (*Client) GetSource added in v0.5.0 

func (c *Client) GetSource(ctx context.Context, id uuid.UUID) (types.Source, error)

GetSource fetches one library source. GET /api/v1/sources/{id}.

func (*Client) GetTemplate added in v0.9.0 

func (c *Client) GetTemplate(ctx context.Context, id uuid.UUID, revision int) (Template, error)

GetTemplate returns one template by id: revision 0 is the current one.

func (*Client) GetWorkspace added in v0.3.1 

func (c *Client) GetWorkspace(ctx context.Context, id uuid.UUID) (types.Workspace, error)

GetWorkspace fetches a single workspace by id. Returns 404/APIError when unknown.

func (*Client) GetWorkspaceBuild added in v0.9.0 

func (c *Client) GetWorkspaceBuild(ctx context.Context, id uuid.UUID) (WorkspaceBuild, error)

GetWorkspaceBuild reads a workspace's image-build state. GET /api/v1/workspaces/{id}/build.

func (*Client) GrantTemplateGroupAdmin added in v0.9.0 

func (c *Client) GrantTemplateGroupAdmin(ctx context.Context, grant TemplateGroupAdmin) (TemplateGroupAdmin, error)

GrantTemplateGroupAdmin lets one person manage one group's templates. Admin only; the grant reaches nothing else.

func (*Client) Healthz added in v0.3.1 

func (c *Client) Healthz(ctx context.Context) (json.RawMessage, error)

Healthz returns the control-plane health payload as raw JSON. GET /healthz (note: NOT under /api/v1, and unauthenticated).

func (*Client) ImportTemplate added in v0.9.0 

func (c *Client) ImportTemplate(ctx context.Context, req TemplateImportRequest) (TemplateImportResult, error)

ImportTemplate asks the server to read an import document. It stores nothing.

func (*Client) KillRun 

func (c *Client) KillRun(ctx context.Context, id uuid.UUID) (KillRunResponse, error)

KillRun initiates the kill sequence for a run: durable state transition (compare-and-swap to KILLED) first, then sandbox teardown, identity revocation, and credential revocation. Returns 202/Accepted with the final state on success. Returns 404/APIError when the run does not exist.

func (*Client) ListApprovals 

func (c *Client) ListApprovals(ctx context.Context, state types.ApprovalState, runID uuid.UUID, opts ...ListOpts) ([]types.ApprovalRequest, error)

ListApprovals returns approval requests filtered by state and (optionally) by run. Pass an empty state to return all states, and uuid.Nil for runID to return approvals for every run — the server's own ?run_id= filter (internal/api/approvals.go's handleListApprovals) was otherwise unreachable from the CLI. Valid states: "PENDING", "APPROVED", "DENIED", "EXPIRED", "CANCELLED" (types.ApprovalState). Prefer ListApprovalsPage, which also returns the server's truncation signal.

func (*Client) ListApprovalsPage added in v0.7.0 

func (c *Client) ListApprovalsPage(ctx context.Context, state types.ApprovalState, runID uuid.UUID, opts ...ListOpts) (aps []types.ApprovalRequest, truncated bool, err error)

ListApprovalsPage is ListApprovals plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists. It matters most on this family — an approval queue read as complete when it is not is a pending decision nobody sees.

func (*Client) ListComponents added in v0.8.9 

func (c *Client) ListComponents(ctx context.Context) ([]Component, error)

ListComponents lists the organisation's components, whole. Admin only. GET /api/v1/components.

func (*Client) ListDeviceEnrolmentTokens added in v0.8.0 

func (c *Client) ListDeviceEnrolmentTokens(ctx context.Context) ([]DeviceEnrolmentToken, error)

ListDeviceEnrolmentTokens returns every enrolment token still redeemable — minted, not yet redeemed, revoked or expired — newest first, never the token itself (admin or security_admin). GET /api/v1/admin/devices/enrolment-tokens.

func (*Client) ListDevices added in v0.8.0 

func (c *Client) ListDevices(ctx context.Context) ([]Device, error)

ListDevices returns every enrolled device, revoked ones included, newest first (admin or security_admin). GET /api/v1/admin/devices.

func (*Client) ListGovernanceChanges added in v0.8.6 

func (c *Client) ListGovernanceChanges(ctx context.Context, state string) ([]GovernanceChange, error)

ListGovernanceChanges lists governance changes held for, or decided by, a second approver. state narrows the list (pending, applied, rejected, expired or stale); "" leaves it to the server's default. GET /api/v1/governance/changes.

func (*Client) ListGrants 

func (c *Client) ListGrants(ctx context.Context, runID uuid.UUID, opts ...ListOpts) ([]types.CredentialGrant, error)

ListGrants returns the credential-grant eligibility records for a run. These are eligibility records (what the run MAY request), not issued credentials — some may never be minted. Pass a ListOpts to page; prefer ListGrantsPage, which also returns the server's truncation signal. Returns 404/APIError when the run does not exist.

func (*Client) ListGrantsPage added in v0.8.0 

func (c *Client) ListGrantsPage(ctx context.Context, runID uuid.UUID, opts ...ListOpts) (grants []types.CredentialGrant, truncated bool, err error)

ListGrantsPage is ListGrants plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists and this one is not the whole list. See the package doc's "# Pagination". Returns 404/APIError when the run does not exist.

func (*Client) ListInvitations added in v0.9.0 

func (c *Client) ListInvitations(ctx context.Context, state InvitationState, opts ...ListOpts) ([]Invitation, error)

ListInvitations lists every person's invitations, newest first (security tier). state is "pending", "claimed", "expired" or "revoked"; empty keeps all. GET /api/v1/invitations.

func (*Client) ListMemberDrives added in v0.9.0 

func (c *Client) ListMemberDrives(ctx context.Context, opts ListOpts) (MemberDriveList, error)

ListMemberDrives returns one page of every person's drives (GET /api/v1/drives/member, super admin).

func (*Client) ListMyInvitations added in v0.9.0 

func (c *Client) ListMyInvitations(ctx context.Context, opts ...ListOpts) ([]Invitation, error)

ListMyInvitations lists the caller's own pending invitations (a signed-in person). GET /api/v1/me/invitations.

func (*Client) ListMyRemoteRunners added in v0.9.0 

func (c *Client) ListMyRemoteRunners(ctx context.Context) ([]RemoteRunnerView, error)

ListMyRemoteRunners lists the remote-hosted runners the caller may add to their own user pools.

func (*Client) ListMyRunners added in v0.9.0 

func (c *Client) ListMyRunners(ctx context.Context) ([]RunnerView, error)

ListMyRunners lists the caller's own runners; an unclaimed one's fingerprint is abbreviated.

func (*Client) ListMySecrets added in v0.9.0 

func (c *Client) ListMySecrets(ctx context.Context, opts ...ListOpts) ([]string, error)

ListMySecrets is ListMySecretsPage without the truncation signal.

func (*Client) ListMySecretsPage added in v0.9.0 

func (c *Client) ListMySecretsPage(ctx context.Context, opts ...ListOpts) (names []string, truncated bool, err error)

ListMySecretsPage lists the names in the caller's OWN namespace, whatever their role (never values; reserved platform keys excluded): GET /api/v1/me/secrets, which responds {"names":[...]}. truncated=true means a further page exists. It needs a signed-in person (403 secret_personal_needs_person for the admin token).

func (*Client) ListMyServiceIdentities added in v0.9.0 

func (c *Client) ListMyServiceIdentities(ctx context.Context, opts ...ListOpts) ([]ServiceIdentity, error)

ListMyServiceIdentities lists the identities the caller sponsors (a signed-in person). GET /api/v1/me/service-identities.

func (*Client) ListPeople added in v0.8.6 

func (c *Client) ListPeople(ctx context.Context, opts ...PeopleListOpts) (PersonList, error)

ListPeople returns one page of the people this deployment knows: everyone who has signed in and everyone pre-created, each with their role, sign-in state and the counts behind the leaver actions (admin or security_admin). Pass a page's NextCursor back as PeopleListOpts.Cursor until it is empty. GET /api/v1/people.

func (*Client) ListPersonInvitations added in v0.9.0 

func (c *Client) ListPersonInvitations(ctx context.Context, principal string, state InvitationState, opts ...ListOpts) ([]Invitation, error)

ListPersonInvitations lists one person's invitations (security tier). GET /api/v1/people/{principal}/invitations.

func (*Client) ListPersonInvitationsPage added in v0.9.0 

func (c *Client) ListPersonInvitationsPage(ctx context.Context, principal string, state InvitationState, opts ...ListOpts) (invitations []Invitation, truncated bool, err error)

ListPersonInvitationsPage is ListPersonInvitations plus the server's X-Wardyn-Truncated signal.

func (*Client) ListPolicies 

func (c *Client) ListPolicies(ctx context.Context, opts ...ListOpts) ([]types.RunPolicy, error)

ListPolicies returns run policies in reverse creation order. Pass a ListOpts to page. Prefer ListPoliciesPage, which also returns the server's truncation signal.

func (*Client) ListPoliciesPage added in v0.7.0 

func (c *Client) ListPoliciesPage(ctx context.Context, opts ...ListOpts) (policies []types.RunPolicy, truncated bool, err error)

ListPoliciesPage is ListPolicies plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists.

func (*Client) ListPresets added in v0.8.0 

func (c *Client) ListPresets(ctx context.Context) (PresetsDocument, error)

ListPresets returns every preset the caller may launch: all of them for an admin, and for anyone else the ones open to their user type.

func (*Client) ListRemoteRunners added in v0.9.0 

func (c *Client) ListRemoteRunners(ctx context.Context) ([]RemoteRunnerView, error)

ListRemoteRunners lists every remote-hosted runner (admin or security admin).

func (*Client) ListRunnerPoolMembers added in v0.9.0 

func (c *Client) ListRunnerPoolMembers(ctx context.Context, poolID uuid.UUID) ([]RunnerPoolMemberView, error)

ListRunnerPoolMembers lists a pool's runners, both kinds, to whoever may read the pool: a user pool's owner, anyone who may use an organization pool, and an administrator or security admin (any pool). Another person's user pool is the unknown-id 404.

func (*Client) ListRunnerPools added in v0.9.0 

func (c *Client) ListRunnerPools(ctx context.Context) (RunnerPoolList, error)

ListRunnerPools lists the pools the caller may use, judged for every run type each takes.

func (*Client) ListRunnerPoolsFor added in v0.9.0 

func (c *Client) ListRunnerPoolsFor(ctx context.Context, runType RunnerPoolRunType) (RunnerPoolList, error)

ListRunnerPoolsFor lists the pools judged for one run type: a pool that refuses it is unavailable with runner_pool_run_type_not_allowed, and each pool's limits hold only that type. "" is every type; a value other than background or interactive is a 400 runner_pool_invalid.

func (*Client) ListRunnerTokens added in v0.9.0 

func (c *Client) ListRunnerTokens(ctx context.Context, owner string, opts ...ListOpts) ([]RunnerRegistrationToken, error)

ListRunnerTokens lists the unused registration tokens (admin or security_admin), newest first, for one owner or with owner "" for everyone's. No token value is returned.

func (*Client) ListRunnerTokensPage added in v0.9.0 

func (c *Client) ListRunnerTokensPage(ctx context.Context, owner string, opts ...ListOpts) (tokens []RunnerRegistrationToken, truncated bool, err error)

ListRunnerTokensPage is ListRunnerTokens plus the server's X-Wardyn-Truncated signal.

func (*Client) ListRunners added in v0.9.0 

func (c *Client) ListRunners(ctx context.Context, state RunnerFilter, opts ...ListOpts) ([]RunnerView, error)

ListRunners lists every person's runners (admin or security_admin), newest first. state is RunnerFilterActive, RunnerFilterRevoked or RunnerFilterAll; empty is active. The window is the server's default page; ListRunnersPage says whether more exist.

func (*Client) ListRunnersPage added in v0.9.0 

func (c *Client) ListRunnersPage(ctx context.Context, state RunnerFilter, opts ...ListOpts) (rows []RunnerView, truncated bool, err error)

ListRunnersPage is ListRunners plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists.

func (*Client) ListRuns 

func (c *Client) ListRuns(ctx context.Context, opts ...ListOpts) ([]types.AgentRun, error)

ListRuns returns runs in reverse creation order. Pass a ListOpts to page. Prefer ListRunsPage, which also returns the server's truncation signal — this form cannot tell "this is everything" from "this is page 1 of more".

func (*Client) ListRunsPage added in v0.7.0 

func (c *Client) ListRunsPage(ctx context.Context, opts ...ListOpts) (runs []types.AgentRun, truncated bool, err error)

ListRunsPage is ListRuns plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists and this one is not the whole list. See the package doc's "# Pagination" for why every list family answers this and not just the audit trail.

func (*Client) ListSSHKeys added in v0.7.0 

func (c *Client) ListSSHKeys(ctx context.Context, opts ...ListOpts) ([]types.SSHPublicKey, error)

ListSSHKeys returns the caller's own registered SSH gateway keys — the gateway's entire trust root (docs/SSH.md §1). There is no admin view of another principal's keys. Pass a ListOpts to page; prefer ListSSHKeysPage, which also returns the server's truncation signal. GET /api/v1/me/ssh-keys.

func (*Client) ListSSHKeysPage added in v0.8.0 

func (c *Client) ListSSHKeysPage(ctx context.Context, opts ...ListOpts) (keys []types.SSHPublicKey, truncated bool, err error)

ListSSHKeysPage is ListSSHKeys plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists and this one is not the whole list. See client.go's package doc's "# Pagination".

func (*Client) ListSecrets 

func (c *Client) ListSecrets(ctx context.Context, opts ...ListOpts) ([]string, error)

ListSecrets returns the managed secret NAMES (never values). Reserved platform-internal keys are excluded server-side. Pass a ListOpts to page; prefer ListSecretsPage, which also returns the server's truncation signal. GET /api/v1/secrets, which responds {"names":[...]}.

func (*Client) ListSecretsPage added in v0.8.0 

func (c *Client) ListSecretsPage(ctx context.Context, opts ...ListOpts) (names []string, truncated bool, err error)

ListSecretsPage is ListSecrets plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists and this one is not the whole list. See the package doc's "# Pagination". GET /api/v1/secrets, which responds {"names":[...],"mine":[...]} — this method surfaces only names, same as ListSecrets.

func (*Client) ListSecretsScoped added in v0.8.0 

func (c *Client) ListSecretsScoped(ctx context.Context, opts ...ListOpts) (names, mine []string, err error)

ListSecretsScoped is ListSecretsScopedPage without the truncation signal.

func (*Client) ListSecretsScopedPage added in v0.8.0 

func (c *Client) ListSecretsScopedPage(ctx context.Context, opts ...ListOpts) (names, mine []string, truncated bool, err error)

ListSecretsScopedPage is ListSecretsPage plus the server's `mine` (the caller's own namespace): for an operator the two are identical; for a member `names` narrows to the operator-owned names an eligible grant pairs with, while `mine` is always the caller's own rows. GET /api/v1/secrets, which responds {"names":[...],"mine":[...]}.

func (*Client) ListServiceIdentities added in v0.9.0 

func (c *Client) ListServiceIdentities(ctx context.Context, opts ...ListOpts) ([]ServiceIdentity, error)

ListServiceIdentities lists every service identity with its derived state (security tier). GET /api/v1/service-identities.

func (*Client) ListServiceIdentitiesPage added in v0.9.0 

func (c *Client) ListServiceIdentitiesPage(ctx context.Context, opts ...ListOpts) (identities []ServiceIdentity, truncated bool, err error)

ListServiceIdentitiesPage is ListServiceIdentities plus the server's X-Wardyn-Truncated signal.

func (*Client) ListServiceTokens added in v0.9.0 

func (c *Client) ListServiceTokens(ctx context.Context, name string, opts ...ListOpts) ([]APIToken, error)

ListServiceTokens lists the tokens of an identity the caller sponsors; no row carries the plaintext. GET /api/v1/me/service-identities/{name}/tokens.

func (*Client) ListServiceTokensPage added in v0.9.0 

func (c *Client) ListServiceTokensPage(ctx context.Context, name string, opts ...ListOpts) (tokens []APIToken, truncated bool, err error)

ListServiceTokensPage is ListServiceTokens plus the server's X-Wardyn-Truncated signal.

func (*Client) ListSharedSecrets added in v0.9.0 

func (c *Client) ListSharedSecrets(ctx context.Context, opts ...ListOpts) ([]string, error)

ListSharedSecrets is ListSharedSecretsPage without the truncation signal.

func (*Client) ListSharedSecretsPage added in v0.9.0 

func (c *Client) ListSharedSecretsPage(ctx context.Context, opts ...ListOpts) (names []string, truncated bool, err error)

ListSharedSecretsPage lists the names of the shared service secrets (never values; reserved platform keys excluded): GET /api/v1/shared-secrets, which responds {"names":[...]}. Operator tier only (403 otherwise). truncated=true means a further page exists.

func (*Client) ListSources added in v0.5.0 

func (c *Client) ListSources(ctx context.Context) ([]types.Source, error)

ListSources returns the whole library. GET /api/v1/sources.

func (*Client) ListTemplateGroupAdmins added in v0.9.0 

func (c *Client) ListTemplateGroupAdmins(ctx context.Context) (TemplateGroupAdmins, error)

ListTemplateGroupAdmins returns every template-management grant. Admin only.

func (*Client) ListTemplates added in v0.9.0 

func (c *Client) ListTemplates(ctx context.Context) (TemplateList, error)

ListTemplates returns the templates the caller may use.

func (*Client) ListWorkspaces added in v0.3.1 

func (c *Client) ListWorkspaces(ctx context.Context, opts ...ListOpts) ([]types.Workspace, error)

ListWorkspaces returns onboarded workspaces in reverse creation order. Pass a ListOpts to page. Prefer ListWorkspacesPage, which also returns the server's truncation signal.

func (*Client) ListWorkspacesPage added in v0.7.0 

func (c *Client) ListWorkspacesPage(ctx context.Context, opts ...ListOpts) (workspaces []types.Workspace, truncated bool, err error)

ListWorkspacesPage is ListWorkspaces plus the server's X-Wardyn-Truncated signal: truncated=true means a further page exists.

func (*Client) Me added in v0.3.1 

func (c *Client) Me(ctx context.Context) (json.RawMessage, error)

Me returns the caller's resolved identity/attribution as raw JSON. GET /api/v1/me.

func (*Client) MintDeviceEnrolmentToken added in v0.8.0 

func (c *Client) MintDeviceEnrolmentToken(ctx context.Context, name string) (DeviceEnrolmentToken, error)

MintDeviceEnrolmentToken mints a single-use token one laptop's first boot exchanges for its device credential (admin only). The returned Token is the only copy — the server keeps a hash — and it expires unused after 72 hours. POST /api/v1/admin/devices/enrolment-tokens.

func (*Client) MintRunnerToken added in v0.9.0 

func (c *Client) MintRunnerToken(ctx context.Context, owner string) (RunnerRegistrationToken, error)

MintRunnerToken mints for the caller when owner is empty, or for a named person (operator only).

func (*Client) MintServiceToken added in v0.9.0 

func (c *Client) MintServiceToken(ctx context.Context, name string, req MintServiceTokenRequest) (APIToken, error)

MintServiceToken mints a token of a service identity the caller sponsors; Token holds the plaintext, which the server shows once. It needs the sponsor's signed-in browser session, so a bearer token cannot mint: the CLI has no verb for it. POST /api/v1/me/service-identities/{name}/tokens.

func (*Client) MoveToken added in v0.9.0 

func (c *Client) MoveToken(ctx context.Context, id uuid.UUID, serviceIdentity string) (TokenMoved, error)

MoveToken links a live admin-minted token to the service identity that replaces it (security tier). It never revokes: the old token keeps working until an admin revokes it. POST /api/v1/tokens/{id}/move.

func (*Client) MyComponents added in v0.8.9 

func (c *Client) MyComponents(ctx context.Context) (MyComponents, error)

MyComponents lists the caller's component surface. GET /api/v1/me/components.

func (*Client) PlanGovernance added in v0.9.0 

func (c *Client) PlanGovernance(ctx context.Context, doc GovernanceDocument, prune bool) (GovernancePlan, error)

PlanGovernance returns the writes ApplyGovernance(ctx, doc, prune) would make against the current state, without making them. It is read-only: one GET /api/v1/governance, and no write request. Its matching rules are ApplyGovernance's, so the create and update steps are the writes an apply issues against the same state. A plan is a snapshot: the server can change before an apply runs.

func (*Client) Preflight added in v0.4.4 

func (c *Client) Preflight(ctx context.Context, req CreateRunRequest) (PreflightResult, error)

Preflight DRY-RUNs a create-run request: the server resolves the policy through the same chokepoint launch uses (so an XOR violation, an unknown secret, or a non-onboarded workspace surface as the REAL launch error) and returns the setup checklist plus the enforced confinement class. It mints nothing, persists nothing, dispatches nothing. Pass the exact CreateRunRequest you would launch with. POST /api/v1/runs/preflight.

func (*Client) PutComponent added in v0.8.9 

func (c *Client) PutComponent(ctx context.Context, id uuid.UUID, req ComponentRequest) (ComponentSaved, error)

PutComponent creates the organisation component with this id, or replaces it. A new component is attachable by nobody until an admin names who may use it under /api/v1/permissions. Admin only. PUT /api/v1/components/{id}.

func (*Client) PutPreset added in v0.8.0 

func (c *Client) PutPreset(ctx context.Context, name string, req PresetRequest) (Preset, error)

PutPreset creates the named preset at version 1, or replaces it and moves its version by one. A body identical to the stored preset changes nothing. Admin only.

func (*Client) PutSiteConfig added in v0.3.1 

func (c *Client) PutSiteConfig(ctx context.Context, cfg types.SiteConfig) (
	out types.SiteConfig, danglingSecretRefs []string, onboardingMarkIgnored bool, err error,
)

PutSiteConfig replaces the operator-wide site config and returns the persisted value plus the write's two advisory signals: danglingSecretRefs — the names of any secret the document now references that the secret store doesn't currently hold (e.g. a `site-config set` recovery run before the referenced secrets were restored) — and onboardingMarkIgnored, true when the body named an onboarding_completed_at the server did not keep (that mark is server-owned and always carried forward; see types.SiteConfig). Both are advisory only, never an error: the ref is still saved as given, and the write still succeeded. PUT /api/v1/site-config.

Integrations is stripped from cfg before the request: the server rejects a non-empty one outright (integrations are managed through their own endpoints, never PUT /site-config), so the documented disaster-recovery round-trip — `wardyn site-config get > f` before a reset, `wardyn site-config set f` after — 400ed outright the moment any integration was ever stored (PLATFORM-API-5). Stripped here, once, so no caller has to remember to (mirrors ui/src/app/lib/api/health.ts's identical fix on the TS side).

Runners is stripped the same way: runners.enabled has its own audited super-admin route (SetRunnersEnabled), and the server refuses a document that names a value other than the stored one, which a captured baseline applied after a reset, or a managed file re-applied on every boot, would otherwise be.

The egress baseline is NOT stripped: a body that changes it is refused 400 site_config_egress_via_own_route, because only PUT /governance/egress-baseline may change it. PutSiteConfigResult is the one that drops the baseline, for restoring a captured document.

func (*Client) PutSiteConfigResult added in v0.8.4 

func (c *Client) PutSiteConfigResult(ctx context.Context, cfg types.SiteConfig) (SiteConfigPutResult, error)

PutSiteConfigResult is PutSiteConfig with every advisory signal, including the ones added after its signature was fixed. PUT /api/v1/site-config.

The egress baseline is stripped the way Integrations is: egress and the baseline mark on each internal_hosts entry are sent as nothing, and the server carries the stored ones forward. It refuses a body that changes the baseline (only PUT /governance/egress-baseline may), so a document captured before a reset, or before the security tier moved the baseline, would otherwise be refused whole. The server's refusal stays for PutSiteConfig and every other caller; EgressBaselineIgnored reports a baseline in cfg that the stored one does not match.

func (*Client) RecentAuditEvents added in v0.3.1 

func (c *Client) RecentAuditEvents(ctx context.Context, opts ...ListOpts) ([]types.AuditEvent, error)

RecentAuditEvents returns the newest-first global audit feed (all runs) — the SIEM-style tail the Audit view renders. Pass a ListOpts to page.

func (*Client) RecordWorkspaceTask added in v0.3.1 

func (c *Client) RecordWorkspaceTask(ctx context.Context, wsID uuid.UUID, taskKey string) (RecordTaskResult, error)

RecordWorkspaceTask launches a named open (allow-all egress) recording session for a workspace via the import pipeline — the operator attaches, does the real activity, and stops the run to capture what it actually used. POST /api/v1/workspaces/{id}/record with body {"task_key": name}. Returns 202 with the launched run; 503 when no runner is wired; 409 while another import step is live.

func (*Client) RegisterRunner added in v0.9.0 

func (c *Client) RegisterRunner(ctx context.Context, req RunnerRegisterRequest) (RunnerRegistration, error)

RegisterRunner exchanges a single-use token for an unclaimed runner identity.

func (*Client) RejectGovernanceChange added in v0.8.6 

func (c *Client) RejectGovernanceChange(ctx context.Context, id uuid.UUID, reason string) (GovernanceChange, error)

RejectGovernanceChange rejects a pending change; nothing is applied. reason is optional ("" omits it). POST /api/v1/governance/changes/{id}/reject.

func (*Client) RemoveMyPoolRemoteRunner added in v0.9.0 

func (c *Client) RemoveMyPoolRemoteRunner(ctx context.Context, poolID uuid.UUID, remoteRunnerID string) error

RemoveMyPoolRemoteRunner takes a remote-hosted runner out of one of the caller's own user pools.

func (*Client) RemoveMyRunnerFromPool added in v0.9.0 

func (c *Client) RemoveMyRunnerFromPool(ctx context.Context, poolID, runnerID uuid.UUID) error

RemoveMyRunnerFromPool takes the caller's own runner out of a pool.

func (*Client) RemoveRunnerPoolRemoteRunner added in v0.9.0 

func (c *Client) RemoveRunnerPoolRemoteRunner(ctx context.Context, poolID uuid.UUID, remoteRunnerID string) error

RemoveRunnerPoolRemoteRunner takes a remote-hosted runner out of an organization pool (admin).

func (*Client) RetireServiceIdentity added in v0.9.0 

func (c *Client) RetireServiceIdentity(ctx context.Context, name string) (ServiceIdentity, error)

RetireServiceIdentity retires an identity for good, revoking its tokens (security tier); calling it again finishes an erase that failed. DELETE /api/v1/service-identities/{name}.

func (*Client) RevokeDevice added in v0.8.0 

func (c *Client) RevokeDevice(ctx context.Context, id uuid.UUID) error

RevokeDevice cuts one device off: its next audit push or heartbeat answers 401 (admin or security_admin). 404 for an unknown or already-revoked id. DELETE /api/v1/admin/devices/{id}.

func (*Client) RevokeDeviceEnrolmentToken added in v0.8.0 

func (c *Client) RevokeDeviceEnrolmentToken(ctx context.Context, id uuid.UUID) error

RevokeDeviceEnrolmentToken cancels a token that has not been redeemed yet, so no laptop can trade it for a device credential (admin or security_admin). 404 for one already redeemed, revoked, expired or unknown. DELETE /api/v1/admin/devices/enrolment-tokens/{id}.

func (*Client) RevokeInvitation added in v0.9.0 

func (c *Client) RevokeInvitation(ctx context.Context, id uuid.UUID) error

RevokeInvitation revokes a pending invitation (security tier). One that is missing, claimed, expired or already revoked answers the same 404. DELETE /api/v1/invitations/{id}.

func (*Client) RevokeRunnerToken added in v0.9.0 

func (c *Client) RevokeRunnerToken(ctx context.Context, id uuid.UUID) error

RevokeRunnerToken stops an unused registration token being redeemed (admin or security_admin).

func (*Client) RevokeServiceToken added in v0.9.0 

func (c *Client) RevokeServiceToken(ctx context.Context, name string, id uuid.UUID) error

RevokeServiceToken revokes one token of an identity the caller sponsors. DELETE /api/v1/me/service-identities/{name}/tokens/{id}.

func (*Client) RevokeSessions added in v0.6.0 

func (c *Client) RevokeSessions(ctx context.Context, sub string, all bool) error

RevokeSessions is D16's "revoke a human now" admin action: POST /api/v1/sessions/revoke, admin-only. Pass exactly one of sub (revoke that one principal's sessions) or all=true (revoke every principal's sessions) — the server 400s on both or neither. 404s when the deployment has no OIDC session store wired (nothing to revoke).

func (*Client) RevokeTemplateGroupAdmin added in v0.9.0 

func (c *Client) RevokeTemplateGroupAdmin(ctx context.Context, grant TemplateGroupAdmin) error

RevokeTemplateGroupAdmin removes the grant of the group and person named.

func (*Client) RunEvents added in v0.8.2 

func (c *Client) RunEvents(ctx context.Context, runID uuid.UUID, afterID uint64, fn func(RunEvent) error) error

RunEvents follows a run's lifecycle feed, calling fn with each event in order, starting after afterID (0 = from the first). The server closes a held stream every few minutes; RunEvents reconnects with Last-Event-ID, so fn sees every event exactly once. It returns nil after fn has seen RunEventEnded, fn's own error if fn returns one, an *APIError for a non-2xx answer (404 for a run the caller cannot read), or the transport error — pass the last ID fn saw back as afterID to resume.

Resume is within the daemon's lifetime: the feed is kept in memory, so after a wardynd restart a run that is still live replays only what happens next, and a run that had already ended answers RunEventEnded alone.

func (*Client) RunFiles added in v0.7.0 

func (c *Client) RunFiles(ctx context.Context, runID uuid.UUID) (RunFiles, error)

RunFiles lists a running sandbox's changed files (owner-or-admin). 409 when the run has no sandbox yet, 501 when the runner cannot exec into one.

func (*Client) RunOutput added in v0.8.2 

func (c *Client) RunOutput(ctx context.Context, runID uuid.UUID, tail int) (RunOutput, error)

RunOutput reads the last tail bytes of a non-interactive run's output (owner-or-admin); tail <= 0 asks for all the server keeps (WARDYN_RUN_OUTPUT_TAIL_BYTES, 64 KiB by default). 409 for an interactive run, when none is kept, or when it is off; 410 once it has expired. Each refusal carries a run_output_* reason.

func (*Client) RunSignIn added in v0.8.8 

func (c *Client) RunSignIn(ctx context.Context, runID uuid.UUID) (RunSignIn, error)

RunSignIn reads, once, whether an AWS sign-in run is waiting for its device-code approval (the run's owner only; a super admin on a person's run gets 403 run_owner_only). 409 run_sign_in_not_aws for any other run; 503 run_sign_in_unreadable when the sandbox's terminal could not be read in time.

func (*Client) SaveMyComponent added in v0.8.9 

func (c *Client) SaveMyComponent(ctx context.Context, req ComponentRequest) (ComponentSaved, error)

SaveMyComponent stores a new component of the caller's own. 422 on an invalid definition or when the caller is at the saved-component limit; 409 on a name they already use; 403 when custom components are not turned on for them. POST /api/v1/me/components.

func (*Client) SaveTemplate added in v0.9.0 

func (c *Client) SaveTemplate(ctx context.Context, id uuid.UUID, req TemplateSaveRequest) (Template, error)

SaveTemplate creates a template when id is uuid.Nil, and updates that template otherwise (req.ExpectedRevision is then required by the server).

func (*Client) ScanSource added in v0.5.0 

func (c *Client) ScanSource(ctx context.Context, id uuid.UUID) (json.RawMessage, error)

ScanSource scans one source — a dir inline (200 with the profile), a repo as a governed run (202 with scan_run_id). The reply shape varies, so it is returned raw. POST /api/v1/sources/{id}/scan.

func (*Client) ScanWorkspace added in v0.3.1 

func (c *Client) ScanWorkspace(ctx context.Context, id uuid.UUID) (json.RawMessage, error)

ScanWorkspace triggers the workspace scan (populates the least-privilege profile). The reply shape varies (a completed profile vs an accepted async run), so it is returned as raw JSON. POST /api/v1/workspaces/{id}/scan.

func (*Client) SetMyRunnerLimits added in v0.9.0 

func (c *Client) SetMyRunnerLimits(ctx context.Context, id uuid.UUID, limits RunnerLimits) (RunnerView, error)

SetMyRunnerLimits declares one of the caller's own runners' limits: Runs at once (1 to 64), the total and the per-run CPU, memory and disk, all of them. Only the runner's owner may; another person's runner answers as an absent id, an administrator's included.

func (*Client) SetMyRunnerPoolDefaults added in v0.9.0 

func (c *Client) SetMyRunnerPoolDefaults(ctx context.Context, d RunnerPoolDefaults) (RunnerPoolDefaults, error)

SetMyRunnerPoolDefaults sets the caller's own default pool, one they may use. A default only seeds a choice: it never grants a pool the caller could not choose.

func (*Client) SetMySecret added in v0.9.0 

func (c *Client) SetMySecret(ctx context.Context, name, value string) error

SetMySecret stores the caller's OWN secret, whatever their role: PUT /api/v1/me/secrets/{name}. Unlike SetSecret, where an admin's write lands in the shared namespace, this never does. It needs a signed-in person (403 secret_personal_needs_person for the admin token).

func (*Client) SetOrgRunnerPoolDefaults added in v0.9.0 

func (c *Client) SetOrgRunnerPoolDefaults(ctx context.Context, d RunnerPoolDefaults) (RunnerPoolDefaults, error)

SetOrgRunnerPoolDefaults replaces the whole organisation document (admin), its default barrier included: a d without Barrier clears it, so read the document first to keep what you do not change. It never rewrites a person's own.

func (*Client) SetRemoteRunnerPeoplePolicy added in v0.9.0 

func (c *Client) SetRemoteRunnerPeoplePolicy(ctx context.Context, id string, req RemoteRunnerPeoplePolicyRequest) (RemoteRunner, error)

SetRemoteRunnerPeoplePolicy sets who may add a remote-hosted runner to their own user pools (admin or security admin). A held write returns a *PendingApprovalError naming the change.

func (*Client) SetRunnerPoolUsePolicy added in v0.9.0 

func (c *Client) SetRunnerPoolUsePolicy(ctx context.Context, poolID uuid.UUID, req RunnerPoolUsePolicyRequest) (RunnerPoolUsePolicy, error)

SetRunnerPoolUsePolicy replaces who may use an organization pool (admin or security admin). A held write returns a *PendingApprovalError naming the change.

func (*Client) SetRunnersEnabled added in v0.9.0 

func (c *Client) SetRunnersEnabled(ctx context.Context, enabled bool) (RunnerSettings, error)

SetRunnersEnabled turns runners on or off (admin). Turning on is refused until the public organisation URL is HTTPS.

func (*Client) SetSecret 

func (c *Client) SetSecret(ctx context.Context, name, value string) error

SetSecret stores (or overwrites) a named secret. The value is write-only — no API path ever returns it. PUT /api/v1/secrets/{name} with body {"value":...}. Returns 400 on an invalid name, 403 for a reserved platform-internal name.

func (*Client) SetSharedSecret added in v0.9.0 

func (c *Client) SetSharedSecret(ctx context.Context, name, value string) error

SetSharedSecret stores a shared service secret in the operator namespace every person's run may fall back to: PUT /api/v1/shared-secrets/{name}. Operator tier only (403 otherwise).

func (*Client) SetupStatus added in v0.3.1 

func (c *Client) SetupStatus(ctx context.Context) (json.RawMessage, error)

SetupStatus returns the first-run setup checklist as raw JSON (the response is a server-internal struct not exported through internal/types). GET /api/v1/setup/status.

func (*Client) SynthesizeProfile added in v0.3.1 

func (c *Client) SynthesizeProfile(ctx context.Context, runID uuid.UUID) (ProfileResult, error)

SynthesizeProfile runs Recording Mode synthesis for a run: from its already- captured audit / egress / ground-truth events the server proposes a tightened, reusable RunPolicy ("sandbox profile"). ADVISORY and READ-ONLY — it mints nothing and persists no policy (save the proposal via CreatePolicy). POST /api/v1/runs/{id}/profile/synthesize (renamed from /profile in 0.8 — docs/sdk.md "Renamed in 0.8" — the old path still answers, as a chi alias, for one minor). Returns 404 when the run does not exist.

func (*Client) UpdateMyComponent added in v0.8.9 

func (c *Client) UpdateMyComponent(ctx context.Context, id uuid.UUID, req ComponentRequest) (ComponentSaved, error)

UpdateMyComponent replaces the name and definition of one of the caller's saved components and moves its version. 404 for an id that is not theirs. PUT /api/v1/me/components/{id}.

func (*Client) UpdateMyRunnerPool added in v0.9.0 

func (c *Client) UpdateMyRunnerPool(ctx context.Context, id uuid.UUID, req UpdateRunnerPoolRequest) (RunnerPool, error)

UpdateMyRunnerPool renames, switches or re-limits one of the caller's own user pools; anyone else's answers as an unknown id does.

func (*Client) UpdatePolicy 

func (c *Client) UpdatePolicy(ctx context.Context, id uuid.UUID, req PolicyRequest) (types.RunPolicy, error)

UpdatePolicy validates and replaces an existing policy's name and spec. Returns the updated RunPolicy on success; 404 when unknown; 400 when invalid.

func (*Client) UpdateRemoteRunner added in v0.9.0 

func (c *Client) UpdateRemoteRunner(ctx context.Context, id string, req UpdateRemoteRunnerRequest) (RemoteRunnerView, error)

UpdateRemoteRunner renames a remote-hosted runner (admin).

func (*Client) UpdateRunnerPool added in v0.9.0 

func (c *Client) UpdateRunnerPool(ctx context.Context, id uuid.UUID, req UpdateRunnerPoolRequest) (RunnerPool, error)

UpdateRunnerPool renames, switches or re-limits an organization pool (admin).

func (*Client) UpdateServiceIdentity added in v0.9.0 

func (c *Client) UpdateServiceIdentity(ctx context.Context, name string, req UpdateServiceIdentityRequest) (ServiceIdentity, error)

UpdateServiceIdentity changes an identity's description, sponsor or suspended state (security tier). A sponsor change revokes every token of the identity. PATCH /api/v1/service-identities/{name}.

func (*Client) UpdateWorkspace added in v0.3.1 

func (c *Client) UpdateWorkspace(ctx context.Context, id uuid.UUID, req WorkspaceRequest) (types.Workspace, error)

UpdateWorkspace replaces a workspace's editable identity fields. Returns the updated row; 404 when unknown; 400 when invalid.

type Component added in v0.8.9 

type Component = types.Component

Component is one stored custom component: the hosts it reaches, the secrets it carries (names, never values) with how each is delivered, and plain config. ComponentDefinition is that contract; ComponentSecret and ComponentDelivery are its secret rows. ComponentRef attaches one to a run, carried in CreateRunRequest.Components.

type ComponentConfigSchema added in v0.9.0 

type ComponentConfigSchema = types.ComponentConfigSchema

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ComponentConfigValues added in v0.9.0 

type ComponentConfigValues = types.ComponentConfigValues

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ComponentDefinition added in v0.8.9 

type ComponentDefinition = types.ComponentDefinition

Domain nouns returned or accepted by Client methods.

type ComponentDelivery added in v0.8.9 

type ComponentDelivery = types.ComponentDelivery

Domain nouns returned or accepted by Client methods.

type ComponentFact added in v0.9.0 

type ComponentFact struct {
	Kind         types.ComponentKind `json:"kind"`
	Provider     string              `json:"provider,omitempty"`
	ID           string              `json:"id"`
	Name         string              `json:"name,omitempty"`
	Version      int                 `json:"version,omitempty"`
	Reason       string              `json:"reason"`
	Status       string              `json:"status"`
	Requirements []PreflightItem     `json:"requirements"`

	Lane  string   `json:"lane,omitempty"`
	Org   string   `json:"org,omitempty"`
	Repos []string `json:"repos,omitempty"`

	Hosts        []string              `json:"hosts,omitempty"`
	Secrets      []ComponentSecretFact `json:"secrets,omitempty"`
	ConfigKeys   []string              `json:"config_keys,omitempty"`
	SelfDefined  bool                  `json:"self_defined,omitempty"`
	AutonomyCap  types.AutonomyLevel   `json:"autonomy_cap,omitempty"`
	VaultFloor   bool                  `json:"vault_floor,omitempty"`
	TLSIntercept bool                  `json:"tls_intercept,omitempty"`
	HighRisk     bool                  `json:"high_risk,omitempty"`

	// Agent is the agent component's own facts (kind agent).
	Agent *AgentFact `json:"agent,omitempty"`

	// A git_provider's additions. Capabilities is the run's resolved set on the
	// lane and CapabilityCeiling the most the person's row allows. PushRules are
	// the rules in force for this provider and organisation. TokenMode and
	// TokenScopes describe the Azure DevOps token; RepoAccess each repository's
	// access; InstallURL is the GitHub App install link, sent to operators only.
	Capabilities      []string             `json:"capabilities,omitempty"`
	CapabilityCeiling []string             `json:"capability_ceiling,omitempty"`
	PushRules         *types.PushRulesSpec `json:"push_rules,omitempty"`
	TokenMode         types.ADOTokenMode   `json:"token_mode,omitempty"`
	TokenScopes       []TokenScopeFact     `json:"token_scopes,omitempty"`
	RepoAccess        []RepoAccessFact     `json:"repo_access,omitempty"`
	InstallURL        string               `json:"install_url,omitempty"`
}

ComponentFact is one row of `components`: something the run is given access to, as the door decided it. It mirrors the server's fact; a refused request has no facts.

type ComponentKind added in v0.9.0 

type ComponentKind = types.ComponentKind

ComponentKind names what a ComponentFact describes. The override narrowing table's OverrideKind, OverrideOp and OverrideRule are the vocabulary RunOverrides.Items answers in.

type ComponentRef added in v0.8.9 

type ComponentRef = types.ComponentRef

Domain nouns returned or accepted by Client methods.

type ComponentRequest added in v0.8.9 

type ComponentRequest struct {
	Name       string              `json:"name"`
	Definition ComponentDefinition `json:"definition"`
}

ComponentRequest is the body for POST /api/v1/me/components, PUT /api/v1/me/components/{id} and PUT /api/v1/components/{id}. The server validates the definition as the owner's kind of row: a person's saved component names DNS hosts only and cannot be shared or sent over plain HTTP, an organisation's can.

type ComponentRequirement added in v0.8.9 

type ComponentRequirement struct {
	Kind   string `json:"kind"`
	Name   string `json:"name,omitempty"`
	Status string `json:"status"`
	Fix    string `json:"fix,omitempty"`
}

ComponentRequirement is one thing a saved component still needs before a run can use it: a secret to add, or a connection to make. The server returns the list on every save; it is empty until the component names something it needs.

type ComponentSaved added in v0.8.9 

type ComponentSaved struct {
	Component
	Requirements []ComponentRequirement `json:"requirements"`
}

ComponentSaved answers a component save: the stored row, and what it still needs.

type ComponentSecret added in v0.8.9 

type ComponentSecret = types.ComponentSecret

Domain nouns returned or accepted by Client methods.

type ComponentSecretFact added in v0.9.0 

type ComponentSecretFact struct {
	Delivery string `json:"delivery"` // header | env | file
	Shared   bool   `json:"shared"`
	// LocalDelivery is how an organisation-held secret would reach the person's
	// runner (OD-12): via_org, runner_resident or refuse. Absent for the
	// person's own secret and while the placement lane has not decided.
	LocalDelivery placement.Mode `json:"local_delivery,omitempty"`
}

ComponentSecretFact is one secret of a component: how it reaches the run, and whether the organisation provides it. Never its name.

type ComponentSecretView added in v0.8.9 

type ComponentSecretView struct {
	Delivery ComponentDelivery `json:"delivery"`
	Shared   bool              `json:"shared,omitempty"`
}

ComponentSecretView is one secret an organisation component carries, as a person granted it sees it: how it is delivered and whether the value is the organisation's, never its name.

type ConcurrencyBound added in v0.9.0 

type ConcurrencyBound = types.ConcurrencyBound

The canonical pool shapes, re-exported so SDK callers can name them.

type ConfigBindTarget added in v0.9.0 

type ConfigBindTarget = types.ConfigBindTarget

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigBinding added in v0.9.0 

type ConfigBinding = types.ConfigBinding

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigCondition added in v0.9.0 

type ConfigCondition = types.ConfigCondition

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigField added in v0.9.0 

type ConfigField = types.ConfigField

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigFieldKind added in v0.9.0 

type ConfigFieldKind = types.ConfigFieldKind

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigGroup added in v0.9.0 

type ConfigGroup = types.ConfigGroup

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigIssue added in v0.9.0 

type ConfigIssue = types.ConfigIssue

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfigOption added in v0.9.0 

type ConfigOption = types.ConfigOption

The custom-component configuration schema (internal/types owns it): the declarative fields a component author exposes so the wizard can render the component's settings. Types only; a component row carries a schema once the components lane adds it.

type ConfinementClass 

type ConfinementClass = types.ConfinementClass

ConfinementClass declares how strongly a sandbox confines an agent (AgentRun.ConfinementClass, RunPolicySpec.MinConfinementClass).

type CreateInvitationRequest added in v0.9.0 

type CreateInvitationRequest struct {
	// ExpiresInSeconds is how long the invitation stays claimable; zero asks for the default (72h), at most 14d.
	ExpiresInSeconds int64 `json:"expires_in_seconds,omitempty"`
	// TokenName names the token the claim creates; the claimer may change it.
	TokenName string `json:"token_name,omitempty"`
	// TokenTTLSeconds limits the claimed token's lifetime; zero leaves it to the deployment's rule.
	TokenTTLSeconds int64 `json:"token_ttl_seconds,omitempty"`
	// ReplacesTokenID is a live token an admin minted for the target, revoked when the target claims.
	ReplacesTokenID *uuid.UUID `json:"replaces_token_id,omitempty"`
}

CreateInvitationRequest is the POST /api/v1/people/{principal}/invitations body; every field is optional. internal/api aliases it (createInvitationRequest), so the strict server decode and this struct are one type.

type CreateMyRunnerPoolRequest added in v0.9.0 

type CreateMyRunnerPoolRequest struct {
	Name   string            `json:"name"`
	Limits *RunnerPoolLimits `json:"limits,omitempty"`
}

CreateMyRunnerPoolRequest names a new user pool of the caller's own. Limits are as CreateRunnerPoolRequest's; every run is still bounded by the caller's governance profile.

func (CreateMyRunnerPoolRequest) Validate added in v0.9.0 

func (r CreateMyRunnerPoolRequest) Validate() error

Validate refuses a bad name and limits a pool cannot keep.

type CreateRunRequest 

type CreateRunRequest struct {
	Agent string `json:"agent"`
	Repo  string `json:"repo"`
	// Task is the agent's prompt for a non-interactive run. For an interactive
	// run it is instead the OPTIONAL boot seed: interpreted per
	// InteractiveStart (an initial prompt for "agent", a startup command for
	// "shell") and fired once, at sandbox boot, in the same persistent session
	// the human later attaches to — never re-run on attach. Empty is today's
	// pure-idle behavior, unchanged.
	Task string `json:"task,omitempty"`
	// Title is a short human NAME for the run. Runs that share a title are
	// grouped in the console's run list. OPTIONAL on the wire even though the
	// console requires it: the site-config probe, harness login and workspace
	// record/verify all create runs with no human to name them, and the console
	// falls back to Task for display. Trimmed and stored on the run row.
	Title string `json:"title,omitempty"`
	// Description is optional free-text context — why this run exists. Never
	// interpreted, only stored and displayed.
	Description string     `json:"description,omitempty"`
	PolicyID    *uuid.UUID `json:"policy_id,omitempty"`
	// ConfinementClass, when set, requests a specific confinement class
	// ("CC1"/"CC2"/"CC3"). Empty inherits the policy minimum; an unknown
	// non-empty value is rejected by the server with 400.
	ConfinementClass string `json:"confinement_class,omitempty"`
	// Interactive requests an interactive run: the sandbox comes up idle — or,
	// with a non-empty Task, runs that boot seed in a persistent session — so a
	// human can attach to it (wardyn run attach <id>) either way. Pair with a
	// never-reap policy (AutoStopAfterSec < 0) or the idle reaper will stop the
	// idle sandbox.
	Interactive bool `json:"interactive,omitempty"`
	// WorkspaceID, when set, launches the run against that ONBOARDED workspace:
	// the server prepends the workspace's stored source onto the resolved policy
	// (a repo as a workspace_repos entry, a local dir as a read-only-by-default
	// workspace_mounts entry) so the run inherits its approved egress, built image
	// and bound model/harness credentials. Composes with PolicyID / InlinePolicy /
	// the default policy — it seeds the source those cannot name without
	// hand-reproducing the workspace's exact path. Container-kind workspaces are
	// rejected: pass the image ref as Image instead.
	WorkspaceID *uuid.UUID `json:"workspace_id,omitempty"`
	// InlinePolicy, when set, supplies the run's full RunPolicySpec INLINE
	// instead of referencing a stored PolicyID. It is MUTUALLY EXCLUSIVE with
	// PolicyID (the server rejects both with 400); neither set falls back to the
	// configured default. The server validates it exactly like a stored policy
	// (mounts pass the same deny-list; api_key grants must reference an existing
	// secret) and attaches it with no stored policy id.
	InlinePolicy *RunPolicySpec `json:"inline_policy,omitempty"`
	// PolicyOverlay lays the policy keys it names onto the caller's default
	// policy (their governance ceiling, or the deployment default); a key it
	// leaves out keeps the default's value. A non-empty JSON object of
	// RunPolicySpec keys, never beside PolicyID or InlinePolicy (400
	// policy_overlay_conflict). The keys it names are bounded by the caller's
	// ceiling like an inline policy; the rest stay as the default has them. In a
	// run document it is written under intent.inline_policy.
	PolicyOverlay json.RawMessage `json:"policy_overlay,omitempty"`
	// DevcontainerRepo, when set AND an image builder is wired (WARDYN_ENVBUILD),
	// triggers a devcontainer build of that git repo whose resulting image becomes
	// the sandbox image. Ignored (degrades to the convention image) when no builder
	// is wired. Mutually exclusive with Image.
	DevcontainerRepo string `json:"devcontainer_repo,omitempty"`
	// DevcontainerRef is the optional git ref (branch/tag/sha) to build for
	// DevcontainerRepo.
	DevcontainerRef string `json:"devcontainer_ref,omitempty"`
	// Image, when set, is a USER-supplied base image (Bring Your Own Image); the
	// server wraps it with the runner tools via a trusted finalize stage and
	// requires an image builder to be wired (WARDYN_ENVBUILD) — an explicit
	// Image with no builder wired is a hard 400 rather than a silent fallback.
	// Mutually exclusive with DevcontainerRepo.
	Image string `json:"image,omitempty"`
	// TaskMode selects how a non-interactive run executes Task: "" / "harness"
	// (default) runs the agent harness; "exec" runs Task as a plain shell
	// command in the same governed sandbox (no agent, no LLM credentials — the
	// BYOA/CI lane; see docs/CI.md). Ignored for an interactive run.
	TaskMode string `json:"task_mode,omitempty"`
	// InteractiveStart is TaskMode's interactive counterpart: what the attach
	// shell opens with. "" / "shell" drops the human into a shell in the
	// prepared workspace (the long-standing behavior); "agent" additionally
	// launches the image's agent CLI (claude / codex) there, once, on the first
	// attach. Request-scoped like TaskMode — never persisted on the run row,
	// carried to the sandbox as WARDYN_INTERACTIVE_START and consumed by the
	// image's attach ~/.bashrc. Ignored for a non-interactive run.
	InteractiveStart string `json:"interactive_start,omitempty"`
	// SeedAutoTools, when true, lets an interactive run's boot SEED (Task,
	// interpreted per InteractiveStart — see Task's own doc) use tools before a
	// human attaches, equivalent to --dangerously-skip-permissions for that
	// pre-attach span only. Default false: the seed is supervised, so an
	// unattended agent-started seed parks at its first tool-approval prompt
	// until someone joins. Meaningful only for an agent-started seed with
	// non-empty Task; request-scoped like InteractiveStart — never persisted on
	// the run row, carried to the sandbox as WARDYN_SEED_AUTO_TOOLS.
	SeedAutoTools bool `json:"seed_auto_tools,omitempty"`
	// ToolApprovals governs an AUTONOMOUS (non-interactive) Claude Code run's
	// own tool calls: "" / "auto" (default) is today's behavior — the sandbox
	// and egress policy are the only boundary, same as
	// --dangerously-skip-permissions; "hold" routes every tool call through
	// Wardyn's approval FSM instead, so an operator decides each one before it
	// runs. Rejected for codex-cli (no external tool-approval contract) and
	// ALSO rejected for an interactive run: that run's supervised-seed posture is
	// SeedAutoTools's job, so this field could never take effect there. It used
	// to be accepted and silently discarded, which is worse than refusing it —
	// the caller got a 201 and none of the supervision they asked for.
	// Request-scoped like TaskMode — never persisted on the run row, carried to
	// the sandbox as WARDYN_TOOL_APPROVALS.
	ToolApprovals string `json:"tool_approvals,omitempty"`
	// Workspaces lists the workspaces this run attaches, in order, each with its
	// per-run options: which OPTIONAL requirements (types.Workspace.Requirements,
	// level="optional") it enables, a read-only narrowing, its in-sandbox
	// target and which of its repositories it clones. Every entry is attached;
	// Workspaces[0] is the PRIMARY. At most 32, each named once. WorkspaceID stays a working SINGLE-selection
	// alias: alone it attaches that one workspace with no option, and sent beside
	// Workspaces it must equal Workspaces[0] (400 workspace_selection_invalid
	// otherwise). A REQUIRED requirement needs no option; it applies whenever its
	// workspace is attached. An entry for a workspace the run's policy already
	// attaches (workspace_mounts/workspace_repos), other than the one WorkspaceID
	// names, adds its options only: its paths and repositories are the policy's,
	// so a target or repos there is 422.
	Workspaces []WorkspaceSelection `json:"workspaces,omitempty"`
	// IntegrationID no longer chooses a model credential: a run naming one is
	// refused with a 422. Use ModelProvider.
	IntegrationID string `json:"integration_id,omitempty"`
	// ModelProvider chooses this run's model provider (GET /model-providers,
	// by id), ahead of a workspace's provider pin and the agent's default. It
	// must be one the caller is granted, that is on and that serves Agent —
	// otherwise the run is refused, never moved to another provider. Named on a
	// deployment with no model providers, or on a run that calls no model, it
	// is refused rather than ignored.
	ModelProvider string `json:"model_provider,omitempty"`
	// Drive opts this run into the member's USER DRIVE — the per-user storage
	// an admin allocated them. Nil (the default) mounts nothing, byte for byte
	// today. Nothing here names a path or a drive: the server resolves which
	// drive belongs to the authenticated caller and derives their home from
	// their own identity, so this flag can only ever ask for the storage the
	// caller was already granted.
	Drive *DriveSelection `json:"drive,omitempty"`
	// Drives attaches drives from GET /me/drives by id, each at the target the
	// catalogue shows; the person's legacy drive keeps /home/agent/drive. Each
	// is authorised through the caller's own grants. Sending both Drive and
	// Drives is 400 drive_selection_conflict. One drive that cannot be mounted
	// refuses the run; none is dropped.
	Drives []DriveAttachment `json:"drives,omitempty"`
	// Components attaches custom components to this run: each entry names a
	// stored component by id or carries a run-only definition inline. Nil and
	// empty are the same and attach nothing, byte for byte today.
	Components []ComponentRef `json:"components,omitempty"`
	// AllowedImage chooses one of the images the organisation allows (the
	// preflight and preview `allowed_images`), by ref, instead of the resolved
	// default. Mutually exclusive with Image and DevcontainerRepo. Accepted and
	// validated; a server that cannot apply it yet refuses it with
	// request_field_unavailable, never ignores it.
	AllowedImage string `json:"allowed_image,omitempty"`
	// Placement is where the run's sandbox lives: "remote", the organisation's
	// own executor (the default), or "local", a runner the person registered.
	// Empty is "remote" until a single placement is eligible; "local" is
	// refused with placement_unavailable until the runner lane is enabled.
	Placement Placement `json:"placement,omitempty"`
	// RunnerID names the runner for Placement "local"; with more than one
	// runner online and none named the server answers 422 runner_ambiguous.
	RunnerID string `json:"runner_id,omitempty"`
	// RunnerPoolID names the pool the run starts on (RunnerPoolChoice.ID).
	// Choosing a pool grants no runner, credential or drive: it only narrows
	// where the run may go. Empty keeps today's placement; once the server
	// manages pools it applies the person's, then the organisation's, default.
	// Accepted and validated; a server that cannot honour pools yet refuses it
	// with request_field_unavailable, never ignores it.
	RunnerPoolID string `json:"runner_pool_id,omitempty"`
	// Resources is the CPU and memory this run asks for. A field set here beats
	// the source policy's own; a field left out keeps the policy's, else the
	// default. The server applies it within the strictest of the pool's, the
	// person's governance, the deployment's and (on their own runner) the
	// runner's limits: an over-ask is reduced to that cap, never refused.
	// CreateRunResult.ResourcesApplied and the dry runs say what was applied.
	Resources *RunResources `json:"resources,omitempty"`
	// Overrides are the person's per-component edits on the New Run cards
	// (OD-1), applied inside the resolve fold before the ceiling clamp. See
	// RunOverrides.
	Overrides *RunOverrides `json:"overrides,omitempty"`
	// MaxWaitSec is how long this run may wait for a slot when its runner pool is at its
	// concurrent-run limit, in seconds (1 to 604800; more is cut to 7 days with a warning). Absent
	// is 24 hours for a Background run and 1 hour for an Interactive one. At the end of the wait
	// the run is FAILED with the reason queue_timeout. Ignored by a pool with no limit. A pointer, so
	// a 0 is sent and refused rather than read as absent.
	MaxWaitSec *int `json:"max_wait_sec,omitempty"`
	// ModeContract marks a request as a 0.9 client's, whatever else it carries:
	// it is RunModeContractV09 and nothing else. The server then holds the
	// request to the run-mode contract, so an unset Experience is refused
	// (run_mode_required) and never read as an older client's. The console's New
	// Run wizard always sends it; an older client, and the CLI's older flags,
	// send none and keep the older mapping.
	ModeContract string `json:"mode_contract,omitempty"`
	// Experience is the canonical run mode, "background" or "interactive". A new
	// client sends it with the carriers below, which replace the legacy agent,
	// task, task_mode, interactive, interactive_start, seed_auto_tools,
	// tool_approvals and model_provider (sending both is run_mode_conflict). It
	// is required once any carrier is used; the server never infers it. It is
	// stored on the run, and every interactive door of a background run refuses.
	// A request with none of these fields is an older client's and is read as
	// before.
	Experience Experience `json:"experience,omitempty"`
	// Workload is what a background run executes: an agent task or a command.
	Workload *RunWorkload `json:"workload,omitempty"`
	// Tools are the included tool instances, each with its own provider or
	// configuration and its own tool rules. Distinct from Startup. A server that
	// cannot honour a shape yet (more than one tool, per-tool rules, a component
	// tool, an interactive run with none) refuses it with
	// request_field_unavailable, never ignores it.
	Tools []IncludedTool `json:"tools,omitempty"`
	// Startup is what an interactive run starts on its own: none, one included
	// harness or one command.
	Startup *RunStartup `json:"startup,omitempty"`
	// StartFolder is the run's one working directory. Accepted and validated; a
	// server that cannot apply an attachment folder yet refuses it with
	// request_field_unavailable.
	StartFolder *StartFolder `json:"start_folder,omitempty"`
	// NoRepositoriesOrDrives is the explicit choice to attach nothing. It cannot
	// be combined with any repository, workspace or drive. Nothing in the
	// sandbox is kept when the run ends unless it is pushed or copied out.
	NoRepositoriesOrDrives bool `json:"no_repositories_or_drives,omitempty"`
	// Shape is the New Run choice a run was set up from: agent_task,
	// environment or application. Optional; the server checks it against
	// experience, workload and tools and otherwise does not use it.
	Shape RunShape `json:"shape,omitempty"`
	// EndsAfterSec ends the run this many seconds after it is created, 1 to
	// 2147483647 (below 1 is a 400, run_end_after_too_small). An end past what the pool, the deployment and the person's
	// governance allow is cut to it, and the 201 says so; it is never refused. A
	// run with neither this nor NoEnd gets the effective default end. Setting both
	// is a 400 (run_end_conflicting_fields).
	EndsAfterSec *int `json:"ends_after_sec,omitempty"`
	// NoEnd asks for a run with no end. It is allowed only where the pool and the
	// deployment leave the lifetime unlimited and the person's governance permits
	// No end (allow_no_end with user_changes_limits); otherwise 403
	// run_end_no_end_not_allowed or run_limits_gate_denied.
	NoEnd bool `json:"no_end,omitempty"`
	// Preset launches the named launch preset (see Preset): the server
	// expands it into the equivalent explicit request and runs the unchanged
	// create path under the caller's own ceiling. Alongside it only Title,
	// Task and PresetVersion may be set; any other field is refused.
	Preset string `json:"preset,omitempty"`
	// PresetVersion, with Preset, pins the version the caller expects: a
	// preset changed since is refused (409) rather than launched. 0 launches
	// the current version. The created run records the version it used.
	PresetVersion int `json:"preset_version,omitempty"`
}

CreateRunRequest is the body for POST /api/v1/runs.

func (CreateRunRequest) EffectiveExperience added in v0.9.0 

func (r CreateRunRequest) EffectiveExperience() Experience

EffectiveExperience is the documented compatibility mapping from an older client's fields: a request is Interactive when it says so or has no task (the server coerces such a request to idle and attachable), and Background otherwise. A request that carries `experience` is its own answer. The mapping is for reading old requests (display, documentation); the server stores an experience only for a request that carried one, so an older client's run keeps every door's behaviour. Never use it to admit a run: admission reads the stored value (types.RunnerPoolLimits.AllowsRunType).

func (CreateRunRequest) PlacementRequest added in v0.9.0 

func (r CreateRunRequest) PlacementRequest() placement.Request

PlacementRequest is the placement a request asks for, in the shape the placement package validates and resolves.

func (CreateRunRequest) UsesRunMode added in v0.9.0 

func (r CreateRunRequest) UsesRunMode() bool

UsesRunMode reports whether the request is a new client's: it carries the contract marker or any of the run-mode contract's fields, so its mode must be explicit. The marker is what lets the server refuse "nothing chosen" instead of reading a client that sent no carrier as an older one.

type CreateRunResult added in v0.4.4 

type CreateRunResult struct {
	types.AgentRun
	// Warnings are ADVISORY notices the server raised while resolving the run —
	// discouraged, never blocking: a member's inline policy narrowed to what
	// they are granted (an egress host, a secret-referencing grant, a workspace
	// repo), a workspace-directory collision with another active run, or an
	// ssh_key grant dropped because the agent has no SSH clone lane. Surface
	// them: the run is live either way, so a dropped warning is a silently
	// degraded run.
	Warnings []string `json:"warnings,omitempty"`
	// ResourcesApplied is the CPU and memory the run asked for and got, and
	// which limit bound each.
	ResourcesApplied *AppliedResources `json:"resources_applied,omitempty"`
}

CreateRunResult is the decoded POST /api/v1/runs 201 reply. AgentRun is EMBEDDED (the server puts the run's fields at the top level), so .ID/.State read straight off the result.

type CreateRunnerPoolRequest added in v0.9.0 

type CreateRunnerPoolRequest struct {
	Name   string            `json:"name"`
	Limits *RunnerPoolLimits `json:"limits,omitempty"`
}

CreateRunnerPoolRequest names a new organization pool (admin). Limits are validated (RunnerPoolLimits.Validate); a pool created without them adds no bound of its own.

func (CreateRunnerPoolRequest) Validate added in v0.9.0 

func (r CreateRunnerPoolRequest) Validate() error

Validate refuses a bad name and limits a pool cannot keep.

type CreateServiceIdentityRequest added in v0.9.0 

type CreateServiceIdentityRequest struct {
	// Name is "^[a-z][a-z0-9-]{2,62}$"; the identity's principal is "service:<name>".
	Name        string `json:"name"`
	Description string `json:"description"`
	// Sponsor is the signed-in person who mints the identity's tokens and sees its runs.
	Sponsor string `json:"sponsor"`
	// UserType is an existing user type; it sets the identity's ceiling.
	UserType string `json:"user_type"`
}

CreateServiceIdentityRequest is the POST /api/v1/service-identities body. internal/api aliases it (serviceIdentityRequest), so the strict server decode and this struct are one type.

type CredentialGrant 

type CredentialGrant = types.CredentialGrant

CredentialGrant is a credential-grant eligibility record. Returned by ListGrants.

type DecisionOpts added in v0.5.0 

type DecisionOpts struct {
	// Scope is the decision's blast radius: ScopeOnce, ScopeRun (the zero
	// value, and today's default), ScopeUntil, or ScopeAlways. Meaningful
	// only for an egress_domain approval; the server rejects it otherwise.
	Scope ApprovalScope
	// Until is the expiry for Scope == ScopeUntil: required by the server in
	// that case, and rejected if set for any other scope.
	Until *time.Time
}

DecisionOpts is the optional scope/expiry for Approve/Deny. This repo has no WithX functional-option precedent (see ListOpts); DecisionOpts follows the same plain-struct-passed-variadically shape. Pass at most one.

type Device added in v0.8.0 

type Device = types.Device

Device is one enrolled laptop in the organisation's inventory (no credential material). Returned by ListDevices.

type DeviceEnrolmentToken added in v0.8.0 

type DeviceEnrolmentToken = types.DeviceEnrolmentToken

DeviceEnrolmentToken is a minted single-use enrolment token; Token holds the plaintext on the mint response only. Returned by MintDeviceEnrolmentToken.

type DeviceEnrolmentTokenRequest added in v0.8.0 

type DeviceEnrolmentTokenRequest struct {
	// Name is the laptop's inventory name; the device it enrols carries it.
	Name string `json:"name"`
}

DeviceEnrolmentTokenRequest is the POST /api/v1/admin/devices/enrolment-tokens body. internal/api aliases it (mintEnrolmentTokenRequest), so the strict server decode and this struct are one type.

type DriveAttachment added in v0.9.0 

type DriveAttachment struct {
	// DriveID is a drive id from GET /me/drives, in its canonical spelling.
	DriveID string `json:"drive_id"`
	// ReadOnly narrows only, as DriveSelection.ReadOnly does: false against a
	// read-only drive is 422.
	ReadOnly *bool `json:"read_only,omitempty"`
}

DriveAttachment is one entry of CreateRunRequest.Drives.

type DriveBackend added in v0.8.0 

type DriveBackend = types.DriveBackend

DriveBackend names where a drive's bytes live and therefore which runner can mount it (DriveRequest.Backend, UserDrive.Backend).

type DriveGrantRequest added in v0.8.0 

type DriveGrantRequest struct {
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	DriveID     uuid.UUID             `json:"drive_id"`
	// Additional allocates this drive beside the subject's other drives
	// instead of replacing them (0.9: a run may attach several drives).
	Additional bool `json:"additional,omitempty"`
	// Priority breaks ties within a tier (higher wins) when a subject's
	// membership qualifies it for more than one group-tier grant. It does not
	// cross tiers (user beats group beats all).
	Priority int `json:"priority"`
	// SizeMiBOverride replaces the drive's allocation for this subject. 0
	// means "use the drive's".
	SizeMiBOverride int `json:"size_mib_override,omitempty"`
	// WritableOverride is TRI-STATE: nil is "use the drive's posture", and an
	// explicit false is "this subject reads only" even on a writable drive.
	WritableOverride *bool `json:"writable_override,omitempty"`
	// HomeOverride is TRI-STATE for the same reason: nil leaves a previously
	// pinned directory name alone, and an explicit "" (or a name) states the
	// field, which is itself the confirmation to change it. User-tier
	// subjects only.
	HomeOverride *string `json:"home_override,omitempty"`
	// Enabled is TRI-STATE and defaults to true when nil: allocating a drive
	// is a deliberate act, so omitting the field means "give it to them", not
	// "pause it". An explicit false pauses the allocation without deleting it.
	Enabled *bool `json:"enabled,omitempty"`
}

DriveGrantRequest is the POST /drives/grants body — one allocation of a drive to a subject. It REPLACES the subject's allocation: the subject ends with exactly this drive, and an existing allocation is repointed (200), so a second POST for the same subject moves them to the new drive. With Additional the drive is allocated BESIDE the subject's others, keyed on (subject_type, subject, drive_id).

type DriveReclaim added in v0.8.0 

type DriveReclaim = types.DriveReclaim

DriveReclaim is the declared intent for a drive's storage objects when an allocation is removed (DriveRequest.Reclaim, UserDrive.Reclaim).

type DriveRequest added in v0.8.0 

type DriveRequest struct {
	Name    string       `json:"name"`
	Backend DriveBackend `json:"backend"`
	// HostRoot is the operator-mounted tree a host_path drive binds a
	// subdirectory of. Meaningless for every other backend, and refused
	// outright when it names a path outside this deployment's configured
	// drive host roots.
	HostRoot string `json:"host_root,omitempty"`
	// StorageClass is the k8s_pvc provisioner to request; "" means the
	// cluster default. Meaningless for every other backend.
	StorageClass string `json:"storage_class,omitempty"`
	// HomeTemplate is which identity a drive's per-user home name is derived
	// from. "" means the server's default (HomeTemplateHash).
	HomeTemplate HomeTemplate `json:"home_template,omitempty"`
	// SizeMiB is the allocation, not a guarantee — see types.StorageEnforcement.
	// Required (and enforced) on a k8s_pvc drive; advisory elsewhere.
	SizeMiB int `json:"size_mib,omitempty"`
	// Writable is the drive's DEFAULT posture and it defaults to false. A
	// grant may narrow it and a run may narrow it again; neither may widen it.
	Writable bool `json:"writable,omitempty"`
	// Reclaim is the declared intent for the drive's storage objects once an
	// allocation is removed. "" means the server's default (DriveReclaimRetain).
	Reclaim DriveReclaim `json:"reclaim,omitempty"`
}

DriveRequest is the POST /drives / PUT /drives/{id} body — one admin-registered drive. ID/CreatedAt/UpdatedAt/CreatedBy are never accepted from the wire: the id comes from the path (an update) or the server (a create), and provenance is always server-assigned. Name and Backend are always on the wire (no omitempty); the rest default to the zero value a new drive would otherwise want.

type DriveSelection added in v0.7.0 

type DriveSelection struct {
	// Enabled asks for the caller's drive to be mounted. False (and an absent
	// Drive) mounts nothing. A caller with no drive allocated, or one whose
	// governance profile carries DenyUserDrive, is refused rather than silently
	// given a run without it — asking for storage and not getting it is how
	// work is lost.
	Enabled bool `json:"enabled"`
	// ReadOnly, when set, NARROWS this run's mount: true forces read-only even
	// on a writable allocation. Nil leaves the resolved allocation's own posture
	// in effect.
	//
	// FALSE IS NOT A NO-OP EVERYWHERE, and the difference matters to a caller
	// scripting a run: against a READ-ONLY allocation it is REFUSED (422) and
	// never silently honoured — a run the caller believes is writable would only
	// reveal itself when the work failed to persist. On a WRITABLE allocation it
	// is a no-op, since that is the posture already in force.
	//
	// The same direction WorkspaceSelection.ReadOnly enforces, and for the same
	// reason: a run-level option may only ever narrow what an admin granted.
	ReadOnly *bool `json:"read_only,omitempty"`
}

DriveSelection is the per-run user-drive option set. See CreateRunRequest.Drive.

type DrivesApplyResult added in v0.9.0 

type DrivesApplyResult struct {
	Document DrivesDocument `json:"document"`
	// Steps are the writes issued, in order, with their outcome.
	Steps []ApplyStep `json:"steps,omitempty"`
}

DrivesApplyResult is ApplyDrivesResult's answer.

type DrivesDocument added in v0.8.0 

type DrivesDocument struct {
	Drives              []UserDriveListItem `json:"drives"`
	Grants              []UserDriveGrant    `json:"grants"`
	HostRootsConfigured bool                `json:"host_roots_configured"`
	RunnerTarget        string              `json:"runner_target"`
	Disabled            bool                `json:"disabled"`
	GrantTotal          int                 `json:"grant_total"`
}

DrivesDocument is GET /drives's body and ApplyDrives's parameter: every registered drive, every allocation (GetDrives reads every page), and the deployment facts an operator cannot derive from the rows alone (whether host_path drives are even authorable here, which substrate this deployment dispatches to, and whether the org switch is off). `wardyn drive get` prints this verbatim; ApplyDrives strict-decodes it back — HostRootsConfigured, RunnerTarget, Disabled and GrantTotal are read-only and ignored on write.

type EffectOption added in v0.9.0 

type EffectOption struct {
	Effect    types.ToolEffect `json:"effect"`
	Available bool             `json:"available"`
	Reason    string           `json:"reason,omitempty"`
}

EffectOption is one effect a person may choose, or why they may not.

type EffectiveLimit added in v0.9.0 

type EffectiveLimit = types.EffectiveLimit

The canonical pool shapes, re-exported so SDK callers can name them.

type EffectiveRunLimits added in v0.9.0 

type EffectiveRunLimits = types.EffectiveRunLimits

The canonical pool shapes, re-exported so SDK callers can name them.

type EgressRedirect added in v0.5.0 

type EgressRedirect = types.EgressRedirect

EgressRedirect is one outbound redirect (package registry or otherwise), carried in SiteConfig.EgressRedirects. Aliased for the same reason as ArtifactOverride: GetSiteConfig returns a nil slice when unconfigured, so without a nameable element type a caller could not author one at all.

type ErasePersonResult added in v0.8.6 

type ErasePersonResult struct {
	// Person is the principal the name resolved to.
	Person string `json:"person"`
	// Scopes are the scopes erased, in the order they ran.
	Scopes []string `json:"scopes"`
	// Outcome is each scope's result: "done".
	Outcome map[string]string `json:"outcome"`
	// Detail is each scope's counts.
	Detail map[string]any `json:"detail"`
}

ErasePersonResult is what POST /api/v1/people/{principal}/erasure answers once every scope asked for is erased.

type Experience added in v0.9.0 

type Experience = types.RunExperience

Experience is the canonical run mode.

type GitPATOverride added in v0.9.0 

type GitPATOverride struct {
	Host   string    `json:"host"`
	Repos  *[]string `json:"repos,omitempty"`
	Access string    `json:"access,omitempty"`
	API    *bool     `json:"api,omitempty"`
}

GitPATOverride narrows one git_pat grant, found by its forge host. Each field that is set narrows: Repos to a subset, Access to read, API to false. A value that would widen the grant (access write, api true) is refused.

type GovernanceApplyResult added in v0.8.6 

type GovernanceApplyResult struct {
	// Document is a fresh GetGovernance after the apply: what is actually in
	// force, which excludes every pending write.
	Document GovernanceDocument `json:"document"`
	// Pending are the writes held for a second approver. Nothing in them is
	// applied until they are approved.
	Pending []GovernanceChange `json:"pending,omitempty"`
	// Deferred are the assignments not sent because the profile they name has
	// a pending write. Apply again once that change is approved.
	Deferred []GovernanceDeferredWrite `json:"deferred,omitempty"`
	// PruneSkipped is true when prune was requested and did not run to
	// completion because a write was pending.
	PruneSkipped bool `json:"prune_skipped,omitempty"`
	// Steps are the writes issued, in order, with their outcome. Unchanged
	// items are omitted.
	Steps []ApplyStep `json:"steps,omitempty"`
}

GovernanceApplyResult is ApplyGovernanceResult's answer.

type GovernanceAssignment added in v0.8.0 

type GovernanceAssignment = types.GovernanceAssignment

GovernanceAssignment binds one profile to one subject (GovernanceDocument.Assignments). Returned by GetGovernance and ApplyGovernance.

type GovernanceAssignmentRequest added in v0.8.0 

type GovernanceAssignmentRequest struct {
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	ProfileID   uuid.UUID             `json:"profile_id"`
	Priority    int                   `json:"priority"`
}

GovernanceAssignmentRequest is POST /governance/assignments's body. There is no PUT for an assignment: the natural key (subject_type, subject) upserts, repointing an existing binding rather than accumulating a second one, the same shape DriveGrantRequest already takes for a drive allocation.

type GovernanceChange added in v0.8.6 

type GovernanceChange struct {
	ID         uuid.UUID            `json:"id"`
	TargetKind string               `json:"target_kind"`
	Op         string               `json:"op"`
	TargetKey  string               `json:"target_key"`
	State      string               `json:"state"`
	ProposedBy string               `json:"proposed_by"`
	ProposedAt time.Time            `json:"proposed_at"`
	ExpiresAt  time.Time            `json:"expires_at"`
	Diff       GovernanceChangeDiff `json:"diff"`
}

GovernanceChange is one governance write held for a second approver: the body of a 202's pending_change, and the row the /governance/changes routes list, approve and reject. State is pending, applied, rejected, expired or stale.

type GovernanceChangeDiff added in v0.8.6 

type GovernanceChangeDiff struct {
	Before  json.RawMessage `json:"before,omitempty"`
	After   json.RawMessage `json:"after,omitempty"`
	Changed []string        `json:"changed,omitempty"`
}

GovernanceChangeDiff is a pending change's server-rendered diff: the target's current and proposed rows (both redacted for read) and the changed field paths. The client never computes its own.

type GovernanceDeferredWrite added in v0.8.6 

type GovernanceDeferredWrite struct {
	SubjectType CapabilitySubjectType `json:"subject_type"`
	Subject     string                `json:"subject"`
	// Profile is the pending profile's name.
	Profile string `json:"profile"`
	// Base is set when the deferred write is a PROFILE rather than an assignment: Profile is the
	// child that was not sent, Base the profile it composes on whose write is pending.
	Base string `json:"base,omitempty"`
}

GovernanceDeferredWrite is a write ApplyGovernanceResult did not send because the profile it names (an assignment's profile, or a child profile's base) has a write pending approval. Apply again once that change is approved.

type GovernanceDocument added in v0.8.0 

type GovernanceDocument struct {
	Profiles    []GovernanceProfile    `json:"profiles"`
	Assignments []GovernanceAssignment `json:"assignments"`
}

GovernanceDocument is GET /governance's body and ApplyGovernance's parameter: every profile plus every assignment. `wardyn governance get` prints this verbatim; ApplyGovernance strict-decodes it back.

type GovernanceLimits added in v0.8.0 

type GovernanceLimits = types.GovernanceLimits

GovernanceLimits carries the request-shape autonomy switches a GovernanceProfile bounds a principal by, carried in GovernanceProfile.Limits. Aliased so a caller can author one through GovernanceProfileRequest.

type GovernancePlan added in v0.9.0 

type GovernancePlan struct {
	Steps       []ApplyStep `json:"steps"`
	Unchanged   int         `json:"unchanged"`
	Destructive bool        `json:"destructive"` // true when any step is a delete
}

GovernancePlan is PlanGovernance's answer. Steps is never null.

type GovernanceProfile added in v0.8.0 

type GovernanceProfile = types.GovernanceProfile

GovernanceProfile is one named, assignable ceiling (migration 0052's governance_profiles row), carried in GovernanceDocument.Profiles. Returned by GetGovernance and ApplyGovernance.

type GovernanceProfileRequest added in v0.8.0 

type GovernanceProfileRequest struct {
	Name    string           `json:"name"`
	Ceiling RunPolicySpec    `json:"ceiling"`
	Limits  GovernanceLimits `json:"limits"`
	// Contact is who owns the profile and how a person it refuses asks for a
	// change. nil leaves the stored contact unchanged (an older caller that
	// never sets it cannot wipe it); a pointer to an empty Contact clears it.
	Contact *PolicyContact `json:"contact,omitempty"`
	// BaseProfileID, Overlay and OverlayLimits are a composed profile's members. Left nil they are
	// omitted, which keeps the stored value; ApplyGovernance sets each to an explicit JSON null when
	// it must clear one, so a repeat apply reproduces the document and not a merge of it.
	BaseProfileID json.RawMessage `json:"base_profile_id,omitempty"`
	Overlay       json.RawMessage `json:"overlay,omitempty"`
	OverlayLimits json.RawMessage `json:"overlay_limits,omitempty"`
}

GovernanceProfileRequest is the POST /governance/profiles / PUT /governance/profiles/{id} body — one named ceiling. ID/CreatedAt/UpdatedAt/ CreatedBy are never accepted from the wire, matching DriveRequest: the id comes from the path (an update) or the server (a create), and provenance is always server-assigned.

type GovernanceProfileResponse added in v0.8.0 

type GovernanceProfileResponse struct {
	Profile  GovernanceProfile `json:"profile"`
	Warnings []string          `json:"warnings,omitempty"`
}

GovernanceProfileResponse is a profile write's body: the saved profile plus any omission warnings the write raised (a ceiling grant the deployment no longer provisions — see internal/api/governance.go's reintersect note).

type GrantKind 

type GrantKind = types.GrantKind

GrantKind enumerates broker-mintable credential kinds (GrantSpec.Kind).

type GrantSpec 

type GrantSpec = types.GrantSpec

GrantSpec is a credential scope description carried in RunPolicySpec.EligibleGrants.

type HarnessFact added in v0.9.0 

type HarnessFact struct {
	ID     string `json:"id"`
	Starts bool   `json:"starts"`
	// ModelCredential is this harness's provider, kind and residency; absent when
	// the harness takes none or its choice is still open.
	ModelCredential *HarnessModelCredential `json:"model_credential,omitempty"`
}

HarnessFact is one included harness: whether it starts with the run, and the model credential it gets.

type HarnessModelCredential added in v0.9.0 

type HarnessModelCredential struct {
	Provider  string `json:"provider"`
	Kind      string `json:"kind"`
	Residency string `json:"residency"`
}

HarnessModelCredential is one harness's model credential: its provider, the provider's kind, and where the credential lands (proxy or sandbox).

type HarnessSetFact added in v0.9.0 

type HarnessSetFact struct {
	Harnesses []HarnessFact `json:"harnesses"`
	// SharedModelAccess: two or more harnesses carry a model credential. The
	// proxy injects each by destination host, so any process in the sandbox can
	// use each one.
	SharedModelAccess bool `json:"shared_model_access"`
}

HarnessSetFact is the run's included harnesses as this door resolved them. Absent for an older client's request and for a run with no harness.

type HomeTemplate added in v0.8.0 

type HomeTemplate = types.HomeTemplate

HomeTemplate names which identity a drive's per-user home name is derived from (DriveRequest.HomeTemplate, UserDrive.HomeTemplate).

type ImageBuild added in v0.9.0 

type ImageBuild = types.ImageBuild

ImageBuild is a workspace's image-build record: the inputs and the image it produced. Carried by WorkspaceBuild.Record.

type ImageFact added in v0.9.0 

type ImageFact struct {
	Ref    string      `json:"ref"`
	Source ImageSource `json:"source"`
}

ImageFact is the image the run would start from, as the door resolved it. A door that has not resolved one sends none.

type ImageSource added in v0.9.0 

type ImageSource struct {
	Kind string `json:"kind"`
	Name string `json:"name,omitempty"`
}

ImageSource says where the resolved image comes from, so the Runner tab can say "from {source}". Name is the workspace, the build, the allowed entry, the harness (agent) or the declared set's key (harness_set); it is empty for base.

type IncludedTool added in v0.9.0 

type IncludedTool struct {
	// ID names the instance, once per request. For a harness it is the agent
	// name; it is the key Startup.Tool, the approval broker and the per-harness
	// rules all use.
	ID   string           `json:"id"`
	Kind IncludedToolKind `json:"kind"`
	// ModelProvider is a harness's model provider (GET /model-providers, by id).
	// Empty takes the same defaults a run's model_provider does.
	ModelProvider string `json:"model_provider,omitempty"`
	// Component is a component tool's reference and its bounded configuration.
	Component *ComponentRef `json:"component,omitempty"`
	// ToolRules are this harness's tool rules, in the language of a policy's
	// tool_rules, and DefaultEffect its own "*" effect. The approval broker
	// evaluates the rules of the harness that raised the call.
	ToolRules     []types.ToolRule `json:"tool_rules,omitempty"`
	DefaultEffect types.ToolEffect `json:"default_effect,omitempty"`
}

IncludedTool is one tool instance the run includes. Including a tool is not starting it and grants it no credential: each tool carries its own model provider or configuration, its own tool rules and its own default effect, so independent tools never share one selection.

type IncludedToolKind added in v0.9.0 

type IncludedToolKind string

IncludedToolKind says what an included tool is. 

const (
	// IncludedToolHarness is an agent harness; its ID is its agent name.
	IncludedToolHarness IncludedToolKind = "harness"
	// IncludedToolComponent is a component with a bounded configuration.
	IncludedToolComponent IncludedToolKind = "component"
)

type Invitation added in v0.9.0 

type Invitation = types.Invitation

Invitation lets one named person mint their own API token (ListInvitations, ClaimInvitation); InvitationState is its derived state.

type InvitationState added in v0.9.0 

type InvitationState = types.InvitationState

Domain nouns returned or accepted by Client methods.

type KillRunResponse 

type KillRunResponse struct {
	ID    uuid.UUID      `json:"id"`
	State types.RunState `json:"state"`
}

KillRunResponse is the body returned by POST /api/v1/runs/{id}/kill.

type LimitAmount added in v0.9.0 

type LimitAmount = types.LimitAmount

The canonical pool shapes, re-exported so SDK callers can name them.

type LimitSource added in v0.9.0 

type LimitSource = types.LimitSource

The canonical pool shapes, re-exported so SDK callers can name them.

type ListOpts added in v0.3.1 

type ListOpts struct {
	Limit  int
	Offset int
}

ListOpts carries the server's ?limit=&offset= pagination for the list and audit endpoints. The zero value sends nothing, so the server applies its default page size. Methods take it variadically; pass at most one.

type LocalPlacementFact added in v0.9.0 

type LocalPlacementFact struct {
	// Kind is host, source or component; Key is the host, the workspace
	// source's id or the component's fact id.
	Kind string `json:"kind"`
	Key  string `json:"key"`
	// LocalPlaceable is false when the runner cannot honour the entry.
	LocalPlaceable bool `json:"local_placeable"`
	// Reason is the placement refusal reason that applies when it is false.
	Reason placement.Reason `json:"reason,omitempty"`
}

LocalPlacementFact says whether one entry of the run can be placed on the person's own runner. An entry with no row has not been evaluated; the answers come from the placement lane, so an older server sends none.

type LockedToolRule added in v0.9.0 

type LockedToolRule struct {
	Tool   string           `json:"tool"`
	Effect types.ToolEffect `json:"effect"`
	Source ProvenanceSource `json:"source"`
}

LockedToolRule is a rule the policy sets and the person cannot change.

type MCPView added in v0.9.0 

type MCPView struct {
	URL       string `json:"url"`
	Transport string `json:"transport"`
}

MCPView is the non-secret face of an MCP server row.

type MainDriveApplied added in v0.9.0 

type MainDriveApplied struct {
	// RequestedMiB is the request's own size; absent when it sent none.
	RequestedMiB int `json:"requested_mib,omitempty"`
	// AppliedMiB is what the run gets; 0 is no size, unbounded scratch.
	AppliedMiB int            `json:"applied_mib"`
	Basis      MainDriveBasis `json:"basis"`
	// DefaultSource names the limit whose default sized the run, with basis default.
	DefaultSource LimitSource `json:"default_source,omitempty"`
	// ClampedBy names what cut the size, when something did.
	ClampedBy MainDriveClampSource `json:"clamped_by,omitempty"`
	// Soft is true when a runner that cannot cap disk starts the run uncapped. A size
	// the run's policy writes is never soft.
	Soft bool `json:"soft"`
}

MainDriveApplied is the main-drive size the dry doors say a run gets: the same number dispatch creates the sandbox with.

type MainDriveBasis added in v0.9.0 

type MainDriveBasis string

MainDriveBasis says where a run's main-drive size came from. 

const (
	MainDriveBasisRequest MainDriveBasis = "request" // the run's own request
	MainDriveBasisPolicy  MainDriveBasis = "policy"  // a size the run's policy writes
	MainDriveBasisDefault MainDriveBasis = "default" // the pool's or the server's default
	MainDriveBasisNone    MainDriveBasis = "none"    // no size: unbounded scratch
)

The bases of MainDriveApplied.

type MainDriveClampSource added in v0.9.0 

type MainDriveClampSource string

MainDriveClampSource says what cut a main-drive size. 

const (
	MainDriveClampPool       MainDriveClampSource = "pool"
	MainDriveClampGovernance MainDriveClampSource = "governance"
	MainDriveClampDeployment MainDriveClampSource = "deployment"
	MainDriveClampPolicy     MainDriveClampSource = "policy"
)

The clamp sources of MainDriveApplied.

type MainDriveCoverage added in v0.9.0 

type MainDriveCoverage string

MainDriveCoverage is how much of the sandbox the enforced size covers.

type MainDriveEnforcement added in v0.9.0 

type MainDriveEnforcement string

MainDriveEnforcement is how a pool binds a run's main-drive size. Never request or external.

type MainDriveFacts added in v0.9.0 

type MainDriveFacts struct {
	// Enforcement is the WEAKEST word across the targets; unknown when any target's is unknown (offline,
	// never reported, or no target at all).
	Enforcement MainDriveEnforcement `json:"enforcement"`
	// Basis is substrate (a remote-hosted runner) or runner_asserted (a self-hosted runner's own report).
	Basis types.RunEvidenceSource `json:"basis"`
	// Coverage is absent when enforcement is none or unknown.
	Coverage MainDriveCoverage `json:"coverage,omitempty"`
	// Keep is what happens to an Interactive run's sandbox at its end time.
	Keep MainDriveKeep `json:"keep"`
	// DriveMounts: the pool's runners can mount drives at all (false for a user pool).
	DriveMounts bool `json:"drive_mounts"`
}

MainDriveFacts is what a pool's runners do with the main drive, over the caller's eligible targets.

type MainDriveKeep added in v0.9.0 

type MainDriveKeep struct {
	Supported bool `json:"supported"`
	GraceSec  int  `json:"grace_sec,omitempty"` // set only when Supported
}

MainDriveKeep: every target keeps a stopped sandbox and the deployment's ended-run grace is above zero.

type ManagedSettingsFact added in v0.9.0 

type ManagedSettingsFact struct {
	Path     string `json:"path"`
	Document string `json:"document"`
	// Locked is the B-P2 variant that adds the managed-only locks; LockedBy is
	// profile or organisation, and Profile names the profile.
	Locked   bool   `json:"locked,omitempty"`
	LockedBy string `json:"locked_by,omitempty"`
	Profile  string `json:"profile,omitempty"`
}

ManagedSettingsFact is the exact frozen managed-settings document Wardyn writes for the resolved autonomy level (OD-2). Read-only: Document is the bytes agentpolicy.ForAgent returns.

type MeDrive added in v0.9.0 

type MeDrive struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Section is user (a managed backend) or shared (a share backend).
	Section string `json:"section"`
	// Source is the tier of the grant that wins this drive for the caller:
	// personal (a user grant), team (a group grant) or organisation (an all or
	// user type grant).
	Source  string             `json:"source"`
	Backend types.DriveBackend `json:"backend"`
	// Target is where the drive mounts, derived by the server.
	Target string `json:"target"`
	// Writable is the grant's resolved posture; a run may only narrow it.
	Writable    bool                     `json:"writable"`
	SizeMiB     int                      `json:"size_mib,omitempty"`
	Enforcement types.StorageEnforcement `json:"enforcement"`
	// Legacy marks the drive drive.enabled mounts at /home/agent/drive: the
	// caller's top-ranked grant.
	Legacy bool `json:"legacy"`
	// UnavailableReason is why a run cannot attach this drive now: paused,
	// unmountable or not_in_pool. "" when it can.
	UnavailableReason string `json:"unavailable_reason,omitempty"`
	// Owned is true for a drive the caller created (POST /me/drives). Only an
	// owned drive takes DELETE /me/drives/{id}.
	Owned bool `json:"owned"`
}

MeDrive is one drive of the catalogue.

type MeDriveCatalogue added in v0.9.0 

type MeDriveCatalogue struct {
	// Drives is never null. It is empty when nothing is granted, when a
	// profile shuts the door (DeniedByProfile) or when the catalogue could not
	// be answered (Unavailable).
	Drives []MeDrive `json:"drives"`
	// DeniedByProfile names the governance profile whose deny_user_drive
	// shuts the door for the caller.
	DeniedByProfile string `json:"denied_by_profile,omitempty"`
	// Unavailable is why the catalogue could not be answered:
	// groups_snapshot_stale, user_type_unknown, unavailable or
	// governance_unavailable (the /me.user_drive_unavailable tokens).
	Unavailable string `json:"unavailable,omitempty"`
	// PoolChecked is true when runner_pool_id named a pool the caller may use,
	// so UnavailableReason includes not_in_pool. False for no pool and for one
	// the caller cannot use; the pool is checked again at launch.
	PoolChecked bool `json:"pool_checked"`
	// Create is whether the caller may create a drive now (POST /me/drives).
	// Absent when the caller is not a person: a device, a delegated caller,
	// SCIM, a service identity, the admin token or local mode.
	Create *MemberDriveCreate `json:"create,omitempty"`
}

MeDriveCatalogue is GET /api/v1/me/drives: every drive the caller's own grants reach, the ones a run may attach through CreateRunRequest.Drives. Nothing here names a host path, a storage object or another person.

type MemberDriveAdminItem added in v0.9.0 

type MemberDriveAdminItem struct {
	ID           uuid.UUID          `json:"id"`
	Name         string             `json:"name"`
	Owner        string             `json:"owner"`
	Backend      types.DriveBackend `json:"backend"`
	SizeMiB      int                `json:"size_mib,omitempty"`
	StorageClass string             `json:"storage_class,omitempty"`
	// Object is the Docker volume or claim name the drive stores into.
	Object    string    `json:"object"`
	CreatedAt time.Time `json:"created_at"`
	// Deleting is true while a delete of the drive is in flight.
	Deleting bool `json:"deleting"`
}

MemberDriveAdminItem is one person's drive in GET /api/v1/drives/member.

type MemberDriveCreate added in v0.9.0 

type MemberDriveCreate struct {
	Allowed bool `json:"allowed"`
	// Reason is set exactly when Allowed is false.
	Reason MemberDriveCreateReason `json:"reason,omitempty"`
	// DeniedByProfile names the profile, with reason denied_by_profile.
	DeniedByProfile string `json:"denied_by_profile,omitempty"`
	// Count is the caller's drives, one being deleted included.
	Count int `json:"count"`
	// Limit is the switch's drives per person; 0 when the switch is off.
	Limit int `json:"limit"`
}

MemberDriveCreate is the catalogue's create availability, decided by the same gates as POST /me/drives except the name.

type MemberDriveCreateReason added in v0.9.0 

type MemberDriveCreateReason string

MemberDriveCreateReason is why a person cannot create a drive now. Closed; the TS twin is MemberDriveCreateReason in ui/src/app/lib/api/me-drives.ts. 

const (
	// MemberDriveCreateDisabled: the org switch is off, or drives are off.
	MemberDriveCreateDisabled MemberDriveCreateReason = "disabled"
	// MemberDriveCreateDeniedByProfile: deny_member_drives or deny_user_drive.
	MemberDriveCreateDeniedByProfile MemberDriveCreateReason = "denied_by_profile"
	// MemberDriveCreateLimitReached: Count has reached Limit.
	MemberDriveCreateLimitReached MemberDriveCreateReason = "limit_reached"
	// MemberDriveCreateUnsupported: no managed backend for this deployment.
	MemberDriveCreateUnsupported MemberDriveCreateReason = "unsupported"
	// MemberDriveCreateDeleteUnavailable: the substrate could not delete one.
	MemberDriveCreateDeleteUnavailable MemberDriveCreateReason = "delete_unavailable"
	// MemberDriveCreateGovernance: the caller's governance could not be read.
	MemberDriveCreateGovernance MemberDriveCreateReason = "governance_unavailable"
	// MemberDriveCreateGroupsStale: the caller's group snapshot is stale.
	MemberDriveCreateGroupsStale MemberDriveCreateReason = "groups_snapshot_stale"
)

type MemberDriveCreateRequest added in v0.9.0 

type MemberDriveCreateRequest struct {
	// Name is 1 to 128 characters with at least one letter or digit, unique
	// among the drives the caller can use.
	Name string `json:"name"`
}

MemberDriveCreateRequest is POST /api/v1/me/drives: a person creates their own drive. The server picks the backend, the size and the mount path.

type MemberDriveDeleteResult added in v0.9.0 

type MemberDriveDeleteResult struct {
	Drive   string             `json:"drive"`
	DriveID uuid.UUID          `json:"drive_id"`
	Owner   string             `json:"owner"`
	Backend types.DriveBackend `json:"backend"`
	Object  string             `json:"object"`
	Outcome string             `json:"outcome"`
}

MemberDriveDeleteResult is DELETE /api/v1/drives/member/{id}'s answer: the same facts its drive.member.delete audit row carries. Outcome is deleted or already_absent.

type MemberDriveList added in v0.9.0 

type MemberDriveList struct {
	Drives []MemberDriveAdminItem `json:"drives"`
	Total  int                    `json:"total"`
}

MemberDriveList is GET /api/v1/drives/member: one page of every person's drives, by owner then name, and how many there are in all.

type MintServiceTokenRequest added in v0.9.0 

type MintServiceTokenRequest struct {
	Name string `json:"name"`
	// TTLSeconds is at most 90 days, or the deployment's cap if lower; zero takes that longest lifetime.
	TTLSeconds int64 `json:"ttl_seconds,omitempty"`
}

MintServiceTokenRequest is the POST /api/v1/me/service-identities/{name}/tokens body. internal/api aliases it (serviceTokenRequest).

type ModelProvider added in v0.8.0 

type ModelProvider = types.ModelProvider

Domain nouns returned or accepted by Client methods.

type ModelProviderKind added in v0.8.0 

type ModelProviderKind = types.ModelProviderKind

Domain nouns returned or accepted by Client methods.

type ModelProviders added in v0.8.0 

type ModelProviders = types.ModelProviders

ModelProviders is the admin's model-provider configuration, carried in SiteConfig.ModelProviders; the types below are its parts. Aliased so a caller can author the block through PutSiteConfig. Configuration only: no credential lives on a record.

type ModelProvidersRead added in v0.9.0 

type ModelProvidersRead = types.ModelProvidersRead

ModelProvidersRead is GetModelProviders' answer: the block plus how many people hold a credential of their own per provider. Counts only, never a credential.

type MoveTokenRequest added in v0.9.0 

type MoveTokenRequest struct {
	ServiceIdentity string `json:"service_identity"`
}

MoveTokenRequest is the POST /api/v1/tokens/{id}/move body. internal/api aliases it (moveTokenRequest).

type MyComponents added in v0.8.9 

type MyComponents struct {
	// MayDefine is whether the caller may define their own components.
	MayDefine bool `json:"may_define"`
	// ResidentDeliveryAllowed is false when the deployment refuses environment and
	// file delivery for every component.
	ResidentDeliveryAllowed bool `json:"resident_delivery_allowed"`
	// AutonomyCap is the level an unattended run carrying a component of one's own
	// is held to; empty means no cap.
	AutonomyCap AutonomyLevel `json:"autonomy_cap"`
	// Mine are the caller's saved components, by name.
	Mine []Component `json:"mine"`
	// Org are the organisation components the caller is granted, by name.
	Org []OrgComponentView `json:"org"`
	// CLIs is always five cards in a fixed order. Its sentence for a card with no
	// granted row never depends on whether an ungranted row exists.
	CLIs []CatalogueCLI `json:"clis"`
}

MyComponents answers GET /api/v1/me/components: what the caller may do with components, the ones they saved, and the organisation's they are granted.

type OrgComponentView added in v0.8.9 

type OrgComponentView struct {
	ID         uuid.UUID             `json:"id"`
	Name       string                `json:"name"`
	Hosts      []string              `json:"hosts"`
	Secrets    []ComponentSecretView `json:"secrets"`
	ConfigKeys []string              `json:"config_keys"`
	// Category is what kind of card the row is: cli, mcp or api (neither block).
	Category string   `json:"category"`
	CLI      *CLIView `json:"cli,omitempty"`
	MCP      *MCPView `json:"mcp,omitempty"`
}

OrgComponentView is an organisation component as a person granted it sees it: where it reaches and how, with no secret names and no config values.

type OverrideItem added in v0.9.0 

type OverrideItem struct {
	Kind    types.OverrideKind
	Op      types.OverrideOp
	Subject string
}

OverrideItem is one edit of a RunOverrides, in the narrowing table's terms. Subject names what is edited, for a sentence the caller can act on.

type OverrideKind added in v0.9.0 

type OverrideKind = types.OverrideKind

Domain nouns returned or accepted by Client methods.

type OverrideOp added in v0.9.0 

type OverrideOp = types.OverrideOp

Domain nouns returned or accepted by Client methods.

type PendingApprovalError added in v0.8.6 

type PendingApprovalError struct {
	// Changes are the writes held for approval.
	Changes []GovernanceChange
	// Deferred are the apply's writes that depend on a pending one and were
	// not sent (ApplyGovernance only).
	Deferred []GovernanceDeferredWrite
	// PruneSkipped is true when prune was requested and did not run to
	// completion because a write was pending (ApplyGovernance only).
	PruneSkipped bool
}

PendingApprovalError is returned when a write was held for a second approver instead of applied (the server answered 202 with a pending_change). It is not a failure of the request: nothing is applied until the change is approved (ApproveGovernanceChange, or `wardyn governance changes approve`).

func (*PendingApprovalError) Error added in v0.8.6 

func (e *PendingApprovalError) Error() string

type PeopleListOpts added in v0.8.6 

type PeopleListOpts struct {
	// Limit is the page size: 50 when zero, at most 200.
	Limit int
	// Cursor is the NextCursor of the previous page.
	Cursor string
	// Query keeps people whose principal or email starts with it.
	Query string
	// State is "active" or "deactivated"; empty keeps both.
	State string
}

PeopleListOpts narrows and pages ListPeople. The zero value is the first page of everyone.

type PersonAllowance added in v0.9.0 

type PersonAllowance struct {
	// Active is every non-terminal run the caller created, in any pool.
	Active int `json:"active"`
	// Max is the profile's max_concurrent_runs; absent means no personal limit.
	Max         *int   `json:"max,omitempty"`
	ProfileName string `json:"profile_name,omitempty"`
}

PersonAllowance is the caller's own concurrent runs against their governance limit: counts only.

type PersonList added in v0.8.6 

type PersonList = types.PersonList

Domain nouns returned or accepted by Client methods.

type PersonSummary added in v0.8.6 

type PersonSummary = types.PersonSummary

PersonSummary is one row of ListPeople; PersonList is one page of it.

type Placement added in v0.9.0 

type Placement = placement.Placement

Placement says where a run's sandbox lives: PlacementRemote, the organisation's own executor, or PlacementLocal, a runner the person registered. The console calls the field "Runs on".

type PlacementMode added in v0.9.0 

type PlacementMode = placement.Mode

PlacementMode is how an organisation-held credential reaches a local run (own, via_org, runner_resident or refuse); PlacementReason is the machine-readable reason a placement is refused.

type PlacementReason added in v0.9.0 

type PlacementReason = placement.Reason

Domain nouns returned or accepted by Client methods.

type PolicyContact added in v0.8.6 

type PolicyContact = policyref.Contact

PolicyContact is the contact a GovernanceProfile (and SiteConfig.PolicyHelp) publishes: owner, email, request_url and request_text, validated by the server on write.

type PolicyRef added in v0.8.6 

type PolicyRef = policyref.Ref

PolicyRef is the policy a ceiling refusal names: the leaf profile (or the deployment) that bound the caller, plus the contact it published. APIError.Policy carries one.

type PolicyRequest 

type PolicyRequest struct {
	Name string              `json:"name"`
	Spec types.RunPolicySpec `json:"spec"`
}

PolicyRequest is the body for POST/PUT /api/v1/policies. Name is required; Spec is validated server-side before persistence (a bad spec is rejected with 400, fail closed).

type PolicySaved added in v0.8.9 

type PolicySaved struct {
	types.RunPolicy
	Requirements []ComponentRequirement `json:"requirements"`
}

PolicySaved is what POST /api/v1/policies and PUT /api/v1/policies/{id} answer: the stored policy and the stored secrets its grants name, each present or missing in the saver's namespace. The list is advisory, never a refusal.

type PoolCapacity added in v0.9.0 

type PoolCapacity struct {
	Total         types.RunnerTally   `json:"total"`
	InUse         types.RunnerTally   `json:"in_use"`
	Available     types.RunnerTally   `json:"available"`
	LargestPerRun types.RunnerAmounts `json:"largest_per_run"`
	Runners       int                 `json:"runners"`
	RunnersOnline int                 `json:"runners_online"`
}

PoolCapacity is a pool's runners added up, numbers only and never saying whose runs they are. Total and InUse add every member that declares limits; Available adds only those that are online, and is zero for a pool that is switched off. LargestPerRun is the biggest run any such member takes. Runners counts the members, RunnersOnline those that can take a run now.

type PoolDefault added in v0.9.0 

type PoolDefault struct {
	PoolID    *uuid.UUID          `json:"pool_id,omitempty"`
	Selection RunnerPoolSelection `json:"selection,omitempty"`
	Reason    RunnerPoolReason    `json:"reason,omitempty"`
}

PoolDefault is the pool a run that names none resolves to (runnerpool.Resolve), or, with Reason runner_pool_default_unavailable, the default that no longer applies and whose it was.

type PoolRunner added in v0.9.0 

type PoolRunner struct {
	ID     uuid.UUID `json:"id"`
	Name   string    `json:"name"`
	Online bool      `json:"online"`
}

PoolRunner is one of the caller's own self-hosted runners in a user pool.

type PoolSlots added in v0.9.0 

type PoolSlots struct {
	// Used is the runs holding one of the pool's slots; Waiting the runs queued for one.
	Used    int `json:"used"`
	Waiting int `json:"waiting"`
	// Max is the pool's max_concurrent_runs; absent means no pool limit.
	Max *int `json:"max,omitempty"`
	// Verdict is SlotsWaits when the pool has a limit and is at it or has runs waiting, else SlotsStartsNow.
	Verdict string `json:"verdict"`
	// MaxWaitSec is how long a run of that type waits by default: 86400 Background, 3600 Interactive.
	MaxWaitSec int `json:"max_wait_sec,omitempty"`
}

PoolSlots is a pool's slot counts, everyone's and never saying whose. On the pool list MaxWaitSec is set only when ?run_type= is asked; on preflight and the policy preview it is the run's own.

type PreflightItem added in v0.4.4 

type PreflightItem struct {
	Kind       string `json:"kind"`
	ID         string `json:"id"`
	Label      string `json:"label"`
	RequiredBy string `json:"required_by"`
	Status     string `json:"status"` // "satisfied" | "missing" | "unverified"
	Detail     string `json:"detail,omitempty"`
}

PreflightItem is one row of the preflight setup checklist: something the run needs, and whether it is already satisfied. Only the fields callers render are modeled — the full server row additionally carries a structured UI "fix" action and a credential-residency label.

type PreflightResult added in v0.4.4 

type PreflightResult struct {
	SetupItems               []PreflightItem        `json:"setup_items"`
	EnforcedConfinementClass types.ConfinementClass `json:"enforced_confinement_class"`
	// Warnings carries resolveRunPolicy's clamp notes — a member's silently
	// narrowed inline policy, a filtered grant. The same list rides
	// CreateRunResult.Warnings at launch, so a preview and the real thing say
	// the same words about the same drop.
	Warnings []string `json:"warnings,omitempty"`
	// Components is what the run is given access to: its agent, the Git
	// providers its repositories live on and its attached components. Absent
	// for a run with none of them.
	Components []ComponentFact `json:"components,omitempty"`
	// Provenance explains which source contributed each resolved policy entry.
	Provenance []ProvenanceEntry `json:"provenance"`
	// Limits is what this run may get: the resolved pool's, the person's
	// governance and the deployment's limits for the run's type, folded.
	// ResourcesApplied is the CPU and memory it asked for and would get.
	Limits           *EffectiveRunLimits `json:"limits,omitempty"`
	ResourcesApplied *AppliedResources   `json:"resources_applied,omitempty"`
	// MainDrive is the main-drive size it asked for and would get, with its basis.
	MainDrive *MainDriveApplied `json:"main_drive,omitempty"`
	// LocalPlacement says per host, workspace source and component whether the
	// person's runner can honour it. Empty until the placement lane fills it.
	LocalPlacement []LocalPlacementFact `json:"local_placement"`
	// Image is the image the run would start from and where it comes from;
	// absent until the image lane resolves it. AllowedImages are the images the
	// organisation lets the person choose; empty until that lane fills it.
	Image         *ImageFact     `json:"image,omitempty"`
	AllowedImages []AllowedImage `json:"allowed_images"`
	// RunnerPool is the pool the request resolves to and how it was chosen;
	// absent until the pool lane resolves one. RunnerPools are the pools the
	// person may choose, each with whether it is available; empty until that
	// lane fills it. Neither is admission: a launch re-checks both.
	RunnerPool  *ResolvedRunnerPool `json:"runner_pool,omitempty"`
	RunnerPools []RunnerPoolChoice  `json:"runner_pools"`
	// BarrierOptions are the resolved pool's three barriers under this draft's
	// floors (policy_floor and access_floor appear only here); empty when unpooled.
	BarrierOptions []BarrierOption `json:"barrier_options"`
	// RunnerPoolSlots is the resolved pool's slot counts, with the run's max_wait_sec; absent when
	// unpooled. Advisory: the launch decides.
	RunnerPoolSlots *PoolSlots `json:"runner_pool_slots,omitempty"`
	// Access is what the run brings in: its rows, hosts, credentials, the line
	// for an unlisted host and the setup still needed. The policy preview
	// answers the same block for the same request.
	Access *AccessFacts `json:"access,omitempty"`
}

PreflightResult is the decoded POST /api/v1/runs/preflight reply: the setup checklist plus the confinement class the run would ACTUALLY enforce after the policy floor and blast-radius raise.

type Preset added in v0.8.0 

type Preset struct {
	Name        string `json:"name"`
	Version     int    `json:"version"`
	Description string `json:"description,omitempty"`
	// UserTypes narrows who may list and launch the preset to these user
	// types; empty is every type. Admins see and launch every preset.
	UserTypes []string `json:"user_types"`
	// Request is the stored create-run body. It may not carry the
	// per-launch fields (title, task) or a preset of its own.
	Request   CreateRunRequest `json:"request"`
	CreatedAt time.Time        `json:"created_at"`
	UpdatedAt time.Time        `json:"updated_at"`
	CreatedBy string           `json:"created_by,omitempty"`
	UpdatedBy string           `json:"updated_by,omitempty"`
}

Preset is one launch preset: an admin-managed, named bundle of existing CreateRunRequest fields a launcher names (CreateRunRequest.Preset) instead of sending the whole spec. The server expands it and runs the unchanged create path, so the caller's own ceiling, capabilities, secrets and drive apply exactly as they would to Request sent explicitly. Version, the timestamps and the author fields are read-only.

type PresetRequest added in v0.8.0 

type PresetRequest struct {
	Description string           `json:"description,omitempty"`
	UserTypes   []string         `json:"user_types,omitempty"`
	Request     CreateRunRequest `json:"request"`
}

PresetRequest is the PUT /api/v1/presets/{name} body.

type PresetsDocument added in v0.8.0 

type PresetsDocument struct {
	Presets []Preset `json:"presets"`
}

PresetsDocument is GET /api/v1/presets's body and ApplyPresets's parameter: `wardyn preset get` prints it and `wardyn preset set` reads it back.

type ProfileResult added in v0.3.1 

type ProfileResult struct {
	Proposed struct {
		InlinePolicy RunPolicySpec `json:"inline_policy"`
	} `json:"proposed"`
	OverallRisk  string `json:"overall_risk"`
	Observations struct {
		Domains []struct {
			Host    string   `json:"host"`
			Methods []string `json:"methods"`
		} `json:"domains"`
		Anomalies []string `json:"anomalies"`
	} `json:"observations"`
	Warnings []string `json:"warnings"`
}

ProfileResult is the decoded POST /api/v1/runs/{id}/profile/synthesize reply (Recording Mode): the synthesized least-privilege sandbox profile plus the observations it was built from. Only the fields callers render/save are modeled — the full server response (profileResponse) additionally carries a per-item risk breakdown the SDK does not surface.

type ProvenanceEntry added in v0.9.0 

type ProvenanceEntry struct {
	Field  string           `json:"field"`
	Value  string           `json:"value"`
	Source ProvenanceSource `json:"source"`
	Effect string           `json:"effect"`
}

ProvenanceEntry explains one redaction-safe policy entry in preflight. Effect is added, clamped, narrowed or removed; readers tolerate future values.

type ProvenanceSource added in v0.9.0 

type ProvenanceSource struct {
	Kind string `json:"kind"`
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

ProvenanceSource identifies the source of one resolved policy entry. Unknown kinds must not be presented as a known source.

type ProviderAuth added in v0.8.0 

type ProviderAuth = types.ProviderAuth

Domain nouns returned or accepted by Client methods.

type ProviderHarness added in v0.8.0 

type ProviderHarness = types.ProviderHarness

Domain nouns returned or accepted by Client methods.

type PushContentScope added in v0.8.0 

type PushContentScope = types.PushContentScope

PushContentScope is a push_content approval's requested_scope: the held push's repository, refs, credential, matched paths and commits.

type PushRuleOverride added in v0.9.0 

type PushRuleOverride struct {
	// Provider is github or azure_devops.
	Provider string `json:"provider"`
	// Host is the provider's host, for a GitHub Enterprise Server or an Azure
	// DevOps Server. Empty is the provider's public host.
	Host string `json:"host,omitempty"`
	// Org is the GitHub owner or the Azure DevOps organisation, in the
	// canonical spelling types.CanonicalPushOrg accepts.
	Org                string   `json:"org"`
	DenyPaths          []string `json:"deny_paths,omitempty"`
	RequireReviewPaths []string `json:"require_review_paths,omitempty"`
}

PushRuleOverride adds push content rules for one provider host and organisation. Monotone: it can add a deny or a require-review path, never remove one, and it is met with the policy's and the ceiling's rules before the ceiling clamp (types.PushRuleSet).

func (PushRuleOverride) PushRuleKey added in v0.9.0 

func (p PushRuleOverride) PushRuleKey() string

PushRuleKey is the SCM entry a push-rule override is keyed by: the provider host and the canonical organisation (types.PushRuleKey), "" when it names no entry. Two overrides with one key are refused as duplicates, so "Acme" and "acme" cannot both claim one entry.

type PushRulesSpec added in v0.8.0 

type PushRulesSpec = types.PushRulesSpec

PushRulesSpec declares content rules for a run's brokered git pushes, carried in RunPolicySpec.PushRules: deny_paths refuse, and require_review_paths hold the push for an admin's decision for up to hold_seconds.

type RecordTaskResult added in v0.3.1 

type RecordTaskResult struct {
	RecordRunID string   `json:"record_run_id"`
	TaskKey     string   `json:"task_key"`
	Mode        string   `json:"mode"`
	Detail      string   `json:"detail"`
	Warnings    []string `json:"warnings"`
}

RecordTaskResult is the decoded POST /api/v1/workspaces/{id}/record reply: the launched open-egress recording run plus the resolved session key/mode.

type RemoteRunner added in v0.9.0 

type RemoteRunner = types.RemoteRunner

The remote-hosted runner shapes, re-exported so SDK callers can name them.

type RemoteRunnerPeoplePolicyRequest added in v0.9.0 

type RemoteRunnerPeoplePolicyRequest struct {
	Revision    *int64                  `json:"revision,omitempty"`
	PeoplePools RemoteRunnerPeoplePools `json:"people_pools"`
	Subjects    []RunnerPoolSubject     `json:"subjects,omitempty"`
}

RemoteRunnerPeoplePolicyRequest makes a remote-hosted runner available to people's pools: everyone (no subjects), or the listed people, groups and roles (1 to 64). Revision is optional optimistic concurrency against the runner's revision. Turning it off is ClearRemoteRunnerPeoplePolicy.

type RemoteRunnerPeoplePools added in v0.9.0 

type RemoteRunnerPeoplePools = types.RemoteRunnerPeoplePools

The remote-hosted runner shapes, re-exported so SDK callers can name them.

type RemoteRunnerPoolRef added in v0.9.0 

type RemoteRunnerPoolRef = types.RemoteRunnerPoolRef

The remote-hosted runner shapes, re-exported so SDK callers can name them.

type RemoteRunnerView added in v0.9.0 

type RemoteRunnerView struct {
	RemoteRunner
	Configured bool                  `json:"configured"`
	Online     bool                  `json:"online"`
	Pools      []RemoteRunnerPoolRef `json:"pools"`
	Usage      types.RunnerUsage     `json:"usage"`
}

RemoteRunnerView is a remote-hosted runner as the server reads it. Configured says this server runs it; a runner that is not configured stays listed and never takes a run. Online is whether it answered its last health read. Pools are the live pools it is in: every pool on the operators' reads, the caller's own user pools on ListMyRemoteRunners (which also leaves out the people list). Usage covers every run on it, from every pool: it is shared infrastructure.

type RepoAccessFact added in v0.9.0 

type RepoAccessFact struct {
	Repo   string `json:"repo"`
	Access string `json:"access"` // read | write
	// CanWrite is whether the person may raise a read repository to write.
	CanWrite bool `json:"can_write"`
}

RepoAccessFact is the access a run has to one repository of a Git provider.

type RepoSelection added in v0.9.0 

type RepoSelection struct {
	// Repo is the repository exactly as the workspace source stores it.
	Repo string `json:"repo"`
	// Ref is a branch, tag or full commit. Empty is the source's own ref, else
	// the remote's default branch. A ref that could read as a git option or a
	// revision expression (a leading "-", "..", "@{", control characters) is
	// 400 run_ref_invalid.
	Ref string `json:"ref,omitempty"`
}

RepoSelection is one repository a WorkspaceSelection clones.

type ResolvedRunnerPool added in v0.9.0 

type ResolvedRunnerPool = types.ResolvedRunnerPool

The canonical pool shapes, re-exported so SDK callers can name them.

type RunAttachment added in v0.9.0 

type RunAttachment struct {
	// Kind is repository, folder (a host local_dir source, shown read-only in
	// Review) or drive.
	Kind        string `json:"kind"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	Repo        string `json:"repo,omitempty"`
	// Ref is the ref the clone checks out; "" is the remote's default branch.
	Ref     string `json:"ref,omitempty"`
	DriveID string `json:"drive_id,omitempty"`
	// Name is the workspace or drive NAME, never a host path.
	Name     string `json:"name"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only"`
	// StartsHere marks the attachment that holds the run's starting folder.
	StartsHere bool `json:"starts_here"`
}

RunAttachment is one entry of the server's mount map for a run, as the preflight and the policy preview return it: what is mounted or cloned where.

type RunEgressOverrides added in v0.9.0 

type RunEgressOverrides struct {
	// FirstUseApproval is how a destination no list names is handled:
	// always_deny, deny_with_review or wait_for_review.
	FirstUseApproval types.FirstUseMode `json:"first_use_approval,omitempty"`
	// AllowAllEgress true requests every other public destination (the deny
	// list still wins). False is not an edit: omit it.
	AllowAllEgress *bool `json:"allow_all_egress,omitempty"`
}

RunEgressOverrides are the run-wide egress choices a person makes beside the base policy's own. Both are bounded by the ceiling like any host they add.

type RunEndReason added in v0.9.0 

type RunEndReason = types.RunEndReason

The canonical pool shapes, re-exported so SDK callers can name them.

type RunEvent added in v0.8.2 

type RunEvent struct {
	ID     uint64    `json:"id"`
	Type   string    `json:"type"`
	Reason string    `json:"reason,omitempty"`
	State  RunState  `json:"state,omitempty"`
	At     time.Time `json:"at"`
}

RunEvent is one entry of a run's lifecycle feed, GET /api/v1/runs/{id}/events. ID is monotonic per run. Reason is set on RunEventFailed only, State on RunEventEnded only. It never carries log or secret content.

type RunFileStat added in v0.7.0 

type RunFileStat struct {
	Path string `json:"path"`
	// Status is git's porcelain code ("M", "A", "D", "??", …); empty when git
	// listed the file in the diff but not in status.
	Status  string `json:"status,omitempty"`
	Added   *int   `json:"added,omitempty"`
	Deleted *int   `json:"deleted,omitempty"`
	// Binary marks a file git declined to count lines for.
	Binary bool `json:"binary,omitempty"`
}

RunFileStat is one changed file in a RunFiles listing.

type RunFiles added in v0.7.0 

type RunFiles struct {
	VCS       string        `json:"vcs"`
	Path      string        `json:"path,omitempty"`
	Files     []RunFileStat `json:"files"`
	Truncated bool          `json:"truncated"`
}

RunFiles is GET /api/v1/runs/{id}/files: what changed in a RUNNING sandbox's workspace, read by one exec inside the sandbox. VCS is "git" (Files is the diff-stat), "none" (Path names the directory inspected and it is not a git work tree) or "unknown" (git ran and failed — most often it is missing from the image). Path is present on every outcome so a caller can tell "no repo here" from "looked in the wrong place".

type RunHostOverrides added in v0.9.0 

type RunHostOverrides struct {
	// AddAllowed are destinations to reach. Bare DNS names only; the ceiling
	// still bounds them, and the preview shows the ones it dropped.
	AddAllowed []string `json:"add_allowed,omitempty"`
	// AddDenied are destinations to refuse. A host or a wildcard; a deny wins
	// over every allow, so it only takes reach away.
	AddDenied []string `json:"add_denied,omitempty"`
	// RemoveAllowed and RemoveDenied would drop a host of the base policy. They
	// are always refused (override_refused): the base is read-only on a run.
	RemoveAllowed []string `json:"remove_allowed,omitempty"`
	RemoveDenied  []string `json:"remove_denied,omitempty"`
}

RunHostOverrides are the hosts a person adds to the run as a whole, beside the chosen base policy's own (the agent component's hosts are AgentOverrides').

type RunOutput added in v0.8.2 

type RunOutput struct {
	Output string `json:"output"`
	// Truncated: Output does not start at the run's first byte.
	Truncated bool `json:"truncated"`
	// Complete: this capture attempt is final. A later recording upload can
	// improve a finalized recording result; Incomplete remains true for that source.
	Complete bool `json:"complete"`
	// Source is "stdout", "pane_snapshot", or "recording". The latter two
	// retain the recording's owner-or-operator privacy gate.
	Source string `json:"source"`
	// Incomplete: bytes may be missing (a copy did not end in time or failed, or
	// a byte arrived after the capture was sealed).
	Incomplete bool `json:"incomplete"`
	// CaptureGap: a capture was lost or could not be recovered. Output may
	// retain partial stdout chunks that were already masked and persisted.
	CaptureGap bool `json:"capture_gap"`
	// MaskScope is "run" when the capture was masked against the run's complete
	// manifest throughout, "globals_only" when it was not; empty when this
	// deployment keeps no manifests.
	MaskScope string `json:"mask_scope,omitempty"`
	// CapturedAt is when the final row was written; nil while the run is live.
	CapturedAt *time.Time `json:"captured_at,omitempty"`
}

RunOutput is GET /runs/{id}/output's body: the end of a non-interactive run's combined stdout/stderr.

type RunOverrides added in v0.9.0 

type RunOverrides struct {
	// Agent edits the agent component: its destinations, its header secrets and
	// its tool rules.
	Agent *AgentOverrides `json:"agent,omitempty"`
	// AzureDevOps narrows the run's one Azure DevOps capability set.
	AzureDevOps *ADOOverrides `json:"azure_devops,omitempty"`
	// GitPAT narrows a git_pat grant's scope, one entry per forge host.
	GitPAT []GitPATOverride `json:"git_pat,omitempty"`
	// PushRules adds push content rules, keyed by provider and organisation:
	// each Git section edits its own set and the proxy's git route applies the
	// set matching the repository's provider and organisation.
	PushRules []PushRuleOverride `json:"push_rules,omitempty"`
	// Hosts adds to the run-wide allowed and denied lists on top of the chosen
	// base policy. The base's own hosts are read-only.
	Hosts *RunHostOverrides `json:"hosts,omitempty"`
	// Egress sets the run-wide egress scalars on top of the chosen base policy.
	Egress *RunEgressOverrides `json:"egress,omitempty"`
}

RunOverrides carries the edits a person made on the New Run cards, one block per component (OD-1). They apply inside the server's resolve fold, before the ceiling clamp and the member grant pipeline, so every one is bounded by what the person's ceiling allows. types.OverrideNarrowingTable decides, per kind and operation, whether an edit may be asked for at all; Items lists a value's edits in the table's terms.

An override that only narrows is always accepted. One that widens is clamped to the ceiling or refused (see the table). A server that cannot yet apply an override refuses it with request_field_unavailable instead of dropping it.

func (RunOverrides) Items added in v0.9.0 

func (o RunOverrides) Items() []OverrideItem

Items lists every edit, in a fixed order, with its narrowing-table kind and operation. A value with no edits has none.

func (RunOverrides) Pruned added in v0.9.0 

func (o RunOverrides) Pruned() RunOverrides

Pruned is o with every block that holds no edit dropped, so a record of what took effect carries no empty shell.

type RunOverridesDiff added in v0.9.0 

type RunOverridesDiff struct {
	RunOverrides
	Clamped []string `json:"clamped,omitempty"`
}

RunOverridesDiff is a run's recorded New Run edits (policy_source.overrides_diff on run.create, and RunPolicySource.OverridesDiff on the run). Clamped lists the edits the person's ceiling then dropped, as "field value".

func (RunOverridesDiff) Empty added in v0.9.0 

func (d RunOverridesDiff) Empty() bool

Empty reports whether a recorded diff holds no edit and no clamped edit.

type RunPolicy 

type RunPolicy = types.RunPolicy

RunPolicy is a declarative policy attached to runs. Returned by the policy methods (ListPolicies, GetPolicy, CreatePolicy, UpdatePolicy).

type RunPolicyChange added in v0.8.2 

type RunPolicyChange struct {
	Cause   string   `json:"cause"`
	Field   string   `json:"field"`
	Added   []string `json:"added,omitempty"`
	Removed []string `json:"removed,omitempty"`
	// Detail is the launch-time narrowing sentences, verbatim (Cause "limits" only).
	Detail  []string   `json:"detail,omitempty"`
	Profile string     `json:"profile,omitempty"`
	At      *time.Time `json:"at,omitempty"` // when the run was restarted (Cause "restart")
}

RunPolicyChange is one group of entries changed at launch for one Cause: workspace, source_control, mirror, model_access, git_broker, overlay, profile, org_disk, restart, limits or launch. Field is a RunPolicySpec json name. Entries are keys that never name a hidden value: a grant is "kind:host" or "kind:repo,repo", a mount its target, a repo "repo@ref", an app its name.

type RunPolicySource added in v0.8.2 

type RunPolicySource struct {
	Kind          string     `json:"kind"`
	PolicyID      *uuid.UUID `json:"policy_id,omitempty"`
	Name          string     `json:"name,omitempty"`
	Deleted       bool       `json:"deleted,omitempty"`
	Preset        string     `json:"preset,omitempty"`
	PresetVersion int        `json:"preset_version,omitempty"`
	// OverridesDiff is what the person changed on the New Run cards: the edits
	// that stood, never a secret value. Absent for a run they did not edit.
	OverridesDiff *RunOverridesDiff `json:"overrides_diff,omitempty"`
}

RunPolicySource says where a run's policy started: Kind is "stored" (a saved policy, PolicyID and Name as of launch, Deleted once it is gone), "inline", "default", "profile" (Name is the governance profile), or "unknown".

type RunPolicySpec 

type RunPolicySpec = types.RunPolicySpec

RunPolicySpec is the policy body carried in PolicyRequest.Spec. As a true `=` alias it carries the full wire surface, including AllowAllEgress (json:"allow_all_egress,omitempty") for the "allow all (deny-list only)" egress mode — no separate SDK struct to keep in sync.

type RunPolicyView added in v0.8.2 

type RunPolicyView struct {
	RunID      uuid.UUID            `json:"run_id"`
	State      string               `json:"state"`
	RecordedAt *time.Time           `json:"recorded_at,omitempty"`
	Source     RunPolicySource      `json:"source"`
	Spec       *types.RunPolicySpec `json:"spec,omitempty"`
	// Redacted is true when the reader is below the security admin tier and the
	// policy holds mount sources or secret names, which read as "<redacted>" or
	// are dropped. Such a spec is a starting point, not a policy that validates.
	Redacted bool `json:"redacted"`
	// Changes is never null.
	Changes  []RunPolicyChange `json:"changes"`
	Complete bool              `json:"complete"`
	// StoredPolicyNow is set when the run started from a saved policy.
	StoredPolicyNow *StoredPolicyNow `json:"stored_policy_now,omitempty"`
}

RunPolicyView is GET /api/v1/runs/{id}/policy: the policy a run got, where it started from, and what Wardyn changed when it started.

State is "recorded", "not_yet" (the run has not reached sandbox setup) or "never" (it ended before that, so no policy was applied); Spec and RecordedAt are set only for "recorded". Spec is a normal policy document, with hidden values replaced (see Redacted). Complete is false for a run launched before Wardyn recorded each change, whose Changes may be missing entries.

type RunResources added in v0.9.0 

type RunResources struct {
	// CPUMillis is milli-CPU: 2000 is two CPUs. The console works in tenths of a CPU.
	CPUMillis int `json:"cpu_millis,omitempty"`
	// MemoryMiB is whole MiB.
	MemoryMiB int `json:"memory_mib,omitempty"`
	// DiskMiB is the main drive's size in MiB, 0 to 16 TiB. It is a request: over the
	// effective cap it is reduced and said so, never refused, and a runner that cannot
	// cap disk starts the run uncapped. A size the run's policy writes stays a
	// requirement, and a request may only lower it.
	DiskMiB int `json:"disk_mib,omitempty"`
}

RunResources is the CPU, memory and main-drive size a request asks for. A zero field asks for what the run's source policy sets, else the default. The server applies what it is given within the strictest of the pool's, the person's governance, the deployment's and (on their own runner) the runner's limits: a value over that cap is reduced to it, never refused, and the dry runs and the 201 say what was applied (AppliedResources, MainDriveApplied).

type RunShape added in v0.9.0 

type RunShape string

RunShape is the New Run choice a run was set up from. It is not a second mode: the server checks it against experience, workload and tools, and otherwise ignores it. 

const (
	RunShapeAgentTask   RunShape = "agent_task"
	RunShapeEnvironment RunShape = "environment"
	RunShapeApplication RunShape = "application"
)

The run shapes.

func (RunShape) Valid added in v0.9.0 

func (s RunShape) Valid() bool

Valid reports whether the shape is one of the three.

type RunSignIn added in v0.8.8 

type RunSignIn struct {
	// State is SignInWaiting or SignInNotWaiting.
	State string `json:"state"`
	// VerificationURL is the page to approve the sign-in on, with the code
	// pre-filled; set only when waiting. It comes from the sign-in sandbox's
	// terminal, so check its host before opening it.
	VerificationURL string `json:"verification_url,omitempty"`
	// UserCode is the code the page asks for; set only when waiting.
	UserCode string `json:"user_code,omitempty"`
}

RunSignIn is GET /api/v1/runs/{id}/sign-in: whether a running AWS sign-in is waiting for its device-code approval.

type RunStartup added in v0.9.0 

type RunStartup struct {
	Kind StartupKind `json:"kind"`
	// Tool is the included tool a harness startup launches.
	Tool string `json:"tool,omitempty"`
	// Command is the startup command a command startup runs once at boot.
	Command string `json:"command,omitempty"`
	// Prompt is the starting prompt a harness startup opens with: the startup
	// harness's first message. A harness startup only; it is task text, held to
	// the same scans and limits as a task.
	Prompt string `json:"prompt,omitempty"`
}

RunStartup is what an Interactive run starts on its own: nothing, one included harness, or one command. It is one choice, never two competing launches, and removing the startup harness clears it; the server never substitutes another. Absent is the same as none.

type RunState 

type RunState = types.RunState

RunState is the AgentRun lifecycle state (AgentRun.State, KillRunResponse.State).

type RunWorkload added in v0.9.0 

type RunWorkload struct {
	Kind WorkloadKind `json:"kind"`
	// Agent is the harness an agent task runs (claude-code, codex-cli, a custom
	// agent): the id of the one included tool it runs.
	Agent string `json:"agent,omitempty"`
	// Task is the harness's prompt.
	Task string `json:"task,omitempty"`
	// Command is the shell command a command workload runs, as task_mode "exec"
	// runs a task today.
	Command string `json:"command,omitempty"`
}

RunWorkload is what a Background run does. Exactly one of the two shapes: agent_task carries Agent and Task, command carries Command. Autonomous execution follows from the mode, so there is no separate autonomy choice.

type RunnerAmounts added in v0.9.0 

type RunnerAmounts = types.RunnerAmounts

RunnerLimits is a runner's declared limit set; RunnerUsage is what its runs hold now.

type RunnerFilter added in v0.9.0 

type RunnerFilter = types.RunnerFilter

RunnerFilter is the state filter of ListRunners.

type RunnerKind added in v0.9.0 

type RunnerKind = types.RunnerKind

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerLimits added in v0.9.0 

type RunnerLimits = types.RunnerLimits

RunnerLimits is a runner's declared limit set; RunnerUsage is what its runs hold now.

type RunnerPool added in v0.9.0 

type RunnerPool = types.RunnerPool

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolAmount added in v0.9.0 

type RunnerPoolAmount = types.RunnerPoolAmount

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolBackgroundLimits added in v0.9.0 

type RunnerPoolBackgroundLimits = types.RunnerPoolBackgroundLimits

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolCatalogueEntry added in v0.9.0 

type RunnerPoolCatalogueEntry struct {
	RunnerPoolChoice
	RunTypes []RunnerPoolRunType `json:"run_types"`
	// RunTypesSource is RunTypesSourcePool or RunTypesSourceNone.
	RunTypesSource string          `json:"run_types_source,omitempty"`
	BarrierOptions []BarrierOption `json:"barrier_options"`
	// MyRunners is every one of the caller's OWN self-hosted runners that is a
	// member of a user pool, whether or not it can take a run now; never another
	// person's. It is how a person reads which pools each of their runners is in.
	MyRunners []PoolRunner `json:"my_runners,omitempty"`
	// Slots is how busy the pool is; absent on a row the caller may only manage.
	Slots *PoolSlots `json:"slots,omitempty"`
	// Capacity is its runners' limits and usage added up; absent on a row the caller may only manage.
	Capacity *PoolCapacity `json:"capacity,omitempty"`
	// Owner is a user pool's owner: the caller on their own pools, and the
	// person each other pool belongs to on an administrator's oversight rows.
	Owner string `json:"owner,omitempty"`
}

RunnerPoolCatalogueEntry is one row of GET /runner-pools. A pool the caller may use carries its run types, the effective limits of each (Limits, one per run type, or only the ?run_type= one) and its three barriers. A pool the caller may only manage (reason runner_pool_not_found) carries none of them: nothing is computed for a pool the caller may not use.

type RunnerPoolChoice added in v0.9.0 

type RunnerPoolChoice struct {
	ID           uuid.UUID                `json:"id"`
	Name         string                   `json:"name"`
	Scope        RunnerPoolScope          `json:"scope"`
	Availability string                   `json:"availability"`
	Reason       RunnerPoolReason         `json:"reason,omitempty"`
	Limits       []EffectiveRunLimits     `json:"limits,omitempty"`
	Barriers     []types.ConfinementClass `json:"barriers,omitempty"`
	// MainDrive is what this pool's runners do with a run's main-drive size, for the caller's own eligible
	// targets. Absent on a pool the caller may only manage. The enforcement word reaches members only here.
	MainDrive *MainDriveFacts `json:"main_drive,omitempty"`
}

RunnerPoolChoice is one pool a person may choose, as the preflight and the policy preview show it. Only pools the caller may use appear; an inaccessible pool's name, members and counts are never sent. Reason says why a pool that is not available is not: a pool refusal reason or one of runnerpool.AvailabilityReasons. The pool list answers the same five leading fields for the same pool and caller (RunnerPoolCatalogueEntry).

Limits and Barriers are never filled on these doors: the list carries a pool's limits and barrier_options, and preflight carries this run's. MainDrive is filled on the list and on both doors.

type RunnerPoolDefaults added in v0.9.0 

type RunnerPoolDefaults = types.RunnerPoolDefaults

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolDuration added in v0.9.0 

type RunnerPoolDuration = types.RunnerPoolDuration

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolInteractiveLimits added in v0.9.0 

type RunnerPoolInteractiveLimits = types.RunnerPoolInteractiveLimits

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolLimits added in v0.9.0 

type RunnerPoolLimits = types.RunnerPoolLimits

The pool's own limits and what a run of each type effectively gets.

type RunnerPoolList added in v0.9.0 

type RunnerPoolList struct {
	Pools []RunnerPoolCatalogueEntry `json:"pools"`
	// Allowance is absent for a caller whose runs stand outside governance.
	Allowance *PersonAllowance `json:"allowance,omitempty"`
	// Default is absent when no default applies.
	Default *PoolDefault `json:"default,omitempty"`
}

RunnerPoolList is the caller's pool catalogue, their allowance and the pool an untouched run resolves to.

type RunnerPoolMember added in v0.9.0 

type RunnerPoolMember = types.RunnerPoolMember

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolMemberView added in v0.9.0 

type RunnerPoolMemberView struct {
	Kind       RunnerKind          `json:"kind"`
	ID         string              `json:"id"`
	Name       string              `json:"name"`
	Online     bool                `json:"online"`
	Configured bool                `json:"configured,omitempty"`
	Runner     *types.RunnerView   `json:"runner,omitempty"`
	Limits     *types.RunnerLimits `json:"limits"`
	Usage      types.RunnerUsage   `json:"usage"`
}

RunnerPoolMemberView is one runner of a pool, either kind. ID is the self-hosted runner's id or the remote-hosted runner's. Runner is a self-hosted member's runner view, its owner named on an operator's read; Configured is set for a remote-hosted member this server runs. Limits and Usage are the member's own, either kind.

type RunnerPoolReason added in v0.9.0 

type RunnerPoolReason = runnerpool.Reason

RunnerPoolReason is a pool selection refusal reason; it matches APIError.Reason.

type RunnerPoolRunType added in v0.9.0 

type RunnerPoolRunType = types.RunnerPoolRunType

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolScope added in v0.9.0 

type RunnerPoolScope = types.RunnerPoolScope

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolSelection added in v0.9.0 

type RunnerPoolSelection = types.RunnerPoolSelection

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolState added in v0.9.0 

type RunnerPoolState = types.RunnerPoolState

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolSubject added in v0.9.0 

type RunnerPoolSubject = types.RunnerPoolSubject

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolSwitch added in v0.9.0 

type RunnerPoolSwitch string

RunnerPoolSwitch is the state an update may put a pool in: active or disabled. Deleting a pool is DeleteRunnerPool alone, so it has one audit action. 

const (
	RunnerPoolSwitchActive   RunnerPoolSwitch = "active"
	RunnerPoolSwitchDisabled RunnerPoolSwitch = "disabled"
)

type RunnerPoolUsePolicy added in v0.9.0 

type RunnerPoolUsePolicy = types.RunnerPoolUsePolicy

The canonical pool shapes, re-exported so SDK callers can name them.

type RunnerPoolUsePolicyRequest added in v0.9.0 

type RunnerPoolUsePolicyRequest struct {
	Revision *int64              `json:"revision,omitempty"`
	Subjects []RunnerPoolSubject `json:"subjects"`
}

RunnerPoolUsePolicyRequest sets who may use an organization pool. Revision, when given, is the pool revision the caller read: a pool changed since then is refused as stale.

type RunnerRegisterRequest added in v0.9.0 

type RunnerRegisterRequest = types.RunnerRegisterRequest

RunnerRegisterRequest submits a one-use token and the runner's public key.

type RunnerRegistration added in v0.9.0 

type RunnerRegistration = types.RunnerRegistration

RunnerRegistration is the public registration identity, without owner facts or private key.

type RunnerRegistrationToken added in v0.9.0 

type RunnerRegistrationToken = types.RunnerRegistrationToken

RunnerRegistrationToken is returned once at mint.

type RunnerSettings added in v0.9.0 

type RunnerSettings = types.RunnerSettings

RunnerSettings is the runners on/off switch.

type RunnerTally added in v0.9.0 

type RunnerTally = types.RunnerTally

RunnerLimits is a runner's declared limit set; RunnerUsage is what its runs hold now.

type RunnerUsage added in v0.9.0 

type RunnerUsage = types.RunnerUsage

RunnerLimits is a runner's declared limit set; RunnerUsage is what its runs hold now.

type RunnerView added in v0.9.0 

type RunnerView = types.RunnerView

RunnerView is a registered runner as the management routes show it. Posture and everything else a runner says about itself is as reported, never verified.

type SSHPublicKey added in v0.7.0 

type SSHPublicKey = types.SSHPublicKey

SSHPublicKey is one registered SSH gateway key (never a secret — the authorized_keys line plus its fingerprint). Returned by ListSSHKeys and AddSSHKey.

type SecretOverride added in v0.9.0 

type SecretOverride struct {
	SecretName string `json:"secret_name"`
	Host       string `json:"host"`
	// Header and Format default as an api_key grant's do.
	Header string `json:"header,omitempty"`
	Format string `json:"format,omitempty"`
}

SecretOverride injects one stored secret, as a header, on one host.

type ServiceIdentity added in v0.9.0 

type ServiceIdentity = types.ServiceIdentity

ServiceIdentity is a named, sponsored non-human principal; ServiceIdentityState is its derived state.

type ServiceIdentityState added in v0.9.0 

type ServiceIdentityState = types.ServiceIdentityState

Domain nouns returned or accepted by Client methods.

type SiteConfig added in v0.4.4 

type SiteConfig = types.SiteConfig

SiteConfig is the operator-wide site config. Returned by GetSiteConfig and accepted by PutSiteConfig.

type SiteConfigPutResult added in v0.8.4 

type SiteConfigPutResult struct {
	types.SiteConfig
	DanglingSecretRefs           []string `json:"dangling_secret_refs,omitempty"`
	OnboardingCompletedAtIgnored bool     `json:"onboarding_completed_at_ignored,omitempty"`
	// BrandingLogoPending (#1215): branding.logo_path was valid but not attached,
	// because the console has no branding record yet. Apply again after saving
	// the Branding card.
	BrandingLogoPending bool `json:"branding_logo_pending,omitempty"`
	// EgressBaselineIgnored is set by the SDK, not the server: the document named an egress baseline
	// (egress.baseline_hosts, or a baseline mark on an internal host) that differs from the stored
	// one, and PutSiteConfigResult did not send it. A document that names no egress block is never
	// reported (an older file is silent about the baseline). Only PUT /governance/egress-baseline writes it.
	EgressBaselineIgnored bool `json:"-"`
	// ModelProviderWarnings are advisories on the model_providers block, such as an azure_foundry
	// endpoint that resolves to a private address no internal_hosts entry covers.
	ModelProviderWarnings []string `json:"model_provider_warnings,omitempty"`
}

SiteConfigPutResult is PUT /site-config's answer: the stored document plus the write's advisory signals. A field is added here rather than a return value to PutSiteConfig, whose signature is public.

type Source added in v0.5.0 

type Source = types.Source

Source is one tier-1 library entry: a repo/dir configured once (its own contract + scan) and attached to many workspaces.

type SourceKind added in v0.5.0 

type SourceKind = types.SourceKind

SourceKind discriminates a library source: local_dir | repo.

type SourceRequest added in v0.5.0 

type SourceRequest struct {
	Kind types.SourceKind `json:"kind"`
	// Locator is a host directory path (local_dir) or repo slug/clone URL (repo).
	Locator string `json:"locator"`
	// Ref is an optional git ref; repo only. Part of the identity — the same
	// repo at two refs is two sources with two contracts.
	Ref  string `json:"ref,omitempty"`
	Name string `json:"name,omitempty"`
	// Requirements seeds the source's own contract (secret:/egress:/write:
	// keys; integration: keys are tier-3-only and rejected here).
	Requirements map[string]types.WorkspaceRequirement `json:"requirements,omitempty"`
}

SourceRequest is the body for POST /api/v1/sources — one repo/dir configured ONCE (its own requirements contract, its own scan profile) and attached to any number of workspaces. The server dedupes on canonical identity (kind, locator, ref): re-creating an existing source answers 200 with the existing row, contract and all, rather than a duplicate.

type StartFolder added in v0.9.0 

type StartFolder struct {
	Kind StartFolderKind `json:"kind"`
	// Attachment is the workspace id of one of the request's attachments, or
	// StartFolderDrive for the person's drive. An attachment kind names exactly
	// one of Attachment and DriveID.
	Attachment string `json:"attachment,omitempty"`
	// Repo, with a workspace Attachment, names one of the repositories the run
	// clones from it: the folder is that clone. Without it the folder is the
	// workspace's first attachment.
	Repo string `json:"repo,omitempty"`
	// DriveID names one drive of the run's drive list. Refused with
	// request_field_unavailable until the server attaches several drives.
	DriveID string `json:"drive_id,omitempty"`
	// Subpath is a relative path inside the attachment's mount: no "..", no
	// leading "/". Empty is the mount's root.
	Subpath string `json:"subpath,omitempty"`
}

StartFolder is the run's one starting folder: the initial working directory of every start (a background command or task, an interactive terminal, a harness). Every other mount stays available without becoming a second one.

type StartFolderKind added in v0.9.0 

type StartFolderKind string

StartFolderKind says where the run's one working directory comes from. 

const (
	// StartFolderImageDefault is the image's own working directory.
	StartFolderImageDefault StartFolderKind = "image_default"
	// StartFolderAttachment is a folder inside one attached workspace or drive.
	StartFolderAttachment StartFolderKind = "attachment"
)

type StartupKind added in v0.9.0 

type StartupKind string

StartupKind is the one discriminator of what starts automatically. 

const (
	StartupNone    StartupKind = "none"
	StartupHarness StartupKind = "harness"
	StartupCommand StartupKind = "command"
)

type StoredPolicyNow added in v0.8.2 

type StoredPolicyNow struct {
	State     string     `json:"state"`
	Name      string     `json:"name,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

StoredPolicyNow compares the saved policy a run started from with what it reads now: State is "same", "changed", "updated" (an older run whose saved policy was edited since — possibly a rename only) or "deleted".

type TelemetryFact added in v0.9.0 

type TelemetryFact struct {
	Off bool     `json:"off"`
	Env []string `json:"env,omitempty"`
}

TelemetryFact says whether agent telemetry is off and which variables Wardyn sets to turn it off.

type Template added in v0.9.0 

type Template struct {
	ID    uuid.UUID     `json:"id"`
	Scope TemplateScope `json:"scope"`
	// OwnerID is the owning person's subject, for person scope.
	OwnerID string `json:"owner_id,omitempty"`
	// GroupID is the group's canonical subject, for group scope.
	GroupID string `json:"group_id,omitempty"`
	// GroupLabel is the group's display label, when an administrator set one.
	GroupLabel  string           `json:"group_label,omitempty"`
	Kind        TemplateKind     `json:"kind"`
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Revision    int              `json:"revision"`
	Coverage    TemplateCoverage `json:"coverage"`
	Document    TemplateDocument `json:"document"`
	// Writable says whether the caller may update or delete it.
	Writable  bool      `json:"writable"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	// CreatedBy and UpdatedBy are set only for a caller who may write it:
	// the people a template is offered to are not told who published it.
	CreatedBy string `json:"created_by,omitempty"`
	UpdatedBy string `json:"updated_by,omitempty"`
}

Template is one catalogue entry, as the server returns it.

type TemplateCopyRequest added in v0.9.0 

type TemplateCopyRequest struct {
	Scope   TemplateScope `json:"scope"`
	GroupID string        `json:"group_id,omitempty"`
	Name    string        `json:"name,omitempty"`
}

TemplateCopyRequest copies (publishes) a template into another scope. The caller needs to read the source and to write the target scope; the server re-checks every reference the copy would disclose.

type TemplateCoverage added in v0.9.0 

type TemplateCoverage string

TemplateCoverage says what a template intends to hold. Full is a whole run setup: nothing in it is waiting on a later choice. Partial is a mix of parts, and may list what it needs set up when it is used. 

const (
	TemplateCoverageFull    TemplateCoverage = "full"
	TemplateCoveragePartial TemplateCoverage = "partial"
)

The template coverages.

type TemplateDiagnostic added in v0.9.0 

type TemplateDiagnostic struct {
	Path    string `json:"path"`
	Reason  string `json:"reason"`
	Message string `json:"message"`
}

TemplateDiagnostic is one problem with a document: where, why (a closed reason) and a sentence. Path is a JSON path such as intent.workspaces[1].target.

type TemplateDocument added in v0.9.0 

type TemplateDocument struct {
	APIVersion  string           `json:"api_version"`
	Kind        string           `json:"kind"`
	Name        string           `json:"name,omitempty"`
	Description string           `json:"description,omitempty"`
	Coverage    TemplateCoverage `json:"coverage,omitempty"`
	Intent      TemplateIntent   `json:"intent"`
	// NeedsSetup lists what a partial template leaves for use time. A full
	// template lists none.
	NeedsSetup []TemplateSetupNeed `json:"needs_setup,omitempty"`
}

TemplateDocument is the import and export document of one template (YAML or JSON). It carries content only. Owner, scope, group, revision and authorship belong to the catalogue and come from the authenticated request; a document that names them is refused.

func PresetDocument added in v0.9.0 

func PresetDocument(p Preset, everyone bool) (TemplateDocument, error)

PresetDocument converts a stored launch preset into a RunTemplate document: the one place a preset becomes a template, so every client converts it the same way. The document is partial, named and described as the preset is, and holds the preset's request field by field. Whether it is publishable is the server's to say, at the save door.

A preset limited to some user types is offered to those types only; a template is offered to everyone in its scope. So the conversion refuses such a preset unless everyone is true, which is the caller saying it knows the limit is lost.

A preset's inline_policy replaced the caller's default policy whole; in a template it is laid onto the default, so a key the preset left out now takes the default's value instead of its zero value.

Three things in a preset's request are not content and are dropped: the mode_contract marker, which belongs to the request a client sends, and an empty string or null, which says nothing (agent, repo, first_use_approval, min_confinement_class and a nil allowed_domains are always written, and a template reads a key that is present as a choice).

type TemplateFormat added in v0.9.0 

type TemplateFormat string

TemplateFormat is the text an import is written in. 

const (
	TemplateFormatJSON TemplateFormat = "json"
	TemplateFormatYAML TemplateFormat = "yaml"
)

The import formats.

type TemplateGroupAdmin added in v0.9.0 

type TemplateGroupAdmin = types.TemplateGroupAdmin

TemplateGroupAdmin is a bounded grant letting one person manage one group's templates; an organisation administrator writes it.

type TemplateGroupAdmins added in v0.9.0 

type TemplateGroupAdmins struct {
	Grants []TemplateGroupAdmin `json:"grants"`
}

TemplateGroupAdmins is GET /api/v1/admin/template-group-admins.

type TemplateImportRequest added in v0.9.0 

type TemplateImportRequest struct {
	Format TemplateFormat `json:"format"`
	Source string         `json:"source"`
	// Kind is the document kind the caller expects: Run, RunTemplate, or empty
	// for either. A document of the other kind is refused.
	Kind string `json:"kind,omitempty"`
}

TemplateImportRequest asks the server to read an import document and say whether it can become a draft. It stores nothing.

type TemplateImportResult added in v0.9.0 

type TemplateImportResult struct {
	Document    *TemplateDocument    `json:"document,omitempty"`
	Diagnostics []TemplateDiagnostic `json:"diagnostics"`
}

TemplateImportResult is POST /api/v1/templates/import's answer. Document is the normalised document and is set only when Diagnostics is empty; with diagnostics the caller keeps its own text and shows them.

type TemplateIntent added in v0.9.0 

type TemplateIntent struct {
	// contains filtered or unexported fields
}

TemplateIntent is the reusable part of a run request: the fields the template says something about, and no others. It keeps PRESENCE. A field that is absent means "this template does not specify it"; a field that is present and false, zero, empty or an empty list is a choice. The Go zero values of CreateRunRequest cannot tell those apart, so the intent holds each field's JSON as written and Request materialises the present ones. Null is never a value.

Its fields are the canonical request fields (CreateRunRequest) that a template may carry, with inline_policy as a partial policy spec: the server lays only the keys present onto a readable source policy, and a key left out keeps the source's value. Request is a shape check, not that overlay.

func (TemplateIntent) Has added in v0.9.0 

func (i TemplateIntent) Has(name string) bool

Has reports whether the intent specifies the field, whatever its value.

func (TemplateIntent) MarshalJSON added in v0.9.0 

func (i TemplateIntent) MarshalJSON() ([]byte, error)

MarshalJSON writes the fields in sorted order, each as stored.

func (TemplateIntent) Names added in v0.9.0 

func (i TemplateIntent) Names() []string

Names are the fields the intent specifies, sorted.

func (TemplateIntent) Raw added in v0.9.0 

func (i TemplateIntent) Raw(name string) json.RawMessage

Raw is the field's JSON as stored, nil when absent.

func (TemplateIntent) Request added in v0.9.0 

func (i TemplateIntent) Request() (CreateRunRequest, error)

Request materialises the present fields into a request, for shape checks. A request cannot tell an absent field from an empty one, and a request's inline_policy replaces its source policy, so this is not how a template is applied: the server overlays the present policy keys onto the source policy. A field the request does not know is an error, never dropped.

func (*TemplateIntent) Set added in v0.9.0 

func (i *TemplateIntent) Set(name string, value any) error

Set specifies one field, replacing any earlier value.

func (*TemplateIntent) UnmarshalJSON added in v0.9.0 

func (i *TemplateIntent) UnmarshalJSON(data []byte) error

UnmarshalJSON reads the intent's fields in canonical form: compact, with every object's keys sorted, so the same document written as YAML or as JSON, in any key order, holds the same bytes (revisions and diffs stay stable). Whether each is a field a template may carry is the server's decoder's to say.

func (*TemplateIntent) Unset added in v0.9.0 

func (i *TemplateIntent) Unset(name string)

Unset removes a field: the template stops specifying it.

type TemplateKind added in v0.9.0 

type TemplateKind = types.TemplateKind

TemplateKind says what a template holds: a run setup, or a policy (only run-wide network, credential and access-rule keys under inline_policy).

type TemplateList added in v0.9.0 

type TemplateList struct {
	Templates []TemplateSummary `json:"templates"`
	Publish   TemplatePublish   `json:"publish"`
}

TemplateList is GET /api/v1/templates: the templates the caller may use, and where they may save one.

type TemplatePart added in v0.9.0 

type TemplatePart string

TemplatePart is one group the refinement flow lets a person keep or leave out, and one entry of a template's Includes. 

const (
	TemplatePartRunner       TemplatePart = "runner"
	TemplatePartResources    TemplatePart = "resources"
	TemplatePartRepositories TemplatePart = "repositories"
	TemplatePartDrives       TemplatePart = "drives"
	TemplatePartToolsImage   TemplatePart = "tools_image"
	TemplatePartEgress       TemplatePart = "egress"
	TemplatePartCredentials  TemplatePart = "credentials"
	TemplatePartComponents   TemplatePart = "components"
	TemplatePartAccessRules  TemplatePart = "access_rules"
	TemplatePartPolicyRef    TemplatePart = "policy_ref"
)

The template parts.

type TemplatePublish added in v0.9.0 

type TemplatePublish struct {
	Org    bool     `json:"org"`
	Groups []string `json:"groups"`
	// GroupLabels holds the display label of each of Groups that has one.
	GroupLabels map[string]string `json:"group_labels,omitempty"`
	// GroupsUnverified: the sign-in's group list is missing or incomplete, so
	// no group is offered until the person signs in again.
	GroupsUnverified bool `json:"groups_unverified"`
}

TemplatePublish says where the caller may save a template: always their own scope, the organisation only as an organisation administrator in the Admin view, and each group only as a verified member who holds that group's grant.

type TemplateRef added in v0.9.0 

type TemplateRef struct {
	ID       uuid.UUID `json:"id"`
	Revision int       `json:"revision"`
}

TemplateRef pins a template revision in a new-run draft. A later edit of the template does not change a draft that holds an earlier revision; refreshing it is an explicit draft action.

type TemplateSaveRefusal added in v0.9.0 

type TemplateSaveRefusal struct {
	Error       string               `json:"error"`
	Reason      string               `json:"reason"`
	Diagnostics []TemplateDiagnostic `json:"diagnostics"`
}

TemplateSaveRefusal is the body of a save, update or copy the document door refused: the first diagnostic's reason and sentence, and every diagnostic.

type TemplateSaveRequest added in v0.9.0 

type TemplateSaveRequest struct {
	Scope       TemplateScope `json:"scope"`
	GroupID     string        `json:"group_id,omitempty"`
	Name        string        `json:"name"`
	Description string        `json:"description,omitempty"`
	// Kind is template when empty. An update keeps the template's kind.
	Kind             TemplateKind     `json:"kind,omitempty"`
	Document         TemplateDocument `json:"document"`
	ExpectedRevision *int             `json:"expected_revision,omitempty"`
}

TemplateSaveRequest creates a template, or updates one when ExpectedRevision names the revision the caller read. An update against any other revision is a conflict. Scope and GroupID say where it is published; the server checks the caller's authority for exactly that scope.

type TemplateScope added in v0.9.0 

type TemplateScope = types.TemplateScope

TemplateScope says who a template is for.

type TemplateSetupNeed added in v0.9.0 

type TemplateSetupNeed struct {
	// Field is an intent field, or inline_policy.<field>, that the intent does not specify.
	Field  string `json:"field"`
	Reason string `json:"reason,omitempty"`
}

TemplateSetupNeed names a field the template leaves out but the fields it does carry depend on, so the person who uses it knows to set it up.

type TemplateSummary added in v0.9.0 

type TemplateSummary struct {
	ID          uuid.UUID        `json:"id"`
	Scope       TemplateScope    `json:"scope"`
	GroupID     string           `json:"group_id,omitempty"`
	GroupLabel  string           `json:"group_label,omitempty"`
	Kind        TemplateKind     `json:"kind"`
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Revision    int              `json:"revision"`
	Coverage    TemplateCoverage `json:"coverage"`
	Includes    []TemplatePart   `json:"includes"`
	// Fields are the intent fields it specifies, inline_policy expanded to
	// inline_policy.<key>, sorted.
	Fields     []string  `json:"fields"`
	NeedsSetup []string  `json:"needs_setup"`
	Writable   bool      `json:"writable"`
	UpdatedAt  time.Time `json:"updated_at"`
}

TemplateSummary is one row of the picker: what the template is and what it includes, without the document.

type TokenDisposition added in v0.9.0 

type TokenDisposition = types.TokenDisposition

Domain nouns returned or accepted by Client methods.

type TokenMove added in v0.9.0 

type TokenMove = types.TokenMove

Domain nouns returned or accepted by Client methods.

type TokenMoved added in v0.9.0 

type TokenMoved = types.TokenMoved

TokenMoved is MoveToken's answer: the link written and the token's new disposition.

type TokenScopeFact added in v0.9.0 

type TokenScopeFact struct {
	Scope  string   `json:"scope"`
	Covers []string `json:"covers"`
}

TokenScopeFact is one scope of the token a person creates for an Azure DevOps own-token sign-in, with the capabilities it covers (#1880).

type ToolDefaultFact added in v0.9.0 

type ToolDefaultFact struct {
	Effective types.ToolEffect `json:"effective"`
	Source    ProvenanceSource `json:"source"`
	Options   []EffectOption   `json:"options"`
}

ToolDefaultFact is a harness's default for a tool no rule names.

type ToolEffect added in v0.9.0 

type ToolEffect = types.ToolEffect

Domain nouns returned or accepted by Client methods.

type ToolPolicyFact added in v0.9.0 

type ToolPolicyFact struct {
	Harness     string           `json:"harness"`
	Lane        string           `json:"lane"`
	Enforcer    string           `json:"enforcer"`
	Default     ToolDefaultFact  `json:"default"`
	PolicyRules []LockedToolRule `json:"policy_rules"`
	RuleEffects []EffectOption   `json:"rule_effects"`
	RuleTools   string           `json:"rule_tools"`
	MCPServers  []string         `json:"mcp_servers"`
}

ToolPolicyFact is one included harness's tool policy: the lane its calls take (gated, ungated, attended or unsupported), who enforces it (wardyn_gate, harness_settings, mcp_broker — the broker, for a harness whose MCP tools are its only rules — or none), its default, the policy's locked rules, the effects a person may choose for a tool the policy does not name, whether rules may name any tool or MCP tools only, and the MCP servers turned on for it.

type ToolRule added in v0.9.0 

type ToolRule = types.ToolRule

ToolRule is one tool name and what to do with it, carried in RunPolicySpec.ToolRules and AgentOverrides.ToolRules; ToolEffect is its allow, hold or deny.

type UpdateRemoteRunnerRequest added in v0.9.0 

type UpdateRemoteRunnerRequest struct {
	Revision int64               `json:"revision"`
	Name     *string             `json:"name,omitempty"`
	Limits   *types.RunnerLimits `json:"limits,omitempty"`
}

UpdateRemoteRunnerRequest renames a remote-hosted runner, or declares its limits, at the revision the caller read. Limits is the whole set (Runs at once 1 to 1024).

func (UpdateRemoteRunnerRequest) Validate added in v0.9.0 

func (r UpdateRemoteRunnerRequest) Validate() error

Validate refuses a revision that was never read, a request that changes nothing, a bad name and a bad limit set.

type UpdateRunnerPoolRequest added in v0.9.0 

type UpdateRunnerPoolRequest struct {
	Revision int64             `json:"revision"`
	Name     *string           `json:"name,omitempty"`
	State    *RunnerPoolSwitch `json:"state,omitempty"`
	Limits   *RunnerPoolLimits `json:"limits,omitempty"`
}

UpdateRunnerPoolRequest renames, switches off/on or re-limits one pool. Revision is the revision the caller read: a stale one is refused with runner_pool_stale. A present Limits replaces the pool's limits as a WHOLE block, so a client sends back the block it read with its change in it (an omitted max_concurrent_runs removes the cap); an absent Limits leaves the stored block unchanged.

func (UpdateRunnerPoolRequest) Validate added in v0.9.0 

func (r UpdateRunnerPoolRequest) Validate() error

Validate refuses an update that changes nothing, a revision that was never read, a bad name, limits a pool cannot keep, and any state but active or disabled (never deleted).

type UpdateServiceIdentityRequest added in v0.9.0 

type UpdateServiceIdentityRequest struct {
	Description *string `json:"description,omitempty"`
	Sponsor     *string `json:"sponsor,omitempty"`
	Suspended   *bool   `json:"suspended,omitempty"`
}

UpdateServiceIdentityRequest is the PATCH /api/v1/service-identities/{name} body: the fields present change. internal/api aliases it (updateServiceIdentityRequest).

type UserDrive added in v0.8.0 

type UserDrive = types.UserDrive

UserDrive is one admin-registered drive (migration 0054's user_drives row), embedded in UserDriveListItem. Written via DriveRequest.

type UserDriveGrant added in v0.8.0 

type UserDriveGrant = types.UserDriveGrant

UserDriveGrant allocates one drive to one subject (DrivesDocument.Grants). Written via DriveGrantRequest.

type UserDriveListItem added in v0.8.0 

type UserDriveListItem = types.UserDriveListItem

UserDriveListItem is one DrivesDocument.Drives row: the drive plus how many grants allocate it. Returned by GetDrives and ApplyDrives.

type WorkloadKind added in v0.9.0 

type WorkloadKind string

WorkloadKind says what a background run executes. 

const (
	// WorkloadAgentTask runs one harness on a task.
	WorkloadAgentTask WorkloadKind = "agent_task"
	// WorkloadCommand runs a plain shell command in the governed sandbox: no
	// harness and no model credential.
	WorkloadCommand WorkloadKind = "command"
)

type Workspace added in v0.4.4 

type Workspace = types.Workspace

Workspace is an onboarded local dir / repo / container. Returned by ListWorkspaces, GetWorkspace, CreateWorkspace, and UpdateWorkspace.

type WorkspaceAttachment added in v0.5.0 

type WorkspaceAttachment = types.WorkspaceAttachment

WorkspaceAttachment is one tier-3 composition row (Workspace.Attachments): either a library Source reference (SourceID set) or an inline ephemeral scratch row.

type WorkspaceBaseImage added in v0.5.0 

type WorkspaceBaseImage = types.WorkspaceBaseImage

WorkspaceBaseImage is a Workspace's base-image choice, carried in WorkspaceRequest.BaseImage and returned in Workspace.BaseImage.

type WorkspaceBuild added in v0.9.0 

type WorkspaceBuild struct {
	State        string      `json:"state"`
	Image        string      `json:"image,omitempty"`
	Detail       string      `json:"detail,omitempty"`
	StartedAt    *time.Time  `json:"started_at,omitempty"`
	Log          []string    `json:"log,omitempty"`
	Record       *ImageBuild `json:"record,omitempty"`
	RecordSHA256 string      `json:"record_sha256,omitempty"`
	Reproducible *bool       `json:"reproducible,omitempty"`
}

WorkspaceBuild is one workspace's image-build view (GET/POST /api/v1/workspaces/{id}/build). Record is present only while the workspace's build record is current; Reproducible false reads "not reproducible".

type WorkspaceKind added in v0.4.4 

type WorkspaceKind = types.WorkspaceKind

WorkspaceKind is what a workspace onboards (Workspace.Kind, WorkspaceRequest.Kind). Deprecated: a DERIVED READ-ONLY MIRROR of Workspace.Sources[0] (single-source only) — see WorkspaceSourceType for the field a multi-source Workspace actually carries per-source.

type WorkspaceLLMCred added in v0.4.4 

type WorkspaceLLMCred = types.WorkspaceLLMCred

WorkspaceLLMCred is the operator-owned model binding carried in WorkspaceRequest.LLMCred: ProviderRef pins the workspace's runs to one model provider. "" (or a nil WorkspaceLLMCred) means no pin. On a read, ProviderUnavailable in place of ProviderRef means the workspace is pinned to a provider the caller is not granted; a write never sets it.

type WorkspaceMount 

type WorkspaceMount = types.WorkspaceMount

WorkspaceMount is an operator/policy-controlled host bind mount carried in RunPolicySpec.WorkspaceMounts.

type WorkspaceRequest added in v0.3.1 

type WorkspaceRequest struct {
	Name string `json:"name"`
	// Sources is the workspace's composition: one-or-more local_dir/repo/
	// ephemeral sources. Mutually exclusive with the legacy scalar fields
	// below (Kind/Source/Ref/DefaultTarget/Writable) — set one or the other,
	// never both. Omitting both onboards the composition floor: one ephemeral
	// scratch source.
	Sources []types.WorkspaceSource `json:"sources,omitempty"`
	// BaseImage is the workspace's base-image choice. Nil means the platform
	// default convention image for the detected/scanned stack.
	BaseImage *types.WorkspaceBaseImage `json:"base_image,omitempty"`

	// Deprecated: Kind/Source/Ref/DefaultTarget/Writable are the pre-
	// composition-model scalar shape — a single source, folded server-side
	// into Sources[0] (legacyWorkspaceSource). Kept so
	// `wardyn workspace create --kind local_dir --source /x` and existing SDK
	// callers keep working; prefer Sources for a new caller, especially a
	// multi-source one.
	Kind          types.WorkspaceKind `json:"kind,omitempty"`
	Source        string              `json:"source,omitempty"`
	Ref           string              `json:"ref,omitempty"`
	DefaultTarget string              `json:"default_target,omitempty"`
	// Deprecated: see Kind. Writable opts the single legacy source into a
	// READ-WRITE mount for import Record/Verify runs; omitted/false is
	// read-only (the safe default). A sandboxed agent's changes then PERSIST
	// to the host directory. A multi-source caller sets WorkspaceSource.Writable
	// per source instead.
	Writable bool `json:"writable,omitempty"`
	// LLMCred is the operator-owned model/harness credential BINDING for this
	// workspace/container (refs/names only). A run that picks the workspace
	// inherits this model access. Nil => no binding. CREATE-ONLY: the update
	// handler ignores it, so changing a binding needs the standalone
	// PUT /workspaces/{id}/llm-cred route (not covered by this SDK).
	LLMCred *types.WorkspaceLLMCred `json:"llm_cred,omitempty"`
}

WorkspaceRequest is the body for POST/PUT /api/v1/workspaces. Name is required, plus either Sources or the legacy scalar shape (Kind+Source); the server validates each source with the same deny-list the run path uses (local_dir bind-mount safety, repo slug/URL shape) before persisting.

internal/api aliases this type (`type workspaceRequest = client.WorkspaceRequest`) so server and SDK cannot drift; the server rejects unknown JSON fields, so a field missing here is unreachable from the SDK rather than merely undocumented.

type WorkspaceRequirement added in v0.5.0 

type WorkspaceRequirement = types.WorkspaceRequirement

WorkspaceRequirement is one entry in Workspace.Requirements.

type WorkspaceSelection added in v0.5.0 

type WorkspaceSelection struct {
	// WorkspaceID is the workspace this selection applies to (string form of
	// its uuid — matched against the run's referenced workspaces by id).
	WorkspaceID string `json:"workspace_id"`
	// EnabledOptional lists the workspace's OPTIONAL requirement KEYS (the
	// exact "<type>:<key>" form, e.g. "egress:api.stripe.com" or
	// "write:/home/user/repo") this run opts into. A key not listed here stays
	// at its safe default (no egress, no grant, read-only mount).
	EnabledOptional []string `json:"enabled_optional,omitempty"`
	// ReadOnly, when set, NARROWS this workspace's write:<path> requirements —
	// true forces every one read-only even if Required or enabled; false is a
	// no-op (a selection may only narrow what the contract already grants,
	// never widen it — see the fold in internal/api/runs_create.go). Nil
	// leaves the contract's own resolved default in effect.
	ReadOnly *bool `json:"read_only,omitempty"`
	// Target is where this workspace appears inside the sandbox. It must be an
	// absolute, cleaned path strictly under /home/agent with no ".." element,
	// and outside the drive roots. It names one place, so it applies to a
	// workspace that attaches exactly one repository or folder (see Repos);
	// otherwise it is 422. Empty keeps the workspace's own source targets.
	//
	// Every resolved target of the run is compared, not only the ones a request
	// names: equal or nested targets across different workspaces (a drive's
	// included), or two repositories cloning into one directory, are refused
	// with 422 workspace_target_overlap. Nesting inside one workspace's own
	// sources stays allowed.
	//
	// The PRIMARY workspace is Workspaces[0]: the run is listed under it. Every
	// attached workspace must agree on the model-provider pin, the base image
	// and the Azure DevOps organisation (422 workspace_pin_conflict,
	// image_conflict, workspace_ado_org_conflict).
	Target string `json:"target,omitempty"`
	// Repos picks which of this workspace's repository sources the run clones,
	// each at an optional ref. Nil: every repository source at its onboarded
	// ref. Present: exactly these, so an empty list clones none (a pointer, so
	// an explicit [] survives json.Marshal). A repo the workspace does not carry
	// is 422 workspace_repo_unknown. The workspace's other sources attach as
	// they would without it.
	Repos *[]RepoSelection `json:"repos,omitempty"`
}

WorkspaceSelection is one per-run option set for an attached workspace. See CreateRunRequest.Workspaces.

type WorkspaceSource added in v0.5.0 

type WorkspaceSource = types.WorkspaceSource

WorkspaceSource is one entry in a Workspace's composition, carried in WorkspaceRequest.Sources and returned in Workspace.Sources.

type WorkspaceSourceType added in v0.5.0 

type WorkspaceSourceType = types.WorkspaceSourceType

WorkspaceSourceType discriminates a WorkspaceSource's kind (local_dir | repo | ephemeral).

type WorkspaceStatus added in v0.5.0 

type WorkspaceStatus = types.WorkspaceStatus

WorkspaceStatus is the onboarding/scan lifecycle of a Workspace or Source (Workspace.Status, Source.Status): not-yet-scanned, mid-scan, scanned (ready to use), or errored.

Source Files

View all Source files

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.