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 DirectTurnWaker interface {
	WakeHelper() string
	InvocationTimeoutSeconds(*ResolvedClaw) (int, error)
}

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 {
	StartPeriod string
	Test        []string
	Interval    string
	Timeout     string
	Retries     int
}

type HermesConfig struct {
	AllowTools  []string
	AllowSilent bool
}

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)
	Channel  string           `json:"channel,omitempty"` // resolved delivery platform
	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
	User            string            // optional compose user override (lower priority than explicit compose user)
	Healthcheck     *Healthcheck
	ReadOnly        bool   // default: true
	Restart         string // default: "on-failure"
	StopGracePeriod string // optional driver default; explicit compose value wins
	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
	HostPathByService map[string]string // optional host path override keyed by emitted compose service name
	ContainerPath     string
	ReadOnly          bool
}

type OpenRouterPreferences struct {
	Only              []string
	ZDR               *bool  // true only
	AllowFallbacks    *bool  // false only
	RequireParameters *bool  // true only
	DataCollection    string // "deny" only
}

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
	ReasoningEffort map[string]string                 // slot -> per-run reasoning effort (x-claw.reasoning-effort)
	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
	RuntimeEnv      map[string]string // compose interpolation context: pod .env plus process env
	Timezone        string            // resolved service timezone from TZ env (falls back to UTC)
	Cllama          []string          // ordered cllama proxy types (e.g., ["passthrough"])
	CllamaToken     string            // per-agent bearer token injected when cllama is active
	Hermes          *HermesConfig     // Hermes-specific pod config

	// ProviderPreferences maps an openrouter/* model slot to the OpenRouter
	// routing preferences a per-run worker sends (x-claw.provider-preferences).
	ProviderPreferences map[string]*OpenRouterPreferences
}

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 RunResultContract struct {
	// Source is "stdout".
	Source string `json:"source"`
	// Marker, when set, starts the answer: the answer is everything after the
	// first occurrence of Marker in the stream, minus one trailing newline.
	Marker string `json:"marker,omitempty"`
}

type RunWorkerCompiler interface {
	ValidateRunWorker(rc *ResolvedClaw) error
	CompileRunWorker(rc *ResolvedClaw, opts RunWorkerOpts) (*RunWorkerSpec, error)
}

type RunWorkerOpts struct {
	PodName string
}

type RunWorkerSpec struct {
	// Entrypoint and Command are pinned; the image ENTRYPOINT is overridden.
	// Command elements may reference inputs as ${NAME} Compose interpolations.
	Entrypoint []string `json:"entrypoint"`
	Command    []string `json:"command,omitempty"`
	// Environment holds static, non-secret container env.
	Environment map[string]string `json:"environment,omitempty"`
	// Inputs maps a container env name to a value template. Templates may embed
	// run placeholders. Inputs are interpolated, never written to disk.
	Inputs map[string]string `json:"inputs"`
	// Tmpfs mounts are the only writable paths; the root filesystem is read-only.
	Tmpfs []string `json:"tmpfs"`
	// Result describes where the worker reports its answer.
	Result RunResultContract `json:"result"`
}

type RunnerBaseProvider interface {
	BaseImageProvider
	RunnerAlias() string
}

type RunnerVersionProber interface {
	RunnerVersionProbe() []string
}

type ServiceEndpoint struct {
	Method      string
	Path        string
	Description string
}

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