mirror of
https://github.com/hanzo-cpp/sdk.git
synced 2026-11-20 19:55:32 +00:00
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.
498 lines
36 KiB
C++
498 lines
36 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.
|
|
*/
|
|
|
|
/*
|
|
* AgentApi.h
|
|
*
|
|
*
|
|
*/
|
|
|
|
#ifndef HANZO_API_AgentApi_H_
|
|
#define HANZO_API_AgentApi_H_
|
|
|
|
|
|
|
|
#include "hanzo/ApiClient.h"
|
|
|
|
#include "hanzo/model/ActivityFeed.h"
|
|
#include "hanzo/model/AgentDetail.h"
|
|
#include "hanzo/model/AgentList.h"
|
|
#include "hanzo/model/AgentView.h"
|
|
#include "hanzo/model/BuildList.h"
|
|
#include "hanzo/model/BuildView.h"
|
|
#include "hanzo/model/ClaimKeyOut.h"
|
|
#include "hanzo/model/CodingStartIn.h"
|
|
#include "hanzo/model/CodingStarted.h"
|
|
#include "hanzo/model/ControlDrain.h"
|
|
#include "hanzo/model/ControlIn.h"
|
|
#include "hanzo/model/ControlResult.h"
|
|
#include "hanzo/model/CreateAgentIn.h"
|
|
#include "hanzo/model/EventIn.h"
|
|
#include "hanzo/model/EventView.h"
|
|
#include "hanzo/model/MetricsView.h"
|
|
#include "hanzo/model/PatchSessionIn.h"
|
|
#include "hanzo/model/PatchTargetIn.h"
|
|
#include "hanzo/model/RegisterReq.h"
|
|
#include "hanzo/model/ReportOut.h"
|
|
#include "hanzo/model/ReportRunIn.h"
|
|
#include "hanzo/model/RoutedRunOut.h"
|
|
#include "hanzo/model/RunList.h"
|
|
#include "hanzo/model/SessionDetail.h"
|
|
#include "hanzo/model/SessionList.h"
|
|
#include "hanzo/model/SessionProgress.h"
|
|
#include "hanzo/model/SessionView.h"
|
|
#include "hanzo/model/TargetDeleted.h"
|
|
#include "hanzo/model/TargetList.h"
|
|
#include "hanzo/model/TargetReq.h"
|
|
#include "hanzo/model/TargetView.h"
|
|
#include "hanzo/model/TreeNode.h"
|
|
#include "hanzo/model/UpdateAgentIn.h"
|
|
#include <cpprest/details/basic_types.h>
|
|
#include <boost/optional.hpp>
|
|
|
|
namespace hanzo {
|
|
namespace api {
|
|
|
|
using namespace hanzo::model;
|
|
|
|
|
|
|
|
class AgentApi
|
|
{
|
|
public:
|
|
|
|
explicit AgentApi( std::shared_ptr<const ApiClient> apiClient );
|
|
|
|
virtual ~AgentApi();
|
|
|
|
/// <summary>
|
|
/// Removes an agent and every run recorded against it.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Removes an agent and every run recorded against it. Answers 204.
|
|
/// </remarks>
|
|
/// <param name="ref">Ref is the agent's public id (the agent_… handle create and list return) or its org-unique name, from the path. Either resolves the same agent.</param>
|
|
pplx::task<void> deleteAgentByRef(
|
|
utility::string_t ref
|
|
) const;
|
|
/// <summary>
|
|
/// Deregisters one machine.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Deregisters one machine. Only its owner, or an org admin, may remove it; an unknown id, a cross-org id and a machine owned by someone else all answer the same not-found, so a probe learns nothing about what exists.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the target to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<TargetDeleted>> deleteAgentTargetsById(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Returns every agent defined in the caller's org, each with the number of runs recorded against it.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every agent defined in the caller's org, each with the number of runs recorded against it.
|
|
/// </remarks>
|
|
pplx::task<std::shared_ptr<AgentList>> getAgent(
|
|
) const;
|
|
/// <summary>
|
|
/// Serves the org-wide recent-activity feed.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Serves the org-wide recent-activity feed. Events are REAL: each recorded run is an invoked (ok) or failed (error) event; each agent's own create/update timestamps are created/updated events. Merged, newest first, capped. Nothing is invented — an org with no agents and no runs gets [].
|
|
/// </remarks>
|
|
pplx::task<std::shared_ptr<ActivityFeed>> getAgentActivity(
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the public index of every published build, most recently updated first, so a gallery can link straight to the story behind each product.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the public index of every published build, most recently updated first, so a gallery can link straight to the story behind each product. PUBLIC, no tenancy: publishing is the author's act, and only published root sessions appear here.
|
|
/// </remarks>
|
|
/// <param name="limit">Limit caps the page. Absent, zero or over 500 reads as 100. (optional, default to 0L)</param>
|
|
pplx::task<std::shared_ptr<BuildList>> getAgentBuilds(
|
|
boost::optional<int64_t> limit
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the readable build of one product: the agent session that produced it, turn by turn — the prompts, the reasoning, the commits each turn produced — plus the exact `git log` that re-derives every commit binding from git itself, so nothing here has to be taken on trust.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the readable build of one product: the agent session that produced it, turn by turn — the prompts, the reasoning, the commits each turn produced — plus the exact `git log` that re-derives every commit binding from git itself, so nothing here has to be taken on trust. PUBLIC, no tenancy: it answers only for a session its author explicitly published, which is what makes it safe to be anonymous. An unpublished session is invisible here no matter who asks; its owner reads it through the org-scoped /v1/agent/sessions routes, which need a validated principal.
|
|
/// </remarks>
|
|
/// <param name="org">Org is the org that published the build, from the path.</param>
|
|
/// <param name="project">Project is the product's slug, from the path.</param>
|
|
pplx::task<std::shared_ptr<BuildView>> getAgentBuildsByOrgByProject(
|
|
utility::string_t org,
|
|
utility::string_t project
|
|
) const;
|
|
/// <summary>
|
|
/// Returns one agent with its system prompt and its 20 most recent runs.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns one agent with its system prompt and its 20 most recent runs. The ref is the agent's public id or its org-unique name — a created agent is immediately gettable by whatever create handed back.
|
|
/// </remarks>
|
|
/// <param name="ref">Ref is the agent's public id (the agent_… handle create and list return) or its org-unique name, from the path. Either resolves the same agent.</param>
|
|
pplx::task<std::shared_ptr<AgentDetail>> getAgentByRef(
|
|
utility::string_t ref
|
|
) const;
|
|
/// <summary>
|
|
/// Returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns one agent's execution history, newest first — each run's input, its output or its error, and how long it took. Every row is a run that actually happened.
|
|
/// </remarks>
|
|
/// <param name="ref">Ref is the agent's public id or its org-unique name, from the path.</param>
|
|
/// <param name="limit">Limit caps how many runs come back, newest first. Absent, zero or out of range (1..200) reads as 50. (optional, default to 0L)</param>
|
|
pplx::task<std::shared_ptr<RunList>> getAgentByRefRuns(
|
|
utility::string_t ref,
|
|
boost::optional<int64_t> limit
|
|
) const;
|
|
/// <summary>
|
|
/// List the agent threads in your org
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns a summary of every agent conversation in the caller's org — id, derived title, and when it was last appended to — for populating a thread list. Scoped to the caller's org and nothing else, and that isolation is structural rather than a filter: conversations are persisted in a store opened PER ORG, so there is no query in which another tenant's threads could appear. A validated principal with a non-empty org is required; 403 without one.
|
|
/// </remarks>
|
|
pplx::task<void> getAgentChatConversations(
|
|
) const;
|
|
/// <summary>
|
|
/// Read one agent thread in full
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every message of one conversation in order — role, content, the assistant's tool calls where it made any, and each message's creation time — which is the transcript a client replays to resume a thread. The lookup happens inside the caller's OWN per-org store, so an id belonging to another tenant is not refused, it is simply absent: the answer is 200 with an empty message list. Read it as \"no such conversation for you\" rather than as an empty thread. A validated principal with a non-empty org is required; 403 without one.
|
|
/// </remarks>
|
|
/// <param name="id"></param>
|
|
pplx::task<void> getAgentChatConversationsById(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// List the agent presets available to a caller
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the preset catalog: each entry's id, its description and whether it is server-executing — the flag that decides if a preset's tool calls run here or come back for the client to apply. The ids are what the round accepts in `preset`. The catalog is compiled into the build, identical for every caller, and this is the one read in the group that needs no principal.
|
|
/// </remarks>
|
|
pplx::task<void> getAgentChatPresets(
|
|
) const;
|
|
/// <summary>
|
|
/// Serves the invocations-over-time histogram for the org's Agents dashboard.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Serves the invocations-over-time histogram for the org's Agents dashboard. Every point is a REAL count of recorded runs in that time bucket — one series line per agent that ran in the window. The Resource Usage rollup is all-null because this store meters no CPU/memory/storage/cost; the console renders those as \"—\" rather than a fabricated figure. No runs => empty series (an honest \"not connected / no activity yet\"), never a synthesized trend.
|
|
/// </remarks>
|
|
/// <param name="range">Range is the window to bucket: 24H, 7D or 30D. Anything else reads as 30D. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
pplx::task<std::shared_ptr<MetricsView>> getAgentMetrics(
|
|
boost::optional<utility::string_t> range
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the org's agent runs across EVERY agent, newest first — what ran here, for whom, on which model, how long it took, and why it failed.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the org's agent runs across EVERY agent, newest first — what ran here, for whom, on which model, how long it took, and why it failed. It is the feed the per-agent history could not be: an operator asking \"what is this tenant's agent plane doing\" does not start out knowing an agent ref, and answering by listing the agents and then paging each one's history is N+1 round trips to reconstruct one ordering the database already has (RunsSince, ordered by created_at over the org index). The org is the CALLER's, resolved from identity by tenantStore — never a parameter. There is deliberately no org field on orgRunsQuery to forge: run history is the tenant's own record, and the only tenant this can answer for is the one asking.
|
|
/// </remarks>
|
|
/// <param name="limit">Limit caps how many runs come back, newest first. Absent, zero or out of range (1..200) reads as 50. (optional, default to 0L)</param>
|
|
/// <param name="status">Status keeps only runs with this outcome (\"ok\" or \"error\"). Empty keeps both. It is the filter an operator reaches for first — \"show me what broke\" — and answering it here rather than by paging the whole history client-side is the difference between a usable feed and a download. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
pplx::task<std::shared_ptr<RunList>> getAgentRuns(
|
|
boost::optional<int64_t> limit,
|
|
boost::optional<utility::string_t> status
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event. With no filter it returns ROOT sessions only, so a dashboard shows one row per flow rather than one per subagent; ?root= or ?parent= descends.
|
|
/// </remarks>
|
|
/// <param name="root">Root scopes the page to one subagent tree (its root session id). (optional, default to utility::conversions::to_string_t(""))</param>
|
|
/// <param name="parent">Parent scopes the page to the direct children of one session. Ignored when root is set; with neither, only ROOT sessions come back. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
/// <param name="status">Status filters to running, paused, done or error. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
/// <param name="project">Project filters to the sessions tagged with one product slug. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
/// <param name="room">Room filters to the sessions started in one collaborative room — the query a space view runs to show what has been run in it. (optional, default to utility::conversions::to_string_t(""))</param>
|
|
/// <param name="limit">Limit caps the page. Absent, zero or over 500 reads as 100. (optional, default to 0L)</param>
|
|
pplx::task<std::shared_ptr<SessionList>> getAgentSessions(
|
|
boost::optional<utility::string_t> root,
|
|
boost::optional<utility::string_t> parent,
|
|
boost::optional<utility::string_t> status,
|
|
boost::optional<utility::string_t> project,
|
|
boost::optional<utility::string_t> room,
|
|
boost::optional<int64_t> limit
|
|
) const;
|
|
/// <summary>
|
|
/// Returns one session with its direct child sessions and its 50 most recent events, oldest of those first.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns one session with its direct child sessions and its 50 most recent events, oldest of those first.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<SessionDetail>> getAgentSessionsById(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the steering commands (pause/resume/stop/message) recorded against the caller's own session that are newer than the cursor, oldest first, with the cursor to poll from next.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the steering commands (pause/resume/stop/message) recorded against the caller's own session that are newer than the cursor, oldest first, with the cursor to poll from next. It is how a locally started `hanzo code` session — which is not task-backed, so nothing forwards its commands to an execution engine — consumes what the dashboard posted. Read-only and bounded at 200 per poll, so a steady poll is cheap and an applied command is never redelivered.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session whose commands are being drained, from the path.</param>
|
|
/// <param name="after">After is the last seq this poller applied; only commands newer than it come back. Absent or negative reads as 0, which drains from the beginning. (optional, default to 0L)</param>
|
|
pplx::task<std::shared_ptr<ControlDrain>> getAgentSessionsByIdControl(
|
|
utility::string_t id,
|
|
boost::optional<int64_t> after
|
|
) const;
|
|
/// <summary>
|
|
/// Returns how far along one run is: the share of its goal that is done, whether it is running, blocked or finished, and a line saying what it is doing right now.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns how far along one run is: the share of its goal that is done, whether it is running, blocked or finished, and a line saying what it is doing right now. It is a MODEL ESTIMATE read off the run's own transcript, not a measurement — `estimated` says so on every answer, and a run whose progress cannot be told reports phase \"unknown\" with no percentage rather than a zero it does not mean. A session that has already finished answers from its own status instead, and is marked not estimated. The list and detail reads carry the same value; this address is the one that WAITS. Where the stored estimate has gone stale it is remade before answering, so a human deciding whether to step into a run gets a current reading rather than the last poll's — which costs one small completion, charged to the same wallet the session already names, at most once every thirty seconds per run.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<SessionProgress>> getAgentSessionsByIdProgress(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Returns the subagent-flow graph rooted at this session: the session, its children, their children, each node carrying its own event count.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the subagent-flow graph rooted at this session: the session, its children, their children, each node carrying its own event count. One indexed read pulls the whole flow (every node of a flow shares a root id), so the shape is assembled in memory rather than by walking the store per node.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<TreeNode>> getAgentSessionsByIdTree(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Live session and event updates for the caller's org, as Server-Sent Events.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Holds the connection open as text/event-stream and pushes a frame each time the org's registry moves: an `event: session` frame carrying the same session shape the list and detail reads answer with (a registration, an update, or a login-manager revoke tearing a session down), and an `event: event` frame carrying one appended turn. Optional ?root=<session id> narrows the feed to a single subagent tree. Requires a validated principal carrying an org; 403 without one. Org-scoped fail-closed: the bus filters on tenant before it fans out, so a subscriber only ever receives its own org's updates, and ?root= narrows that further but can never widen it. Delivery is best-effort and the GET reads remain the source of truth. A subscriber that falls more than 256 frames behind is DROPPED — its channel is closed and the stream ends — so one stuck dashboard can never back-pressure a session write; the client reconnects and re-reads the session endpoints to resynchronise. A `: ping` comment every 25 seconds holds the connection open through proxies and is how a departed client is noticed.
|
|
/// </remarks>
|
|
pplx::task<void> getAgentSessionsStream(
|
|
) const;
|
|
/// <summary>
|
|
/// Returns every machine registered to the caller's org, newest first, each with its live session load.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns every machine registered to the caller's org, newest first, each with its live session load.
|
|
/// </remarks>
|
|
pplx::task<std::shared_ptr<TargetList>> getAgentTargets(
|
|
) const;
|
|
/// <summary>
|
|
/// Returns one registered machine, with its live session load.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns one registered machine, with its live session load.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the target to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<TargetView>> getAgentTargetsById(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Changes an agent in place.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Changes an agent in place. Every field is optional; a field the request omits keeps its stored value. The resulting mode+schedule are re-validated together, so a partial update can never leave a long-running agent without the cron the scheduler needs to fire it, and a transition INTO long-running counts against the per-org cap on scheduled agents.
|
|
/// </remarks>
|
|
/// <param name="ref">Ref is the agent to update — its public id or org-unique name, from the path.</param>
|
|
/// <param name="updateAgentIn"></param>
|
|
pplx::task<std::shared_ptr<AgentView>> patchAgentByRef(
|
|
utility::string_t ref,
|
|
std::shared_ptr<UpdateAgentIn> updateAgentIn
|
|
) const;
|
|
/// <summary>
|
|
/// Updates a session's surface-owned truth: its status, its title, the run-target it is dispatched to, and the product it built plus whether that build's story is public.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Updates a session's surface-owned truth: its status, its title, the run-target it is dispatched to, and the product it built plus whether that build's story is public. A FINISHED session stays finished — reopening a done/error run would fabricate liveness — and publishing is refused unless the session names the project it built, because the public build route is keyed on (org, project).
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to update, from the path.</param>
|
|
/// <param name="patchSessionIn"></param>
|
|
pplx::task<std::shared_ptr<SessionView>> patchAgentSessionsById(
|
|
utility::string_t id,
|
|
std::shared_ptr<PatchSessionIn> patchSessionIn
|
|
) const;
|
|
/// <summary>
|
|
/// Updates one machine in place.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Updates one machine in place. Every field is optional; a field the request omits is left alone. A metrics patch IS a heartbeat — the server stamps its own clock, so a client can neither forge nor backdate staleness.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the target to update, from the path.</param>
|
|
/// <param name="patchTargetIn"></param>
|
|
pplx::task<std::shared_ptr<TargetView>> patchAgentTargetsById(
|
|
utility::string_t id,
|
|
std::shared_ptr<PatchTargetIn> patchTargetIn
|
|
) const;
|
|
/// <summary>
|
|
/// Defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Defines an agent in the caller's org: a model, a system prompt (instructions) and a set of tool names. The name must be unique in the org and match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$. An omitted model takes the deployment's configured default; a named one is checked against the gateway's served catalog, so a model this deployment never serves is refused here rather than failing at run time. A long-running agent must carry a 5-field cron schedule (the scheduler would otherwise never fire it) and counts against a per-org cap on scheduled agents.
|
|
/// </remarks>
|
|
/// <param name="createAgentIn"></param>
|
|
pplx::task<std::shared_ptr<AgentView>> postAgent(
|
|
std::shared_ptr<CreateAgentIn> createAgentIn
|
|
) const;
|
|
/// <summary>
|
|
/// Run one of your org's agents and get the recorded run back.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Composes the agent's stored instructions with the caller's `input`, executes one real chat completion through the same in-process AI client the rest of the console uses, and answers with the run that was recorded: its id, status, model, output, duration and error. Every run this returns reflects an execution that actually happened — a model failure is recorded and reported, never hidden and never fabricated. A transient upstream failure (429, 5xx, empty choices) is retried up to three times with jittered backoff, and a configured failover model is tried before the run is called an error. `ref` is the agent's public `agent_…` id or its org-unique name; either resolves the same agent, and it must belong to the caller's org, so an agent in another tenant is a 404 exactly like one that does not exist. A validated principal is required and the check is made twice on purpose: this route MOVES MONEY, so the debit's principal requirement is asserted where the money moves rather than inherited from the tenant lookup. The org's balance is authorized BEFORE any inference, so an unfunded tenant gets 402 and no free compute, and a billing plane that cannot answer gets 503 rather than a free run. The flat per-run fee is an operator knob; setting it to zero makes runs free and removes the balance gate with them. Only a SUCCESSFUL run is billed, attributed to the model actually used — a failover run bills the model it fell over to, not the one it started on. A deployment with no inference wired answers 503 before any of this. THE RULE A READER GETS WRONG: a failed run is a 502 whose body is the RUN, not an error envelope. The execution happened, the run was persisted to this agent's history, and its `error` field is the product — so a client that treats every non-2xx as an opaque failure throws away the only account of what went wrong. Each run also opens a root session in the live session registry, best-effort: a bookkeeping failure there never fails the run, because the run and its billing already happened.
|
|
/// </remarks>
|
|
/// <param name="ref"></param>
|
|
pplx::task<void> postAgentByRefRun(
|
|
utility::string_t ref
|
|
) const;
|
|
/// <summary>
|
|
/// Run one tool-calling round against your org's own tools
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Answers one turn of a conversation with four things: the model's `reply`, the `actions` the server executed on the caller's behalf, the `ops` the client must apply itself, and the `conversationId` the turn was recorded under. The split between actions and ops is the rule most easily got wrong. A tool call is executed HERE only when the chosen preset is server-executing AND the tool resolves in the caller's own scope; every other call is handed back as an op for the client to apply to its own graph or UI. A tool that fails still comes back as an action, carrying its error rather than failing the round. `preset` selects the system prompt and the tool set (`capability` is a legacy alias for it); an unknown one is refused. `conversationId` continues an existing thread, and its absence starts one. A validated principal with a non-empty org is required — the org is the sole authority for both persistence and tool scope, and is NEVER read from the body. A completion refused for the caller's own reason — 402 insufficient balance, 429, 403 — is relayed with its own status and body verbatim, so the real billing message reaches the client instead of an opaque gateway error. Only a genuine upstream fault becomes a 502.
|
|
/// </remarks>
|
|
pplx::task<void> postAgentChat(
|
|
) const;
|
|
/// <summary>
|
|
/// Record turns in a conversation
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Writes turns to the caller's thread store without running a completion, and answers the `conversationId` they were written under. An absent `conversationId` opens a new thread; supplying one appends to it. This is for a client that streams its own turn through /v1/chat/completions and still wants the conversation in its history — the round records what IT answers, and is otherwise the only writer. It takes the same store, the same per-org isolation and the same notion of a thread: what is recorded here reads back through the two GETs beside it and the round can continue it by id. A validated principal with a non-empty org is required; 403 without one.
|
|
/// </remarks>
|
|
pplx::task<void> postAgentChatConversations(
|
|
) const;
|
|
/// <summary>
|
|
/// Start one autonomous coding run against a repo in the caller's org
|
|
/// </summary>
|
|
/// <remarks>
|
|
///
|
|
/// </remarks>
|
|
/// <param name="codingStartIn"></param>
|
|
pplx::task<std::shared_ptr<CodingStarted>> postAgentCoding(
|
|
std::shared_ptr<CodingStartIn> codingStartIn
|
|
) const;
|
|
/// <summary>
|
|
/// Opens a live agent session in the caller's org — the row every surface (the CLI's outer agent, hanzo.bot, the console, chat) hangs its activity off.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Opens a live agent session in the caller's org — the row every surface (the CLI's outer agent, hanzo.bot, the console, chat) hangs its activity off. A session with a parentSessionId becomes a subagent of that session and inherits its root, so one flow is one tree; without one it is itself a root. Registering with a terminal status records a session that has already finished.
|
|
/// </remarks>
|
|
/// <param name="registerReq"></param>
|
|
pplx::task<std::shared_ptr<SessionView>> postAgentSessions(
|
|
std::shared_ptr<RegisterReq> registerReq
|
|
) const;
|
|
/// <summary>
|
|
/// Records one turn of a session's transcript and answers 201 with it.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Records one turn of a session's transcript and answers 201 with it. A `progress` turn additionally MOVES THE SESSION'S PROGRESS, marked as the run's own word rather than an estimate, and pushes the updated session onto the live stream — so a board's bar follows the run without polling and without a second write path. See progress.go. THE TURN IS SCANNED BEFORE IT IS STORED. The same engine the code-security surface runs reads the payload at this boundary, and a credential in it refuses the append with 422 rather than redacting it — a redacted transcript is one that still had the secret in it once, and this way the author learns which value to rotate. The refusal carries every finding: the rule, the severity, the line, a MASKED preview and the fingerprint. The secret is never in the answer.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to append to, from the path.</param>
|
|
/// <param name="eventIn"></param>
|
|
pplx::task<std::shared_ptr<EventView>> postAgentSessionsByIdEvents(
|
|
utility::string_t id,
|
|
std::shared_ptr<EventIn> eventIn
|
|
) const;
|
|
/// <summary>
|
|
/// Sends a steering message to a running session — the endpoint a human or another agent interrupts through.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Sends a steering message to a running session — the endpoint a human or another agent interrupts through. It requires a `message` or a `payload`; the other three commands do not.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to steer, from the path.</param>
|
|
/// <param name="controlIn"></param>
|
|
pplx::task<std::shared_ptr<ControlResult>> postAgentSessionsByIdMessage(
|
|
utility::string_t id,
|
|
std::shared_ptr<ControlIn> controlIn
|
|
) const;
|
|
/// <summary>
|
|
/// Asks a running session to pause.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Asks a running session to pause. Recorded durably, and forwarded to the durable-execution engine when the session is task-backed.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to steer, from the path.</param>
|
|
/// <param name="controlIn"></param>
|
|
pplx::task<std::shared_ptr<ControlResult>> postAgentSessionsByIdPause(
|
|
utility::string_t id,
|
|
std::shared_ptr<ControlIn> controlIn
|
|
) const;
|
|
/// <summary>
|
|
/// Asks a paused session to continue, on the same terms as a pause.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Asks a paused session to continue, on the same terms as a pause.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to steer, from the path.</param>
|
|
/// <param name="controlIn"></param>
|
|
pplx::task<std::shared_ptr<ControlResult>> postAgentSessionsByIdResume(
|
|
utility::string_t id,
|
|
std::shared_ptr<ControlIn> controlIn
|
|
) const;
|
|
/// <summary>
|
|
/// Ends a running session.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Ends a running session. `message` is recorded as the cancellation reason, which is what a later reader of the transcript sees. STOPPING IS NOT DELETING: the session, its transcript and anything it produced stay readable. A session that has already finished is 409 rather than a second stop.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the session to steer, from the path.</param>
|
|
/// <param name="controlIn"></param>
|
|
pplx::task<std::shared_ptr<ControlResult>> postAgentSessionsByIdStop(
|
|
utility::string_t id,
|
|
std::shared_ptr<ControlIn> controlIn
|
|
) const;
|
|
/// <summary>
|
|
/// Registers a machine as an agent target, or re-links one that is already registered.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Registers a machine as an agent target, or re-links one that is already registered. Re-linking is idempotent and keyed on org+host+owner, so a machine that reconnects refreshes its own row rather than piling up duplicates; it answers 200, while a first registration answers 201.
|
|
/// </remarks>
|
|
/// <param name="targetReq"></param>
|
|
pplx::task<std::shared_ptr<TargetView>> postAgentTargets(
|
|
std::shared_ptr<TargetReq> targetReq
|
|
) const;
|
|
/// <summary>
|
|
/// ClaimRoutedRun is the machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// ClaimRoutedRun is the machine's long poll for work: it authenticates the daemon, stamps the liveness the dispatch gate reads (the poll IS the proof a runner is listening), and waits up to 25 seconds for the next run addressed to THIS machine. It answers the run when one arrives and 204 with no body when the window elapses, on which the daemon re-polls immediately. TWO independent proofs are required and both fail closed to the same 403: the caller must own this machine (or be an org admin) AND present its claim key in X-Target-Key. A run offered to one machine is unreachable from another's claim.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the target to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<RoutedRunOut>> postAgentTargetsByIdClaim(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Mints (or rotates) the claim key a `hanzo code --serve` daemon presents to claim work for this machine, and returns it ONCE: only its SHA-256 hash is stored.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Mints (or rotates) the claim key a `hanzo code --serve` daemon presents to claim work for this machine, and returns it ONCE: only its SHA-256 hash is stored. Rotating supersedes any prior daemon, so only the machine's owner — or an org admin — may call it; every other caller gets the same not-found an unknown id gets, and learns nothing about what exists.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the target to act on, from the path.</param>
|
|
pplx::task<std::shared_ptr<ClaimKeyOut>> postAgentTargetsByIdKey(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Completes a claimed run: it delivers the terminal result to the run's durable owner, which is what lets that workflow finish.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Completes a claimed run: it delivers the terminal result to the run's durable owner, which is what lets that workflow finish. Scoped to (org, target, run) and claim-key authenticated, so a machine can only ever report a run it legitimately holds. Idempotent — a report for an unknown or already-finished run answers delivered:false rather than failing, because the session's terminal state was already set by the machine's own stream.
|
|
/// </remarks>
|
|
/// <param name="id">ID is the machine reporting, from the path.</param>
|
|
/// <param name="runId">RunID is the routed run being completed, from the path.</param>
|
|
/// <param name="reportRunIn"></param>
|
|
pplx::task<std::shared_ptr<ReportOut>> postAgentTargetsByIdRunsByRunidReport(
|
|
utility::string_t id,
|
|
utility::string_t runId,
|
|
std::shared_ptr<ReportRunIn> reportRunIn
|
|
) const;
|
|
|
|
protected:
|
|
std::shared_ptr<const ApiClient> m_ApiClient;
|
|
};
|
|
|
|
}
|
|
}
|
|
|
|
#endif /* HANZO_API_AgentApi_H_ */
|
|
|