driver

type ChannelConfig struct {
	Guilds map[string]ChannelGuildConfig // guild ID → routing config
	DM     ChannelDMConfig
}

type ChannelDMConfig struct {
	Enabled   bool
	Policy    string   // "allowlist", "denylist", or ""
	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 {
	Schedule string // 5-field cron expression (e.g., "15 8 * * 1-5")
	Message  string // agent task payload (agentTurn message)
	To       string // Discord channel ID for delivery (empty = openclaw uses last channel)
	Name     string // human-readable job name (optional, derived from message if empty)
}

type MaterializeOpts struct {
	RuntimeDir string // host directory for generated artifacts
	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
	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
	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 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)
	ChannelConfig *ChannelConfig // non-nil only for map-form channel surfaces
}