surface

package
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: GPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package surface adapts the shared semantic runtime to user-visible input and output contracts. It does not own query, permission, or persistence policy.

Index

Constants

View Source 
const (
	// UserContentVersionAttachments identifies the first provider-neutral
	// attachment-bearing user-content union.
	UserContentVersionAttachments = attachment.ProtocolVersion

	// MaxUserMessageAttachments is the exact first-version per-message count
	// bound. Byte bounds are additionally enforced by attachment.Manifest.
	MaxUserMessageAttachments = attachment.DefaultMaxAttachmentsPerMessage
)
View Source 
const (
	// AttachmentImportProtocolVersion is the sole stream-json attachment import
	// version supported by this runtime.
	AttachmentImportProtocolVersion = attachment.ProtocolVersion
)
View Source 
const MaxNDJSONRecordBytes = 8 << 20

Variables

View Source 
var (
	ErrClosed  = errors.New("structured control stream closed")
	ErrAborted = errors.New("structured control request aborted")
)

Functions

func DecodeUserText 

func DecodeUserText(raw json.RawMessage) (string, error)

DecodeUserText retains the legacy text-only projection. New callers should use DecodeUserMessage so attachment metadata cannot be silently discarded.

func NewUUID 

func NewUUID() (string, error)

NewUUID creates a version-4 RFC 4122 identifier for SDK fields whose public schema specifically requires UUID rather than an internal typed identifier.

func SealedOutputErrorClassifications 

func SealedOutputErrorClassifications(err error) []error

SealedOutputErrorClassifications exposes exact, bounded policy identities only for this package's opaque output failure. It never returns the raw error graph or invokes callback-owned behavior.

func ValidateUUID added in v1.0.7 

func ValidateUUID(value string) error

ValidateUUID checks the canonical RFC 4122 textual UUID shape used by the versioned attachment protocol. Legacy text-only SDK prompt identifiers retain their existing compatibility validation elsewhere.

Types

type AttachmentImport added in v1.0.7 

type AttachmentImport struct {
	Version      int                       `json:"version"`
	Operation    AttachmentImportOperation `json:"operation"`
	PromptUUID   string                    `json:"prompt_uuid,omitempty"`
	UploadID     attachment.UploadID       `json:"upload_id"`
	AttachmentID attachment.ID             `json:"attachment_id,omitempty"`
	Name         string                    `json:"name,omitempty"`
	SizeBytes    int64                     `json:"size_bytes,omitempty"`
	MIMEType     string                    `json:"mime_type,omitempty"`
	SHA256       string                    `json:"sha256,omitempty"`
	Sequence     int                       `json:"sequence,omitempty"`
	Data         string                    `json:"data,omitempty"`
}

AttachmentImport is one strictly decoded stream-json import operation. Chunk Data remains encoded; only the owning attachment.Store may retain or commit decoded bytes.

func DecodeAttachmentImport added in v1.0.7 

func DecodeAttachmentImport(raw json.RawMessage) (AttachmentImport, error)

DecodeAttachmentImport strictly decodes one complete versioned import envelope. Base64 is decoded only into bounded scratch space to validate its strict syntax; the returned record retains only the original encoded chunk.

func (AttachmentImport) BeginUpload added in v1.0.7 

func (r AttachmentImport) BeginUpload() (attachment.BeginUpload, bool)

BeginUpload projects the begin operation into the attachment-store request.

type AttachmentImportOperation added in v1.0.7 

type AttachmentImportOperation string

AttachmentImportOperation is the closed upload state-machine discriminator. 

const (
	AttachmentImportBegin  AttachmentImportOperation = "begin"
	AttachmentImportChunk  AttachmentImportOperation = "chunk"
	AttachmentImportCommit AttachmentImportOperation = "commit"
	AttachmentImportAbort  AttachmentImportOperation = "abort"
)

type AttachmentReference added in v1.0.7 

type AttachmentReference = attachment.Manifest

AttachmentReference is safe immutable metadata. It never contains source or runtime filesystem paths and cannot resolve its StorageID without the owning attachment.Store.

type ControlBroker 

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

ControlBroker correlates concurrent permission and SDK requests. A waiter is registered before its request is emitted, closing the fast-response race.

func NewControlBroker 

func NewControlBroker() *ControlBroker

func (*ControlBroker) AbortPending 

func (b *ControlBroker) AbortPending() error

AbortPending synchronously emits cancellations in request order and then settles the detached waiters.

func (*ControlBroker) AbortPendingThen 

func (b *ControlBroker) AbortPendingThen(after func() error) error

AbortPendingThen detaches pending waiters, emits every cancellation, runs after while those waiters are still parked, and only then releases them. The interrupt adapter uses after for its acknowledgement, preventing waiter cleanup events from racing between cancellation and acknowledgement.

func (*ControlBroker) Cancel 

func (b *ControlBroker) Cancel(id identity.RequestID) bool

func (*ControlBroker) Close 

func (b *ControlBroker) Close()

func (*ControlBroker) Pending 

func (b *ControlBroker) Pending() int

func (*ControlBroker) Request 

func (b *ControlBroker) Request(ctx context.Context, request ControlRequest, emit func(OutputEnvelope) error) (ControlResponseBody, error)

func (*ControlBroker) Resolve 

func (b *ControlBroker) Resolve(id identity.RequestID, response ControlResponseBody) bool

type ControlRequest 

type ControlRequest struct {
	Subtype string          `json:"-"`
	Data    json.RawMessage `json:"-"`
}

ControlRequest serializes operation fields beside subtype, never under an internal data wrapper. Data must be either absent or a JSON object.

func NewControlRequest 

func NewControlRequest(subtype string, fields any) (ControlRequest, error)

func (ControlRequest) MarshalJSON 

func (r ControlRequest) MarshalJSON() ([]byte, error)

func (*ControlRequest) UnmarshalJSON 

func (r *ControlRequest) UnmarshalJSON(data []byte) error

type ControlResponseBody 

type ControlResponseBody struct {
	Subtype                   string             `json:"subtype"`
	RequestID                 identity.RequestID `json:"request_id"`
	Response                  json.RawMessage    `json:"response,omitempty"`
	Error                     string             `json:"error,omitempty"`
	PendingPermissionRequests []OutputEnvelope   `json:"pending_permission_requests,omitempty"`
}

ControlResponseBody is the closed published success/error response union. Response is operation-specific and is validated by the selected waiter.

func (ControlResponseBody) MarshalJSON 

func (r ControlResponseBody) MarshalJSON() ([]byte, error)

func (*ControlResponseBody) UnmarshalJSON 

func (r *ControlResponseBody) UnmarshalJSON(data []byte) error

type Decoder 

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

Decoder accepts arbitrary reader chunking, skips blank records, processes a final record without a newline, and fails the stream on malformed JSON.

func NewDecoder 

func NewDecoder(reader io.Reader, warnings io.Writer) *Decoder

func (*Decoder) Next 

func (d *Decoder) Next() (InputEnvelope, error)

type Encoder 

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

Encoder serializes protocol records atomically. Diagnostics must use a separate writer; stdout remains protocol-only.

func NewEncoder 

func NewEncoder(writer io.Writer) *Encoder

func (*Encoder) Encode 

func (e *Encoder) Encode(value any) error

func (*Encoder) SetValidator 

func (e *Encoder) SetValidator(validator func([]byte) error) error

SetValidator installs a complete-record validator before the first write. It is intended for session-scoped egress policy that must inspect JSON framing as well as individual semantic fields.

type InputEnvelope 

type InputEnvelope struct {
	Type                 string               `json:"type"`
	UUID                 string               `json:"uuid,omitempty"`
	SessionID            string               `json:"session_id,omitempty"`
	Message              json.RawMessage      `json:"message,omitempty"`
	ParentToolUseID      *string              `json:"parent_tool_use_id,omitempty"`
	IsReplay             bool                 `json:"isReplay,omitempty"`
	IsSynthetic          bool                 `json:"isSynthetic,omitempty"`
	ToolUseResult        json.RawMessage      `json:"tool_use_result,omitempty"`
	Priority             string               `json:"priority,omitempty"`
	Timestamp            string               `json:"timestamp,omitempty"`
	RequestID            identity.RequestID   `json:"request_id,omitempty"`
	Request              *ControlRequest      `json:"request,omitempty"`
	Response             *ControlResponseBody `json:"response,omitempty"`
	EnvironmentVariables map[string]string    `json:"variables,omitempty"`
	AttachmentImport     *AttachmentImport    `json:"-"`
	// contains filtered or unexported fields
}

InputEnvelope is the documented aggregate stdin envelope. Message is kept raw until the semantic runner validates the API-message role and content. Request-ID camel-case aliases are accepted only by UnmarshalJSON.

func (InputEnvelope) OriginalByteSize 

func (e InputEnvelope) OriginalByteSize() int

OriginalByteSize reports the complete decoded input record's byte size before compatibility aliases and fields were projected into InputEnvelope. Queue owners use it for bounded admission without retaining another copy of the raw record.

func (*InputEnvelope) UnmarshalJSON 

func (e *InputEnvelope) UnmarshalJSON(data []byte) error

type OutputEnvelope 

type OutputEnvelope struct {
	Type      string               `json:"type"`
	RequestID identity.RequestID   `json:"request_id,omitempty"`
	Request   *ControlRequest      `json:"request,omitempty"`
	Response  *ControlResponseBody `json:"response,omitempty"`
}

OutputEnvelope is used only for the three control envelopes. Ordinary SDK messages have dedicated projections in pkg/app and do not use Data.

type UserContent added in v1.0.7 

type UserContent struct {
	Type       UserContentType
	Text       string
	Attachment *AttachmentReference
}

UserContent contains exactly one text value or immutable attachment reference. Attachment metadata is flattened by MarshalJSON to match the versioned external union.

func (UserContent) MarshalJSON added in v1.0.7 

func (c UserContent) MarshalJSON() ([]byte, error)

MarshalJSON emits one closed content-block variant. Attachment manifest fields deliberately remain flat and contain no bytes or paths.

type UserContentType added in v1.0.7 

type UserContentType string

UserContentType is the closed, provider-neutral input-content discriminator. 

const (
	UserContentText       UserContentType = "text"
	UserContentAttachment UserContentType = "attachment_ref"
)

type UserMessage added in v1.0.7 

type UserMessage struct {
	Role           string
	ContentVersion int
	Content        []UserContent
}

UserMessage is the typed external user message admitted by structured input. Role is always user after decoding. ContentVersion is zero only for legacy text-only forms.

func DecodeUserMessage added in v1.0.7 

func DecodeUserMessage(raw json.RawMessage) (UserMessage, error)

DecodeUserMessage accepts legacy strings, legacy API user-message content strings and text/input_text arrays, plus the version-1 attachment union. Message and block objects are closed and duplicate members are always rejected before map/struct decoding.

func (UserMessage) AttachmentIDs added in v1.0.7 

func (m UserMessage) AttachmentIDs() []attachment.ID

AttachmentIDs returns a new ordered slice of stable attachment identities.

func (UserMessage) HasAttachments added in v1.0.7 

func (m UserMessage) HasAttachments() bool

HasAttachments reports whether the message contains any attachment references.

func (UserMessage) MarshalJSON added in v1.0.7 

func (m UserMessage) MarshalJSON() ([]byte, error)

MarshalJSON emits only the closed external user-message union.

func (UserMessage) Text added in v1.0.7 

func (m UserMessage) Text() string

Text joins ordered text blocks using the legacy DecodeUserText separator. Attachment positions remain represented by Content and are not converted to prompt placeholders.

func (UserMessage) Validate added in v1.0.7 

func (m UserMessage) Validate() error

Validate checks the complete typed union, including immutable manifest, duplicate identity, count, and aggregate decoded-byte bounds.

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.