attachment

type Attachment struct {
	Kind  AttachmentKind `json:"kind"`
	Label string         `json:"label"`

	// Mode selected for this attachment for the current turn.
	// Frontend picks smart defaults; backend can override missing values.
	Mode AttachmentContentBlockMode `json:"mode,omitempty"`
	// Optional: allowed modes for this attachment (primarily for UI).
	AvailableContentBlockModes []AttachmentContentBlockMode `json:"availableContentBlockModes,omitempty"`

	// Exactly one field below should be non-nil.
	FileRef    *FileRef    `json:"fileRef,omitempty"`
	ImageRef   *ImageRef   `json:"imageRef,omitempty"`
	URLRef     *URLRef     `json:"urlRef,omitempty"`
	GenericRef *GenericRef `json:"genericRef,omitempty"`

	ContentBlock *ContentBlock `json:"contentBlock,omitempty"`
}

type AttachmentContentBlockKind string

type AttachmentContentBlockMode string

type AttachmentKind string

type ContentBlock struct {
	Kind AttachmentContentBlockKind `json:"kind"`

	// For Kind == text: Text, MIMEType and FileName are populated when read from local file.
	// For URL based text attachments, Filename will not be present, MIMEType _may_ be present.
	Text     *string `json:"text,omitempty"`
	MIMEType *string `json:"mimeType,omitempty"`
	FileName *string `json:"fileName,omitempty"`

	// For Kind == image or file: Base64Data will be populated for local file.
	// For URL based attachments, Base64Data may or may not be present depending on AttachmentMode.
	Base64Data *string `json:"base64Data,omitempty"`

	// URL is populated for URL-based attachments.
	URL *string `json:"url,omitempty"`
}

type ContentBlockOption func(*buildContentBlockOptions)

type DirectoryAttachmentsResult struct {
	DirPath      string                  `json:"dirPath"`
	Attachments  []Attachment            `json:"attachments"`  // included attachments (flattened)
	OverflowDirs []DirectoryOverflowInfo `json:"overflowDirs"` // directories not fully included
	MaxFiles     int                     `json:"maxFiles"`     // max number of files returned (after clamping)
	TotalSize    int64                   `json:"totalSize"`    // sum of Files[i].Size
	HasMore      bool                    `json:"hasMore"`      // true if not all content included
}

type DirectoryOverflowInfo struct {
	DirPath      string `json:"dirPath"`
	RelativePath string `json:"relativePath"`
	FileCount    int    `json:"fileCount"`
	Partial      bool   `json:"partial"`
}

type ExtensionMode string

type FileExt string

type FileFilter struct {
	DisplayName string
	Extensions  []FileExt // normalized, e.g. ".png".
}

type FileRef struct {
	PathInfo

	// Snapshot of the original file state when it was first attached.
	// This lets us detect if the underlying file changed between turns.
	OrigPath    string    `json:"origPath"`
	OrigSize    int64     `json:"origSize"`
	OrigModTime time.Time `json:"origModTime"`
}

type GenericRef struct {
	Handle string `json:"handle"`

	OrigHandle string `json:"origHandle"`
}

type ImageRef struct {
	Path    string     `json:"path"`
	Name    string     `json:"name"`
	Exists  bool       `json:"exists"`
	IsDir   bool       `json:"isDir"`
	Size    int64      `json:"size,omitempty"`
	ModTime *time.Time `json:"modTime,omitempty"`

	Width    int      `json:"width,omitempty"`
	Height   int      `json:"height,omitempty"`
	Format   string   `json:"format,omitempty"`   // e.g. "jpeg", "png"
	MIMEType MIMEType `json:"mimeType,omitempty"` // e.g. "image/jpeg"

	// Original snapshot (for change detection across turns).
	OrigPath    string    `json:"origPath"`
	OrigSize    int64     `json:"origSize"`
	OrigModTime time.Time `json:"origModTime"`
}

type MIMEType string

type PathInfo struct {
	Path    string     `json:"path"`
	Name    string     `json:"name"`
	Exists  bool       `json:"exists"`
	IsDir   bool       `json:"isDir"`
	Size    int64      `json:"size,omitempty"`
	ModTime *time.Time `json:"modTime,omitempty"`
}

type URLRef struct {
	URL            string `json:"url"`
	Normalized     string `json:"normalized,omitempty"`
	OrigNormalized string `json:"origNormalized"`
}

type WalkDirectoryWithFilesResult struct {
	DirPath      string                  `json:"dirPath"`
	Files        []PathInfo              `json:"files"`        // included files (flattened)
	OverflowDirs []DirectoryOverflowInfo `json:"overflowDirs"` // directories not fully included
	MaxFiles     int                     `json:"maxFiles"`     // max number of files returned (after clamping)
	TotalSize    int64                   `json:"totalSize"`    // sum of Files[i].Size
	HasMore      bool                    `json:"hasMore"`      // true if not all content included
}