Files
zeekay 189ce08e51 Regenerate against the document the deployment answers for
The projection these were generated from was a month old and predated the
compute migration, so every one of them described /v1/visor — which the API
serves at zero paths now. That is why a hand-written console client and a
generated one had drifted the same way at the same time.

No /v1/visor path survives here. The word still appears as a source-plane
value and inside gvisor and supervisor, which are not this rename.
2026-09-05 18:07:13 -07:00

267 lines
20 KiB
C++

/**
* Hanzo Cloud API
* The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
*
* The version of the OpenAPI document: v1
*
* NOTE: This class is auto generated by OpenAPI-Generator 7.14.0.
* https://openapi-generator.tech
* Do not edit the class manually.
*/
/*
* ToolApi.h
*
*
*/
#ifndef HANZO_API_ToolApi_H_
#define HANZO_API_ToolApi_H_
#include "hanzo/ApiClient.h"
#include "hanzo/model/ActivationReq.h"
#include "hanzo/model/ActivationSet.h"
#include "hanzo/model/AuthoredPluginList.h"
#include "hanzo/model/AuthoredSkillList.h"
#include "hanzo/model/BuildOut.h"
#include "hanzo/model/BuildRequest.h"
#include "hanzo/model/CreateServerReq.h"
#include "hanzo/model/CurateReq.h"
#include "hanzo/model/MCPListing.h"
#include "hanzo/model/MCPServer.h"
#include "hanzo/model/McpCatalog.h"
#include "hanzo/model/McpCatalogSync.h"
#include "hanzo/model/McpServerList.h"
#include "hanzo/model/PluginDeleted.h"
#include "hanzo/model/PluginMountList.h"
#include "hanzo/model/SkillDeleted.h"
#include "hanzo/model/SkillIn.h"
#include "hanzo/model/SkillWritten.h"
#include "hanzo/model/SourceToolList.h"
#include "hanzo/model/ToolCall.h"
#include "hanzo/model/ToolList.h"
#include "hanzo/model/ToolResult.h"
#include <cpprest/details/basic_types.h>
#include <boost/optional.hpp>
namespace hanzo {
namespace api {
using namespace hanzo::model;
class ToolApi
{
public:
explicit ToolApi( std::shared_ptr<const ApiClient> apiClient );
virtual ~ToolApi();
/// <summary>
/// Deregisters one of the caller org&#39;s external MCP servers, so its tools leave the registry.
/// </summary>
/// <remarks>
/// Deregisters one of the caller org&#39;s external MCP servers, so its tools leave the registry. Scoped to the caller&#39;s org, so an id belonging to another tenant is a 404 and not a delete. Answers 204 with no body; a server this org does not have is 404.
/// </remarks>
/// <param name="id">ID is the server to deregister, from the path.</param>
pplx::task<void> deleteToolMcpServersById(
utility::string_t id
) const;
/// <summary>
/// Removes one of the caller org&#39;s built plugins, so the runtime can no longer load it.
/// </summary>
/// <remarks>
/// Removes one of the caller org&#39;s built plugins, so the runtime can no longer load it. Scoped to the caller&#39;s org, so an id belonging to another tenant answers 404 and is not deleted.
/// </remarks>
/// <param name="id">ID is the plugin to remove, from the path.</param>
pplx::task<std::shared_ptr<PluginDeleted>> deleteToolPluginsAuthoredById(
utility::string_t id
) const;
/// <summary>
/// Removes one of the caller org&#39;s authored skills.
/// </summary>
/// <remarks>
/// Removes one of the caller org&#39;s authored skills. Scoped to the caller&#39;s org, so an id belonging to another tenant is never reached. Removing what is not there is not an error — the caller&#39;s intent is \&quot;gone\&quot;, and it is.
/// </remarks>
/// <param name="id">ID is the skill to remove, from the path. It is the skill&#39;s name.</param>
pplx::task<std::shared_ptr<SkillDeleted>> deleteToolSkillsById(
utility::string_t id
) const;
/// <summary>
/// Lists every tool the caller&#39;s org and project can reach, from every source, each flagged with whether it is activated.
/// </summary>
/// <remarks>
/// Lists every tool the caller&#39;s org and project can reach, from every source, each flagged with whether it is activated. This is the discovery surface: one flat set of names spanning connector actions, user functions, zap-service routes, agents, skills and the org&#39;s own external MCP servers, deduplicated by name so the highest-precedence source wins a collision. It lists; it does not call — dispatch is POST /v1/tool/call.
/// </remarks>
/// <param name="source">Source keeps only tools from one source — connector, function, zap-service, agent, skill or mcp. Empty keeps every source. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="activated">Activated keeps only the tools activated for the caller&#39;s org and project, and only when it is exactly the string \&quot;true\&quot;. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
pplx::task<std::shared_ptr<ToolList>> getTool(
boost::optional<utility::string_t> source,
boost::optional<utility::string_t> activated
) const;
/// <summary>
/// Reports which tools are switched on for the caller&#39;s org and project.
/// </summary>
/// <remarks>
/// Reports which tools are switched on for the caller&#39;s org and project. Activation is what makes a tool dispatchable and what makes it visible to an agent, so this is the set the MCP tool list is drawn from — every other tool in the registry is discoverable but refused at call time.
/// </remarks>
pplx::task<std::shared_ptr<ActivationSet>> getToolActivation(
) const;
/// <summary>
/// Lists the MCP servers the public registries publish, as we hold them: our canonical copy of registry.modelcontextprotocol.io, plus what we decided about each entry.
/// </summary>
/// <remarks>
/// Lists the MCP servers the public registries publish, as we hold them: our canonical copy of registry.modelcontextprotocol.io, plus what we decided about each entry. This is the SHELF an org picks from. A listing with a streamable-http endpoint can be enabled as-is — POST /v1/tool/mcp/servers with its id — and its tools then join the org&#39;s tool plane and the fleet&#39;s MCP server. A listing that only ships a stdio package needs a process to run it, which is why the transports are on every entry rather than implied. Hidden entries are absent: they are the ones we took off the shelf. A platform SuperAdmin sees them, because the same query answers \&quot;what is on the shelf\&quot; and \&quot;what is in the catalog\&quot; and two queries would drift apart. It is PAGED — 50 by default, 200 at most. The public registry publishes tens of thousands of servers, so an unbounded answer is a twenty-megabyte response and a storefront that renders in a minute. total is the whole match, not the page.
/// </remarks>
/// <param name="q">Q matches the name, title or description, case-insensitively. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="featured">Featured keeps only the listings we put on the front of the shelf, and only when it is exactly the string \&quot;true\&quot;. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="official">Official keeps only the vendors&#39; OWN servers — not third-party copies of them — and only when it is exactly the string \&quot;true\&quot;. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="limit">Limit bounds the page: default 50, maximum 200. A value that is not a positive integer reads as the default. (optional, default to 0L)</param>
/// <param name="offset">Offset skips that many listings. (optional, default to 0L)</param>
pplx::task<std::shared_ptr<McpCatalog>> getToolCatalog(
boost::optional<utility::string_t> q,
boost::optional<utility::string_t> featured,
boost::optional<utility::string_t> official,
boost::optional<int64_t> limit,
boost::optional<int64_t> offset
) const;
/// <summary>
/// Returns one catalog entry in full: the publisher&#39;s description, its repository and site, every package form with the runtime that launches it, and every hosted endpoint.
/// </summary>
/// <remarks>
/// Returns one catalog entry in full: the publisher&#39;s description, its repository and site, every package form with the runtime that launches it, and every hosted endpoint. It is what a branding page renders, and what tells a caller whether the listing can be enabled here and now (a streamable-http remote) or needs somewhere to run first (a stdio package). A HIDDEN listing is not served to an org — a shelf that renders what it does not list would be a way around the shelf — but is served to a SuperAdmin, who is the one deciding whether to put it back.
/// </remarks>
/// <param name="id">ID is the listing, from the path. It is the publisher&#39;s reverse-DNS name with its one slash written as an underscore — \&quot;com.stripe_mcp\&quot;.</param>
pplx::task<std::shared_ptr<MCPListing>> getToolCatalogById(
utility::string_t id
) const;
/// <summary>
/// Lists the external MCP servers the caller&#39;s org has registered.
/// </summary>
/// <remarks>
/// Lists the external MCP servers the caller&#39;s org has registered. Each record carries the URL and the name of the header its credential is injected into; the credential VALUE lives only in KMS and is never returned, so hasSecret is the whole of what this surface says about it.
/// </remarks>
pplx::task<std::shared_ptr<McpServerList>> getToolMcpServers(
) const;
/// <summary>
/// Reports what this deployment actually mounted: every subsystem the composition root declared and whether it is switched on.
/// </summary>
/// <remarks>
/// Reports what this deployment actually mounted: every subsystem the composition root declared and whether it is switched on. A plugin here is MOUNTED CODE that extends the deployment&#39;s own surface — not a tool an agent calls — so this is an inventory and not a tool source. It is read off the same boot snapshot every traced request resolves its subsystem label against, so it cannot drift from what is serving. Enabled-only by default, because a caller asking what this deployment can do wants what is running; ?all&#x3D;true adds the configured-but-off ones.
/// </remarks>
/// <param name="all">All includes the configured-but-disabled subsystems too, but only when it is exactly the string \&quot;true\&quot;. Otherwise only the running ones are reported. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
pplx::task<std::shared_ptr<PluginMountList>> getToolPlugins(
boost::optional<utility::string_t> all
) const;
/// <summary>
/// Lists the plugins the caller&#39;s org BUILT, newest first, each with the TypeScript as authored.
/// </summary>
/// <remarks>
/// Lists the plugins the caller&#39;s org BUILT, newest first, each with the TypeScript as authored. That is a different set with a different lifecycle from GET /v1/tool/plugins, which reports the subsystems this deployment mounted. The bundled CommonJS the runtime executes is never included, and neither is any credential — a plugin names the connectors provider it needs and reads the credential from ctx.auth at run time.
/// </remarks>
pplx::task<std::shared_ptr<AuthoredPluginList>> getToolPluginsAuthored(
) const;
/// <summary>
/// Lists the skills the caller&#39;s org can reach — the brand&#39;s embedded catalogue plus the org&#39;s own authored ones — with each one&#39;s activation flag.
/// </summary>
/// <remarks>
/// Lists the skills the caller&#39;s org can reach — the brand&#39;s embedded catalogue plus the org&#39;s own authored ones — with each one&#39;s activation flag. A skill is discovery and activation metadata attached to an agent, never called directly, so every entry here is non-dispatchable. It is GET /v1/tool narrowed to one source, not a second store: a name a caller sees here is the same entry, with the same activation state, that discovery reports.
/// </remarks>
/// <param name="activated">Activated keeps only the tools activated for the caller&#39;s org and project, and only when it is exactly the string \&quot;true\&quot;. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
pplx::task<std::shared_ptr<SourceToolList>> getToolSkills(
boost::optional<utility::string_t> activated
) const;
/// <summary>
/// Lists the caller org&#39;s OWN skills with their SKILL.md bodies.
/// </summary>
/// <remarks>
/// Lists the caller org&#39;s OWN skills with their SKILL.md bodies. GET /v1/tool/skills is the registry view — the brand&#39;s catalogue plus this org&#39;s, with activation flags and no bodies; this is the EDITABLE set, so it carries the content that view omits and nothing the org did not write.
/// </remarks>
pplx::task<std::shared_ptr<AuthoredSkillList>> getToolSkillsAuthored(
) const;
/// <summary>
/// Sets what WE say about one catalog entry — hidden, featured, official, logo — and answers with the stored listing.
/// </summary>
/// <remarks>
/// Sets what WE say about one catalog entry — hidden, featured, official, logo — and answers with the stored listing. SuperAdmin only; every other caller is refused. Curation is the half of a catalog row a sync cannot write, and this is the only thing that writes it. The upstream half is never editable here: a description that disagreed with the publisher&#39;s would be a fork of their listing, and the next sync would silently undo it.
/// </remarks>
/// <param name="id">ID is the listing to curate, from the path.</param>
/// <param name="curateReq"></param>
pplx::task<std::shared_ptr<MCPListing>> patchToolCatalogById(
utility::string_t id,
std::shared_ptr<CurateReq> curateReq
) const;
/// <summary>
/// Runs one of the caller&#39;s activated tools and answers with its output.
/// </summary>
/// <remarks>
/// Runs one of the caller&#39;s activated tools and answers with its output. This is the endpoint onto the tool plane&#39;s DYNAMIC half — the half no build-time catalogue can hold, because it is per-tenant: an org&#39;s connected connector actions, its authored skills, its agents and functions, and the tools of every external MCP server it registered. A tool&#39;s existence, its price and its activation are all rows, not code, so they cannot be known until the caller is. One policy, the registry&#39;s: resolve by precedence, refuse an unactivated tool 403, settle a priced one through the x402 client or fail closed 402, then dispatch to the winning source bound to the caller&#39;s own (org, project). One metered unit, one audit record. A caller can only ever dispatch its own tools. Discovery is GET /v1/tool — ?activated&#x3D;true for the callable set.
/// </remarks>
/// <param name="toolCall"></param>
pplx::task<std::shared_ptr<ToolResult>> postToolCall(
std::shared_ptr<ToolCall> toolCall
) const;
/// <summary>
/// Pulls the public MCP registry into our canonical copy and reports what changed.
/// </summary>
/// <remarks>
/// Pulls the public MCP registry into our canonical copy and reports what changed. SuperAdmin only; every other caller is refused. It is IDEMPOTENT: a listing is keyed by the publisher&#39;s own reverse-DNS name, so a second pass over an unchanged registry rewrites the same rows and reports added&#x3D;0, updated&#x3D;0. It never deletes — a listing that vanishes upstream may be one an org has already enabled, and dropping its description would not drop its server. And it never touches CURATION: hidden, featured, an admin-set official and a logo survive every sync, because the write does not name those columns.
/// </remarks>
pplx::task<std::shared_ptr<McpCatalogSync>> postToolCatalogSync(
) const;
/// <summary>
/// Gives the caller&#39;s org one more external MCP server, so its tools join the org&#39;s tool plane and the fleet&#39;s MCP server.
/// </summary>
/// <remarks>
/// Gives the caller&#39;s org one more external MCP server, so its tools join the org&#39;s tool plane and the fleet&#39;s MCP server. It is the ONE way an org gains a server, whether it typed the URL in or enabled a catalog listing: both write the SAME record, and &#x60;source&#x60; says which it was. A second registration path would be a second place for a server to exist, and then a second place to forget to check the credential. The credential VALUE is sealed in KMS under a per-org ref; the row keeps only the URL, the header name to inject it into, and a has-secret flag — so a secret with no KMS configured is refused 503 rather than stored in the clear. The URL is SSRF-validated here and re-checked by the dialer at connect time, which is the DNS-rebinding defense. Enabling a listing the org already enabled REVISES that server rather than adding a near-duplicate beside it, so a retried enable is the same one server. Answers 201 with the stored record.
/// </remarks>
/// <param name="createServerReq"></param>
pplx::task<std::shared_ptr<MCPServer>> postToolMcpServers(
std::shared_ptr<CreateServerReq> createServerReq
) const;
/// <summary>
/// Builds and stores one plugin for the caller&#39;s org.
/// </summary>
/// <remarks>
/// Builds and stores one plugin for the caller&#39;s org. The 201 carries the bundle&#39;s size, whether a model wrote the source, and the plugin as stored. Post &#x60;source&#x60; to build TypeScript as-is, or &#x60;spec&#x60; — an OpenAPI document or plain prose describing the endpoints — to have one generated; the generated source comes back in the answer, so a caller reads what will run before it runs. Exactly one of the two, and &#x60;name&#x60; must be one lowercase path segment; both or neither is 400. COMPILING IS THE GATE. The source goes through the same pipeline the committed connectors do — esbuild to one CommonJS program, then compiled in the goja runtime that will actually execute it — and anything that fails is rejected and NEVER stored. So a plugin in the store is one this deployment has already loaded once, not one a model claimed was fine. A failed build answers 422 carrying the diagnostics a caller needs to fix it: the bundler&#39;s error (&#x60;detail&#x60;), the source that failed, and whether the model wrote it. CREDENTIALS ARE NOT PART OF A PLUGIN. A plugin names the connectors &#x60;provider&#x60; it needs and reads that credential from &#x60;ctx.auth&#x60; at run time, under KMS custody. Source that carries something key-shaped is REFUSED rather than silently persisted — a scrubbed key looks like it worked.
/// </remarks>
/// <param name="buildRequest"></param>
pplx::task<std::shared_ptr<BuildOut>> postToolPluginsBuild(
std::shared_ptr<BuildRequest> buildRequest
) const;
/// <summary>
/// Adds or revises one of the caller org&#39;s own skills, and answers 201 with the stored record.
/// </summary>
/// <remarks>
/// Adds or revises one of the caller org&#39;s own skills, and answers 201 with the stored record. The id is derived from the name, so writing the same name again REVISES that skill rather than accumulating near-duplicates that would then collide in the registry. An org&#39;s skills are private to it by construction — they live in a different store from the brand&#39;s embedded catalogue and have no path into the public gallery — and a brand skill always wins a name collision against an org&#39;s.
/// </remarks>
/// <param name="skillIn"></param>
pplx::task<std::shared_ptr<SkillWritten>> postToolSkills(
std::shared_ptr<SkillIn> skillIn
) const;
/// <summary>
/// Switches tools on and off for the caller&#39;s org and project, and answers with the resulting activated set.
/// </summary>
/// <remarks>
/// Switches tools on and off for the caller&#39;s org and project, and answers with the resulting activated set. It is the ONE write path that turns skills, plugins and connectors into callable tools — an unactivated tool is listed by discovery but refused 403 at dispatch. Activate is applied before Deactivate, so a name in both lists ends up off. More than 256 toggles in one request is refused 413.
/// </remarks>
/// <param name="activationReq"></param>
pplx::task<std::shared_ptr<ActivationSet>> putToolActivation(
std::shared_ptr<ActivationReq> activationReq
) const;
protected:
std::shared_ptr<const ApiClient> m_ApiClient;
};
}
}
#endif /* HANZO_API_ToolApi_H_ */