serve

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 54 Imported by: 0

Documentation

Overview

Package serve provides REST API endpoints for account management.

Package serve provides audit trail functionality for REST and WebSocket actions.

Package serve provides REST API endpoints for beads and bv robot integration. beads.go implements the /api/v1/beads endpoints.

Package serve provides REST API endpoints for CASS and CM (Memory) integration. cass.go implements the /api/v1/cass and /api/v1/memory endpoints.

Package serve provides REST API endpoints for checkpoint management.

Package serve provides REST API endpoints for Agent Mail and file reservations. mail.go implements the /api/v1/mail and /api/v1/reservations endpoints.

Package serve provides HTTP server functionality including OpenAPI spec generation.

Package serve provides REST API endpoints for pipeline management. pipelines.go implements the /api/v1/pipelines endpoints.

Package serve provides RBAC (Role-Based Access Control) for the NTM HTTP server.

Package serve provides REST API handlers for safety and policy management.

Package serve provides REST API endpoints for UBS scanner integration. scanner.go implements the /api/v1/scanner endpoints.

Package serve provides an HTTP server for NTM with REST API and event streaming.

Package serve provides WebSocket event persistence, resume, and backpressure handling.

Index

Constants

View Source 
const (
	ErrCodeBeadsUnavailable = "BEADS_UNAVAILABLE"
	ErrCodeBeadNotFound     = "BEAD_NOT_FOUND"
	ErrCodeBVUnavailable    = "BV_UNAVAILABLE"
)

Beads-specific error codes

View Source 
const (
	ErrCodeCASSUnavailable   = "CASS_UNAVAILABLE"
	ErrCodeMemoryUnavailable = "MEMORY_UNAVAILABLE"
	ErrCodeDaemonNotRunning  = "DAEMON_NOT_RUNNING"
	ErrCodeDaemonRunning     = "DAEMON_ALREADY_RUNNING"
	ErrCodeSearchFailed      = "SEARCH_FAILED"
	ErrCodeContextFailed     = "CONTEXT_FAILED"
	ErrCodeOutcomeFailed     = "OUTCOME_FAILED"
	ErrCodePrivacyFailed     = "PRIVACY_FAILED"
)

CASS/Memory-specific error codes

View Source 
const (
	ErrCodeMailUnavailable   = "MAIL_UNAVAILABLE"
	ErrCodeAgentNotFound     = "AGENT_NOT_FOUND"
	ErrCodeMessageNotFound   = "MESSAGE_NOT_FOUND"
	ErrCodeThreadNotFound    = "THREAD_NOT_FOUND"
	ErrCodeReservationFailed = "RESERVATION_FAILED"
	ErrCodeContactDenied     = "CONTACT_DENIED"
)

Mail-specific error codes

View Source 
const (
	ErrCodePipelineNotFound = "PIPELINE_NOT_FOUND"
	ErrCodePipelineRunning  = "PIPELINE_RUNNING"
	ErrCodePipelineFailed   = "PIPELINE_FAILED"
	ErrCodeInvalidWorkflow  = "INVALID_WORKFLOW"
	ErrCodeMissingWorkflow  = "MISSING_WORKFLOW"
	ErrCodeMissingSession   = "MISSING_SESSION"
	ErrCodeTemplateNotFound = "TEMPLATE_NOT_FOUND"
	ErrCodeNoResumableState = "NO_RESUMABLE_STATE"
)

Pipeline-specific error codes

View Source 
const (
	ErrCodeScannerUnavailable = "SCANNER_UNAVAILABLE"
	ErrCodeScanNotFound       = "SCAN_NOT_FOUND"
	ErrCodeFindingNotFound    = "FINDING_NOT_FOUND"
	ErrCodeScanInProgress     = "SCAN_IN_PROGRESS"
	ErrCodeScanFailed         = "SCAN_FAILED"
)

Scanner-specific error codes

View Source 
const (
	ErrCodeBadRequest       = "BAD_REQUEST"
	ErrCodeUnauthorized     = "UNAUTHORIZED"
	ErrCodeForbidden        = "FORBIDDEN"
	ErrCodeNotFound         = "NOT_FOUND"
	ErrCodeMethodNotAllowed = "METHOD_NOT_ALLOWED"
	ErrCodeConflict         = "CONFLICT"
	ErrCodeInternalError    = "INTERNAL_ERROR"
	ErrCodeServiceUnavail   = "SERVICE_UNAVAILABLE"
	ErrCodeIdempotentReplay = "IDEMPOTENT_REPLAY"
	ErrCodeJobPending       = "JOB_PENDING"
)

Common error codes (matching robot mode conventions).

View Source 
const ErrCodeApprovalRequired = "APPROVAL_REQUIRED"

ErrCodeApprovalRequired is the error code for operations requiring approval.

Variables

This section is empty.

Functions

func CheckPermission 

func CheckPermission(w http.ResponseWriter, r *http.Request, perm Permission) bool

CheckPermission is a helper for handlers to check permissions inline. Returns true if permission is granted, false otherwise. When false, it also writes an error response.

func RedactJSON added in v1.7.0 

func RedactJSON(data interface{}, cfg redaction.Config) (interface{}, int)

RedactJSON redacts sensitive content in a JSON value. This is useful for redacting specific fields in request/response structures.

func RedactRequestFields added in v1.7.0 

func RedactRequestFields(cfg redaction.Config, fields ...*string) int

RedactRequestFields redacts specific fields in a request struct. Fields must be string pointers or string fields.

func SetAuditAction 

func SetAuditAction(r *http.Request, action AuditAction)

SetAuditAction sets the audit action type.

func SetAuditApproval 

func SetAuditApproval(r *http.Request, approvalID string)

SetAuditApproval sets the approval ID for audit logging.

func SetAuditContext 

func SetAuditContext(r *http.Request, ac *AuditContext) *http.Request

SetAuditContext adds audit context to a request.

func SetAuditDetails 

func SetAuditDetails(r *http.Request, details string)

SetAuditDetails sets additional details for audit logging.

func SetAuditResource 

func SetAuditResource(r *http.Request, resource, resourceID string)

SetAuditResource sets the resource being accessed for audit logging. Handlers should call this to provide context for the audit record.

func SetAuditSession 

func SetAuditSession(r *http.Request, sessionID, paneID, agentID string)

SetAuditSession sets session/pane/agent IDs for audit logging.

func ValidateConfig 

func ValidateConfig(cfg Config) error

ValidateConfig checks server configuration for security and completeness.

Types

type APIError 

type APIError struct {
	APIResponse
	Error     string                 `json:"error"`
	ErrorCode string                 `json:"error_code,omitempty"`
	Details   map[string]interface{} `json:"details,omitempty"`
	Hint      string                 `json:"hint,omitempty"`
}

APIError represents a structured error response.

type APIResponse 

type APIResponse struct {
	Success   bool   `json:"success"`
	Timestamp string `json:"timestamp"`
	RequestID string `json:"request_id,omitempty"`
}

APIResponse is the base envelope for all API responses.

type AccountRotationEvent 

type AccountRotationEvent struct {
	Timestamp       string `json:"timestamp"`
	Provider        string `json:"provider"`
	PreviousAccount string `json:"previous_account,omitempty"`
	NewAccount      string `json:"new_account,omitempty"`
	Reason          string `json:"reason,omitempty"`
	Automatic       bool   `json:"automatic"`
	Success         bool   `json:"success"`
	Error           string `json:"error,omitempty"`
}

AccountRotationEvent records a rotation event for history.

type AccountsConfig 

type AccountsConfig struct {
	// AutoRotateEnabled controls whether auto-rotation is enabled.
	AutoRotateEnabled bool `json:"auto_rotate_enabled"`

	// AutoRotateCooldownSeconds is the cooldown between auto-rotations.
	AutoRotateCooldownSeconds int `json:"auto_rotate_cooldown_seconds"`

	// AutoRotateOnRateLimit triggers rotation on rate limit detection.
	AutoRotateOnRateLimit bool `json:"auto_rotate_on_rate_limit"`
}

AccountsConfig holds configuration for account management endpoints.

type AddDependencyRequest 

type AddDependencyRequest struct {
	BlockedBy string `json:"blocked_by"` // ID of the bead that blocks this one
}

AddDependencyRequest is the request body for POST /api/v1/beads/{id}/deps

type AgentInterruptRequest 

type AgentInterruptRequest struct {
	Panes   []string `json:"panes,omitempty"`
	Message string   `json:"message,omitempty"`
	Force   bool     `json:"force,omitempty"`
	NoWait  bool     `json:"no_wait,omitempty"`
}

AgentInterruptRequest is the request body for POST /sessions/{id}/agents/interrupt.

type AgentRestartRequest 

type AgentRestartRequest struct {
	Panes     []string `json:"panes,omitempty"`
	AgentType string   `json:"agent_type,omitempty"`
	All       bool     `json:"all,omitempty"`
	DryRun    bool     `json:"dry_run,omitempty"`
}

AgentRestartRequest is the request body for POST /sessions/{id}/agents/restart.

type AgentSendRequest 

type AgentSendRequest struct {
	Panes      []string `json:"panes,omitempty"`
	AgentTypes []string `json:"agent_types,omitempty"`
	Message    string   `json:"message"`
	All        bool     `json:"all,omitempty"`
}

AgentSendRequest is the request body for POST /sessions/{id}/agents/send.

type AgentSpawnRequest 

type AgentSpawnRequest struct {
	CCCount   int    `json:"cc_count,omitempty"`
	CodCount  int    `json:"cod_count,omitempty"`
	GmiCount  int    `json:"gmi_count,omitempty"`
	Preset    string `json:"preset,omitempty"`
	WaitReady bool   `json:"wait_ready,omitempty"`
}

AgentSpawnRequest is the request body for POST /sessions/{id}/agents/spawn.

type AgentWaitRequest 

type AgentWaitRequest struct {
	Condition   string `json:"condition"`
	TimeoutMs   int    `json:"timeout_ms,omitempty"`
	PollMs      int    `json:"poll_ms,omitempty"`
	Panes       []int  `json:"panes,omitempty"`
	AgentType   string `json:"agent_type,omitempty"`
	WaitForAny  bool   `json:"wait_for_any,omitempty"`
	ExitOnError bool   `json:"exit_on_error,omitempty"`
}

AgentWaitRequest is the request body for POST /sessions/{id}/agents/wait.

type Approval 

type Approval struct {
	ID          string    `json:"id"`
	Action      string    `json:"action"`       // The action requiring approval
	Resource    string    `json:"resource"`     // The resource being acted on
	Requestor   string    `json:"requestor"`    // Who requested the action
	Reason      string    `json:"reason"`       // Why approval is needed
	SLBRequired bool      `json:"slb_required"` // Whether SLB two-person approval is needed
	Status      string    `json:"status"`       // pending, approved, denied, expired
	CreatedAt   time.Time `json:"created_at"`
	ExpiresAt   time.Time `json:"expires_at"`
	ApprovedBy  string    `json:"approved_by,omitempty"`
	ApprovedAt  time.Time `json:"approved_at,omitempty"`
}

Approval represents a pending approval request.

type ApprovalDecisionResponse 

type ApprovalDecisionResponse struct {
	ID       string `json:"id"`
	Status   string `json:"status"`
	Decision string `json:"decision"`
}

ApprovalDecisionResponse is the REST response for approval decision.

type ApprovalRequestRequest 

type ApprovalRequestRequest struct {
	Action     string `json:"action"`
	Resource   string `json:"resource"`
	Reason     string `json:"reason,omitempty"`
	TTLSeconds int    `json:"ttl_seconds,omitempty"` // Default 3600 (1 hour)
}

ApprovalRequestRequest is the request to create a new approval request.

type ApprovalRequestResponse 

type ApprovalRequestResponse struct {
	ID          string    `json:"id"`
	Status      string    `json:"status"`
	ExpiresAt   time.Time `json:"expires_at"`
	SLBRequired bool      `json:"slb_required"`
}

ApprovalRequestResponse is the REST response for creating an approval request.

type ApprovalRequired 

type ApprovalRequired struct {
	Action      string `json:"action"`
	Resource    string `json:"resource"`
	ApprovalID  string `json:"approval_id"`
	ApprovalURL string `json:"approval_url,omitempty"`
	ExpiresAt   string `json:"expires_at,omitempty"`
	Message     string `json:"message"`
}

ApprovalRequired is returned when an operation requires approval.

type ApprovalsListResponse 

type ApprovalsListResponse struct {
	Approvals []Approval `json:"approvals"`
	Count     int        `json:"count"`
}

ApprovalsListResponse is the REST response for approvals list.

type AuditAction 

type AuditAction string

AuditAction represents the type of action being audited. 

const (
	AuditActionCreate    AuditAction = "create"
	AuditActionUpdate    AuditAction = "update"
	AuditActionDelete    AuditAction = "delete"
	AuditActionApprove   AuditAction = "approve"
	AuditActionDeny      AuditAction = "deny"
	AuditActionExecute   AuditAction = "execute"
	AuditActionLogin     AuditAction = "login"
	AuditActionLogout    AuditAction = "logout"
	AuditActionSubscribe AuditAction = "subscribe"
)

type AuditContext 

type AuditContext struct {
	Resource   string
	ResourceID string
	SessionID  string
	PaneID     string
	AgentID    string
	Details    string
	ApprovalID string
	Action     AuditAction
}

AuditContext holds audit information collected during request processing.

func AuditContextFromRequest 

func AuditContextFromRequest(r *http.Request) *AuditContext

AuditContextFromRequest extracts audit context from request context.

type AuditFilter 

type AuditFilter struct {
	UserID     string
	Action     AuditAction
	Resource   string
	SessionID  string
	RequestID  string
	ApprovalID string
	Since      time.Time
	Until      time.Time
	Limit      int
	Offset     int
}

AuditFilter specifies criteria for querying audit records.

type AuditRecord 

type AuditRecord struct {
	ID         int64       `json:"id"`
	Timestamp  time.Time   `json:"timestamp"`
	RequestID  string      `json:"request_id"`
	UserID     string      `json:"user_id"`
	Role       Role        `json:"role"`
	Action     AuditAction `json:"action"`
	Resource   string      `json:"resource"`
	ResourceID string      `json:"resource_id,omitempty"`
	Method     string      `json:"method"`
	Path       string      `json:"path"`
	StatusCode int         `json:"status_code"`
	Duration   int64       `json:"duration_ms"`
	SessionID  string      `json:"session_id,omitempty"`
	PaneID     string      `json:"pane_id,omitempty"`
	AgentID    string      `json:"agent_id,omitempty"`
	Details    string      `json:"details,omitempty"`
	RemoteAddr string      `json:"remote_addr"`
	UserAgent  string      `json:"user_agent,omitempty"`
	ApprovalID string      `json:"approval_id,omitempty"`
}

AuditRecord represents a single audit trail entry.

type AuditStore 

type AuditStore struct {
	// contains filtered or unexported fields
}

AuditStore persists audit records to durable storage.

func NewAuditStore 

func NewAuditStore(cfg AuditStoreConfig) (*AuditStore, error)

NewAuditStore creates a new audit store with SQLite and JSONL persistence.

func (*AuditStore) Close 

func (s *AuditStore) Close() error

Close closes the audit store and releases resources.

func (*AuditStore) Query 

func (s *AuditStore) Query(filter AuditFilter) ([]AuditRecord, error)

Query retrieves audit records matching the filter.

func (*AuditStore) Record 

func (s *AuditStore) Record(rec *AuditRecord) error

Record stores an audit record.

func (*AuditStore) RecordApprovalAction 

func (s *AuditStore) RecordApprovalAction(
	ctx context.Context,
	action AuditAction,
	approvalID string,
	userID string,
	role Role,
	details string,
) error

RecordApprovalAction records an approval-related audit event.

func (*AuditStore) RecordWebSocketAction 

func (s *AuditStore) RecordWebSocketAction(
	clientID string,
	action AuditAction,
	userID string,
	role Role,
	topics []string,
	remoteAddr string,
) error

RecordWebSocketAction records a WebSocket-related audit event.

type AuditStoreConfig 

type AuditStoreConfig struct {
	// DBPath is the SQLite database file path.
	DBPath string

	// JSONLPath is the JSONL file path for append-only logging.
	JSONLPath string

	// Retention is how long to keep audit records.
	Retention time.Duration

	// CleanupInterval is how often to run retention cleanup.
	CleanupInterval time.Duration
}

AuditStoreConfig configures the audit store.

func DefaultAuditStoreConfig 

func DefaultAuditStoreConfig(dataDir string) AuditStoreConfig

DefaultAuditStoreConfig returns sensible defaults for audit storage.

type AuthConfig 

type AuthConfig struct {
	Mode   AuthMode
	APIKey string
	OIDC   OIDCConfig
	MTLS   MTLSConfig
}

AuthConfig holds server authentication configuration.

type AuthMode 

type AuthMode string

AuthMode configures authentication for the server. 

const (
	AuthModeLocal  AuthMode = "local"
	AuthModeAPIKey AuthMode = "api_key"
	AuthModeOIDC   AuthMode = "oidc"
	AuthModeMTLS   AuthMode = "mtls"
)

func ParseAuthMode 

func ParseAuthMode(raw string) (AuthMode, error)

type AutomationGetResponse 

type AutomationGetResponse struct {
	AutoCommit   bool   `json:"auto_commit"`
	AutoPush     bool   `json:"auto_push"`
	ForceRelease string `json:"force_release"`
}

AutomationGetResponse is the REST response for automation settings.

type AutomationUpdateRequest 

type AutomationUpdateRequest struct {
	AutoCommit   *bool   `json:"auto_commit,omitempty"`
	AutoPush     *bool   `json:"auto_push,omitempty"`
	ForceRelease *string `json:"force_release,omitempty"`
}

AutomationUpdateRequest is the request to update automation settings.

type AutomationUpdateResponse 

type AutomationUpdateResponse struct {
	AutoCommit   bool   `json:"auto_commit"`
	AutoPush     bool   `json:"auto_push"`
	ForceRelease string `json:"force_release"`
	Modified     bool   `json:"modified"`
}

AutomationUpdateResponse is the REST response for automation update.

type BugNotifyRequest 

type BugNotifyRequest struct {
	Channel     string `json:"channel"`                // slack, email, webhook
	Endpoint    string `json:"endpoint"`               // URL or address
	MinSeverity string `json:"min_severity,omitempty"` // Minimum severity to notify
}

BugNotifyRequest is the request body for POST /api/v1/bugs/notify

type BugSummaryResponse 

type BugSummaryResponse struct {
	TotalFindings  int            `json:"total_findings"`
	Critical       int            `json:"critical"`
	Warning        int            `json:"warning"`
	Info           int            `json:"info"`
	BySeverity     map[string]int `json:"by_severity"`
	ByCategory     map[string]int `json:"by_category"`
	ByFile         map[string]int `json:"by_file"`
	DismissedCount int            `json:"dismissed_count"`
	LinkedBeads    int            `json:"linked_beads"`
}

BugSummaryResponse is the response for GET /api/v1/bugs/summary

type CASSSearchRequest 

type CASSSearchRequest struct {
	Query     string `json:"query"`
	Limit     int    `json:"limit,omitempty"`
	Offset    int    `json:"offset,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Workspace string `json:"workspace,omitempty"`
	Since     string `json:"since,omitempty"`
	Until     string `json:"until,omitempty"`
	Cursor    string `json:"cursor,omitempty"`
	Fields    string `json:"fields,omitempty"`
	MaxTokens int    `json:"max_tokens,omitempty"`
	Aggregate string `json:"aggregate,omitempty"`
	Explain   bool   `json:"explain,omitempty"`
	Highlight bool   `json:"highlight,omitempty"`
}

CASSSearchRequest is the request body for POST /api/v1/cass/search

type CASSStatusResponse 

type CASSStatusResponse struct {
	Installed     bool   `json:"installed"`
	Healthy       bool   `json:"healthy"`
	Version       string `json:"version,omitempty"`
	IndexSize     int64  `json:"index_size,omitempty"`
	DocCount      int64  `json:"doc_count,omitempty"`
	LastIndexed   string `json:"last_indexed,omitempty"`
	NeedsReindex  bool   `json:"needs_reindex,omitempty"`
	ReindexReason string `json:"reindex_reason,omitempty"`
}

CASSStatusResponse is the response for GET /api/v1/cass/status

type CheckpointGitResponse 

type CheckpointGitResponse struct {
	Branch         string `json:"branch"`
	Commit         string `json:"commit"`
	IsDirty        bool   `json:"is_dirty"`
	StagedCount    int    `json:"staged_count,omitempty"`
	UnstagedCount  int    `json:"unstaged_count,omitempty"`
	UntrackedCount int    `json:"untracked_count,omitempty"`
	HasPatch       bool   `json:"has_patch,omitempty"`
}

CheckpointGitResponse represents git state in checkpoint responses.

type CheckpointResponse 

type CheckpointResponse struct {
	ID          string                    `json:"id"`
	Name        string                    `json:"name"`
	Description string                    `json:"description,omitempty"`
	SessionName string                    `json:"session_name"`
	WorkingDir  string                    `json:"working_dir,omitempty"`
	CreatedAt   string                    `json:"created_at"`
	PaneCount   int                       `json:"pane_count"`
	Git         *CheckpointGitResponse    `json:"git,omitempty"`
	Session     *CheckpointSessionSummary `json:"session,omitempty"`
	Age         string                    `json:"age,omitempty"`
}

CheckpointResponse represents a checkpoint in API responses.

type CheckpointSessionSummary 

type CheckpointSessionSummary struct {
	PaneCount       int      `json:"pane_count"`
	ActivePaneIndex int      `json:"active_pane_index"`
	Layout          string   `json:"layout,omitempty"`
	AgentTypes      []string `json:"agent_types,omitempty"`
}

CheckpointSessionSummary summarizes session state in checkpoint responses.

type ClaimBeadRequest 

type ClaimBeadRequest struct {
	Assignee string `json:"assignee"`
}

ClaimBeadRequest is the request body for POST /api/v1/beads/{id}/claim

type Config 

type Config struct {
	Host string
	Port int
	// PublicBaseURL advertises the externally reachable base URL for clients.
	// Optional: leave empty to derive from host/port in documentation or clients.
	PublicBaseURL string
	EventBus      *events.EventBus
	StateStore    *state.Store
	Auth          AuthConfig
	// AllowedOrigins controls CORS origin allowlist. Empty means default localhost only.
	AllowedOrigins []string
}

Config holds server configuration.

type ContactRequestBody 

type ContactRequestBody struct {
	FromAgent  string `json:"from_agent"`
	ToAgent    string `json:"to_agent"`
	ToProject  string `json:"to_project,omitempty"`
	Reason     string `json:"reason,omitempty"`
	TTLSeconds int    `json:"ttl_seconds,omitempty"`
}

ContactRequest is the request body for POST /api/v1/mail/contacts/request

type ContactRespondRequest 

type ContactRespondRequest struct {
	ToAgent    string `json:"to_agent"`
	FromAgent  string `json:"from_agent"`
	Accept     bool   `json:"accept"`
	TTLSeconds int    `json:"ttl_seconds,omitempty"`
}

ContactRespondRequest is the request body for POST /api/v1/mail/contacts/respond

type ContextBuildRequest 

type ContextBuildRequest struct {
	Question   string `json:"question"`
	ProjectDir string `json:"project_dir,omitempty"`
	BeadID     string `json:"bead_id,omitempty"`
	AgentType  string `json:"agent_type,omitempty"`
}

ContextBuildRequest represents a context pack build request.

type CreateAgentRequest 

type CreateAgentRequest struct {
	Program         string `json:"program"`
	Model           string `json:"model"`
	Name            string `json:"name,omitempty"`
	TaskDescription string `json:"task_description,omitempty"`
}

CreateAgentRequest is the request body for POST /api/v1/mail/agents

type CreateBeadFromFindingRequest 

type CreateBeadFromFindingRequest struct {
	Title    string   `json:"title,omitempty"`    // Override default title
	Labels   []string `json:"labels,omitempty"`   // Additional labels
	Priority string   `json:"priority,omitempty"` // P0-P3
}

CreateBeadFromFindingRequest is the request body for POST /api/v1/scanner/findings/{id}/create-bead

type CreateBeadRequest 

type CreateBeadRequest struct {
	Title       string   `json:"title"`
	Description string   `json:"description,omitempty"`
	Type        string   `json:"type,omitempty"`     // task, bug, epic, etc.
	Priority    string   `json:"priority,omitempty"` // P0, P1, P2, P3
	Labels      []string `json:"labels,omitempty"`
	Parent      string   `json:"parent,omitempty"`     // Parent bead ID for sub-tasks
	BlockedBy   []string `json:"blocked_by,omitempty"` // IDs this bead is blocked by
}

CreateBeadRequest is the request body for POST /api/v1/beads

type CreateCheckpointRequest 

type CreateCheckpointRequest struct {
	Name            string `json:"name"`
	Description     string `json:"description,omitempty"`
	CaptureGit      *bool  `json:"capture_git,omitempty"`
	ScrollbackLines *int   `json:"scrollback_lines,omitempty"`
}

CreateCheckpointRequest is the payload for creating a new checkpoint.

type CreateJobRequest 

type CreateJobRequest struct {
	Type    string                 `json:"type"`
	Params  map[string]interface{} `json:"params,omitempty"`
	Session string                 `json:"session,omitempty"`
}

CreateJobRequest is the request body for job creation.

type CreateSessionRequest 

type CreateSessionRequest struct {
	Session string `json:"session"`
	Panes   int    `json:"panes,omitempty"`
}

CreateSessionRequest is the request body for POST /sessions.

type DismissFindingRequest 

type DismissFindingRequest struct {
	Reason string `json:"reason,omitempty"`
}

DismissFindingRequest is the request body for POST /api/v1/scanner/findings/{id}/dismiss

type ExampleRef 

type ExampleRef struct {
	Summary string `json:"summary,omitempty"`
	Value   any    `json:"value,omitempty"`
}

ExampleRef holds an example value.

type ExportCheckpointRequest 

type ExportCheckpointRequest struct {
	Format            string `json:"format,omitempty"` // "tar.gz" or "zip"
	RedactSecrets     bool   `json:"redact_secrets,omitempty"`
	RewritePaths      bool   `json:"rewrite_paths,omitempty"`
	IncludeScrollback *bool  `json:"include_scrollback,omitempty"`
	IncludeGitPatch   *bool  `json:"include_git_patch,omitempty"`
}

ExportCheckpointRequest is the payload for exporting a checkpoint.

type ExportCheckpointResponse 

type ExportCheckpointResponse struct {
	Filename    string `json:"filename"`
	Size        int64  `json:"size"`
	ContentType string `json:"content_type"`
	Data        string `json:"data,omitempty"` // Base64 encoded if inline
	DownloadURL string `json:"download_url,omitempty"`
}

ExportCheckpointResponse is the response after exporting a checkpoint.

type FindingRecord 

type FindingRecord struct {
	ID          string          `json:"id"`
	ScanID      string          `json:"scan_id"`
	Finding     scanner.Finding `json:"finding"`
	Dismissed   bool            `json:"dismissed"`
	DismissedAt *time.Time      `json:"dismissed_at,omitempty"`
	DismissedBy string          `json:"dismissed_by,omitempty"`
	BeadID      string          `json:"bead_id,omitempty"`
	CreatedAt   time.Time       `json:"created_at"`
}

FindingRecord represents a finding with additional metadata

type ForceReleaseRequest 

type ForceReleaseRequest struct {
	AgentName      string `json:"agent_name"`
	Note           string `json:"note,omitempty"`
	NotifyPrevious bool   `json:"notify_previous,omitempty"`
}

ForceReleaseRequest is the request body for POST /api/v1/reservations/{id}/force-release

type GitSyncRequest 

type GitSyncRequest struct {
	Session  string `json:"session,omitempty"`
	PullOnly bool   `json:"pull_only,omitempty"`
	PushOnly bool   `json:"push_only,omitempty"`
	Force    bool   `json:"force,omitempty"`
	DryRun   bool   `json:"dry_run,omitempty"`
}

GitSyncRequest represents a git sync request.

type IdempotencyStore 

type IdempotencyStore struct {
	// contains filtered or unexported fields
}

IdempotencyStore caches responses by idempotency key.

func NewIdempotencyStore 

func NewIdempotencyStore(ttl time.Duration) *IdempotencyStore

NewIdempotencyStore creates an idempotency cache with the given TTL.

func (*IdempotencyStore) Get 

func (s *IdempotencyStore) Get(key string) ([]byte, int, bool)

Get returns a cached response for the idempotency key.

func (*IdempotencyStore) Set 

func (s *IdempotencyStore) Set(key string, response []byte, statusCode int)

Set stores a response for the idempotency key.

func (*IdempotencyStore) Stop 

func (s *IdempotencyStore) Stop()

Stop terminates the cleanup goroutine. Call this when the store is no longer needed. Safe to call multiple times.

type ImportCheckpointRequest 

type ImportCheckpointRequest struct {
	// Data is the base64-encoded archive content
	Data string `json:"data,omitempty"`
	// TargetSession overrides the session name on import
	TargetSession string `json:"target_session,omitempty"`
	// TargetDir overrides the working directory on import
	TargetDir string `json:"target_dir,omitempty"`
	// VerifyChecksums validates file integrity on import
	VerifyChecksums *bool `json:"verify_checksums,omitempty"`
	// AllowOverwrite permits overwriting existing checkpoints
	AllowOverwrite bool `json:"allow_overwrite,omitempty"`
}

ImportCheckpointRequest is the payload for importing a checkpoint.

type Job 

type Job struct {
	ID        string                 `json:"id"`
	Type      string                 `json:"type"`
	Status    JobStatus              `json:"status"`
	Progress  float64                `json:"progress,omitempty"`
	Result    map[string]interface{} `json:"result,omitempty"`
	Error     string                 `json:"error,omitempty"`
	CreatedAt string                 `json:"created_at"`
	UpdatedAt string                 `json:"updated_at"`
}

Job represents an asynchronous operation.

type JobStatus 

type JobStatus string

JobStatus represents the state of a job. 

const (
	JobStatusPending   JobStatus = "pending"
	JobStatusRunning   JobStatus = "running"
	JobStatusCompleted JobStatus = "completed"
	JobStatusFailed    JobStatus = "failed"
	JobStatusCancelled JobStatus = "cancelled"
)

type JobStore 

type JobStore struct {
	// contains filtered or unexported fields
}

JobStore manages asynchronous jobs.

func NewJobStore 

func NewJobStore() *JobStore

NewJobStore creates a new job store.

func (*JobStore) Create 

func (s *JobStore) Create(jobType string) *Job

Create creates a new job.

func (*JobStore) Delete 

func (s *JobStore) Delete(id string) bool

Delete removes a job.

func (*JobStore) Get 

func (s *JobStore) Get(id string) *Job

Get retrieves a job by ID.

func (*JobStore) List 

func (s *JobStore) List() []*Job

List returns all jobs.

func (*JobStore) Update 

func (s *JobStore) Update(id string, status JobStatus, progress float64, result map[string]interface{}, errMsg string)

Update updates a job's status and progress.

type MTLSConfig 

type MTLSConfig struct {
	CertFile     string
	KeyFile      string
	ClientCAFile string
}

MTLSConfig configures mutual TLS for API access.

type MediaType 

type MediaType struct {
	Schema   *Schema               `json:"schema,omitempty"`
	Examples map[string]ExampleRef `json:"examples,omitempty"`
}

MediaType describes media type content.

type MemoryContextRequest 

type MemoryContextRequest struct {
	Task        string `json:"task"`
	MaxRules    int    `json:"max_rules,omitempty"`
	MaxSnippets int    `json:"max_snippets,omitempty"`
}

MemoryContextRequest is the request body for POST /api/v1/memory/context

type MemoryDaemonInfo 

type MemoryDaemonInfo struct {
	State     MemoryDaemonState `json:"state"`
	PID       int               `json:"pid,omitempty"`
	Port      int               `json:"port,omitempty"`
	StartedAt *time.Time        `json:"started_at,omitempty"`
	SessionID string            `json:"session_id,omitempty"`
}

MemoryDaemonInfo holds information about the memory daemon

type MemoryDaemonRequest 

type MemoryDaemonRequest struct {
	Port      int    `json:"port,omitempty"`
	SessionID string `json:"session_id,omitempty"`
}

MemoryDaemonRequest is the request body for POST /api/v1/memory/daemon/start

type MemoryDaemonState 

type MemoryDaemonState string

MemoryDaemonState tracks the memory daemon status 

const (
	DaemonStateStopped  MemoryDaemonState = "stopped"
	DaemonStateStarting MemoryDaemonState = "starting"
	DaemonStateRunning  MemoryDaemonState = "running"
	DaemonStateStopping MemoryDaemonState = "stopping"
)

type MemoryOutcomeRequest 

type MemoryOutcomeRequest struct {
	Status    string   `json:"status"` // success, failure, partial
	RuleIDs   []string `json:"rule_ids,omitempty"`
	Sentiment string   `json:"sentiment,omitempty"`
	Notes     string   `json:"notes,omitempty"`
}

MemoryOutcomeRequest is the request body for POST /api/v1/memory/outcome

type MemoryRule 

type MemoryRule struct {
	ID       string `json:"id"`
	Content  string `json:"content"`
	Category string `json:"category,omitempty"`
	Source   string `json:"source,omitempty"`
}

MemoryRule represents a rule from the CM playbook

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore provides in-memory caching for memory operations

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new memory store

func (*MemoryStore) GetDaemonInfo 

func (s *MemoryStore) GetDaemonInfo() *MemoryDaemonInfo

GetDaemonInfo returns current daemon info

func (*MemoryStore) SetDaemonInfo 

func (s *MemoryStore) SetDaemonInfo(info *MemoryDaemonInfo)

SetDaemonInfo updates daemon info

type MetricsCompareRequest 

type MetricsCompareRequest struct {
	Session      string `json:"session,omitempty"`
	BaselineName string `json:"baseline_name,omitempty"`
}

MetricsCompareRequest represents a metrics comparison request.

type MetricsSnapshotSaveRequest 

type MetricsSnapshotSaveRequest struct {
	Name    string `json:"name"`
	Session string `json:"session,omitempty"`
}

MetricsSnapshotSaveRequest represents a snapshot save request.

type OIDCConfig 

type OIDCConfig struct {
	Issuer   string
	Audience string
	JWKSURL  string
	CacheTTL time.Duration
}

OIDCConfig configures OIDC/JWT verification for API access.

type OpenAPIComponents 

type OpenAPIComponents struct {
	Schemas         map[string]*Schema         `json:"schemas,omitempty"`
	SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitempty"`
}

OpenAPIComponents holds reusable components.

type OpenAPIInfo 

type OpenAPIInfo struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

OpenAPIInfo contains API metadata.

type OpenAPIServer 

type OpenAPIServer struct {
	URL         string `json:"url"`
	Description string `json:"description,omitempty"`
}

OpenAPIServer describes an API server.

type OpenAPISpec 

type OpenAPISpec struct {
	OpenAPI    string              `json:"openapi"`
	Info       OpenAPIInfo         `json:"info"`
	Servers    []OpenAPIServer     `json:"servers,omitempty"`
	Paths      map[string]PathItem `json:"paths"`
	Components *OpenAPIComponents  `json:"components,omitempty"`
	Tags       []OpenAPITag        `json:"tags,omitempty"`
}

OpenAPISpec represents an OpenAPI 3.1 specification.

func GenerateOpenAPISpec 

func GenerateOpenAPISpec(version, serverURL string) *OpenAPISpec

GenerateOpenAPISpec generates an OpenAPI 3.1 spec from the kernel registry.

type OpenAPITag 

type OpenAPITag struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

OpenAPITag categorizes operations.

type Operation 

type Operation struct {
	Tags        []string              `json:"tags,omitempty"`
	Summary     string                `json:"summary,omitempty"`
	Description string                `json:"description,omitempty"`
	OperationID string                `json:"operationId,omitempty"`
	Parameters  []Parameter           `json:"parameters,omitempty"`
	RequestBody *RequestBody          `json:"requestBody,omitempty"`
	Responses   map[string]Response   `json:"responses"`
	Security    []map[string][]string `json:"security,omitempty"`
	Deprecated  bool                  `json:"deprecated,omitempty"`
}

Operation describes a single API operation.

type PaneInputRequest 

type PaneInputRequest struct {
	Text  string `json:"text"`
	Enter bool   `json:"enter,omitempty"`
}

PaneInputRequest is the request body for POST /sessions/{id}/panes/{paneIdx}/input.

type PaneTitleRequest 

type PaneTitleRequest struct {
	Title string `json:"title"`
}

PaneTitleRequest is the request body for PATCH /sessions/{id}/panes/{paneIdx}/title.

type Parameter 

type Parameter struct {
	Name        string  `json:"name"`
	In          string  `json:"in"`
	Description string  `json:"description,omitempty"`
	Required    bool    `json:"required,omitempty"`
	Schema      *Schema `json:"schema,omitempty"`
}

Parameter describes an operation parameter.

type PathItem 

type PathItem struct {
	Get    *Operation `json:"get,omitempty"`
	Post   *Operation `json:"post,omitempty"`
	Put    *Operation `json:"put,omitempty"`
	Patch  *Operation `json:"patch,omitempty"`
	Delete *Operation `json:"delete,omitempty"`
}

PathItem contains operations for a path.

type Permission 

type Permission string

Permission represents a specific action that can be authorized. 

const (
	// Read permissions
	PermReadSessions     Permission = "sessions:read"
	PermReadAgents       Permission = "agents:read"
	PermReadPipelines    Permission = "pipelines:read"
	PermReadApprovals    Permission = "approvals:read"
	PermReadJobs         Permission = "jobs:read"
	PermReadHealth       Permission = "health:read"
	PermReadEvents       Permission = "events:read"
	PermReadWebSocket    Permission = "ws:read"
	PermReadMail         Permission = "mail:read"
	PermReadReservations Permission = "reservations:read"
	PermReadBeads        Permission = "beads:read"
	PermReadAccounts     Permission = "accounts:read"
	PermReadMemory       Permission = "memory:read"

	// Write/operation permissions
	PermWriteSessions     Permission = "sessions:write"
	PermWriteAgents       Permission = "agents:write"
	PermWritePipelines    Permission = "pipelines:write"
	PermWriteJobs         Permission = "jobs:write"
	PermWriteMail         Permission = "mail:write"
	PermWriteReservations Permission = "reservations:write"
	PermWriteBeads        Permission = "beads:write"
	PermWriteAccounts     Permission = "accounts:write"
	PermWriteMemory       Permission = "memory:write"
	PermApproveRequests   Permission = "approvals:approve"

	// Dangerous operations (require admin or approval)
	PermDangerousOps Permission = "dangerous:execute"
	PermForceRelease Permission = "dangerous:force_release"
	PermKillAgent    Permission = "dangerous:kill_agent"
	PermSystemConfig Permission = "system:config"
)

type PipelineCleanupRequest 

type PipelineCleanupRequest struct {
	OlderThanHours int `json:"older_than_hours,omitempty"`
}

PipelineCleanupRequest is the request body for POST /api/v1/pipelines/cleanup

type PipelineExecRequest 

type PipelineExecRequest struct {
	Workflow   pipeline.Workflow      `json:"workflow"`
	Session    string                 `json:"session"`
	Variables  map[string]interface{} `json:"variables,omitempty"`
	Background bool                   `json:"background,omitempty"`
}

PipelineExecRequest is the request body for POST /api/v1/pipelines/exec (inline workflow)

type PipelineResumeRequest 

type PipelineResumeRequest struct {
	Session   string                 `json:"session,omitempty"`
	Variables map[string]interface{} `json:"variables,omitempty"`
}

PipelineResumeRequest is the request body for POST /api/v1/pipelines/{id}/resume

type PipelineRunRequest 

type PipelineRunRequest struct {
	WorkflowFile string                 `json:"workflow_file"`
	Session      string                 `json:"session"`
	Variables    map[string]interface{} `json:"variables,omitempty"`
	DryRun       bool                   `json:"dry_run,omitempty"`
	Background   bool                   `json:"background,omitempty"`
}

PipelineRunRequest is the request body for POST /api/v1/pipelines/run

type PipelineTemplate 

type PipelineTemplate struct {
	Name        string `json:"name"`
	Path        string `json:"path"`
	Description string `json:"description,omitempty"`
}

PipelineTemplate represents an available workflow template

type PipelineValidateRequest 

type PipelineValidateRequest struct {
	WorkflowFile    string `json:"workflow_file,omitempty"`
	WorkflowContent string `json:"workflow_content,omitempty"`
}

PipelineValidateRequest is the request body for POST /api/v1/pipelines/validate

type PolicyGetResponse 

type PolicyGetResponse struct {
	Version    int                     `json:"version"`
	PolicyPath string                  `json:"policy_path,omitempty"`
	IsDefault  bool                    `json:"is_default"`
	Stats      PolicyStatsResponse     `json:"stats"`
	Automation policy.AutomationConfig `json:"automation"`
	Rules      *PolicyRulesResponse    `json:"rules,omitempty"`
}

PolicyGetResponse is the REST response for policy get.

type PolicyResetResponse 

type PolicyResetResponse struct {
	PolicyPath string `json:"policy_path"`
	Action     string `json:"action"`
}

PolicyResetResponse is the REST response for policy reset.

type PolicyRuleSummary 

type PolicyRuleSummary struct {
	Pattern string `json:"pattern"`
	Reason  string `json:"reason,omitempty"`
	SLB     bool   `json:"slb,omitempty"`
}

PolicyRuleSummary is a simplified rule representation.

type PolicyRulesResponse 

type PolicyRulesResponse struct {
	Blocked          []PolicyRuleSummary `json:"blocked,omitempty"`
	ApprovalRequired []PolicyRuleSummary `json:"approval_required,omitempty"`
	Allowed          []PolicyRuleSummary `json:"allowed,omitempty"`
}

PolicyRulesResponse contains detailed rule information.

type PolicyStatsResponse 

type PolicyStatsResponse struct {
	Blocked  int `json:"blocked"`
	Approval int `json:"approval"`
	Allowed  int `json:"allowed"`
	SLBRules int `json:"slb_rules"`
}

PolicyStatsResponse contains rule counts.

type PolicyUpdateRequest 

type PolicyUpdateRequest struct {
	Content string `json:"content"` // YAML content
}

PolicyUpdateRequest is the request to update the policy.

type PolicyUpdateResponse 

type PolicyUpdateResponse struct {
	PolicyPath string              `json:"policy_path"`
	Stats      PolicyStatsResponse `json:"stats"`
}

PolicyUpdateResponse is the REST response for policy update.

type PolicyValidateRequest 

type PolicyValidateRequest struct {
	Content string `json:"content,omitempty"` // YAML content to validate (optional, uses file if not provided)
}

PolicyValidateRequest is the request to validate a policy.

type PolicyValidateResponse 

type PolicyValidateResponse struct {
	Valid      bool     `json:"valid"`
	PolicyPath string   `json:"policy_path,omitempty"`
	Errors     []string `json:"errors,omitempty"`
	Warnings   []string `json:"warnings,omitempty"`
}

PolicyValidateResponse is the REST response for policy validation.

type PrivacySettings 

type PrivacySettings struct {
	Enabled       bool     `json:"enabled"`
	AllowedAgents []string `json:"allowed_agents,omitempty"`
	UpdatedAt     string   `json:"updated_at,omitempty"`
}

PrivacySettings represents cross-agent privacy settings

type PrivacyUpdateRequest 

type PrivacyUpdateRequest struct {
	Enabled bool     `json:"enabled"`
	Agents  []string `json:"agents,omitempty"`
}

PrivacyUpdateRequest is the request body for PUT /api/v1/memory/privacy

type RBACConfig 

type RBACConfig struct {
	// Enabled controls whether RBAC is enforced.
	Enabled bool

	// DefaultRole is the role assigned when no role claim is found.
	DefaultRole Role

	// RoleClaimKey is the JWT claim key for role extraction.
	RoleClaimKey string

	// AllowAnonymous permits requests without authentication (as viewer).
	AllowAnonymous bool
}

RBACConfig holds RBAC configuration options.

func DefaultRBACConfig 

func DefaultRBACConfig() RBACConfig

DefaultRBACConfig returns sensible RBAC defaults.

type RedactionConfig added in v1.7.0 

type RedactionConfig struct {
	// Enabled determines if redaction is active.
	Enabled bool
	// Config is the redaction library configuration.
	Config redaction.Config
}

RedactionConfig holds the server-level redaction configuration.

type RedactionSummary added in v1.7.0 

type RedactionSummary struct {
	RequestID     string         `json:"request_id"`
	Path          string         `json:"path"`
	Method        string         `json:"method"`
	RequestFinds  int            `json:"request_findings"`
	ResponseFinds int            `json:"response_findings"`
	Categories    map[string]int `json:"categories,omitempty"`
	Blocked       bool           `json:"blocked,omitempty"`
}

RedactionSummary is logged after request/response redaction.

type ReleaseReservationsRequest 

type ReleaseReservationsRequest struct {
	AgentName string   `json:"agent_name"`
	Paths     []string `json:"paths,omitempty"`
	IDs       []int    `json:"ids,omitempty"`
}

ReleaseReservationsRequest is the request body for DELETE /api/v1/reservations

type RenewReservationsRequest 

type RenewReservationsRequest struct {
	AgentName     string `json:"agent_name"`
	ExtendSeconds int    `json:"extend_seconds,omitempty"`
}

RenewReservationsRequest is the request body for POST /api/v1/reservations/{id}/renew

type ReplyMessageRequest 

type ReplyMessageRequest struct {
	SenderName string   `json:"sender_name"`
	BodyMD     string   `json:"body_md"`
	To         []string `json:"to,omitempty"`
	CC         []string `json:"cc,omitempty"`
}

ReplyMessageRequest is the request body for POST /api/v1/mail/messages/{id}/reply

type RequestBody 

type RequestBody struct {
	Description string               `json:"description,omitempty"`
	Required    bool                 `json:"required,omitempty"`
	Content     map[string]MediaType `json:"content"`
}

RequestBody describes a request body.

type ReservePathsRequest 

type ReservePathsRequest struct {
	AgentName  string   `json:"agent_name"`
	Paths      []string `json:"paths"`
	TTLSeconds int      `json:"ttl_seconds,omitempty"`
	Exclusive  bool     `json:"exclusive,omitempty"`
	Reason     string   `json:"reason,omitempty"`
}

ReservePathsRequest is the request body for POST /api/v1/reservations

type Response 

type Response struct {
	Description string               `json:"description"`
	Content     map[string]MediaType `json:"content,omitempty"`
}

Response describes an operation response.

type RestoreCheckpointRequest 

type RestoreCheckpointRequest struct {
	Force           bool   `json:"force,omitempty"`
	SkipGitCheck    bool   `json:"skip_git_check,omitempty"`
	InjectContext   bool   `json:"inject_context,omitempty"`
	DryRun          bool   `json:"dry_run,omitempty"`
	CustomDirectory string `json:"custom_directory,omitempty"`
	ScrollbackLines int    `json:"scrollback_lines,omitempty"`
}

RestoreCheckpointRequest is the payload for restoring a checkpoint.

type RestoreCheckpointResponse 

type RestoreCheckpointResponse struct {
	SessionName     string   `json:"session_name"`
	PanesRestored   int      `json:"panes_restored"`
	ContextInjected bool     `json:"context_injected"`
	DryRun          bool     `json:"dry_run"`
	Warnings        []string `json:"warnings,omitempty"`
}

RestoreCheckpointResponse is the response after restoring a checkpoint.

type Role 

type Role string

Role represents a user's access level in the system. 

const (
	// RoleViewer can read data but not make changes.
	RoleViewer Role = "viewer"

	// RoleOperator can perform standard operations and view data.
	RoleOperator Role = "operator"

	// RoleAdmin has full access including dangerous operations and approvals.
	RoleAdmin Role = "admin"
)

func ParseRole 

func ParseRole(s string) Role

ParseRole converts a string to a Role, defaulting to viewer if unknown.

func (Role) HasPermission 

func (r Role) HasPermission(p Permission) bool

HasPermission checks if a role has a specific permission.

type RoleContext 

type RoleContext struct {
	Role      Role
	UserID    string
	ClaimsRaw map[string]interface{}
}

RoleContext holds RBAC information for a request.

func RoleFromContext 

func RoleFromContext(ctx context.Context) *RoleContext

RoleFromContext extracts RBAC context from a request context.

type RollbackRequest 

type RollbackRequest struct {
	CheckpointRef string `json:"checkpoint_ref,omitempty"` // ID, name, or "~N" notation
	NoStash       bool   `json:"no_stash,omitempty"`
	NoGit         bool   `json:"no_git,omitempty"`
	DryRun        bool   `json:"dry_run,omitempty"`
}

RollbackRequest is the payload for rolling back to a checkpoint.

type RollbackResponse 

type RollbackResponse struct {
	CheckpointID   string   `json:"checkpoint_id"`
	CheckpointName string   `json:"checkpoint_name"`
	GitRestored    bool     `json:"git_restored"`
	StashCreated   bool     `json:"stash_created,omitempty"`
	StashRef       string   `json:"stash_ref,omitempty"`
	DryRun         bool     `json:"dry_run"`
	Warnings       []string `json:"warnings,omitempty"`
}

RollbackResponse is the response after a rollback operation.

type SafetyBlockedResponse 

type SafetyBlockedResponse struct {
	Entries []policy.BlockedEntry `json:"entries"`
	Count   int                   `json:"count"`
}

SafetyBlockedResponse is the REST response for blocked commands.

type SafetyCheckRequest 

type SafetyCheckRequest struct {
	Command string `json:"command"`
}

SafetyCheckRequest is the request to check a command against policy.

type SafetyCheckResponse 

type SafetyCheckResponse struct {
	Command string `json:"command"`
	Action  string `json:"action"` // allow, block, approve
	Pattern string `json:"pattern,omitempty"`
	Reason  string `json:"reason,omitempty"`
	SLB     bool   `json:"slb,omitempty"` // Requires SLB two-person approval
}

SafetyCheckResponse is the REST response for safety check.

type SafetyInstallRequest 

type SafetyInstallRequest struct {
	Force bool `json:"force"`
}

SafetyInstallRequest configures safety installation options.

type SafetyInstallResponse 

type SafetyInstallResponse struct {
	GitWrapper string `json:"git_wrapper"`
	RmWrapper  string `json:"rm_wrapper"`
	Hook       string `json:"hook"`
	Policy     string `json:"policy"`
}

SafetyInstallResponse is the REST response for safety install.

type SafetyStatusResponse 

type SafetyStatusResponse struct {
	Installed     bool   `json:"installed"`
	PolicyPath    string `json:"policy_path,omitempty"`
	BlockedCount  int    `json:"blocked_rules"`
	ApprovalCount int    `json:"approval_rules"`
	AllowedCount  int    `json:"allowed_rules"`
	WrapperPath   string `json:"wrapper_path,omitempty"`
	HookInstalled bool   `json:"hook_installed"`
}

SafetyStatusResponse is the REST response for safety status.

type SafetyUninstallResponse 

type SafetyUninstallResponse struct {
	Removed []string `json:"removed"`
}

SafetyUninstallResponse is the REST response for safety uninstall.

type ScanOptionsRequest 

type ScanOptionsRequest struct {
	Path           string   `json:"path,omitempty"`        // Path to scan (defaults to project dir)
	Languages      []string `json:"languages,omitempty"`   // Languages to include
	Exclude        []string `json:"exclude,omitempty"`     // Languages to exclude
	StagedOnly     bool     `json:"staged_only,omitempty"` // Only scan staged files
	DiffOnly       bool     `json:"diff_only,omitempty"`   // Only scan modified files
	CI             bool     `json:"ci,omitempty"`          // CI mode
	FailOnWarning  bool     `json:"fail_on_warning,omitempty"`
	TimeoutSeconds int      `json:"timeout_seconds,omitempty"`
}

ScanOptionsRequest is the request body for POST /api/v1/scanner/run

type ScanRecord 

type ScanRecord struct {
	ID          string              `json:"id"`
	State       ScanState           `json:"state"`
	Path        string              `json:"path"`
	Options     *ScanOptionsRequest `json:"options,omitempty"`
	StartedAt   time.Time           `json:"started_at"`
	CompletedAt *time.Time          `json:"completed_at,omitempty"`
	Result      *scanner.ScanResult `json:"result,omitempty"`
	Error       string              `json:"error,omitempty"`
	FindingIDs  []string            `json:"finding_ids,omitempty"`
}

ScanRecord represents a historical scan record

type ScanState 

type ScanState string

ScanState represents the state of a scan 

const (
	ScanStatePending   ScanState = "pending"
	ScanStateRunning   ScanState = "running"
	ScanStateCompleted ScanState = "completed"
	ScanStateFailed    ScanState = "failed"
)

type ScanStatusResponse 

type ScanStatusResponse struct {
	Available     bool        `json:"available"`
	Version       string      `json:"version,omitempty"`
	CurrentScan   *ScanRecord `json:"current_scan,omitempty"`
	LastScan      *ScanRecord `json:"last_scan,omitempty"`
	TotalScans    int         `json:"total_scans"`
	TotalFindings int         `json:"total_findings"`
}

ScanStatusResponse is the response for GET /api/v1/scanner/status

type ScannerStore 

type ScannerStore struct {
	// contains filtered or unexported fields
}

ScannerStore provides in-memory storage for scan history and findings

func NewScannerStore 

func NewScannerStore() *ScannerStore

NewScannerStore creates a new scanner store

func (*ScannerStore) AddFinding 

func (s *ScannerStore) AddFinding(finding *FindingRecord)

AddFinding adds a finding record

func (*ScannerStore) AddScan 

func (s *ScannerStore) AddScan(scan *ScanRecord)

AddScan adds a scan record

func (*ScannerStore) GetFinding 

func (s *ScannerStore) GetFinding(id string) (*FindingRecord, bool)

GetFinding retrieves a finding by ID

func (*ScannerStore) GetFindings 

func (s *ScannerStore) GetFindings(scanID string, includeDismissed bool, severity string, limit, offset int) []*FindingRecord

GetFindings returns findings with optional filtering

func (*ScannerStore) GetFindingsByScan 

func (s *ScannerStore) GetFindingsByScan(scanID string) []*FindingRecord

GetFindingsByScan returns all findings for a specific scan

func (*ScannerStore) GetRunningScan 

func (s *ScannerStore) GetRunningScan() *ScanRecord

GetRunningScan returns the currently running scan, if any

func (*ScannerStore) GetScan 

func (s *ScannerStore) GetScan(id string) (*ScanRecord, bool)

GetScan retrieves a scan by ID

func (*ScannerStore) GetScans 

func (s *ScannerStore) GetScans(limit, offset int) []*ScanRecord

GetScans returns scans in reverse chronological order

func (*ScannerStore) UpdateFinding 

func (s *ScannerStore) UpdateFinding(finding *FindingRecord)

UpdateFinding updates a finding record

func (*ScannerStore) UpdateScan 

func (s *ScannerStore) UpdateScan(scan *ScanRecord)

UpdateScan updates a scan record

type Schema 

type Schema struct {
	Type                 string             `json:"type,omitempty"`
	Format               string             `json:"format,omitempty"`
	Description          string             `json:"description,omitempty"`
	Properties           map[string]*Schema `json:"properties,omitempty"`
	Required             []string           `json:"required,omitempty"`
	Items                *Schema            `json:"items,omitempty"`
	Ref                  string             `json:"$ref,omitempty"`
	AdditionalProperties any                `json:"additionalProperties,omitempty"`
}

Schema describes a JSON Schema.

type SecurityScheme 

type SecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	Description  string `json:"description,omitempty"`
}

SecurityScheme describes an authentication scheme.

type SendMessageRequest 

type SendMessageRequest struct {
	SenderName  string   `json:"sender_name"`
	To          []string `json:"to"`
	Subject     string   `json:"subject"`
	BodyMD      string   `json:"body_md"`
	CC          []string `json:"cc,omitempty"`
	BCC         []string `json:"bcc,omitempty"`
	Importance  string   `json:"importance,omitempty"`
	AckRequired bool     `json:"ack_required,omitempty"`
	ThreadID    string   `json:"thread_id,omitempty"`
}

SendMessageRequest is the request body for POST /api/v1/mail/messages

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server provides HTTP API and event streaming for NTM.

func New 

func New(cfg Config) *Server

New creates a new HTTP server.

func (*Server) AuditMiddleware 

func (s *Server) AuditMiddleware(store *AuditStore) func(http.Handler) http.Handler

AuditMiddleware creates middleware that records audit trail for mutating requests.

func (*Server) GetRedactionConfig added in v1.7.0 

func (s *Server) GetRedactionConfig() *RedactionConfig

GetRedactionConfig returns the current redaction configuration.

func (*Server) Port 

func (s *Server) Port() int

Port returns the configured port.

func (*Server) RequirePermission 

func (s *Server) RequirePermission(perm Permission) func(http.Handler) http.Handler

RequirePermission creates a middleware that enforces a specific permission.

func (*Server) RequireRole 

func (s *Server) RequireRole(minRole Role) func(http.Handler) http.Handler

RequireRole creates a middleware that enforces a minimum role.

func (*Server) Router 

func (s *Server) Router() chi.Router

Router returns the chi router for testing.

func (*Server) SetRedactionConfig added in v1.7.0 

func (s *Server) SetRedactionConfig(cfg *RedactionConfig)

SetRedactionConfig sets the redaction configuration for the server. Pass nil to disable redaction.

func (*Server) Start 

func (s *Server) Start(ctx context.Context) error

Start starts the HTTP server and blocks until shutdown.

func (*Server) WSHub 

func (s *Server) WSHub() *WSHub

WSHub returns the WebSocket hub for testing.

type SessionZoomRequest 

type SessionZoomRequest struct {
	Pane int `json:"pane"`
}

SessionZoomRequest is the request body for POST /sessions/{id}/zoom.

type SetContactPolicyRequest 

type SetContactPolicyRequest struct {
	AgentName string `json:"agent_name"`
	Policy    string `json:"policy"` // open, auto, contacts_only, block_all
}

SetContactPolicyRequest is the request body for PUT /api/v1/mail/contacts/policy

type UpdateBeadRequest 

type UpdateBeadRequest struct {
	Title       *string  `json:"title,omitempty"`
	Description *string  `json:"description,omitempty"`
	Priority    *string  `json:"priority,omitempty"`
	Labels      []string `json:"labels,omitempty"`
	Assignee    *string  `json:"assignee,omitempty"`
}

UpdateBeadRequest is the request body for PATCH /api/v1/beads/{id}

type VerifyCheckpointResponse 

type VerifyCheckpointResponse struct {
	Valid            bool              `json:"valid"`
	SchemaValid      bool              `json:"schema_valid"`
	FilesPresent     bool              `json:"files_present"`
	ChecksumsValid   bool              `json:"checksums_valid"`
	ConsistencyValid bool              `json:"consistency_valid"`
	Errors           []string          `json:"errors,omitempty"`
	Warnings         []string          `json:"warnings,omitempty"`
	Details          map[string]string `json:"details,omitempty"`
}

VerifyCheckpointResponse is the response from checkpoint verification.

type WSClient 

type WSClient struct {
	// contains filtered or unexported fields
}

WSClient represents a connected WebSocket client.

func (*WSClient) Subscribe 

func (c *WSClient) Subscribe(topics []string)

Subscribe adds topics to the client's subscription.

func (*WSClient) Topics 

func (c *WSClient) Topics() []string

Topics returns the client's subscribed topics.

func (*WSClient) Unsubscribe 

func (c *WSClient) Unsubscribe(topics []string)

Unsubscribe removes topics from the client's subscription.

type WSDroppedInfo 

type WSDroppedInfo struct {
	Topic           string `json:"topic"`
	ClientID        string `json:"client_id"`
	DroppedCount    int    `json:"dropped_count"`
	FirstDroppedSeq int64  `json:"first_dropped_seq,omitempty"`
	LastDroppedSeq  int64  `json:"last_dropped_seq,omitempty"`
	Reason          string `json:"reason"`
}

WSDroppedInfo tracks dropped events for a client.

type WSError 

type WSError struct {
	Type      WSMessageType `json:"type"`
	Timestamp string        `json:"ts"`
	RequestID string        `json:"request_id,omitempty"`
	Code      string        `json:"code"`
	Message   string        `json:"message"`
}

WSError represents a WebSocket error frame.

type WSEvent 

type WSEvent struct {
	Type      WSMessageType `json:"type"`
	Timestamp string        `json:"ts"`
	Seq       int64         `json:"seq"`
	Topic     string        `json:"topic"`
	EventType string        `json:"event_type"`
	Data      interface{}   `json:"data"`
}

WSEvent is an event pushed to clients.

type WSEventStore 

type WSEventStore struct {
	// contains filtered or unexported fields
}

WSEventStore provides event persistence and replay for WebSocket connections. It maintains an in-memory ring buffer for fast access and persists to SQLite for durability across restarts.

func NewWSEventStore 

func NewWSEventStore(db *sql.DB, cfg WSEventStoreConfig) *WSEventStore

NewWSEventStore creates a new event store. If db is nil, operates in memory-only mode (no persistence).

func (*WSEventStore) BufferStats 

func (s *WSEventStore) BufferStats() (size int, used int, oldestSeq int64, newestSeq int64)

BufferStats returns statistics about the ring buffer.

func (*WSEventStore) CurrentSeq 

func (s *WSEventStore) CurrentSeq() int64

CurrentSeq returns the current sequence number (highest assigned).

func (*WSEventStore) GetDroppedStats 

func (s *WSEventStore) GetDroppedStats(clientID string, since time.Time) ([]WSDroppedInfo, error)

GetDroppedStats gets dropped event statistics for a client.

func (*WSEventStore) GetSince 

func (s *WSEventStore) GetSince(since int64, topic string, limit int) ([]WSStoredEvent, bool, error)

GetSince retrieves events after the given sequence number. First tries the ring buffer, falls back to database if needed. Returns events and a boolean indicating if a cursor reset is needed.

func (*WSEventStore) RecordDropped 

func (s *WSEventStore) RecordDropped(clientID, topic, reason string, firstSeq, lastSeq int64) error

RecordDropped records dropped events for a client.

func (*WSEventStore) Stop 

func (s *WSEventStore) Stop()

Stop stops the event store's background goroutines.

func (*WSEventStore) Store 

func (s *WSEventStore) Store(topic, eventType string, data interface{}) (*WSStoredEvent, error)

Store stores an event in both the ring buffer and database.

type WSEventStoreConfig 

type WSEventStoreConfig struct {
	BufferSize       int           // Number of events in ring buffer (default: 10000)
	RetentionSeconds int64         // How long to keep events in SQLite (default: 3600 = 1 hour)
	CleanupInterval  time.Duration // How often to run cleanup (default: 5 minutes)
}

WSEventStoreConfig configures the event store.

func DefaultWSEventStoreConfig 

func DefaultWSEventStoreConfig() WSEventStoreConfig

DefaultWSEventStoreConfig returns sensible defaults.

type WSHub 

type WSHub struct {
	// contains filtered or unexported fields
}

WSHub manages WebSocket connections and topic routing.

func NewWSHub 

func NewWSHub() *WSHub

NewWSHub creates a new WebSocket hub.

func (*WSHub) ClientCount 

func (h *WSHub) ClientCount() int

ClientCount returns the number of connected clients.

func (*WSHub) GetRedactionConfig added in v1.7.0 

func (h *WSHub) GetRedactionConfig() *RedactionConfig

GetRedactionConfig returns the current redaction configuration.

func (*WSHub) Publish 

func (h *WSHub) Publish(topic, eventType string, data interface{})

Publish publishes an event to a topic.

func (*WSHub) Run 

func (h *WSHub) Run()

Run starts the hub's main event loop.

func (*WSHub) SetRedactionConfig added in v1.7.0 

func (h *WSHub) SetRedactionConfig(cfg *RedactionConfig)

SetRedactionConfig sets the redaction configuration for WebSocket events.

func (*WSHub) Stop 

func (h *WSHub) Stop()

Stop shuts down the hub.

type WSMessage 

type WSMessage struct {
	Type      WSMessageType          `json:"type"`
	Timestamp string                 `json:"ts"`
	RequestID string                 `json:"request_id,omitempty"`
	Data      map[string]interface{} `json:"data,omitempty"`
}

WSMessage is the base WebSocket message envelope.

type WSMessageType 

type WSMessageType string

WSMessageType defines WebSocket message types. 

const (
	WSMsgSubscribe   WSMessageType = "subscribe"
	WSMsgUnsubscribe WSMessageType = "unsubscribe"
	WSMsgEvent       WSMessageType = "event"
	WSMsgError       WSMessageType = "error"
	WSMsgAck         WSMessageType = "ack"
	WSMsgPing        WSMessageType = "ping"
	WSMsgPong        WSMessageType = "pong"
)

type WSPaneOutputDropped 

type WSPaneOutputDropped struct {
	Type         WSMessageType `json:"type"`
	Timestamp    string        `json:"ts"`
	Topic        string        `json:"topic"`
	DroppedCount int           `json:"dropped_count"`
	FirstSeq     int64         `json:"first_seq,omitempty"`
	LastSeq      int64         `json:"last_seq,omitempty"`
	Reason       string        `json:"reason"`
}

WSPaneOutputDropped is sent when pane output is dropped due to backpressure.

func NewPaneOutputDropped 

func NewPaneOutputDropped(topic string, count int, firstSeq, lastSeq int64, reason string) *WSPaneOutputDropped

NewPaneOutputDropped creates a pane output dropped message.

type WSStoredEvent 

type WSStoredEvent struct {
	Seq       int64     `json:"seq"`
	Topic     string    `json:"topic"`
	EventType string    `json:"event_type"`
	Data      string    `json:"data"` // JSON-encoded
	CreatedAt time.Time `json:"created_at"`
}

WSStoredEvent is an event stored in the ring buffer and database.

type WSStreamReset 

type WSStreamReset struct {
	Type        WSMessageType `json:"type"`
	Timestamp   string        `json:"ts"`
	Topic       string        `json:"topic,omitempty"`
	Reason      string        `json:"reason"`
	CurrentSeq  int64         `json:"current_seq"`
	OldestAvail int64         `json:"oldest_available,omitempty"`
}

WSStreamReset is sent to clients when their cursor has expired.

func NewStreamReset 

func NewStreamReset(topic, reason string, currentSeq, oldestAvail int64) *WSStreamReset

NewStreamReset creates a stream reset message.

type WSSubscribeRequest 

type WSSubscribeRequest struct {
	Topics []string `json:"topics"`
	Since  int64    `json:"since,omitempty"` // Cursor for replay (Unix ms)
}

WSSubscribeRequest is sent by clients to subscribe to topics.

type WSSubscriptionOptions 

type WSSubscriptionOptions struct {
	Since          int64  `json:"since,omitempty"`             // Cursor: replay events after this seq
	ThrottleMS     int    `json:"throttle_ms,omitempty"`       // Min ms between messages
	MaxLinesPerMsg int    `json:"max_lines_per_msg,omitempty"` // Max output lines per message
	Mode           string `json:"mode,omitempty"`              // "lines" or "raw"
}

WSSubscriptionOptions configures client subscription behavior.

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.