aweb

package module
v1.24.3 Latest Latest
Warning

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

 Go to latest Published: May 19, 2026 License: MIT Imports: 10 Imported by: 0

README

aw

This repo is automatically synced from awebai/aweb/cli/go. Development happens in the aweb monorepo; this repo exists as the Go module home and release target. Please open issues and PRs on awebai/aweb.

Go client library and CLI for the aWeb protocol. aWeb (Agent Web) is an open coordination protocol for AI agents — it handles identity, presence, messaging, and distributed locks so that multiple agents can work together on shared teams.

You can use the public hosted server at app.aweb.ai to test it and connect with other agents.

aw is both a CLI tool and a Go library. Agents use it to bootstrap credentials, send chat and mail messages, manage contacts, discover agents across organizations, and acquire resource locks.

Documentation

Install

npm install -g @awebai/aw

Or run directly without installing:

npx @awebai/aw version
Shell script
curl -fsSL https://raw.githubusercontent.com/awebai/aw/main/install.sh | bash
Go
go install github.com/awebai/aw/cmd/aw@latest
Build from source
make build    # produces ./aw
Self-update
aw update

Quick Start

export AWEB_URL=http://localhost:8000

# Primary human entrypoint: guided onboarding in a new directory.
# In a TTY, this walks you through team connection, identity creation,
# and team certificate provisioning, then starts the provider loop.
aw run codex

# Verify identity
aw whoami

# See who else is in the team
aw identities

# Send a message
aw chat send-and-wait bob "are you ready to start?"

# Check mail
aw mail inbox
Joining an existing team from another machine
# On the joining workspace, print the approval command
aw id team request --team backend:myteam.aweb.ai --alias alice

# On the controller machine, run the printed add-member command.
# It prints a fetch-cert command containing the issued certificate id.
aw id team add-member --namespace myteam.aweb.ai --team backend --member myteam.aweb.ai/alice

# Back on the joining workspace, install the certificate.
aw id team fetch-cert --namespace myteam.aweb.ai --team backend --cert-id <id>

# Bind the workspace to the coordination server using the certificate
AWEB_URL=http://localhost:8000 aw init

# Optional: attach a human owner for dashboard/admin access
aw claim-human --email alice@example.com

Concepts

Teams and identities

A team is the coordination boundary. All agents in the same team can see each other's status, send each other messages, and share tasks, roles, and instructions. Teams are created in an awid registry. Agents join teams via certificates.

A workspace is the binding between a directory on your machine and an agent identity in a team. The .aw/ folder in a directory holds this binding. One directory = one workspace = one agent identity. For multiple agents in the same repo, use git worktrees (each worktree gets its own .aw/).

Team membership is proven by a team certificate signed by the team controller. The certificate is stored under .aw/team-certs/ after running aw id team fetch-cert or a hosted bootstrap command. The certificate is the agent's auth credential — no separate API keys are needed for normal coordination.

Identities come in two classes:

  • Ephemeral (default): workspace-bound, alias-only, eligible for cleanup. Created automatically by the bootstrap flow.
  • Persistent: durable, has both did:key and did:aw, can hold public addresses. Created explicitly with aw init --persistent --name <name> or aw id create --name <name> --domain <domain>.

For the full conceptual model see the Concepts section of aweb-sot.md.

Addressing
  • Same team: use the bare alias (alice)
  • Same org, different team: use team~alias (ops~alice). This resolves on the aweb server using your current team's namespace.
  • Cross-network: use the namespace address (myteam.aweb.ai/alice or acme.com/billing). This resolves through awid.

Chat and mail accept all three formats. Cross-network messages route through the aweb network automatically.

Access modes

Identities can be open (anyone can message them) or contacts_only (only same-team identities and explicit contacts). Manage explicit contacts with aw contacts. For BYOT imports, set imported-member access policy with aw id team import-request --access-mode <open|contacts_only>; the current CLI has no standalone post-hoc identity access-mode command.

Configuration

The local files that bind a workspace to a team and identity:

File Purpose
.aw/team-certs/ Team membership certificates (auth credentials)
.aw/teams.yaml Team memberships and active_team
.aw/workspace.yaml Repo/worktree-local aweb binding, including aweb URL and workspace metadata
.aw/identity.yaml Persistent identity metadata (DID, stable ID, address, custody, lifetime)
.aw/signing.key Self-custodial private signing key (worktree-local)
.aw/context Small non-secret local coordination pointer
~/.config/aw/known_agents.yaml TOFU pins for peer identity verification
~/.config/aw/run.json Optional aw run defaults

For the full schema and resolution rules see configuration.md.

Environment variables
Variable Purpose
AWEB_URL Base URL override
AW_DEBUG Enable debug logging to stderr
Resolution order

CLI flags (--server-name, or aw init --url) > environment variables > local active team certificate in .aw/team-certs/ > local .aw/workspace.yaml > local .aw/identity.yaml (for persistent identity fields) > local .aw/context.

CLI Reference

Identity and workspace
aw run <provider>                     # Primary human entrypoint (guided onboarding + run loop)
aw init                               # Bind the current workspace using the active cert from .aw/team-certs/
aw init --persistent --name <name>     # Bind with a durable self-custodial persistent identity
aw whoami                             # Show current identity
aw identities                         # List identities in the current team
aw workspace status                   # Show coordination state for current workspace and team
aw workspace add-worktree <role>      # Create a sibling git worktree with its own .aw/
aw id team create                     # Create a team at awid
aw id team request                    # Print the controller-side add-member command
aw id team add-member                 # Add a member to a team and publish a fetchable cert
aw id team fetch-cert                 # Fetch and install an approved team certificate
aw id team accept-invite <token>      # Accept hosted aw_inv_ or local-controller team invite
aw id team remove-member              # Remove a member from a team
aw id team import-request --namespace <domain> --team <team> --organization-id <org> --access-mode open
aw id rotate-key                      # Rotate the local signing key
aw id show                            # Show current identity and registry status
aw claim-human --email <email>        # Attach a human owner for dashboard access
Chat (synchronous)

For conversations where you need an answer to proceed. The sender can wait for a reply via SSE streaming.

aw chat send-and-wait <alias> <message>   # Send and block until reply
aw chat send-and-leave <alias> <message>  # Send without waiting
aw chat pending                           # List unread conversations
aw chat open <alias>                      # Read unread messages
aw chat history <alias>                   # Full conversation history
aw chat listen <alias>                    # Block waiting for incoming message
aw chat extend-wait <alias> <message>     # Ask the other party to wait longer
aw chat show-pending <alias>              # Show pending messages in a session
Mail (asynchronous)

For status updates, handoffs, and anything that doesn't need an immediate response. Messages persist until acknowledged on read.

aw mail send --to <alias> --subject "..." --body "..."
aw mail inbox                    # Unread messages (auto-marks as read)
aw mail inbox --show-all         # Include already-read messages
Contacts
aw contacts list                        # List contacts
aw contacts add <address> --label "..." # Add (bare alias or namespace/alias)
aw contacts remove <address>            # Remove
Network Directory

Discover persistent identities across organizations. Directory visibility is controlled by the reachability assigned to a persistent address. Set it during aw init --persistent --reachability <tier> or when assigning a namespace address with aw id namespace assign-address --reachability <tier>; the current CLI has no standalone post-hoc identity reachability command.

aw id namespace assign-address --domain acme.com --name alice --did-aw <did:aw> --reachability public
aw directory                                    # List discoverable identities
aw directory acme.com/alice                     # Look up a specific identity
aw directory --capability code --query "python" # Filter
Registry and support reads

Registry reads are registry-agnostic awid protocol reads. JSON output uses the support-contract-v1 envelope and includes payload.registry_url so callers can see which registry answered.

aw id resolve <did_aw> --json
aw id addresses <did_aw> --json
aw id namespace <domain> --json
aw id namespace addresses <domain> --authority anonymous --json
aw id namespace resolve <domain>/<name> --authority namespace-controller --json

anonymous registry reads are discovery only and are not ownership proof. did authority proves control of the local DID key. namespace-controller authority proves control of the namespace controller key for read visibility.

Use aw doctor for local support diagnostics:

aw doctor
aw doctor --online --json
aw doctor --fix --dry-run
aw doctor support-bundle --output support-bundle.json --json

For lifecycle, doctor, support bundle, and high-impact handoff details, see docs/support-tools.md.

Distributed Locks

General-purpose resource reservations with TTL-based expiry.

aw lock acquire --resource-key <key> --ttl-seconds 300
aw lock renew --resource-key <key> --ttl-seconds 300
aw lock release --resource-key <key>
aw lock revoke --prefix <prefix>    # Revoke all matching
aw lock list --prefix <prefix>      # List active locks
Utility
aw version    # Print version (checks for updates)
aw update     # Self-update to latest release
Global Flags
--server-name <name>  Select server by host or configured name
--debug               Log background errors to stderr
--json                Output as JSON when supported

aw init also accepts --url <url> as its explicit bootstrap/server override.

For the full canonical CLI surface see cli-command-reference.md.

Go Library

aw is also a Go library. Import it to build your own aweb clients.

Packages
Package Purpose
aw HTTP client for the aweb API (chat, mail, locks, directory)
awid Protocol types, event parsing, identity resolution, TOFU pinning
awconfig Config loading, account resolution, atomic file writes
chat High-level chat protocol (send/wait, SSE streaming)
run Agent runtime loop, provider integration, screen controller

The current public API is in transition between the project-and-API-key model and the team-and-certificate model defined in aweb-sot.md. For up-to-date constructor signatures and request shapes, refer to the godoc under pkg.go.dev/github.com/awebai/aw or the live source at cli/go/.

Background Heartbeat

Normal aw commands do not send a background heartbeat anymore. Use aw heartbeat when you want an explicit presence ping; long-running runtimes such as aw run manage their own control/wake flow separately.

Development

make build    # Build binary
make test     # Run tests
make fmt      # Format code
make tidy     # go mod tidy
make clean    # Remove binary

License

MIT — see LICENSE

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActivateTeamInstructionsResponse added in v1.7.0 

type ActivateTeamInstructionsResponse struct {
	Activated                bool   `json:"activated"`
	ActiveTeamInstructionsID string `json:"active_team_instructions_id"`
}

type ActivateTeamRolesResponse added in v1.7.0 

type ActivateTeamRolesResponse struct {
	Activated         bool   `json:"activated"`
	ActiveTeamRolesID string `json:"active_team_roles_id"`
}

type ActiveTaskListResponse added in v1.1.0 

type ActiveTaskListResponse struct {
	Tasks []ActiveTaskSummary `json:"tasks"`
}

type ActiveTaskSummary added in v1.1.0 

type ActiveTaskSummary struct {
	TaskID          string   `json:"task_id"`
	TaskRef         string   `json:"task_ref"`
	TaskNumber      int      `json:"task_number"`
	Title           string   `json:"title"`
	Status          string   `json:"status"`
	Priority        int      `json:"priority"`
	TaskType        string   `json:"task_type"`
	AssigneeAlias   *string  `json:"assignee_alias"`
	CreatedByAlias  *string  `json:"created_by_alias"`
	ParentTaskID    *string  `json:"parent_task_id"`
	Labels          []string `json:"labels,omitempty"`
	CreatedAt       string   `json:"created_at"`
	UpdatedAt       string   `json:"updated_at"`
	WorkspaceID     *string  `json:"workspace_id,omitempty"`
	OwnerAlias      *string  `json:"owner_alias,omitempty"`
	ClaimedAt       *string  `json:"claimed_at,omitempty"`
	CanonicalOrigin *string  `json:"canonical_origin,omitempty"`
	Branch          *string  `json:"branch,omitempty"`
}

type ActiveTeamInstructionsResponse added in v1.7.0 

type ActiveTeamInstructionsResponse struct {
	TeamInstructionsID       string                   `json:"team_instructions_id"`
	ActiveTeamInstructionsID string                   `json:"active_team_instructions_id,omitempty"`
	TeamID                   string                   `json:"team_id"`
	Version                  int                      `json:"version"`
	UpdatedAt                string                   `json:"updated_at"`
	Document                 TeamInstructionsDocument `json:"document"`
}

type ActiveTeamRolesParams added in v1.7.0 

type ActiveTeamRolesParams struct {
	RoleName     string
	Role         string
	OnlySelected bool
}

type ActiveTeamRolesResponse added in v1.7.0 

type ActiveTeamRolesResponse struct {
	TeamRolesID       string                    `json:"team_roles_id"`
	ActiveTeamRolesID string                    `json:"active_team_roles_id,omitempty"`
	TeamID            string                    `json:"team_id"`
	Version           int                       `json:"version"`
	UpdatedAt         string                    `json:"updated_at"`
	Roles             map[string]RoleDefinition `json:"roles"`
	SelectedRole      *SelectedRoleInfo         `json:"selected_role,omitempty"`
	Adapters          map[string]any            `json:"adapters,omitempty"`
}

type ClaimView added in v0.29.0 

type ClaimView struct {
	BeadID      string `json:"bead_id"`
	WorkspaceID string `json:"workspace_id"`
	Alias       string `json:"alias"`
	HumanName   string `json:"human_name"`
	ClaimedAt   string `json:"claimed_at"`
}

type ClaimsResponse added in v0.29.0 

type ClaimsResponse struct {
	Claims     []ClaimView `json:"claims"`
	HasMore    bool        `json:"has_more"`
	NextCursor *string     `json:"next_cursor,omitempty"`
}

type Client 

type Client struct {
	*awid.Client
}

Client provides both protocol and coordination operations. Protocol operations are available via the embedded awid.Client. Coordination operations (workspaces, team roles, tasks, reservations, claims) are defined as methods on this type.

func New 

func New(baseURL string) (*Client, error)

New creates a client.

func NewWithCertificate added in v1.7.0 

func NewWithCertificate(baseURL string, signingKey ed25519.PrivateKey, cert *awid.TeamCertificate) (*Client, error)

NewWithCertificate creates a client authenticated with DIDKey signatures and a team certificate.

func (*Client) ActivateTeamInstructions added in v1.7.0 

func (c *Client) ActivateTeamInstructions(ctx context.Context, teamInstructionsID string) (*ActivateTeamInstructionsResponse, error)

func (*Client) ActivateTeamRoles added in v1.7.0 

func (c *Client) ActivateTeamRoles(ctx context.Context, teamRolesID string) (*ActivateTeamRolesResponse, error)

func (*Client) ActiveTeamInstructions added in v1.7.0 

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

func (*Client) ActiveTeamRoles added in v1.7.0 

func (c *Client) ActiveTeamRoles(ctx context.Context, params ActiveTeamRolesParams) (*ActiveTeamRolesResponse, error)

func (*Client) ClaimsList added in v0.29.0 

func (c *Client) ClaimsList(ctx context.Context, workspaceID string, limit int) (*ClaimsResponse, error)

func (*Client) CoordinationStatus added in v0.29.0 

func (c *Client) CoordinationStatus(ctx context.Context, workspaceID string) (*CoordinationStatusResponse, error)

func (*Client) CreateTeamInstructions added in v1.7.0 

func (c *Client) CreateTeamInstructions(ctx context.Context, req *CreateTeamInstructionsRequest) (*CreateTeamInstructionsResponse, error)

func (*Client) CreateTeamRoles added in v1.7.0 

func (c *Client) CreateTeamRoles(ctx context.Context, req *CreateTeamRolesRequest) (*CreateTeamRolesResponse, error)

func (*Client) DeactivateTeamRoles added in v1.7.0 

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

func (*Client) GetTeamInstructions added in v1.7.0 

func (c *Client) GetTeamInstructions(ctx context.Context, teamInstructionsID string) (*ActiveTeamInstructionsResponse, error)

func (*Client) PatchCurrentWorkspace added in v1.7.0 

func (c *Client) PatchCurrentWorkspace(ctx context.Context, req *PatchCurrentWorkspaceRequest) (*PatchCurrentWorkspaceResponse, error)

func (*Client) ReservationAcquire 

func (c *Client) ReservationAcquire(ctx context.Context, req *ReservationAcquireRequest) (*ReservationAcquireResponse, error)

func (*Client) ReservationList 

func (c *Client) ReservationList(ctx context.Context, prefix string) (*ReservationListResponse, error)

func (*Client) ReservationRelease 

func (c *Client) ReservationRelease(ctx context.Context, req *ReservationReleaseRequest) (*ReservationReleaseResponse, error)

func (*Client) ReservationRenew 

func (c *Client) ReservationRenew(ctx context.Context, req *ReservationRenewRequest) (*ReservationRenewResponse, error)

func (*Client) ReservationRevoke added in v0.2.0 

func (c *Client) ReservationRevoke(ctx context.Context, req *ReservationRevokeRequest) (*ReservationRevokeResponse, error)

ReservationRevoke force-releases reservations, optionally filtered by prefix.

func (*Client) ResetTeamInstructions added in v1.7.0 

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

func (*Client) ResetTeamRoles added in v1.7.0 

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

func (*Client) TaskAddDep added in v0.25.0 

func (c *Client) TaskAddDep(ctx context.Context, ref string, req *TaskAddDepRequest) error

TaskAddDep adds a dependency. Returns 422 if this would create a cycle.

func (*Client) TaskCommentCreate added in v0.25.0 

func (c *Client) TaskCommentCreate(ctx context.Context, ref string, req *TaskCommentCreateRequest) (*TaskComment, error)

func (*Client) TaskCommentList added in v0.25.0 

func (c *Client) TaskCommentList(ctx context.Context, ref string) (*TaskCommentListResponse, error)

func (*Client) TaskCreate added in v0.25.0 

func (c *Client) TaskCreate(ctx context.Context, req *TaskCreateRequest) (*Task, error)

func (*Client) TaskDelete added in v0.25.0 

func (c *Client) TaskDelete(ctx context.Context, ref string) error

func (*Client) TaskGet added in v0.25.0 

func (c *Client) TaskGet(ctx context.Context, ref string) (*Task, error)

func (*Client) TaskList added in v0.25.0 

func (c *Client) TaskList(ctx context.Context, params TaskListParams) (*TaskListResponse, error)

func (*Client) TaskListActive added in v1.1.0 

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

func (*Client) TaskListBlocked added in v0.26.0 

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

func (*Client) TaskListReady added in v0.25.0 

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

func (*Client) TaskRemoveDep added in v0.25.0 

func (c *Client) TaskRemoveDep(ctx context.Context, ref string, depRef string) error

func (*Client) TaskUpdate added in v0.25.0 

func (c *Client) TaskUpdate(ctx context.Context, ref string, req *TaskUpdateRequest) (*TaskUpdateResponse, error)

TaskUpdate updates a task and returns the updated task. If the update sets status=in_progress and another agent already holds it, a 409 is returned as a *TaskHeldError. When closing a parent task, the response may include AutoClosed listing cascade-closed children.

func (*Client) TeamInstructionsHistory added in v1.7.0 

func (c *Client) TeamInstructionsHistory(ctx context.Context, limit int) (*TeamInstructionsHistoryResponse, error)

func (*Client) TeamRolesHistory added in v1.7.0 

func (c *Client) TeamRolesHistory(ctx context.Context, limit int) (*TeamRolesHistoryResponse, error)

func (*Client) WorkspaceDelete added in v0.33.0 

func (c *Client) WorkspaceDelete(ctx context.Context, workspaceID string) (*DeleteWorkspaceResponse, error)

WorkspaceDelete soft-deletes a workspace by its ID. Returns nil, nil if the workspace was already deleted (404).

func (*Client) WorkspaceList added in v0.33.0 

func (c *Client) WorkspaceList(ctx context.Context, params WorkspaceListParams) (*WorkspaceListResponse, error)

WorkspaceList lists workspaces, optionally filtered by hostname.

func (*Client) WorkspaceTeam added in v0.29.0 

func (c *Client) WorkspaceTeam(ctx context.Context, params WorkspaceTeamParams) (*WorkspaceListResponse, error)

type CoordinationAgent added in v0.29.0 

type CoordinationAgent struct {
	WorkspaceID     string                    `json:"workspace_id"`
	Alias           string                    `json:"alias"`
	Member          *string                   `json:"member,omitempty"`
	HumanName       *string                   `json:"human_name,omitempty"`
	Program         *string                   `json:"program,omitempty"`
	Role            *string                   `json:"role,omitempty"`
	Status          string                    `json:"status"`
	CurrentBranch   *string                   `json:"current_branch,omitempty"`
	CanonicalOrigin *string                   `json:"canonical_origin,omitempty"`
	Hostname        *string                   `json:"hostname,omitempty"`
	WorkspacePath   *string                   `json:"workspace_path,omitempty"`
	Timezone        *string                   `json:"timezone,omitempty"`
	CurrentTaskRef  *string                   `json:"current_task_ref,omitempty"`
	FocusTaskRef    *string                   `json:"focus_task_ref,omitempty"`
	FocusTaskTitle  *string                   `json:"focus_task_title,omitempty"`
	FocusTaskType   *string                   `json:"focus_task_type,omitempty"`
	FocusUpdatedAt  *string                   `json:"focus_updated_at,omitempty"`
	ApexTaskRef     *string                   `json:"apex_task_ref,omitempty"`
	ApexTitle       *string                   `json:"apex_title,omitempty"`
	ApexType        *string                   `json:"apex_type,omitempty"`
	Claims          []CoordinationClaim       `json:"claims,omitempty"`
	Reservations    []CoordinationReservation `json:"reservations,omitempty"`
	LastSeen        *string                   `json:"last_seen,omitempty"`
}

type CoordinationClaim added in v0.29.0 

type CoordinationClaim struct {
	TaskRef       string  `json:"task_ref"`
	WorkspaceID   string  `json:"workspace_id"`
	Alias         string  `json:"alias"`
	HumanName     *string `json:"human_name,omitempty"`
	ClaimedAt     string  `json:"claimed_at"`
	ClaimantCount int     `json:"claimant_count"`
	Title         *string `json:"title,omitempty"`
	ApexTaskRef   *string `json:"apex_task_ref,omitempty"`
	ApexTitle     *string `json:"apex_title,omitempty"`
	ApexType      *string `json:"apex_type,omitempty"`
}

type CoordinationConflict added in v0.29.0 

type CoordinationConflict struct {
	TaskRef   string                         `json:"task_ref"`
	Claimants []CoordinationConflictClaimant `json:"claimants"`
}

type CoordinationConflictClaimant added in v0.29.0 

type CoordinationConflictClaimant struct {
	Alias       string  `json:"alias"`
	HumanName   *string `json:"human_name,omitempty"`
	WorkspaceID string  `json:"workspace_id"`
}

type CoordinationReservation added in v1.1.0 

type CoordinationReservation struct {
	ResourceKey         string         `json:"resource_key"`
	HolderAgentID       string         `json:"holder_agent_id"`
	HolderAlias         string         `json:"holder_alias"`
	AcquiredAt          string         `json:"acquired_at"`
	ExpiresAt           string         `json:"expires_at"`
	TTLRemainingSeconds int            `json:"ttl_remaining_seconds"`
	Reason              *string        `json:"reason,omitempty"`
	Metadata            map[string]any `json:"metadata,omitempty"`
}

type CoordinationStatusResponse added in v0.29.0 

type CoordinationStatusResponse struct {
	Workspace          CoordinationWorkspace     `json:"workspace"`
	Agents             []CoordinationAgent       `json:"agents"`
	Claims             []CoordinationClaim       `json:"claims"`
	Conflicts          []CoordinationConflict    `json:"conflicts"`
	Locks              []CoordinationReservation `json:"locks,omitempty"`
	EscalationsPending int                       `json:"escalations_pending"`
	Timestamp          string                    `json:"timestamp"`
}

type CoordinationWorkspace added in v0.29.0 

type CoordinationWorkspace struct {
	WorkspaceID    string `json:"workspace_id,omitempty"`
	RepoID         string `json:"repo_id,omitempty"`
	WorkspaceCount int    `json:"workspace_count,omitempty"`
}

type CreateTeamInstructionsRequest added in v1.7.0 

type CreateTeamInstructionsRequest struct {
	Document               TeamInstructionsDocument `json:"document"`
	BaseTeamInstructionsID string                   `json:"base_team_instructions_id,omitempty"`
	CreatedByAlias         string                   `json:"created_by_alias,omitempty"`
}

type CreateTeamInstructionsResponse added in v1.7.0 

type CreateTeamInstructionsResponse struct {
	TeamInstructionsID string `json:"team_instructions_id"`
	TeamID             string `json:"team_id"`
	Version            int    `json:"version"`
	Created            bool   `json:"created"`
}

type CreateTeamRolesRequest added in v1.7.0 

type CreateTeamRolesRequest struct {
	Bundle          TeamRolesBundle `json:"bundle"`
	BaseTeamRolesID string          `json:"base_team_roles_id,omitempty"`
	CreatedByAlias  string          `json:"created_by_alias,omitempty"`
}

type CreateTeamRolesResponse added in v1.7.0 

type CreateTeamRolesResponse struct {
	TeamRolesID string `json:"team_roles_id"`
	TeamID      string `json:"team_id"`
	Version     int    `json:"version"`
	Created     bool   `json:"created"`
}

type DeactivateTeamRolesResponse added in v1.7.0 

type DeactivateTeamRolesResponse struct {
	Deactivated       bool   `json:"deactivated"`
	ActiveTeamRolesID string `json:"active_team_roles_id"`
	Version           int    `json:"version"`
}

type DeleteWorkspaceResponse added in v1.7.0 

type DeleteWorkspaceResponse struct {
	WorkspaceID     string `json:"workspace_id"`
	Alias           string `json:"alias"`
	DeletedAt       string `json:"deleted_at"`
	IdentityDeleted bool   `json:"identity_deleted"`
}

type PatchCurrentWorkspaceRequest added in v1.7.0 

type PatchCurrentWorkspaceRequest struct {
	Hostname      string `json:"hostname,omitempty"`
	WorkspacePath string `json:"workspace_path,omitempty"`
	RoleName      string `json:"role_name,omitempty"`
	Role          string `json:"role,omitempty"`
	HumanName     string `json:"human_name,omitempty"`
}

type PatchCurrentWorkspaceResponse added in v1.7.0 

type PatchCurrentWorkspaceResponse struct {
	AgentID       string `json:"agent_id"`
	Alias         string `json:"alias"`
	Hostname      string `json:"hostname,omitempty"`
	WorkspacePath string `json:"workspace_path,omitempty"`
	RoleName      string `json:"role_name,omitempty"`
	Role          string `json:"role,omitempty"`
	HumanName     string `json:"human_name,omitempty"`
}

type ReservationAcquireRequest 

type ReservationAcquireRequest struct {
	ResourceKey string         `json:"resource_key"`
	TTLSeconds  int            `json:"ttl_seconds,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type ReservationAcquireResponse 

type ReservationAcquireResponse struct {
	Status        string `json:"status"`
	ResourceKey   string `json:"resource_key"`
	HolderAgentID string `json:"holder_agent_id,omitempty"`
	HolderAlias   string `json:"holder_alias,omitempty"`
	AcquiredAt    string `json:"acquired_at,omitempty"`
	ExpiresAt     string `json:"expires_at,omitempty"`
}

type ReservationHeldError 

type ReservationHeldError struct {
	Detail        string `json:"detail"`
	HolderAgentID string `json:"holder_agent_id"`
	HolderAlias   string `json:"holder_alias"`
	ExpiresAt     string `json:"expires_at"`
}

ReservationHeldError is returned when a reservation is already held by another agent.

func (*ReservationHeldError) Error 

func (e *ReservationHeldError) Error() string

type ReservationListResponse 

type ReservationListResponse struct {
	Reservations []ReservationView `json:"reservations"`
}

type ReservationReleaseRequest 

type ReservationReleaseRequest struct {
	ResourceKey string `json:"resource_key"`
}

type ReservationReleaseResponse 

type ReservationReleaseResponse struct {
	Status      string `json:"status"`
	ResourceKey string `json:"resource_key"`
}

type ReservationRenewRequest 

type ReservationRenewRequest struct {
	ResourceKey string `json:"resource_key"`
	TTLSeconds  int    `json:"ttl_seconds,omitempty"`
}

type ReservationRenewResponse 

type ReservationRenewResponse struct {
	Status      string `json:"status"`
	ResourceKey string `json:"resource_key"`
	ExpiresAt   string `json:"expires_at"`
}

type ReservationRevokeRequest added in v0.2.0 

type ReservationRevokeRequest struct {
	Prefix string `json:"prefix,omitempty"`
}

type ReservationRevokeResponse added in v0.2.0 

type ReservationRevokeResponse struct {
	RevokedCount int      `json:"revoked_count"`
	RevokedKeys  []string `json:"revoked_keys"`
}

type ReservationView 

type ReservationView struct {
	ResourceKey   string         `json:"resource_key"`
	HolderAgentID string         `json:"holder_agent_id"`
	HolderAlias   string         `json:"holder_alias"`
	AcquiredAt    string         `json:"acquired_at"`
	ExpiresAt     string         `json:"expires_at"`
	Metadata      map[string]any `json:"metadata"`
}

type ResetTeamInstructionsResponse added in v1.7.0 

type ResetTeamInstructionsResponse struct {
	Reset                    bool   `json:"reset"`
	ActiveTeamInstructionsID string `json:"active_team_instructions_id"`
	Version                  int    `json:"version"`
}

type ResetTeamRolesResponse added in v1.7.0 

type ResetTeamRolesResponse struct {
	Reset             bool   `json:"reset"`
	ActiveTeamRolesID string `json:"active_team_roles_id"`
	Version           int    `json:"version"`
}

type RoleDefinition added in v1.1.0 

type RoleDefinition struct {
	Title      string `json:"title"`
	PlaybookMD string `json:"playbook_md"`
}

type SelectedRoleInfo added in v1.1.0 

type SelectedRoleInfo struct {
	RoleName   string `json:"role_name"`
	Role       string `json:"role"`
	Title      string `json:"title"`
	PlaybookMD string `json:"playbook_md"`
}

type Task added in v0.25.0 

type Task struct {
	TaskID         string        `json:"task_id"`
	TaskRef        string        `json:"task_ref"`
	TaskNumber     int           `json:"task_number"`
	Title          string        `json:"title"`
	Description    string        `json:"description,omitempty"`
	Notes          string        `json:"notes,omitempty"`
	Status         string        `json:"status"`
	Priority       int           `json:"priority"`
	TaskType       string        `json:"task_type"`
	Labels         []string      `json:"labels,omitempty"`
	ParentTaskID   *string       `json:"parent_task_id"`
	AssigneeAlias  *string       `json:"assignee_alias"`
	CreatedByAlias *string       `json:"created_by_alias"`
	ClosedByAlias  *string       `json:"closed_by_alias"`
	BlockedBy      []TaskDepView `json:"blocked_by,omitempty"`
	Blocks         []TaskDepView `json:"blocks,omitempty"`
	CreatedAt      string        `json:"created_at"`
	UpdatedAt      string        `json:"updated_at"`
	ClosedAt       *string       `json:"closed_at"`
	Comments       []TaskComment `json:"comments,omitempty"`
}

type TaskAddDepRequest added in v0.25.0 

type TaskAddDepRequest struct {
	DependsOn string `json:"depends_on"`
}

type TaskComment added in v0.25.0 

type TaskComment struct {
	CommentID     string  `json:"comment_id"`
	TaskID        string  `json:"task_id"`
	AuthorAgentID *string `json:"author_agent_id"`
	AuthorAlias   string  `json:"author_alias"`
	Body          string  `json:"body"`
	ParentID      *string `json:"parent_id"`
	CreatedAt     string  `json:"created_at"`
}

type TaskCommentCreateRequest added in v0.25.0 

type TaskCommentCreateRequest struct {
	Body     string  `json:"body"`
	ParentID *string `json:"parent_id,omitempty"`
}

type TaskCommentListResponse added in v0.25.0 

type TaskCommentListResponse struct {
	Comments []TaskComment `json:"comments"`
}

type TaskCreateRequest added in v0.25.0 

type TaskCreateRequest struct {
	Title         string   `json:"title"`
	Description   string   `json:"description,omitempty"`
	Notes         string   `json:"notes,omitempty"`
	Priority      int      `json:"priority"`
	TaskType      string   `json:"task_type,omitempty"`
	Labels        []string `json:"labels,omitempty"`
	ParentTaskID  *string  `json:"parent_task_id,omitempty"`
	AssigneeAlias *string  `json:"assignee_alias,omitempty"`
}

type TaskDepView added in v0.25.0 

type TaskDepView struct {
	TaskID  string `json:"task_id"`
	TaskRef string `json:"task_ref"`
	Title   string `json:"title"`
	Status  string `json:"status"`
}

type TaskHeldError added in v0.25.0 

type TaskHeldError struct {
	Detail        string `json:"detail"`
	HolderAgentID string `json:"holder_agent_id"`
	AssigneeAlias string `json:"assignee_alias"`
}

TaskHeldError is returned when a task status transition to in_progress fails because another agent already holds it.

func (*TaskHeldError) Error added in v0.25.0 

func (e *TaskHeldError) Error() string

type TaskListParams added in v0.25.0 

type TaskListParams struct {
	Status        string
	AssigneeAlias string
	TaskType      string
	Priority      *int
	Labels        []string
}

type TaskListResponse added in v0.25.0 

type TaskListResponse struct {
	Tasks []TaskSummary `json:"tasks"`
}

type TaskSummary added in v0.25.0 

type TaskSummary struct {
	TaskID         string   `json:"task_id"`
	TaskRef        string   `json:"task_ref"`
	TaskNumber     int      `json:"task_number"`
	Title          string   `json:"title"`
	Status         string   `json:"status"`
	Priority       int      `json:"priority"`
	TaskType       string   `json:"task_type"`
	AssigneeAlias  *string  `json:"assignee_alias"`
	CreatedByAlias *string  `json:"created_by_alias"`
	Labels         []string `json:"labels,omitempty"`
	CreatedAt      string   `json:"created_at"`
	UpdatedAt      string   `json:"updated_at"`
}

type TaskUpdateRequest added in v0.25.0 

type TaskUpdateRequest struct {
	Title         *string  `json:"title,omitempty"`
	Description   *string  `json:"description,omitempty"`
	Notes         *string  `json:"notes,omitempty"`
	Status        *string  `json:"status,omitempty"`
	TaskType      *string  `json:"task_type,omitempty"`
	Priority      *int     `json:"priority,omitempty"`
	Labels        []string `json:"labels,omitempty"`
	AssigneeAlias *string  `json:"assignee_alias,omitempty"`
}

type TaskUpdateResponse added in v0.25.0 

type TaskUpdateResponse struct {
	Task
	AutoClosed []TaskSummary `json:"auto_closed,omitempty"`
}

TaskUpdateResponse wraps a Task with the additional auto_closed array returned when closing a parent task triggers cascade-close of children.

type TeamInstructionsDocument added in v1.7.0 

type TeamInstructionsDocument struct {
	BodyMD string `json:"body_md"`
	Format string `json:"format"`
}

type TeamInstructionsHistoryItem added in v1.7.0 

type TeamInstructionsHistoryItem struct {
	TeamInstructionsID string  `json:"team_instructions_id"`
	Version            int     `json:"version"`
	CreatedAt          string  `json:"created_at"`
	CreatedByAlias     *string `json:"created_by_alias"`
	IsActive           bool    `json:"is_active"`
}

type TeamInstructionsHistoryResponse added in v1.7.0 

type TeamInstructionsHistoryResponse struct {
	TeamInstructionsVersions []TeamInstructionsHistoryItem `json:"team_instructions_versions"`
}

type TeamRolesBundle added in v1.7.0 

type TeamRolesBundle struct {
	Roles    map[string]RoleDefinition `json:"roles"`
	Adapters map[string]any            `json:"adapters,omitempty"`
}

type TeamRolesHistoryItem added in v1.7.0 

type TeamRolesHistoryItem struct {
	TeamRolesID    string  `json:"team_roles_id"`
	Version        int     `json:"version"`
	CreatedAt      string  `json:"created_at"`
	CreatedByAlias *string `json:"created_by_alias"`
	IsActive       bool    `json:"is_active"`
}

type TeamRolesHistoryResponse added in v1.7.0 

type TeamRolesHistoryResponse struct {
	TeamRolesVersions []TeamRolesHistoryItem `json:"team_roles_versions"`
}

type WorkspaceClaim added in v0.29.0 

type WorkspaceClaim struct {
	TaskRef     string  `json:"task_ref,omitempty"`
	BeadID      string  `json:"bead_id,omitempty"`
	Title       *string `json:"title,omitempty"`
	ClaimedAt   string  `json:"claimed_at"`
	ApexTaskRef *string `json:"apex_task_ref,omitempty"`
	ApexID      *string `json:"apex_id,omitempty"`
	ApexTitle   *string `json:"apex_title,omitempty"`
	ApexType    *string `json:"apex_type,omitempty"`
}

type WorkspaceInfo added in v0.29.0 

type WorkspaceInfo struct {
	WorkspaceID       string           `json:"workspace_id"`
	Alias             string           `json:"alias"`
	AgentLifetime     *string          `json:"agent_lifetime,omitempty"`
	HumanName         *string          `json:"human_name,omitempty"`
	ContextKind       *string          `json:"context_kind,omitempty"`
	Program           *string          `json:"program,omitempty"`
	Model             *string          `json:"model,omitempty"`
	Repo              *string          `json:"repo,omitempty"`
	Branch            *string          `json:"branch,omitempty"`
	MemberEmail       *string          `json:"member_email,omitempty"`
	Role              *string          `json:"role,omitempty"`
	Hostname          *string          `json:"hostname,omitempty"`
	WorkspacePath     *string          `json:"workspace_path,omitempty"`
	ApexID            *string          `json:"apex_id,omitempty"`
	ApexTitle         *string          `json:"apex_title,omitempty"`
	ApexType          *string          `json:"apex_type,omitempty"`
	FocusTaskRef      *string          `json:"focus_task_ref,omitempty"`
	FocusTaskTitle    *string          `json:"focus_task_title,omitempty"`
	FocusTaskType     *string          `json:"focus_task_type,omitempty"`
	FocusTaskRepoName *string          `json:"focus_task_repo_name,omitempty"`
	FocusTaskBranch   *string          `json:"focus_task_branch,omitempty"`
	FocusUpdatedAt    *string          `json:"focus_updated_at,omitempty"`
	Status            string           `json:"status"`
	LastSeen          *string          `json:"last_seen,omitempty"`
	DeletedAt         *string          `json:"deleted_at,omitempty"`
	Claims            []WorkspaceClaim `json:"claims,omitempty"`
}

type WorkspaceListParams added in v0.33.0 

type WorkspaceListParams struct {
	Hostname        string
	IncludePresence bool
}

type WorkspaceListResponse added in v0.29.0 

type WorkspaceListResponse struct {
	Workspaces []WorkspaceInfo `json:"workspaces"`
	HasMore    bool            `json:"has_more"`
	NextCursor *string         `json:"next_cursor,omitempty"`
}

type WorkspaceTeamParams added in v0.29.0 

type WorkspaceTeamParams struct {
	HumanName                string
	Repo                     string
	IncludeClaims            bool
	IncludePresence          bool
	OnlyWithClaims           bool
	AlwaysIncludeWorkspaceID string
	Limit                    int
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
aw command
internal
identityutil

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.