image

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package image holds the family image gates: the decoded-byte limits, the media envelope, prompt image validation in both input forms, and output normalization.

Index

Constants

View Source
const (
	FieldPromptImage    = "prompt.image"
	FieldPromptResource = "prompt.resource"
)

Input block fields an input refusal names.

View Source
const (
	ErrorMissingData         = "missing_data"
	ErrorInvalidBase64       = "invalid_base64"
	ErrorInvalidMediaType    = "invalid_media_type"
	ErrorMediaTypeMismatch   = "media_type_mismatch"
	ErrorAnimatedUnsupported = "animated_not_supported"
	ErrorInvalidDimensions   = "invalid_dimensions"
	ErrorTooLarge            = "too_large"
	ErrorUnsupportedByModel  = "unsupported_by_model"
	ErrorInvalidHandoff      = "invalid_handoff"
	ErrorPathNotAllowed      = "path_not_allowed"
	ErrorMissingFile         = "missing_file"
	ErrorDigestMismatch      = "handoff_digest_mismatch"
)

The closed input error vocabulary.

View Source
const (
	ReasonInvalidBase64     = "invalid_base64"
	ReasonNotRaster         = "not_a_raster"
	ReasonMediaTypeMismatch = "media_type_mismatch"
	ReasonMissingFile       = "missing_file"
	ReasonPathNotAllowed    = "path_not_allowed"
	ReasonTooLarge          = "too_large"
	ReasonStorageFailed     = "storage_failed"
)

The closed output reason vocabulary.

View Source
const (
	GuidancePathNotAllowed    = "write the image inside the workspace and try again"
	GuidanceMissingFile       = "the image file could not be read; write the image inside the workspace and try again"
	GuidanceTooLarge          = "the image is too large to send; write a smaller image and try again"
	GuidanceNotRaster         = "the file is not a supported raster image; write a PNG, JPEG, GIF, WebP, BMP, ICO, or TIFF and try again"
	GuidanceInvalidBase64     = "the image payload could not be decoded; write the image to a file inside the workspace and try again"
	GuidanceMediaTypeMismatch = "the declared media type does not match the image; write the image again with a matching media type"
)

Guidance carried back to the model when an output is refused in place. Each string is a constant keyed only by the reason and interpolates nothing about the artifact.

View Source
const (
	MIMEPNG  = "image/png"
	MIMEJPEG = "image/jpeg"
	MIMEGIF  = "image/gif"
	MIMEWebP = "image/webp"
)

The inbound media-type allowlist, in the order the media envelope advertises it.

View Source
const FrameClamp int64 = 7_864_155

FrameClamp is the largest decoded image the pinned ACP SDK can carry in one JSON-RPC frame. Its base64 form plus 220 bytes of envelope fits the SDK's 10,485,760-byte line scanner.

View Source
const OutputStage = "image_output"

OutputStage is the turn-failure stage for image output.

Variables

This section is empty.

Functions

func DecodeOutput

func DecodeOutput(encoded, declaredMIME string, limit int64) (Output, *OutputError)

DecodeOutput validates one native inline image for emission. Output is not format-allowlisted: any sniffable raster is emitted with its sniffed MIME, but a declared image MIME that disagrees with the bytes is refused.

func HandoffAdvertisement

func HandoffAdvertisement() map[string]any

HandoffAdvertisement is the agentCapabilities._meta value advertised while a handoff root is configured.

func IsImageMIME

func IsImageMIME(declared string) bool

IsImageMIME reports whether a normalized media type routes to image validation.

func MediaEnvelope

func MediaEnvelope(limits Limits, envelope Envelope) map[string]any

MediaEnvelope renders the acp-go.dev/mediaEnvelope advertisement from the same effective limits the gates enforce.

func ValidateHandoffRoot

func ValidateHandoffRoot(dir string) error

ValidateHandoffRoot refuses a relative root at construction.

func ValidatePrompt

func ValidatePrompt(ctx context.Context, blocks []acp.ContentBlock, options Options) ([]Decoded, *InputError, error)

ValidatePrompt runs the pinned input gate order over every media-bearing block in request order and stops at the first failure. Image and blob blocks consume media indexes; text resources only spend the aggregate byte budget. The native text/image ordering constraint is checked after the media gates.

A refusal and an abort are different answers: the refusal describes a block the host can fix, while the error return means the caller stopped waiting.

Types

type BlobDisposition

type BlobDisposition int

BlobDisposition is one BlobPolicy answer.

const (
	// BlobGate decodes the blob, bounds it by the per-image gate, and charges it
	// to the prompt aggregate. The sibling decides afterwards what to forward.
	BlobGate BlobDisposition = iota
	// BlobRefuse rejects the blob before any decode with the uniform unsupported
	// error on prompt.resource.
	BlobRefuse
)

The closed blob dispositions.

type BlobPolicy

type BlobPolicy func(normalizedMIME string) BlobDisposition

BlobPolicy decides what a sibling does with an embedded resource blob whose normalized MIME is not an image: gate its bytes, or refuse it before decode.

type Decoded

type Decoded struct {
	Data  []byte
	MIME  string
	Field string
	Block int
	Index int
}

Decoded is one validated image or admitted blob ready for the native request. Block is its position in the prompt; Index counts media blocks, so text resources consume no index.

type Envelope

type Envelope struct {
	// NativeCeiling is an observed native per-image byte cap below the frame
	// clamp, or zero.
	NativeCeiling int64
	// MaxDimension is an enforced native per-dimension pixel bound, or zero.
	MaxDimension int64
	// DocumentFormats lists MIMEs the sibling maps to a native document
	// representation.
	DocumentFormats []string
}

Envelope describes the media envelope inputs that vary per sibling.

type InputError

type InputError struct {
	Code      string
	Field     string
	Message   string
	Index     int
	SizeBytes int64
	MaxBytes  int64
}

InputError is one input gate's refusal. Field names the prompt or its inbound block type; Index counts gated media blocks, or is negative when the refusal reports no media index.

func UnsupportedByModel

func UnsupportedByModel(field string, index int) *InputError

UnsupportedByModel builds the prompt-time refusal for a text-only selected model, naming the first gated-media block.

func (*InputError) Error

func (e *InputError) Error() string

func (*InputError) InvalidParams

func (e *InputError) InvalidParams() *acp.RequestError

InvalidParams renders the refusal as uniform -32602 data.

type Limits

type Limits struct {
	MaxInputBytesPerImage     int64
	MaxInputBytesPerPrompt    int64
	MaxOutputBytesPerImage    int64
	MaxOutputBytesPerToolCall int64
}

Limits bounds decoded image bytes accepted from prompts and emitted as output. Every field counts decoded bytes. A zero disables that policy limit and never bypasses the frame clamp or a native ceiling.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns every field at defaultLimitBytes.

func (Limits) EffectiveOutputPerImage

func (l Limits) EffectiveOutputPerImage() int64

EffectiveOutputPerImage clamps the per-image output limit to the frame bound.

func (Limits) EffectiveOutputPerToolCall

func (l Limits) EffectiveOutputPerToolCall() int64

EffectiveOutputPerToolCall clamps the per-tool-call output limit to the frame bound.

func (Limits) Validate

func (l Limits) Validate() error

Validate refuses a negative field.

type Options

type Options struct {
	Limits Limits
	// HandoffRoot is the configured read root, or empty when handoff is off.
	HandoffRoot string
	// NativeCeiling is an observed native per-image cap below the frame clamp,
	// or zero.
	NativeCeiling int64
	// Blobs decides non-image resource blobs. Nil gates every blob.
	Blobs BlobPolicy
	// TextBeforeImages requires all forwarded text to precede the images when
	// the native prompt carries separate text and image fields.
	TextBeforeImages bool
}

Options configures one prompt's image validation.

type Output

type Output struct {
	Data        string
	MIME        string
	SizeBytes   int64
	Fingerprint string
}

Output is one validated emitted image: the base64 payload, the sniffed MIME, its decoded size, and the SHA-256 fingerprint siblings deduplicate on.

type OutputError

type OutputError struct {
	Reason    string
	Message   string
	SizeBytes int64
	MaxBytes  int64
}

OutputError is one output verdict.

func DecodeInline

func DecodeInline(data string, limit int64) ([]byte, string, int64, *OutputError)

DecodeInline decodes native inline base64 output, bounded by limit. It returns the retained bytes, the sniffed MIME, and the full decoded size.

func ReadFile

func ReadFile(path string, roots []string, limit int64) ([]byte, string, *OutputError)

ReadFile reads one harness-returned artifact path under the allowed roots, bounded by limit, and sniffs its MIME. The path is resolved and compared with roots resolved to the same degree, then opened through the root it fell in, so a symlink swapped in after resolution cannot lead outside that root.

func (*OutputError) Error

func (e *OutputError) Error() string

func (*OutputError) Guidance

func (e *OutputError) Guidance() (string, bool)

Guidance returns the constant text a recoverable verdict reports to the model and whether the verdict is recoverable. Only storage_failed is not.

func (*OutputError) TurnFailure

func (e *OutputError) TurnFailure() wire.TurnFailure

TurnFailure renders a fatal output verdict as the turn-failure envelope members.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL