durable

type AgentSpec struct {
	Name string
	// Options is the canonical agent definition. SessionID and MountSession
	// must be empty; the runtime injects those per turn.
	Options tacklr.AgentOptions
	// OpenVFS builds the agent /workspace tree (typically vfs.Tree). Nil means no VFS.
	OpenVFS vfs.OpenVFS
	// OpenSkills builds a host-only skills tree (typically vfs.Tree with
	// Union of packs). The agent MountSession never includes this tree.
	// Nil means no skills unless Options.SkillsLoader is set.
	OpenSkills vfs.OpenVFS
	// SkillsRoot is the virtual directory the loader walks on the skills
	// session. Empty means /workspace/skills.
	SkillsRoot string
}

type AuthContext struct {
	// Bindings are this slice's mounts and/or provider tokens. A binding with
	// an alias upserts the recipe. A binding with only provider+token refreshes
	// every cached recipe for that provider.
	Bindings []vfs.Binding `json:"bindings,omitempty"`
	// Drop removes cached recipes by alias or provider. Applied before Bindings.
	Drop []string `json:"drop,omitempty"`
}

type Catalog interface {
	Lookup(agentID string) (AgentSpec, bool)
	DefaultID() string
	IDs() []string
}

type CreateSession struct {
	AgentID    string
	SessionID  SessionID
	MCPServers []mcp.MCPConfig
	// Mounts seeds the session recipe cache (no secrets). Tokens arrive on Prompt.
	Mounts []MountRecipe
	// Parent, when set, makes this a child session of that parent. The child
	// reuses the same wait loop. Empty MCPServers/Mounts inherit from parent.
	Parent SessionID
	// Specialist selects a Specialist from the parent's catalog spec. Required
	// with Parent for spawn_specialist children. The host does not register the
	// worker as a top-level catalog agent.
	Specialist string
	// State seeds checkpoint userState (JSON-serializable values).
	// Tools read it via HarnessRuntime.StateGet. Canonical copy is
	// Snapshot.Checkpoint, not Temporal workflow variables. No tokens or clients.
	// Child sessions do not inherit this map.
	State map[string]any
}

type EventLog interface {
	Append(ctx context.Context, sessionID SessionID, topic string, ev tacklr.StreamEvent) error
	Subscribe(ctx context.Context, sessionID SessionID, after Seq) (<-chan tacklr.StreamEvent, error)
	Head(ctx context.Context, sessionID SessionID) (Seq, error)
	CloseSession(ctx context.Context, sessionID SessionID) error
}

type MemoryCatalog struct {
	// contains filtered or unexported fields
}

type MemorySecretStorage struct {
	// contains filtered or unexported fields
}

type MountRecipe struct {
	Provider  string            `json:"provider"`
	Alias     string            `json:"alias"`
	Params    map[string]string `json:"params,omitempty"`
	SourceIDs []string          `json:"sourceIds,omitempty"`
	Writable  bool              `json:"writable,omitempty"`
}

type Prompt struct {
	Text        string
	UserMessage *tacklr.Message
	// AgentID, when set, selects the catalog agent for this turn slice.
	AgentID string
	// MCPServers, when non-nil, replaces session-scoped MCP configs for this turn.
	MCPServers []mcp.MCPConfig
	Auth       AuthContext
	// State merges into checkpoint userState for this turn after restore.
	// JSON-serializable values only. No tokens or clients.
	State map[string]any
}

type Resume struct {
	Responses map[string][]byte
	Auth      AuthContext
	// State merges into checkpoint userState when the parked turn continues.
	State map[string]any
}

type Revision string

type Runtime interface {
	CreateSession(ctx context.Context, req CreateSession) (SessionID, error)
	Prompt(ctx context.Context, sessionID SessionID, msg Prompt) error
	Resume(ctx context.Context, sessionID SessionID, resume Resume) error
	// Cancel aborts the in-flight turn and stops child sessions. The parent
	// session stays open for a later Prompt. Client stop (session/cancel and
	// cancelling the original Prompt/Resume context) uses this.
	Cancel(ctx context.Context, sessionID SessionID) error
	// Close destroys the session and recursively stops children.
	Close(ctx context.Context, sessionID SessionID) error
	// Head is the current EventLog offset. Protocol pumps pass it to Subscribe
	// to tail from now (skip events from prior turns).
	Head(ctx context.Context, sessionID SessionID) (Seq, error)
	Subscribe(ctx context.Context, sessionID SessionID, after Seq) (Subscription, error)
	// Children returns child session ids of parent, in start order.
	Children(ctx context.Context, parent SessionID) ([]SessionID, error)
	// Status is running, complete, failed, or unknown. A child waiting on HITL
	// stays running until that interrupt is resolved.
	Status(ctx context.Context, id SessionID) (SessionStatus, error)
}

type SecretStorage interface {
	// Put replaces Auth when secrets.Auth.Bindings is non-empty.
	// Empty Bindings (including drop-only) is a no-op on the bag.
	Put(ctx context.Context, sessionID SessionID, secrets Secrets) error
	// Get returns the last Put bag. Missing session: zero Secrets, nil error.
	Get(ctx context.Context, sessionID SessionID) (Secrets, error)
	Delete(ctx context.Context, sessionID SessionID) error
}

type Secrets struct {
	Auth AuthContext
}

type Seq uint64

type SessionID string

type SessionState string

type SessionStatus struct {
	ID         SessionID
	Parent     SessionID
	State      SessionState
	Specialist string
	Kind       string
	Result     string
	Err        error
	// Waiting is true while the session is parked for HITL. Parent-facing
	// State stays running until that interrupt is resolved.
	Waiting bool
}

type Snapshot struct {
	AgentID    string
	Specialist string
	Parent     SessionID
	// Children are child session ids in start order (no handles, no tokens).
	Children   []SessionID
	Checkpoint tacklr.SessionCheckpoint
	Mounts     []MountRecipe
}

type SnapshotStore interface {
	Save(ctx context.Context, sessionID SessionID, snap Snapshot, expected Revision) (Revision, error)
	Load(ctx context.Context, sessionID SessionID) (Snapshot, Revision, error)
	Delete(ctx context.Context, sessionID SessionID) error
}

type Subscription interface {
	Events() <-chan tacklr.StreamEvent
	Close() error
}