sxvault

type Actor struct {
	// Name is the human-readable name used for git commit attribution by
	// OpenGit. The Sleuth backend (OpenSkillsNewWithOptions) ignores it and
	// identifies the actor solely by Email.
	Name string
	// Email identifies the actor for audit/identity context across both
	// backends. The git backend also uses it for commit attribution.
	Email string
}

type AgentResult struct {
	// BotKey is the one-time raw bot API token returned only when PutAgent
	// creates a new bot in a vault type that issues bot tokens. It is empty
	// when the bot already exists and for file-backed Git vaults.
	BotKey string
}

type AgentSpec struct {
	BotName   string
	AssetName string
	Version   string
	// Description is the agent asset's description, written into the asset
	// metadata.toml. It is separate from the bot's identity description —
	// publishing multiple agents on the same bot should give each its own
	// Description without rewriting the bot's identity each time.
	Description string
	// BotDescription, when non-empty, becomes the bot's description (on
	// create, or as an update when it differs from the stored value). Leave
	// empty to avoid rewriting an existing bot's description on every
	// publish; pre-create the bot via EnsureBot if you want bot identity
	// fully controlled outside the agent-publish path.
	BotDescription string
	Prompt         string
	// Skills lists existing vault skills to also install on BotName
	// alongside the agent. Each entry must refer to a skill (asset type
	// "skill") already present in the vault — PutAgent verifies this and
	// fails fast on missing names or on a name that resolves to a
	// different asset type. Empty entries are dropped and duplicates are
	// collapsed. Skills are installed on the bot but are NOT persisted
	// into the agent asset's metadata.toml; re-publishing the agent into
	// another vault requires re-supplying Skills.
	//
	// Semantics on re-publish are additive only. Re-publishing the same
	// agent with a shorter Skills list leaves the previously-installed
	// skills attached to BotName — PutAgent never uninstalls. To remove
	// a skill from a bot, call the uninstall path explicitly (out of
	// scope for this facade today).
	//
	// Cost note for git vaults: each skill install is a separate manifest
	// commit + push, so an agent with N skills produces roughly N+2
	// commits per PutAgent call. Keep skill lists modest or expect the
	// publish latency to grow linearly.
	Skills []string
}

type AssetSummary struct {
	Name          string
	Type          string
	LatestVersion string
	VersionsCount int
	Description   string
	// CreatedAt and UpdatedAt are the vault-recorded timestamps for the
	// asset's earliest and latest versions. They may be the zero value when
	// the underlying vault doesn't track timestamps for an entry.
	CreatedAt time.Time
	UpdatedAt time.Time
}

type Bot struct {
	Name string
	// Description is the bot's human-readable identity.
	//
	// On UPDATE (bot already exists): EnsureBot rewrites the stored
	// description only when Description is non-empty and differs from the
	// current value. An empty Description preserves whatever is stored
	// — useful for re-running EnsureBot from an agent-publish flow
	// without re-stamping identity.
	//
	// On CREATE (bot doesn't exist yet): EnsureBot writes Description
	// verbatim, so an empty Description produces a bot with no
	// description at all. Pre-seed identity with an explicit
	// EnsureBot(Bot{Name: ..., Description: "..."}) once before relying
	// on the "empty preserves" path.
	Description string
}

type BotRuntimeTokenResult struct {
	Token     string
	ExpiresAt time.Time
}

type BotRuntimeTokenSpec struct {
	BotName string
	// Label is stored with the short-lived runtime token for audit/display.
	// Empty is allowed and lets the backend apply its default label.
	Label string
	// TTLSeconds controls how long the runtime token is valid. Zero means
	// use the backend default. The Skills.new backend currently accepts
	// values from 60 seconds to 24 hours.
	TTLSeconds int
}

type BotSummary struct {
	Name        string
	Slug        string
	Description string
	Teams       []string
}

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

type GitOptions struct {
	// AuthToken authenticates HTTP(S) git remotes through basic auth. SSH
	// remotes ignore this value and use the caller's SSH configuration.
	// SSHKeyPath takes precedence: when both are set with an HTTP(S) URL,
	// the underlying git client rewrites the URL to SSH and AuthToken is
	// not used.
	AuthToken string

	// AuthUsername is the HTTP(S) basic-auth username to pair with AuthToken.
	// Empty uses a host-specific default, currently "x-access-token" except
	// gitlab.com / *.gitlab.com, which use "oauth2". Self-hosted GitLab
	// instances on custom domains are NOT auto-detected — set this to
	// "oauth2" explicitly when targeting one, or git authentication will
	// fail with the default "x-access-token".
	AuthUsername string

	// SSHKeyPath, when non-empty, points the underlying git client at this
	// SSH private key for SSH remotes. It bypasses the process-global SSH
	// key path set by the CLI's --ssh-key flag / SX_SSH_KEY env var, letting
	// library consumers scope SSH auth to a single Client.
	//
	// When set with an HTTP(S) URL, the git client rewrites the URL to SSH
	// at clone time and SSH key auth is what's used end-to-end —
	// AuthToken is ignored on that combination. buildGitClientOptions
	// drops the basic-auth env in this case so the resulting client carries
	// no inert/conflicting credentials.
	SSHKeyPath string

	Actor Actor
}

type ListOptions struct {
	// Type filters to a single asset-type key (e.g. "skill", "agent",
	// "mcp"). Empty returns every type.
	Type string
	// Search filters returned assets by a free-text query. Semantics
	// differ by backend: Git and Path vaults do a case-insensitive
	// substring match against the asset's name OR description; Sleuth
	// vaults pass the query to the backend's GraphQL search, which may
	// rank or fuzzy-match. Don't depend on exact ordering or scoring
	// across backends.
	Search string
	// Limit caps the number of returned assets. Zero or negative means
	// "backend default" — for Git and Path that is uncapped; for Sleuth
	// the backend silently caps at 50 regardless of the value passed,
	// so callers that need to enumerate every asset in a large Sleuth
	// vault need a different strategy (per-asset lookups) than this
	// list call provides today.
	Limit int
}

type PathOptions struct {
	// Actor identifies the caller for audit/identity context propagated
	// via mgmt.ContextWithIdentity. PathVault doesn't consult identity
	// directly today, but downstream audit / logging hooks read it
	// through actorContext on every method call.
	Actor Actor
}

type SkillZipSpec struct {
	Name    string
	Version string
	// Description overrides metadata.toml's skill description when non-empty.
	// Empty preserves any description already embedded in the uploaded zip.
	Description string
	ZipData     []byte
	// BotName, when non-empty, installs the published skill onto that bot
	// after the asset upload completes. Leave empty to publish the skill
	// without attaching it to any bot.
	BotName string
}

type SkillsNewOptions struct {
	// AuthToken is the bearer token sent on every Sleuth API request.
	// Required — OpenSkillsNewWithOptions returns an error when empty.
	// There is no host-specific default (unlike GitOptions.AuthUsername),
	// because Sleuth endpoints accept exactly one credential shape.
	AuthToken string
	// Actor identifies the caller for audit/identity context propagated
	// via mgmt.ContextWithIdentity. Only Actor.Email is consumed on the
	// Sleuth path — Actor.Name is ignored here (see Actor.Name doc).
	Actor Actor
}