driver

type BaseImageProvider interface {
	BaseImage() (tag string, dockerfile string)
}

type ChannelConfig struct {
	Guilds            map[string]ChannelGuildConfig // guild ID → routing config
	DM                ChannelDMConfig
	AllowFromHandles  bool     // append all declared platform handles to each guild users[] allowlist
	AllowFromServices []string // append Discord bot IDs derived from these pod service envs
}

type ChannelDMConfig struct {
	Enabled   bool
	Policy    string   // "pairing", "allowlist", "open", "disabled", or "" (legacy "denylist" alias supported)
	AllowFrom []string // user IDs allowed to DM the bot
}

type ChannelGuildConfig struct {
	Policy         string   // "allowlist", "denylist", or "" (inherit platform default)
	Users          []string // user IDs for the policy list
	RequireMention bool
}

type ChannelInfo struct {
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
}

type ContainerRef struct {
	ContainerID string
	ServiceName string
}

type Driver interface {
	Validate(rc *ResolvedClaw) error
	Materialize(rc *ResolvedClaw, opts MaterializeOpts) (*MaterializeResult, error)
	PostApply(rc *ResolvedClaw, opts PostApplyOpts) error
	HealthProbe(ref ContainerRef) (*Health, error)
}

type GeneratedSkill struct {
	Name    string // filename (e.g., "surface-fleet-master.md")
	Content []byte // skill file content
}

type GuildInfo struct {
	ID       string        `json:"id"`
	Name     string        `json:"name,omitempty"`
	Channels []ChannelInfo `json:"channels,omitempty"`
}

type HandleInfo struct {
	ID       string      `json:"id"`
	Username string      `json:"username,omitempty"`
	Guilds   []GuildInfo `json:"guilds,omitempty"`
}

type Health struct {
	OK     bool
	Detail string
}

type Healthcheck struct {
	Test     []string
	Interval string
	Timeout  string
	Retries  int
}

type Invocation struct {
	ID       string           `json:"id,omitempty"`
	Schedule string           // 5-field cron expression (e.g., "15 8 * * 1-5")
	Message  string           // agent task payload (agentTurn message)
	To       string           // platform delivery target (channel/chat ID; empty = driver default behavior)
	Name     string           // human-readable job name (optional, derived from message if empty)
	Origin   InvocationOrigin `json:"origin,omitempty"`
	When     *schedule.When   `json:"when,omitempty"`
}

type InvocationOrigin string

type MaterializeOpts struct {
	RuntimeDir string // host directory for generated artifacts
	StateDir   string // host directory for durable writable state
	PodName    string // pod name for context injection (CLAWDAPUS.md)
}

type MaterializeResult struct {
	Mounts      []Mount
	Tmpfs       []string          // paths needing tmpfs (for read_only: true)
	Environment map[string]string // additional env vars
	Healthcheck *Healthcheck
	ReadOnly    bool   // default: true
	Restart     string // default: "on-failure"
	SkillDir    string // container path for skills (e.g., "/claw/skills")
	SkillLayout string // "" (flat, default) or "directory" (Claude Code: skills/name/SKILL.md)
}

type Mount struct {
	HostPath      string
	ContainerPath string
	ReadOnly      bool
}

type PostApplyOpts struct {
	ContainerID string
}

type ResolvedClaw struct {
	ServiceName     string
	ImageRef        string
	ClawType        string
	Agent           string                            // filename from image labels (e.g., "AGENTS.md")
	AgentHostPath   string                            // resolved host path for bind mount
	Persona         string                            // runtime persona ref from x-claw or image metadata
	PersonaHostPath string                            // resolved host path for persona workspace mount
	Models          map[string]string                 // slot -> provider/model
	Handles         map[string]*HandleInfo            // platform -> contact card (from x-claw handles block)
	PeerHandles     map[string]map[string]*HandleInfo // service name -> platform -> HandleInfo for sibling services
	Includes        []ResolvedInclude                 // composed contract fragments from x-claw.include
	Feeds           []ResolvedFeed
	Surfaces        []ResolvedSurface
	Skills          []ResolvedSkill
	Privileges      map[string]string
	Configures      []string          // openclaw config set commands from labels
	Invocations     []Invocation      // scheduled agent tasks from image labels + pod x-claw.invoke
	Count           int               // from pod x-claw (default 1)
	Environment     map[string]string // from pod environment block
	Cllama          []string          // ordered cllama proxy types (e.g., ["passthrough"])
	CllamaToken     string            // per-agent bearer token injected when cllama is active
}

type ResolvedFeed struct {
	Name        string
	Source      string
	Path        string
	TTL         int
	Description string
}

type ResolvedInclude struct {
	ID          string
	Mode        string
	Description string
	HostPath    string
	SkillName   string // set for reference includes mounted into the skill directory
}

type ResolvedSkill struct {
	Name     string // basename (e.g., "custom-workflow.md")
	HostPath string // resolved absolute host path
}

type ResolvedSurface struct {
	Scheme        string              // channel, service, volume, host, egress
	Target        string              // discord, fleet-master, shared-cache, etc.
	AccessMode    string              // read-only, read-write (for volume/host surfaces)
	Ports         []string            // exposed ports from service definition (service surfaces only)
	SkillName     string              // mounted skill filename for this surface when one exists
	ServiceInfo   *ServiceSurfaceInfo // non-nil when a service surface has descriptor metadata
	ChannelConfig *ChannelConfig      // non-nil only for map-form channel surfaces
}

type ServiceEndpoint struct {
	Method      string
	Path        string
	Description string
}

type ServiceSurfaceInfo struct {
	Description string
	AuthType    string
	AuthEnv     string
	Endpoints   []ServiceEndpoint
}