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
- func DecodeOutput(encoded, declaredMIME string, limit int64) (Output, *OutputError)
- func HandoffAdvertisement() map[string]any
- func IsImageMIME(declared string) bool
- func MediaEnvelope(limits Limits, envelope Envelope) map[string]any
- func ValidateHandoffRoot(dir string) error
- func ValidatePrompt(ctx context.Context, blocks []acp.ContentBlock, options Options) ([]Decoded, *InputError, error)
- type BlobDisposition
- type BlobPolicy
- type Decoded
- type Envelope
- type InputError
- type Limits
- type Options
- type Output
- type OutputError
Constants ¶
const ( FieldPromptImage = "prompt.image" FieldPromptResource = "prompt.resource" )
Input block fields an input refusal names.
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.
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.
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.
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.
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.
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 ¶
HandoffAdvertisement is the agentCapabilities._meta value advertised while a handoff root is configured.
func IsImageMIME ¶
IsImageMIME reports whether a normalized media type routes to image validation.
func MediaEnvelope ¶
MediaEnvelope renders the acp-go.dev/mediaEnvelope advertisement from the same effective limits the gates enforce.
func ValidateHandoffRoot ¶
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 ¶
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 ¶
EffectiveOutputPerImage clamps the per-image output limit to the frame bound.
func (Limits) EffectiveOutputPerToolCall ¶
EffectiveOutputPerToolCall clamps the per-tool-call output limit to the frame bound.
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 ¶
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 ¶
OutputError is one output verdict.
func DecodeInline ¶
DecodeInline decodes native inline base64 output, bounded by limit. It returns the retained bytes, the sniffed MIME, and the full decoded size.
func ReadFile ¶
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.