spec

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"`
	ActiveSkillRefs     []SkillRef `json:"activeSkillRefs,omitempty"`

	// Workspace scopes Artifact-based Skill references in this session.
	// Installed Skill references remain valid without this field.
	Workspace *collection.CollectionRef `json:"workspace,omitempty"`
}

type CreateSkillSessionResponse struct {
	Body *CreateSkillSessionResponseBody
}

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

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 RenderSkillRequest struct {
	Body *RenderSkillRequestBody
}

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

	// Workspace is required when SkillRef.Artifact is present and prevents an
	// ArtifactRef from being resolved outside its selected Workspace.
	Workspace *collection.CollectionRef `json:"workspace,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"`

	// SourceTags are tags parsed from SKILL.md frontmatter.
	SourceTags []string `json:"sourceTags,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"`

	// Workspace scopes Artifact-based Skill references. It is required when
	// AllowSkillRefs contains one or more Workspace Artifact references.
	Workspace *collection.CollectionRef `json:"workspace,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"`
	// SourceTags are tags parsed from SKILL.md frontmatter.
	SourceTags     []string                          `json:"sourceTags,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 SkillRef struct {
	Artifact  *artifact.ArtifactRef        `json:"artifact,omitempty"`
	BundleID  skillstoreSpec.SkillBundleID `json:"bundleID,omitempty"`
	SkillSlug skillstoreSpec.SkillSlug     `json:"skillSlug,omitempty"`
	SkillID   skillstoreSpec.SkillID       `json:"skillID,omitempty"`
}