spec

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

type BundlePageToken struct {
	BundleIDs       []bundleitemutils.BundleID `json:"ids,omitempty"` // Optional bundle-ID filter.
	IncludeDisabled bool                       `json:"d,omitempty"`   // Include disabled bundles?
	PageSize        int                        `json:"s"`             // Requested page-size.
	CursorMod       string                     `json:"t,omitempty"`   // RFC-3339-nano modification timestamp.
	CursorID        bundleitemutils.BundleID   `json:"id,omitempty"`  // Tie-breaker for equal timestamps.
}

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

type DeleteToolBundleResponse struct{}

type DeleteToolRequest struct {
	BundleID bundleitemutils.BundleID    `path:"bundleID" required:"true"`
	ToolSlug bundleitemutils.ItemSlug    `path:"toolSlug" required:"true"`
	Version  bundleitemutils.ItemVersion `path:"version"  required:"true"`
}

type DeleteToolResponse struct{}

type GetToolRequest struct {
	BundleID bundleitemutils.BundleID    `path:"bundleID" required:"true"`
	ToolSlug bundleitemutils.ItemSlug    `path:"toolSlug" required:"true"`
	Version  bundleitemutils.ItemVersion `path:"version"  required:"true"`
}

type GetToolResponse struct{ Body *Tool }

type GoToolImpl struct {
	// Fully-qualified registration key, e.g.
	//   "github.com/acme/flexigpt/tools.Weather"
	Func string `json:"func" validate:"required"`
}

type HTTPAuth struct {
	Type          string `json:"type"`
	In            string `json:"in,omitempty"`   // "header" | "query"  (apiKey only)
	Name          string `json:"name,omitempty"` // header/query key
	ValueTemplate string `json:"valueTemplate"`  // may contain ${SECRET}
}

type HTTPBodyOutputMode string

type HTTPRequest struct {
	Method      string            `json:"method,omitempty"`    // default "GET"
	URLTemplate string            `json:"urlTemplate"`         // http(s)://… may contain ${var}
	Query       map[string]string `json:"query,omitempty"`     // k:${var}
	Headers     map[string]string `json:"headers,omitempty"`   // k:${var}
	Body        string            `json:"body,omitempty"`      // raw or template
	Auth        *HTTPAuth         `json:"auth,omitempty"`      // see below
	TimeoutMs   int               `json:"timeoutMs,omitempty"` // default 10 000
}

type HTTPResponse struct {
	SuccessCodes   []int              `json:"successCodes,omitempty"` // default: any 2xx
	ErrorMode      string             `json:"errorMode,omitempty"`    // "fail"(dflt) | "empty"
	BodyOutputMode HTTPBodyOutputMode `json:"bodyOutputMode,omitempty"`
}

type HTTPToolImpl struct {
	Request  HTTPRequest  `json:"request"`
	Response HTTPResponse `json:"response"`
}

type ImageDetail string

type InvokeGoOptions struct {
	// Overrides the tool invocation timeout (in milliseconds). Optional.
	TimeoutMs int `json:"timeoutMs,omitempty"`
}

type InvokeHTTPOptions struct {
	// Overrides the tool-level HTTP timeout (in milliseconds). Optional.
	TimeoutMs int `json:"timeoutMs,omitempty"`
	// ExtraHeaders will be merged into the outgoing request headers (taking precedence).
	ExtraHeaders map[string]string `json:"extraHeaders,omitempty"`
	// Secrets are key->value mappings used for template substitution in HTTP request
	// components (e.g. ${SECRET}). Optional.
	Secrets map[string]string `json:"secrets,omitempty"`
}

type InvokeToolRequest struct {
	BundleID bundleitemutils.BundleID    `path:"bundleID" required:"true"`
	ToolSlug bundleitemutils.ItemSlug    `path:"toolSlug" required:"true"`
	Version  bundleitemutils.ItemVersion `path:"version"  required:"true"`
	Body     *InvokeToolRequestBody
}

type InvokeToolRequestBody struct {
	// Arguments passed to the tool. Must be JSON-serializable.
	Args JSONRawString `json:"args" required:"true"`
	// Tool-type-specific options (only one of these is used depending on the tool type).
	HTTPOptions *InvokeHTTPOptions `json:"httpOptions,omitempty"`
	GoOptions   *InvokeGoOptions   `json:"goOptions,omitempty"`
}

type InvokeToolResponse struct {
	Body *InvokeToolResponseBody
}

type InvokeToolResponseBody struct {
	// Output is the JSON-serializable result produced by the tool. Its shape depends on
	// the tool definition.
	Outputs []ToolStoreOutputUnion `json:"outputs,omitempty"`
	// Meta contains implementation-specific metadata (e.g., HTTP status, duration, etc.).
	Meta map[string]any `json:"meta,omitempty"`
	// True if the tool was served from the built-in data overlay.
	IsBuiltIn bool `json:"isBuiltIn"`

	// True if the tool itself reported an error during execution.
	// When true, Output may be empty or contain a tool-specific error payload.
	IsError bool `json:"isError,omitzero"`
	// ErrorMessage contains the error message returned by the tool, if any.
	// This is set when IsError is true.
	ErrorMessage string `json:"errorMessage,omitzero"`
}

type JSONRawString = string

type JSONSchema = json.RawMessage

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

type ListToolBundlesResponse struct {
	Body *ListToolBundlesResponseBody
}

type ListToolBundlesResponseBody struct {
	ToolBundles   []ToolBundle `json:"toolBundles"`
	NextPageToken *string      `json:"nextPageToken,omitempty"`
}

type ListToolsRequest struct {
	BundleIDs           []bundleitemutils.BundleID `query:"bundleIDs"`
	Tags                []string                   `query:"tags"`
	IncludeDisabled     bool                       `query:"includeDisabled"`
	RecommendedPageSize int                        `query:"recommendedPageSize"`
	PageToken           string                     `query:"pageToken"`
}

type ListToolsResponse struct {
	Body *ListToolsResponseBody
}

type ListToolsResponseBody struct {
	ToolListItems []ToolListItem `json:"toolListItems"`
	NextPageToken *string        `json:"nextPageToken,omitempty"`
}

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

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

type PatchToolBundleResponse struct{}

type PatchToolRequest struct {
	BundleID bundleitemutils.BundleID    `path:"bundleID" required:"true"`
	ToolSlug bundleitemutils.ItemSlug    `path:"toolSlug" required:"true"`
	Version  bundleitemutils.ItemVersion `path:"version"  required:"true"`

	Body *PatchToolRequestBody
}

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

type PatchToolResponse struct{}

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

type PutToolBundleRequestBody 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 PutToolBundleResponse struct{}

type PutToolRequest struct {
	BundleID bundleitemutils.BundleID    `path:"bundleID" required:"true"`
	ToolSlug bundleitemutils.ItemSlug    `path:"toolSlug" required:"true"`
	Version  bundleitemutils.ItemVersion `path:"version"  required:"true"`
	Body     *PutToolRequestBody
}

type PutToolRequestBody struct {
	DisplayName  string   `json:"displayName"           required:"true"`
	Description  string   `json:"description,omitempty"`
	Tags         []string `json:"tags,omitempty"`
	IsEnabled    bool     `json:"isEnabled"             required:"true"`
	UserCallable bool     `json:"userCallable"          required:"true"`
	LLMCallable  bool     `json:"llmCallable"           required:"true"`

	// Take inputs as strings that we can then validate as a json object and put a tool.
	ArgSchema JSONRawString `json:"argSchema" required:"true"`

	Type     ToolImplType  `json:"type"               required:"true"`
	HTTPImpl *HTTPToolImpl `json:"httpImpl,omitempty" required:"true"`
}

type PutToolResponse struct{}

type SDKToolImpl struct {
	// SDKType can be ProviderSDKType.
	SDKType string `json:"sdkType"`
}

type SearchToolsRequest struct {
	Query           string `query:"q"               required:"true"`
	PageToken       string `query:"pageToken"`
	PageSize        int    `query:"pageSize"`
	IncludeDisabled bool   `query:"includeDisabled"`
}

type SearchToolsResponse struct {
	Body *SearchToolsResponseBody
}

type SearchToolsResponseBody struct {
	ToolListItems []ToolListItem `json:"toolListItems"`
	NextPageToken *string        `json:"nextPageToken,omitempty"`
}

type Tool struct {
	SchemaVersion string                      `json:"schemaVersion"`
	ID            bundleitemutils.ItemID      `json:"id"` // UUID-v7
	Slug          bundleitemutils.ItemSlug    `json:"slug"`
	Version       bundleitemutils.ItemVersion `json:"version"` // opaque

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

	// UserCallable indicates whether the tool can be invoked directly by the user
	// (e.g. from the composer UI before sending a message).
	UserCallable bool `json:"userCallable"`
	// LLMCallable indicates whether the model may call this tool as a function.
	LLMCallable bool `json:"llmCallable"`

	// ArgSchema describes the JSON arguments that are passed when the tool is invoked (by the LLM or via InvokeTool).
	// This is primarily used for Go/HTTP tools.
	ArgSchema JSONSchema `json:"argSchema"`

	// UserArgSchema, if present, describes an additional per-choice configuration object that the UI may collect when
	// enabling the tool for a model.
	// For SDK-backed server tools this typically encodes provider-specific options (e.g., web-search settings).
	UserArgSchema JSONSchema `json:"userArgSchema,omitempty"`

	// LLMToolType captures the semantic kind of this tool from the model's point of view, e.g. "function", "custom",
	// "webSearch".
	// This value should always be one of ToolStoreChoiceType values.
	LLMToolType ToolStoreChoiceType `json:"llmToolType"`

	Type     ToolImplType  `json:"type"`
	GoImpl   *GoToolImpl   `json:"goImpl,omitempty"`
	HTTPImpl *HTTPToolImpl `json:"httpImpl,omitempty"`
	SDKImpl  *SDKToolImpl  `json:"sdkImpl,omitempty"`

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

type ToolBundle struct {
	SchemaVersion string                     `json:"schemaVersion"`
	ID            bundleitemutils.BundleID   `json:"id"` // UUID-v7
	Slug          bundleitemutils.BundleSlug `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 ToolImplType string

type ToolListItem struct {
	BundleID       bundleitemutils.BundleID    `json:"bundleID"`
	BundleSlug     bundleitemutils.BundleSlug  `json:"bundleSlug"`
	ToolSlug       bundleitemutils.ItemSlug    `json:"toolSlug"`
	ToolVersion    bundleitemutils.ItemVersion `json:"toolVersion"`
	IsBuiltIn      bool                        `json:"isBuiltIn"`
	ToolDefinition Tool                        `json:"toolDefinition"`
}

type ToolPageToken struct {
	RecommendedPageSize int                        `json:"ps,omitempty"`
	IncludeDisabled     bool                       `json:"d,omitempty"`
	BundleIDs           []bundleitemutils.BundleID `json:"ids,omitempty"`
	Tags                []string                   `json:"tags,omitempty"`
	BuiltInDone         bool                       `json:"bd,omitempty"` // Built-ins already emitted?
	DirTok              string                     `json:"dt,omitempty"` // Directory-store cursor.
}

type ToolStoreChoice struct {
	ChoiceID string `json:"choiceID"`

	// BundleID, BundleSlug, ItemID, ItemSlug are string aliases.
	BundleID   bundleitemutils.BundleID   `json:"bundleID"`
	BundleSlug bundleitemutils.BundleSlug `json:"bundleSlug,omitempty"`

	ToolID      bundleitemutils.ItemID   `json:"toolID,omitempty"`
	ToolSlug    bundleitemutils.ItemSlug `json:"toolSlug"`
	ToolVersion string                   `json:"toolVersion"`

	ToolType    ToolStoreChoiceType `json:"toolType"`
	Description string              `json:"description,omitempty"`
	DisplayName string              `json:"displayName,omitempty"`

	// UserArgSchemaInstance is an optional per-choice configuration object.
	//
	// For SDK-backed tools (Tool.Type == "sdk"), this typically contains provider-specific options validated against
	// Tool.UserArgSchema. The inferencewrapper interprets this JSON and maps it into the appropriate inference-go
	// ToolChoice fields (e.g. WebSearchToolChoiceItem).
	UserArgSchemaInstance JSONRawString `json:"userArgSchemaInstance,omitempty"`
}

type ToolStoreChoiceType string

type ToolStoreOutputFile struct {
	FileName string `json:"fileName"`
	FileMIME string `json:"fileMIME"`
	FileData string `json:"fileData"`
}

type ToolStoreOutputImage struct {
	Detail    ImageDetail `json:"detail"`
	ImageName string      `json:"imageName"`
	ImageMIME string      `json:"imageMIME"`
	ImageData string      `json:"imageData"`
}

type ToolStoreOutputKind string

type ToolStoreOutputText struct {
	Text string `json:"text"`
}

type ToolStoreOutputUnion struct {
	Kind ToolStoreOutputKind `json:"kind"`

	TextItem  *ToolStoreOutputText  `json:"textItem,omitempty"`
	ImageItem *ToolStoreOutputImage `json:"imageItem,omitempty"`
	FileItem  *ToolStoreOutputFile  `json:"fileItem,omitempty"`
}