v0

type Blob struct {

	// MediaType identifies the bytes, e.g. "image/png" or
	// "application/octet-stream".
	MediaType string `protobuf:"bytes,1,opt,name=media_type,json=mediaType,proto3" json:"media_type,omitempty"`
	// Data is the raw binary payload.
	Data []byte `protobuf:"bytes,2,opt,name=data,proto3" json:"data,omitempty"`
	// contains filtered or unexported fields
}

type CallToolRequest struct {

	// Name is the exact tool name from ListToolsResponse.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Arguments are validated by the tool's input_schema before execution.
	Arguments *structpb.Struct `protobuf:"bytes,2,opt,name=arguments,proto3" json:"arguments,omitempty"`
	// Roots constrain the operation's scope. The toolbox MUST refuse
	// operations that touch URIs outside these roots. Empty roots means
	// "use the toolbox's default scope from its manifest."
	Roots []string `protobuf:"bytes,3,rep,name=roots,proto3" json:"roots,omitempty"`
	// contains filtered or unexported fields
}

type CallToolResponse struct {

	// Content blocks returned by the tool. Empty when the tool
	// surfaced only an error.
	Content []*Content `protobuf:"bytes,1,rep,name=content,proto3" json:"content,omitempty"`
	// Error is non-empty when the tool refused or failed. Distinct from
	// a transport-level error; this is the tool saying "I tried, here's
	// why it didn't work."
	Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`
	// CanonicalRouted is true when the toolbox refused because the
	// request targeted a binary/operation it doesn't own — set the
	// suggested toolbox in error and let the agent reroute.
	CanonicalRouted bool `protobuf:"varint,3,opt,name=canonical_routed,json=canonicalRouted,proto3" json:"canonical_routed,omitempty"`
	// RoutedTo is the toolbox the agent should call instead, when
	// CanonicalRouted is true. Empty when the binary has no claimed
	// owner (use the built-in fallback's hint in error).
	RoutedTo string `protobuf:"bytes,4,opt,name=routed_to,json=routedTo,proto3" json:"routed_to,omitempty"`
	// contains filtered or unexported fields
}

type Content struct {

	// Body is the typed payload carried by this content block.
	//
	// Types that are valid to be assigned to Body:
	//
	//	*Content_Text
	//	*Content_Structured
	//	*Content_Blob
	Body isContent_Body `protobuf_oneof:"body"`
	// contains filtered or unexported fields
}

type Content_Blob struct {
	// Binary blob with a media type. For images, archives, etc.
	Blob *Blob `protobuf:"bytes,3,opt,name=blob,proto3,oneof"`
}

type Content_Structured struct {
	// Structured payload (JSON-shaped). Use when the agent should
	// reason about typed fields.
	Structured *structpb.Struct `protobuf:"bytes,2,opt,name=structured,proto3,oneof"`
}

type Content_Text struct {
	// Plain text — the most common path.
	Text string `protobuf:"bytes,1,opt,name=text,proto3,oneof"`
}

type DescribeToolRequest struct {

	// Dotted tool name as returned in ToolSummary.name.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// contains filtered or unexported fields
}

type DescribeToolResponse struct {

	// Full spec when the named tool exists. Unset when error is set.
	Tool *ToolSpec `protobuf:"bytes,1,opt,name=tool,proto3" json:"tool,omitempty"`
	// Set when the requested tool name doesn't exist. Empty on success.
	Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`
	// contains filtered or unexported fields
}

type GetPromptRequest struct {

	// Name is the prompt identifier from ListPromptsResponse.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Arguments supplies values for the prompt's declared parameters.
	Arguments *structpb.Struct `protobuf:"bytes,2,opt,name=arguments,proto3" json:"arguments,omitempty"`
	// contains filtered or unexported fields
}

type GetPromptResponse struct {

	// Description of the rendered prompt for catalog UIs.
	Description string `protobuf:"bytes,1,opt,name=description,proto3" json:"description,omitempty"`
	// Messages making up the rendered prompt.
	Messages []*PromptMessage `protobuf:"bytes,2,rep,name=messages,proto3" json:"messages,omitempty"`
	// contains filtered or unexported fields
}

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

type IdentityResponse struct {

	// Name from the toolbox manifest (e.g. "git", "docker", "bash").
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Version from the manifest (semver).
	Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
	// Description from the manifest, surface in catalog UIs.
	Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
	// CanonicalFor lists the binaries this toolbox claims as canonical
	// owner. Mirrors the manifest field; useful for cross-toolbox
	// diagnostics ("who owns kubectl?").
	CanonicalFor []string `protobuf:"bytes,4,rep,name=canonical_for,json=canonicalFor,proto3" json:"canonical_for,omitempty"`
	// SandboxSummary is a string describing the sandbox the toolbox
	// operates under. Not the policy itself (that's host-side); just a
	// human-readable summary for "show me what this toolbox can do."
	SandboxSummary string `protobuf:"bytes,5,opt,name=sandbox_summary,json=sandboxSummary,proto3" json:"sandbox_summary,omitempty"`
	// contains filtered or unexported fields
}

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

type ListPromptsResponse struct {

	// Prompts is the complete prompt catalog for this toolbox.
	Prompts []*Prompt `protobuf:"bytes,1,rep,name=prompts,proto3" json:"prompts,omitempty"`
	// contains filtered or unexported fields
}

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

type ListResourcesResponse struct {

	// Resources is the complete readable catalog for this toolbox.
	Resources []*Resource `protobuf:"bytes,1,rep,name=resources,proto3" json:"resources,omitempty"`
	// contains filtered or unexported fields
}

type ListToolSummariesRequest struct {

	// Pre-filter: only return tools whose tags include every entry
	// here (conjunctive AND). Empty = no filter. Useful for
	// "read-only" pre-selection.
	TagsFilter []string `protobuf:"bytes,1,rep,name=tags_filter,json=tagsFilter,proto3" json:"tags_filter,omitempty"`
	// contains filtered or unexported fields
}

type ListToolSummariesResponse struct {

	// Catalog entries — one per tool exposed by this toolbox after
	// tags_filter is applied.
	Tools []*ToolSummary `protobuf:"bytes,1,rep,name=tools,proto3" json:"tools,omitempty"`
	// contains filtered or unexported fields
}

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

type ListToolsResponse struct {

	// Tools is the complete callable catalog for this toolbox.
	Tools []*Tool `protobuf:"bytes,1,rep,name=tools,proto3" json:"tools,omitempty"`
	// contains filtered or unexported fields
}

type Prompt struct {

	// Name is the stable prompt identifier.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Description tells the agent when this prompt is useful.
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// Arguments defines the accepted template parameters.
	Arguments []*PromptArgument `protobuf:"bytes,3,rep,name=arguments,proto3" json:"arguments,omitempty"`
	// contains filtered or unexported fields
}

type PromptArgument struct {

	// Name is the parameter key expected by GetPromptRequest.arguments.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Description tells the agent what value to provide.
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// Required marks parameters that must be present for rendering.
	Required bool `protobuf:"varint,3,opt,name=required,proto3" json:"required,omitempty"`
	// contains filtered or unexported fields
}

type PromptMessage struct {

	// Role: "user", "assistant", "system".
	Role string `protobuf:"bytes,1,opt,name=role,proto3" json:"role,omitempty"`
	// Content envelope, same shape as tool/resource content.
	Content []*Content `protobuf:"bytes,2,rep,name=content,proto3" json:"content,omitempty"`
	// contains filtered or unexported fields
}

type ReadResourceRequest struct {

	// URI is the resource identifier returned by ListResourcesResponse.
	Uri string `protobuf:"bytes,1,opt,name=uri,proto3" json:"uri,omitempty"`
	// contains filtered or unexported fields
}

type ReadResourceResponse struct {

	// Content of the resource. Same envelope as CallToolResponse so
	// resources can return text, structured data, or binary blobs.
	Content []*Content `protobuf:"bytes,1,rep,name=content,proto3" json:"content,omitempty"`
	// contains filtered or unexported fields
}

type Resource struct {

	// URI uniquely identifying the resource. Convention:
	// "<scheme>://<path>", e.g. "git://HEAD", "file:///etc/host".
	Uri string `protobuf:"bytes,1,opt,name=uri,proto3" json:"uri,omitempty"`
	// Human-readable name.
	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
	// Description for the agent.
	Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"`
	// MIME type of the resource's content.
	MimeType string `protobuf:"bytes,4,opt,name=mime_type,json=mimeType,proto3" json:"mime_type,omitempty"`
	// contains filtered or unexported fields
}

type Tool struct {

	// Dotted name. Convention: <toolbox>.<verb>, e.g. "git.commit",
	// "docker.run", "bash.exec".
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// One-line description for the agent to decide whether to call it.
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// JSON Schema describing valid arguments. Encoded as a Struct so
	// protobuf doesn't force us to mirror JSON Schema's open recursion
	// in proto.
	InputSchema *structpb.Struct `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"`
	// JSON Schema describing the result Content envelope. Optional;
	// missing means "free-form text + structured side-channel."
	OutputSchema *structpb.Struct `protobuf:"bytes,4,opt,name=output_schema,json=outputSchema,proto3" json:"output_schema,omitempty"`
	// Destructive marks the tool as state-mutating (writes, kills,
	// pushes). The host shows extra confirmation UI for these.
	Destructive bool `protobuf:"varint,5,opt,name=destructive,proto3" json:"destructive,omitempty"`
	// contains filtered or unexported fields
}

type ToolExample struct {

	// Human-readable summary of what this example demonstrates.
	// E.g. "List the last 5 commits on the default branch".
	Description string `protobuf:"bytes,1,opt,name=description,proto3" json:"description,omitempty"`
	// Sample arguments matching input_schema.
	Arguments *structpb.Struct `protobuf:"bytes,2,opt,name=arguments,proto3" json:"arguments,omitempty"`
	// Expected outcome — short prose, not strict assertion.
	// E.g. "returns 5 commit objects with hash, author, message".
	ExpectedOutcome string `protobuf:"bytes,3,opt,name=expected_outcome,json=expectedOutcome,proto3" json:"expected_outcome,omitempty"`
	// contains filtered or unexported fields
}

type ToolSpec struct {

	// Dotted name.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Multi-paragraph description allowed. Spell out the contract,
	// edge cases, when to use vs. not use.
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// JSON Schema for the input. Same shape as Tool.input_schema.
	InputSchema *structpb.Struct `protobuf:"bytes,3,opt,name=input_schema,json=inputSchema,proto3" json:"input_schema,omitempty"`
	// JSON Schema for the result Content envelope. Optional.
	OutputSchema *structpb.Struct `protobuf:"bytes,4,opt,name=output_schema,json=outputSchema,proto3" json:"output_schema,omitempty"`
	// Destructive marker; same semantics as Tool.destructive.
	Destructive bool `protobuf:"varint,5,opt,name=destructive,proto3" json:"destructive,omitempty"`
	// Same tag set as ToolSummary.tags (kept here for self-containment
	// — DescribeTool's response shouldn't require pairing with a
	// separate summary fetch).
	Tags []string `protobuf:"bytes,6,rep,name=tags,proto3" json:"tags,omitempty"`
	// Worked examples. The single biggest win of the two-phase design:
	// LLMs structure arguments dramatically better with 1-2 examples
	// than with a JSON schema alone. Tool authors should always include
	// at least one canonical example.
	Examples []*ToolExample `protobuf:"bytes,7,rep,name=examples,proto3" json:"examples,omitempty"`
	// Idempotency hint for retry / dedup logic.
	// Conventional values: "idempotent" | "side_effecting" | "unknown".
	Idempotency string `protobuf:"bytes,8,opt,name=idempotency,proto3" json:"idempotency,omitempty"`
	// Free-text on what failure looks like — when the tool fails, what
	// does the error message contain, and what should the caller do?
	// Helps the LLM diagnose without re-running the call.
	ErrorModes string `protobuf:"bytes,9,opt,name=error_modes,json=errorModes,proto3" json:"error_modes,omitempty"`
	// contains filtered or unexported fields
}

type ToolSummary struct {

	// Dotted name. Same convention as Tool.name.
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// ONE LINE optimized for routing decisions. ~120 chars or less
	// by convention. Should answer "when would I pick this?"
	Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"`
	// Categories useful for pre-filtering. Conventional values:
	//
	//	read-only       — never mutates state
	//	destructive     — mirrors Tool.destructive; surfaced for symmetry
	//	network         — issues outbound network calls
	//	filesystem      — reads or writes the host filesystem
	//	<toolbox-name>  — every tool tags its toolbox name (git, docker, ...)
	//
	// Plus domain-specific tags the toolbox author chooses.
	Tags []string `protobuf:"bytes,3,rep,name=tags,proto3" json:"tags,omitempty"`
	// Mirrors Tool.destructive — promoted so callers can decide
	// without combing tags.
	Destructive bool `protobuf:"varint,4,opt,name=destructive,proto3" json:"destructive,omitempty"`
	// contains filtered or unexported fields
}

type ToolboxClient interface {
	// Identity returns the toolbox's manifest-derived metadata.
	Identity(ctx context.Context, in *IdentityRequest, opts ...grpc.CallOption) (*IdentityResponse, error)
	// Deprecated: Do not use.
	// ListTools returns every tool this toolbox exposes WITH FULL
	// SPECS (schemas, descriptions). Heavy. Kept for transitional
	// consumers and for MCP transcoding; new code should prefer the
	// two-phase pair below — ListToolSummaries (catalog) +
	// DescribeTool (per-tool spec on demand) — which keeps the LLM's
	// routing context small while making per-call descriptions richer.
	ListTools(ctx context.Context, in *ListToolsRequest, opts ...grpc.CallOption) (*ListToolsResponse, error)
	// ListToolSummaries returns lightweight catalog entries — enough
	// for the LLM to pick a tool, but no schemas or examples. The
	// load-bearing routing surface: with N toolboxes and M tools each,
	// every LLM turn pays only the catalog cost (~50 bytes/tool); the
	// heavy spec is fetched per-tool via DescribeTool right before
	// invoking it, then drops out of context.
	//
	// Optional tags_filter pre-selects (e.g. ["read-only"]) so the
	// LLM doesn't even see destructive tools when the goal is read.
	ListToolSummaries(ctx context.Context, in *ListToolSummariesRequest, opts ...grpc.CallOption) (*ListToolSummariesResponse, error)
	// DescribeTool returns the full spec for ONE tool — input/output
	// schemas, multi-paragraph description, examples, error modes.
	// Called on-demand: the LLM picks a tool from the summary catalog,
	// the host fetches DescribeTool for that one, injects it into the
	// next prompt only, then drops it.
	DescribeTool(ctx context.Context, in *DescribeToolRequest, opts ...grpc.CallOption) (*DescribeToolResponse, error)
	// CallTool invokes a tool by name with structured arguments.
	// The result carries either a Content payload, an error, or both
	// (e.g. partial success + warnings).
	CallTool(ctx context.Context, in *CallToolRequest, opts ...grpc.CallOption) (*CallToolResponse, error)
	// ListResources returns every addressable resource the toolbox
	// exposes for read-only context.
	ListResources(ctx context.Context, in *ListResourcesRequest, opts ...grpc.CallOption) (*ListResourcesResponse, error)
	// ReadResource fetches a resource's content by URI.
	ReadResource(ctx context.Context, in *ReadResourceRequest, opts ...grpc.CallOption) (*ReadResourceResponse, error)
	// ListPrompts returns every parametric prompt template the toolbox
	// exposes.
	ListPrompts(ctx context.Context, in *ListPromptsRequest, opts ...grpc.CallOption) (*ListPromptsResponse, error)
	// GetPrompt renders a prompt with the supplied arguments.
	GetPrompt(ctx context.Context, in *GetPromptRequest, opts ...grpc.CallOption) (*GetPromptResponse, error)
}

type ToolboxServer interface {
	// Identity returns the toolbox's manifest-derived metadata.
	Identity(context.Context, *IdentityRequest) (*IdentityResponse, error)
	// Deprecated: Do not use.
	// ListTools returns every tool this toolbox exposes WITH FULL
	// SPECS (schemas, descriptions). Heavy. Kept for transitional
	// consumers and for MCP transcoding; new code should prefer the
	// two-phase pair below — ListToolSummaries (catalog) +
	// DescribeTool (per-tool spec on demand) — which keeps the LLM's
	// routing context small while making per-call descriptions richer.
	ListTools(context.Context, *ListToolsRequest) (*ListToolsResponse, error)
	// ListToolSummaries returns lightweight catalog entries — enough
	// for the LLM to pick a tool, but no schemas or examples. The
	// load-bearing routing surface: with N toolboxes and M tools each,
	// every LLM turn pays only the catalog cost (~50 bytes/tool); the
	// heavy spec is fetched per-tool via DescribeTool right before
	// invoking it, then drops out of context.
	//
	// Optional tags_filter pre-selects (e.g. ["read-only"]) so the
	// LLM doesn't even see destructive tools when the goal is read.
	ListToolSummaries(context.Context, *ListToolSummariesRequest) (*ListToolSummariesResponse, error)
	// DescribeTool returns the full spec for ONE tool — input/output
	// schemas, multi-paragraph description, examples, error modes.
	// Called on-demand: the LLM picks a tool from the summary catalog,
	// the host fetches DescribeTool for that one, injects it into the
	// next prompt only, then drops it.
	DescribeTool(context.Context, *DescribeToolRequest) (*DescribeToolResponse, error)
	// CallTool invokes a tool by name with structured arguments.
	// The result carries either a Content payload, an error, or both
	// (e.g. partial success + warnings).
	CallTool(context.Context, *CallToolRequest) (*CallToolResponse, error)
	// ListResources returns every addressable resource the toolbox
	// exposes for read-only context.
	ListResources(context.Context, *ListResourcesRequest) (*ListResourcesResponse, error)
	// ReadResource fetches a resource's content by URI.
	ReadResource(context.Context, *ReadResourceRequest) (*ReadResourceResponse, error)
	// ListPrompts returns every parametric prompt template the toolbox
	// exposes.
	ListPrompts(context.Context, *ListPromptsRequest) (*ListPromptsResponse, error)
	// GetPrompt renders a prompt with the supplied arguments.
	GetPrompt(context.Context, *GetPromptRequest) (*GetPromptResponse, error)
	// contains filtered or unexported methods
}

type UnimplementedToolboxServer struct{}

type UnsafeToolboxServer interface {
	// contains filtered or unexported methods
}