sessionoverlay

type Overlay struct {
	// UserPrompt is the session's user-instruction prompt layer. It composes
	// ABOVE the admin base in the lower-trust `<user_instructions>` position
	// (escaped); it can extend the operator's guidance but never precede,
	// replace, or weaken the operator base. There is intentionally NO Base
	// field — a session caller cannot write the operator base.
	UserPrompt string `json:"user_prompt,omitempty"`
	// DisabledServers names MCP servers the session has DISABLED. At
	// projection these are UNIONED into the admin exclusion set (the session
	// can only ADD to the disabled set, never remove an admin exclusion) — so
	// the result can only ever NARROW the admin-allowed exposure.
	DisabledServers []string `json:"disabled_servers,omitempty"`
	// DisabledTools names tools the session has DISABLED. Unioned into the
	// admin exclusion set at projection (narrow-only).
	DisabledTools []string `json:"disabled_tools,omitempty"`
	// PersonalSkills names the session's ephemeral personal skills (the
	// bodies live in the session-scoped SkillStore under the same triple).
	// They are added back to the session's skill view at projection and
	// never promote to the agent/tenant scope.
	PersonalSkills []string `json:"personal_skills,omitempty"`
}

type Store interface {
	// Get returns the session's overlay for the agent and whether one exists.
	// No overlay returns (zero, false, nil).
	Get(ctx context.Context, id identity.Quadruple, agentID string) (Overlay, bool, error)
	// SetUserPrompt sets ONLY the user prompt layer, preserving the disable
	// set + personal skills. An empty prompt clears the user layer.
	SetUserPrompt(ctx context.Context, id identity.Quadruple, agentID, prompt string) (Overlay, error)
	// SetSourceDisables replaces the narrow-only DISABLE set (servers +
	// tools), preserving the user prompt + personal skills. There is no
	// "enable" — the set names what the session wants OFF; the projection
	// unions it into the admin exclusion set, so it can only narrow.
	SetSourceDisables(ctx context.Context, id identity.Quadruple, agentID string, servers, tools []string) (Overlay, error)
	// AddPersonalSkill records a personal-skill name (idempotent), preserving
	// every other field.
	AddPersonalSkill(ctx context.Context, id identity.Quadruple, agentID, name string) (Overlay, error)
	// RemovePersonalSkill removes a personal-skill name (idempotent),
	// preserving every other field.
	RemovePersonalSkill(ctx context.Context, id identity.Quadruple, agentID, name string) (Overlay, error)
	// Close releases resources. Idempotent.
	Close(ctx context.Context) error
}