spec

type AllSkillBundles struct {
	Bundles map[bundleitemutils.BundleID]SkillBundle `json:"bundles"`
}

type CloseSkillSessionRequest struct {
	SessionID agentskillsSpec.SessionID `path:"sessionID" required:"true"`
}

type CloseSkillSessionResponse struct{}

type CreateSkillSessionRequest struct {
	Body *CreateSkillSessionRequestBody
}

type CreateSkillSessionRequestBody struct {
	// Optional: close this previous session (best-effort) before creating a new one.
	CloseSessionID agentskillsSpec.SessionID `json:"closeSessionID,omitempty"`

	MaxActivePerSession int        `json:"maxActivePerSession,omitempty"`
	AllowSkillRefs      []SkillRef `json:"allowSkillRefs,omitempty"`  // enabled allowlist (store ids)
	ActiveSkillRefs     []SkillRef `json:"activeSkillRefs,omitempty"` // desired initial active (subset of allowlist)
}

type CreateSkillSessionResponse struct {
	Body *CreateSkillSessionResponseBody
}

type CreateSkillSessionResponseBody struct {
	SessionID       agentskillsSpec.SessionID `json:"sessionID"`
	ActiveSkillRefs []SkillRef                `json:"activeSkillRefs"`
}

type DeleteSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
}

type DeleteSkillBundleResponse struct{}

type DeleteSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
}

type DeleteSkillResponse struct{}

type GetSkillRequest struct {
	BundleID        bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug       SkillSlug                `path:"skillSlug" required:"true"`
	IncludeDisabled bool                     `                                 query:"includeDisabled"`
}

type GetSkillResponse struct{ Body *Skill }

type GetSkillsPromptRequest struct {
	Body *GetSkillsPromptRequestBody
}

type GetSkillsPromptRequestBody struct {
	Filter *RuntimeSkillFilter `json:"filter,omitempty"`
}

type GetSkillsPromptResponse struct {
	Body *GetSkillsPromptResponseBody
}

type GetSkillsPromptResponseBody struct {
	Prompt string `json:"prompt"`
}

type InvokeSkillToolRequest struct {
	Body *InvokeSkillToolRequestBody
}

type InvokeSkillToolRequestBody struct {
	SessionID agentskillsSpec.SessionID `json:"sessionID"      required:"true"`
	ToolName  string                    `json:"toolName"       required:"true"` // "skills-load" | "skills-unload" | "skills-readresource" | "skills-runscript"
	Args      JSONRawString             `json:"args,omitempty"`                 // JSON object string
}

type InvokeSkillToolResponse struct {
	Body *InvokeSkillToolResponseBody
}

type InvokeSkillToolResponseBody struct {
	Outputs      []llmtoolsSpec.ToolOutputUnion `json:"outputs,omitempty"`
	Meta         map[string]any                 `json:"meta,omitempty"`
	IsBuiltIn    bool                           `json:"isBuiltIn"`
	IsError      bool                           `json:"isError,omitempty"`
	ErrorMessage string                         `json:"errorMessage,omitempty"`
}

type JSONRawString = string

type ListRuntimeSkillsRequest struct {
	Body *ListRuntimeSkillsRequestBody
}

type ListRuntimeSkillsRequestBody struct {
	Filter *RuntimeSkillFilter `json:"filter,omitempty"`
}

type ListRuntimeSkillsResponse struct {
	Body *ListRuntimeSkillsResponseBody
}

type ListRuntimeSkillsResponseBody struct {
	Skills []RuntimeSkillListItem `json:"skills"`
}

type ListSkillBundlesRequest struct {
	BundleIDs       []bundleitemutils.BundleID `query:"bundleIDs"`
	IncludeDisabled bool                       `query:"includeDisabled"`
	PageSize        int                        `query:"pageSize"`
	PageToken       string                     `query:"pageToken"`
}

type ListSkillBundlesResponse struct {
	Body *ListSkillBundlesResponseBody
}

type ListSkillBundlesResponseBody struct {
	SkillBundles  []SkillBundle `json:"skillBundles"`
	NextPageToken *string       `json:"nextPageToken,omitempty"`
}

type ListSkillPhase string

type ListSkillsRequest struct {
	BundleIDs           []bundleitemutils.BundleID    `query:"bundleIDs"`
	Types               []SkillType                   `query:"types"`
	Inserts             []agentskillsSpec.SkillInsert `query:"inserts"`
	Tags                []string                      `query:"tags"`
	IncludeDisabled     bool                          `query:"includeDisabled"`
	IncludeMissing      bool                          `query:"includeMissing"`
	RecommendedPageSize int                           `query:"recommendedPageSize"`
	PageToken           string                        `query:"pageToken"`
}

type ListSkillsResponse struct {
	Body *ListSkillsResponseBody
}

type ListSkillsResponseBody struct {
	SkillListItems []SkillListItem `json:"skillListItems"`
	NextPageToken  *string         `json:"nextPageToken,omitempty"`
}

type PatchSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
	Body     *PatchSkillBundleRequestBody
}

type PatchSkillBundleRequestBody struct {
	IsEnabled bool `json:"isEnabled" required:"true"`
}

type PatchSkillBundleResponse struct{}

type PatchSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PatchSkillRequestBody
}

type PatchSkillRequestBody struct {
	// Built-in skills: only IsEnabled is supported.
	// User skills: IsEnabled, Location, and metadata fields are supported.
	IsEnabled   *bool     `json:"isEnabled,omitempty"`
	Location    *string   `json:"location,omitempty"`
	DisplayName *string   `json:"displayName,omitempty"`
	Description *string   `json:"description,omitempty"`
	Tags        *[]string `json:"tags,omitempty"` // pointer so caller can send [] to clear
}

type PatchSkillResponse struct{}

type PutSkillArtifactRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PutSkillArtifactRequestBody
}

type PutSkillArtifactRequestBody struct {
	// Name is the Agent Skills artifact name. If empty, SkillSlug is used.
	// For filesystem skills, this is also used as the managed directory name.
	Name string `json:"name,omitempty"`

	IsEnabled bool `json:"isEnabled" required:"true"`

	DisplayName string `json:"displayName,omitempty"`
	Description string `json:"description,omitempty"`

	// Insert defaults to instructions.
	Insert agentskillsSpec.SkillInsert `json:"insert,omitempty"`

	Arguments []agentskillsSpec.SkillArgument `json:"arguments,omitempty"`
	Tags      []string                        `json:"tags,omitempty"`

	// MarkdownBody is written after YAML frontmatter in SKILL.md.
	MarkdownBody string `json:"markdownBody" required:"true"`
}

type PutSkillArtifactResponse struct{ Body *PutSkillArtifactResponseBody }

type PutSkillArtifactResponseBody struct {
	Skill Skill `json:"skill"`
}

type PutSkillBundleRequest struct {
	BundleID bundleitemutils.BundleID `path:"bundleID" required:"true"`
	Body     *PutSkillBundleRequestBody
}

type PutSkillBundleRequestBody struct {
	Slug        bundleitemutils.BundleSlug `json:"slug"                  required:"true"`
	DisplayName string                     `json:"displayName"           required:"true"`
	IsEnabled   bool                       `json:"isEnabled"             required:"true"`
	Description string                     `json:"description,omitempty"`
}

type PutSkillBundleResponse struct{}

type PutSkillRequest struct {
	BundleID  bundleitemutils.BundleID `path:"bundleID"  required:"true"`
	SkillSlug SkillSlug                `path:"skillSlug" required:"true"`
	Body      *PutSkillRequestBody
}

type PutSkillRequestBody struct {
	SkillType SkillType `json:"skillType" required:"true"`
	Location  string    `json:"location"  required:"true"`
	Name      string    `json:"name"      required:"true"`
	IsEnabled bool      `json:"isEnabled" required:"true"`

	DisplayName string   `json:"displayName,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`
}

type PutSkillResponse struct{}

type RenderSkillRequest struct {
	Body *RenderSkillRequestBody
}

type RenderSkillRequestBody struct {
	SkillRef  SkillRef          `json:"skillRef"            required:"true"`
	Arguments map[string]string `json:"arguments,omitempty"`
}

type RenderSkillResponse struct {
	Body *RenderSkillResponseBody
}

type RenderSkillResponseBody struct {
	Text string `json:"text"`

	Insert agentskillsSpec.SkillInsert `json:"insert"`

	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	DisplayName string `json:"displayName,omitempty"`

	Resources agentskillsSpec.SkillResourceInfo `json:"resources"`

	Arguments        []agentskillsSpec.SkillArgument `json:"arguments,omitempty"`
	AppliedArguments map[string]string               `json:"appliedArguments,omitempty"`
	RawFrontmatter   map[string]any                  `json:"rawFrontmatter,omitempty"`
	Warnings         []string                        `json:"warnings,omitempty"`
}

type RuntimeSkillFilter struct {
	Types          []string                      `json:"types,omitempty"`
	Inserts        []agentskillsSpec.SkillInsert `json:"inserts,omitempty"`
	LocationPrefix string                        `json:"locationPrefix,omitempty"`
	AllowSkillRefs []SkillRef                    `json:"allowSkillRefs,omitempty"`

	SessionID agentskillsSpec.SessionID     `json:"sessionID,omitempty"`
	Activity  agentskillsSpec.SkillActivity `json:"activity,omitempty"`
}

type RuntimeSkillListItem struct {
	SkillRef SkillRef `json:"skillRef"`

	// Copy of the runtime-facing identity fields (excluding Location) + runtime-indexed metadata.
	// These are read-only and exist only for display/debug.
	Type        string `json:"type,omitempty"`
	Name        string `json:"name,omitempty"`
	DisplayName string `json:"displayName,omitempty"`
	Description string `json:"description,omitempty"`
	Digest      string `json:"digest,omitempty"`

	Insert         agentskillsSpec.SkillInsert       `json:"insert,omitempty"`
	Arguments      []agentskillsSpec.SkillArgument   `json:"arguments,omitempty"`
	Resources      agentskillsSpec.SkillResourceInfo `json:"resources"`
	RawFrontmatter map[string]any                    `json:"rawFrontmatter,omitempty"`
	Warnings       []string                          `json:"warnings,omitempty"`

	// Session-scoped.
	IsActive bool `json:"isActive,omitempty"`

	// Runtime/provider error (if any) for this skill record.
	ErrorMessage string `json:"errorMessage,omitempty"`
}

type Skill struct {
	SchemaVersion string    `json:"schemaVersion"`
	ID            SkillID   `json:"id"`   // UUID-v7
	Slug          SkillSlug `json:"slug"` // unique slug identifier

	Type     SkillType `json:"type"`
	Location string    `json:"location"` // opaque provider/app location; user-created fs skills usually use an absolute base dir.
	Name     string    `json:"name"`     // name of the skill inside SKILL.md.

	DisplayName string   `json:"displayName,omitempty"`
	Description string   `json:"description,omitempty"`
	Tags        []string `json:"tags,omitempty"`

	// Parsed from SKILL.md frontmatter field "insert".
	// Missing/empty defaults to "instructions".
	Insert SkillInsert `json:"insert,omitempty"`

	// Parsed from SKILL.md frontmatter field "arguments".
	Arguments []SkillArgument `json:"arguments,omitempty"`

	// Runtime/provider-indexed resource metadata. Locations are provider-defined
	// values intended for use with skills-readresource.resourceLocation.
	Resources SkillResourceInfo `json:"resources"`

	// Full parsed YAML frontmatter. FlexiGPT only gives semantics to name,
	// description, insert, and arguments; other fields are preserved for callers.
	RawFrontmatter map[string]any `json:"rawFrontmatter,omitempty"`

	// Runtime/provider indexing metadata.
	RuntimeWarnings []string `json:"runtimeWarnings,omitempty"`
	Digest          string   `json:"digest,omitempty"`

	Presence *SkillPresence `json:"presence,omitempty"`

	IsEnabled bool `json:"isEnabled"`
	IsBuiltIn bool `json:"isBuiltIn"`

	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`
}

type SkillArgument = agentskillsSpec.SkillArgument

type SkillBundle struct {
	SchemaVersion string          `json:"schemaVersion"`
	ID            SkillBundleID   `json:"id"` // UUID-v7
	Slug          SkillBundleSlug `json:"slug"`

	DisplayName string `json:"displayName,omitempty"`
	Description string `json:"description,omitempty"`

	IsEnabled  bool      `json:"isEnabled"`
	IsBuiltIn  bool      `json:"isBuiltIn"`
	CreatedAt  time.Time `json:"createdAt"`
	ModifiedAt time.Time `json:"modifiedAt"`

	SoftDeletedAt *time.Time `json:"softDeletedAt,omitempty"`
}

type SkillBundleID = bundleitemutils.BundleID

type SkillBundlePageToken struct {
	BundleIDs       []bundleitemutils.BundleID `json:"ids,omitempty"` //nolint:tagliatelle // Page Token specific. // optional filter
	IncludeDisabled bool                       `json:"d,omitempty"`   //nolint:tagliatelle // Page Token specific.
	PageSize        int                        `json:"s"`             //nolint:tagliatelle // Page Token specific.
	CursorMod       string                     `json:"t,omitempty"`   //nolint:tagliatelle // Page Token specific.// RFC-3339-nano modifiedAt
	CursorID        bundleitemutils.BundleID   `json:"id,omitempty"`  //nolint:tagliatelle // Page Token specific.// tie-breaker
}

type SkillBundleSlug = bundleitemutils.BundleSlug

type SkillID = bundleitemutils.ItemID

type SkillInsert = agentskillsSpec.SkillInsert

type SkillListItem struct {
	BundleID   bundleitemutils.BundleID   `json:"bundleID"`
	BundleSlug bundleitemutils.BundleSlug `json:"bundleSlug"`

	SkillSlug SkillSlug `json:"skillSlug"`
	IsBuiltIn bool      `json:"isBuiltIn"`

	SkillDefinition Skill `json:"skillDefinition"`
}

type SkillPageToken struct {
	RecommendedPageSize int                           `json:"ps,omitempty"`   //nolint:tagliatelle // Page token specific.
	IncludeDisabled     bool                          `json:"d,omitempty"`    //nolint:tagliatelle // Page token specific.
	IncludeMissing      bool                          `json:"m,omitempty"`    //nolint:tagliatelle // Page token specific. // include presence=missing?
	BundleIDs           []bundleitemutils.BundleID    `json:"ids,omitempty"`  //nolint:tagliatelle // Page token specific. // optional filter
	Types               []SkillType                   `json:"ty,omitempty"`   //nolint:tagliatelle // Page token specific. // optional filter
	Inserts             []agentskillsSpec.SkillInsert `json:"in,omitempty"`   //nolint:tagliatelle // Page token specific.
	Tags                []string                      `json:"tags,omitempty"` //nolint:tagliatelle // Page token specific.
	Phase               ListSkillPhase                `json:"ph,omitempty"`   //nolint:tagliatelle //nolint:tagliatelle // Page token specific.
	BuiltInCursor       string                        `json:"bc,omitempty"`   //nolint:tagliatelle // opaque: last (bundleID|skillSlug)
	DirTok              string                        `json:"dt,omitempty"`   //nolint:tagliatelle // user cursor
}

type SkillPresence struct {
	Status SkillPresenceStatus `json:"status"`

	// LastCheckedAt is when we last attempted to validate presence.
	LastCheckedAt *time.Time `json:"lastCheckedAt,omitempty"`

	// LastSeenAt is when the location was last confirmed present.
	LastSeenAt *time.Time `json:"lastSeenAt,omitempty"`

	// MissingSince is set when we transition into "missing".
	MissingSince *time.Time `json:"missingSince,omitempty"`

	// LastCheckError is only meaningful when Status == "error".
	LastCheckError string `json:"lastCheckError,omitempty"`
}

type SkillPresenceStatus string

type SkillRef struct {
	BundleID  SkillBundleID `json:"bundleID"`
	SkillSlug SkillSlug     `json:"skillSlug"`
	SkillID   SkillID       `json:"skillID"`
}

type SkillResourceInfo = agentskillsSpec.SkillResourceInfo

type SkillSelection struct {
	SkillRef          SkillRef `json:"skillRef"`
	PreLoadAsActive   bool     `json:"preLoadAsActive"`
	UseAsInstructions bool     `json:"useAsInstructions"`
}

type SkillSlug = bundleitemutils.ItemSlug

type SkillType string