authorsession

Documentation

Overview

Package authorsession implements the strict local protocol for one authenticated goal-directed browser authoring process. The browser backend owns all live handles; the protocol exposes reduced semantics only.

Index

• Constants
• func Serve(ctx context.Context, input io.Reader, output io.Writer, browser Browser, ...) error
• type Approval
• type Browser
• type BrowserAction
• type BrowserRequest
• type Candidate
• type Checkpoint
• type ClientMessage
• type Diagnostic
• type Execution
• type LabelReduction
  • func ReduceAccessibilityLabel(raw string) LabelReduction
• type LabelReductionReason
• type Observation
• type OutputRequest
• type RawCandidate
• type RawObservation
• type Result
• type ServeOptions
• type ServerMessage
• type Session

Constants

const (
	DefaultNavigationTimeout = 20 * time.Second
	DefaultTotalTimeout      = 10 * time.Minute
	DefaultMaxRequests       = 512
	DefaultMaxResponseBytes  = int64(32 << 20)
	DefaultMaxObservations   = 64
	DefaultMaxCandidates     = 128
	DefaultMaxOutputs        = 16
	AbsoluteMaxOutputs       = 32
	MaxContexts              = 64
	MaxUniqueDiagnostics     = 256
)

const AccessibilityLabelDisclosure = "" /* 232-byte string literal not displayed */

AccessibilityLabelDisclosure is operator-facing guidance for every consumer that displays reduced observations or reviewed authoring traces. Reduction is a useful heuristic, not data loss prevention.

const Protocol = "browsertools.author-session.v2"

Functions

func Serve

func Serve(ctx context.Context, input io.Reader, output io.Writer, browser Browser, options ServeOptions) error

Serve processes one author session until finish, close, or fail-closed termination. It never persists the NDJSON transcript.

Types

type Approval

type Approval struct {
	ID          string `json:"id"`
	Kind        string `json:"kind"`
	Origin      string `json:"origin,omitempty"`
	Action      string `json:"action,omitempty"`
	CandidateID string `json:"candidateId,omitempty"`
	POSTBudget  int    `json:"postBudget,omitempty"`
}

type Browser

type Browser interface {
	Open(context.Context, BrowserRequest) (Session, error)
}

Browser opens one live non-persistent authoring context.

type BrowserAction

type BrowserAction struct {
	Kind         string
	BackendID    string
	URL          string
	Context      string
	POSTBudget   int
	Role         string
	Label        string
	InputKind    string
	TargetOrigin string
	Matches      int
}

BrowserAction is a closed action against a backend-owned candidate.

type BrowserRequest

type BrowserRequest struct {
	URL               string
	ApprovedOrigins   []string
	NavigationTimeout time.Duration
	TotalTimeout      time.Duration
	MaxRequests       int
	MaxResponseBytes  int64
	MaxCandidates     int
}

BrowserRequest fixes the browser-owned authority before launch.

type Candidate

type Candidate struct {
	ID      string `json:"id"`
	Role    string `json:"role"`
	Label   string `json:"label,omitempty"`
	Matches int    `json:"matches"`
}

Candidate is the reduced protocol candidate.

type Checkpoint

type Checkpoint struct {
	Kind           string   `json:"kind"`
	CandidateID    string   `json:"candidateId,omitempty"`
	InputKind      string   `json:"inputKind,omitempty"`
	ChallengeKinds []string `json:"challengeKinds,omitempty"`
}

type ClientMessage

type ClientMessage struct {
	Protocol      string                      `json:"protocol"`
	Type          string                      `json:"type"`
	Title         string                      `json:"title,omitempty"`
	URL           string                      `json:"url,omitempty"`
	DashboardURL  string                      `json:"dashboardUrl,omitempty"`
	Goal          string                      `json:"goal,omitempty"`
	Origins       []string                    `json:"origins,omitempty"`
	GoalPredicate *authorresult.GoalPredicate `json:"goalPredicate,omitempty"`
	Bounds        *authorresult.Bounds        `json:"bounds,omitempty"`
	Context       string                      `json:"context,omitempty"`
	CandidateID   string                      `json:"candidateId,omitempty"`
	Action        string                      `json:"action,omitempty"`
	POSTBudget    int                         `json:"postBudget,omitempty"`
	ApprovalID    string                      `json:"approvalId,omitempty"`
	ChallengeKind string                      `json:"challengeKind,omitempty"`
	Outputs       *[]OutputRequest            `json:"outputs,omitempty"`
	Confirmed     bool                        `json:"confirmed,omitempty"`
}

ClientMessage is the closed NDJSON input union.

type Diagnostic

type Diagnostic struct {
	Code string `json:"code"`
}

type Execution

type Execution struct {
	POSTObserved int
	OpenedID     string
	Opened       *authorresult.Context
}

Execution contains only value-free action facts.

type LabelReduction

type LabelReduction struct {
	Value  string
	Reason LabelReductionReason
}

LabelReduction is the canonical protocol-safe label and its closed reason.

func ReduceAccessibilityLabel

func ReduceAccessibilityLabel(raw string) LabelReduction

ReduceAccessibilityLabel applies the canonical author-session label policy. The rejected raw label is intentionally absent from the result.

type LabelReductionReason

type LabelReductionReason string

LabelReductionReason is the closed explanation for an accessibility-label reduction. Consumers can safely report the reason without retaining the raw page-derived label.

const (
	LabelReasonUnchanged       LabelReductionReason = "unchanged"
	LabelReasonNormalized      LabelReductionReason = "normalized"
	LabelReasonTooLong         LabelReductionReason = "too_long"
	LabelReasonSensitive       LabelReductionReason = "sensitive"
	LabelReasonPromptInjection LabelReductionReason = "prompt_injection"

	RedactedLabel  = "[redacted]"
	UntrustedLabel = "[untrusted-label]"
)

type Observation

type Observation struct {
	Origin      string                          `json:"origin"`
	Path        string                          `json:"path"`
	Context     string                          `json:"context"`
	Contexts    map[string]authorresult.Context `json:"contexts"`
	Candidates  []Candidate                     `json:"candidates"`
	Diagnostics []string                        `json:"diagnostics"`
}

Observation is the only page-derived semantic protocol payload.

type OutputRequest

type OutputRequest struct {
	CandidateID string `json:"candidateId"`
	Key         string `json:"key"`
	Type        string `json:"type"`
	LocatorMode string `json:"locatorMode"`
}

OutputRequest is one human-reviewed accessibility output declaration.

type RawCandidate

type RawCandidate struct {
	BackendID      string
	Role           string
	Label          string
	InputKind      string
	ChallengeKinds []string
	// TargetOrigin is backend-only preflight metadata for portable links. It is
	// never included in an observation; it can only surface as an origin gate.
	TargetOrigin string
	Matches      int
}

RawCandidate identifies one backend-owned accessible target. BackendID is never serialized.

type RawObservation

type RawObservation struct {
	Origin      string
	Path        string
	Context     string
	Candidates  []RawCandidate
	Contexts    map[string]authorresult.Context
	Diagnostics []string
}

RawObservation is an in-process backend record. Serve reduces it before any protocol output is written.

type Result

type Result struct {
	ArtifactPath string `json:"artifactPath"`
	Digest       string `json:"digest"`
}

type ServeOptions

type ServeOptions struct {
	PrivateRoot string
	Clock       func() time.Time
}

ServeOptions are local process controls, not protocol authority.

type ServerMessage

type ServerMessage struct {
	Protocol     string               `json:"protocol"`
	Type         string               `json:"type"`
	Capabilities []string             `json:"capabilities,omitempty"`
	Bounds       *authorresult.Bounds `json:"bounds,omitempty"`
	Phase        string               `json:"phase,omitempty"`
	Context      string               `json:"context,omitempty"`
	Observation  *Observation         `json:"observation,omitempty"`
	Approval     *Approval            `json:"approval,omitempty"`
	Checkpoint   *Checkpoint          `json:"checkpoint,omitempty"`
	Diagnostic   *Diagnostic          `json:"diagnostic,omitempty"`
	Result       *Result              `json:"result,omitempty"`
}

ServerMessage is the closed NDJSON output union.

type Session

type Session interface {
	Observe(context.Context, string) (RawObservation, error)
	Focus(context.Context, BrowserAction) error
	Execute(context.Context, BrowserAction) (Execution, error)
	AddOrigin(string) error
	Close() error
}

Session is the only live-browser surface visible to the state machine. It contains no API for input values, cookies, storage, or session export.