@buoy-gg/agent-core 7.0.53 → 7.0.55

package/lib/typescript/hosted/protocol.d.ts

@@ -0,0 +1,218 @@
+/**
+ * The wire contract between Ask Buoy and the hosted gateway at ai.buoy.gg.
+ *
+ * ONE table, read by both sides: the gateway builds every error reply from
+ * `HOSTED_ERRORS`, and the app decides what to do from the same row. So a new
+ * code is one entry here, and the two can never disagree about what a code
+ * means. Apps already installed keep the table they shipped with, which is why
+ * the gateway serves every protocol from `oldestSupported` up (see
+ * ASK_BUOY_HOSTED_SPEC.md, "Wire versions"), and why a code is never renamed
+ * or given a new meaning once shipped — add a new one instead.
+ *
+ * Pure data: no imports, no runtime, safe to load in a Worker and in RN.
+ */
+export declare const HOSTED_PROTOCOL_VERSION = 1;
+export declare const HOSTED_HEADERS: {
+    /** The `buoys1` access token. Not `Authorization`: buoy.gg's Clerk layer claims that one. */
+    readonly session: "X-Buoy-Session";
+    /** One id for the whole ask, made by the app: `ask_` + ULID. */
+    readonly ask: "X-Buoy-Ask";
+    /** Model round within the ask, from 1. */
+    readonly round: "X-Buoy-Round";
+    /** Try number for this round, from 1. */
+    readonly attempt: "X-Buoy-Attempt";
+    readonly protocol: "X-Buoy-Protocol";
+    /** `ask-buoy/<version> <platform>` */
+    readonly client: "X-Buoy-Client";
+    /** Response: the server-made id shown on error cards and in reports. */
+    readonly requestId: "X-Buoy-Request-Id";
+};
+/**
+ * What the app does with an error.
+ *
+ * - `sign_in` — stop; show the sign-in button.
+ * - `refresh_retry` — refresh the access token once, then send the round again.
+ * - `retry_after` — wait `retry_after_ms` (or 1 s, doubling), then send again.
+ * - `trim_retry` — trim older history and send again (the engine's overflow path).
+ * - `none` — stop and show the card.
+ *
+ * Every retrying action shares one budget per round, so no mix of codes can
+ * loop.
+ */
+export type HostedErrorAction = "sign_in" | "refresh_retry" | "retry_after" | "trim_retry" | "none";
+/** The one button an error card offers, besides Copy details. */
+export type HostedErrorButton = "sign_in" | "see_plans" | "billing" | "own_endpoint" | "new_chat" | "try_again" | "report";
+export interface HostedErrorSpec {
+    status: number;
+    action: HostedErrorAction;
+    /** Shown to the user. `{date}` is replaced with the reset date. */
+    message: string;
+    buttons: readonly HostedErrorButton[];
+}
+export declare const HOSTED_ERRORS: {
+    readonly session_missing: {
+        readonly status: 401;
+        readonly action: "sign_in";
+        readonly message: "Sign in to use hosted Ask Buoy.";
+        readonly buttons: readonly ["sign_in"];
+    };
+    readonly session_expired: {
+        readonly status: 401;
+        readonly action: "refresh_retry";
+        readonly message: "Your sign-in ran out. Sign in again.";
+        readonly buttons: readonly ["sign_in"];
+    };
+    readonly session_revoked: {
+        readonly status: 401;
+        readonly action: "sign_in";
+        readonly message: "You were signed out. Sign in again.";
+        readonly buttons: readonly ["sign_in"];
+    };
+    readonly token_not_allowed: {
+        readonly status: 401;
+        readonly action: "sign_in";
+        readonly message: "This sign-in can't use hosted AI. Sign in as a person.";
+        readonly buttons: readonly ["sign_in"];
+    };
+    readonly client_too_old: {
+        readonly status: 426;
+        readonly action: "none";
+        readonly message: "Update Buoy to keep using hosted Ask Buoy.";
+        readonly buttons: readonly [];
+    };
+    readonly plan_not_eligible: {
+        readonly status: 403;
+        readonly action: "none";
+        readonly message: "Hosted Ask Buoy comes with Pro and Business.";
+        readonly buttons: readonly ["see_plans"];
+    };
+    readonly not_in_pilot: {
+        readonly status: 403;
+        readonly action: "none";
+        readonly message: "Hosted Ask Buoy is in a small test right now.";
+        readonly buttons: readonly [];
+    };
+    readonly team_hosted_off: {
+        readonly status: 403;
+        readonly action: "none";
+        readonly message: "Your team admin turned off hosted AI.";
+        readonly buttons: readonly [];
+    };
+    readonly account_frozen: {
+        readonly status: 403;
+        readonly action: "none";
+        readonly message: "Your account has a billing problem.";
+        readonly buttons: readonly ["billing"];
+    };
+    readonly credits_out: {
+        readonly status: 402;
+        readonly action: "none";
+        readonly message: "You used this week's credits. They come back on {date}.";
+        readonly buttons: readonly ["own_endpoint"];
+    };
+    readonly member_cap: {
+        readonly status: 402;
+        readonly action: "none";
+        readonly message: "You hit your team's limit for you. Ask your admin.";
+        readonly buttons: readonly [];
+    };
+    readonly ask_too_costly: {
+        readonly status: 402;
+        readonly action: "none";
+        readonly message: "This ask got too big. Try a smaller ask.";
+        readonly buttons: readonly [];
+    };
+    readonly ask_busy: {
+        readonly status: 409;
+        readonly action: "retry_after";
+        readonly message: "Another ask is still running.";
+        readonly buttons: readonly [];
+    };
+    readonly duplicate_request: {
+        readonly status: 409;
+        readonly action: "none";
+        readonly message: "That was already sent.";
+        readonly buttons: readonly [];
+    };
+    readonly request_too_large: {
+        readonly status: 413;
+        readonly action: "trim_retry";
+        readonly message: "This chat got too long. Start a new chat.";
+        readonly buttons: readonly ["new_chat"];
+    };
+    readonly media_not_allowed: {
+        readonly status: 400;
+        readonly action: "none";
+        readonly message: "Hosted Ask Buoy can't read images yet.";
+        readonly buttons: readonly [];
+    };
+    readonly bad_request: {
+        readonly status: 400;
+        readonly action: "none";
+        readonly message: "Something in the request was wrong.";
+        readonly buttons: readonly ["report"];
+    };
+    readonly rate_limited: {
+        readonly status: 429;
+        readonly action: "retry_after";
+        readonly message: "Too many asks at once. Trying again.";
+        readonly buttons: readonly [];
+    };
+    readonly hosted_paused: {
+        readonly status: 503;
+        readonly action: "none";
+        readonly message: "Hosted AI is paused right now.";
+        readonly buttons: readonly ["own_endpoint"];
+    };
+    readonly upstream_busy: {
+        readonly status: 503;
+        readonly action: "retry_after";
+        readonly message: "The AI is busy. Trying again.";
+        readonly buttons: readonly [];
+    };
+    readonly upstream_error: {
+        readonly status: 502;
+        readonly action: "retry_after";
+        readonly message: "The AI had a problem.";
+        readonly buttons: readonly ["try_again", "report"];
+    };
+    readonly upstream_refused: {
+        readonly status: 403;
+        readonly action: "none";
+        readonly message: "The AI would not answer that.";
+        readonly buttons: readonly ["report"];
+    };
+    readonly internal: {
+        readonly status: 500;
+        readonly action: "none";
+        readonly message: "Something broke on our side.";
+        readonly buttons: readonly ["try_again", "report"];
+    };
+};
+export type HostedErrorCode = keyof typeof HOSTED_ERRORS;
+export declare function isHostedErrorCode(code: unknown): code is HostedErrorCode;
+/** The `error` object, sent as the JSON body before a stream, or as a `data:` frame after. */
+export interface HostedErrorBody {
+    code: HostedErrorCode;
+    message: string;
+    request_id: string | null;
+    action: HostedErrorAction;
+    retry_after_ms: number | null;
+    /** ISO time credits come back, for `credits_out` and `member_cap`. */
+    reset_at: string | null;
+    help_url: string | null;
+}
+/** Frames the gateway adds around the upstream stream. Old apps skip them. */
+export type HostedBuoyFrame = {
+    phase: "start";
+    request_id: string;
+} | {
+    phase: "end";
+    request_id: string;
+    /** null with `pending: true` when the charge had not settled in time. */
+    credits_left: number | null;
+    credits_reset: string | null;
+    charged: number | null;
+    pending?: true;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/lib/typescript/index.d.ts

@@ -16,7 +16,9 @@ export { projectSnapshot, SNAPSHOT_ACTION } from "./catalog/snapshotReads";
 export { normalizeParams, aliasNote, hashQueryKey } from "./catalog/normalizeParams";
 export { createAnthropicProvider } from "./providers/anthropic";
 export { createOpenAIProvider } from "./providers/openai";
-export type { AgentMessage, Provider, ProviderConfig, ProviderRequest, StreamEvent, ThinkingBlock, TokenUsage, ToolCall, ToolResult, } from "./providers/types";
+export * from "./hosted/protocol";
+export { hostedErrorOf } from "./providers/problem";
+export type { AgentMessage, Provider, ProviderConfig, ProviderRequest, RequestMeta, StreamEvent, ThinkingBlock, TokenUsage, ToolCall, ToolResult, } from "./providers/types";
 export { runAgentTurn, runGatedAction, readTargetDigest, digestOf, type GatedActionInput, type GatedActionOutcome, type RunTurnInput, type TurnEvent, type ApprovalAnswer, type StopReason, } from "./engine/runAgentTurn";
 export { EvidenceStore, type EvidenceEntry } from "./engine/evidence";
 export { TokenCalibration } from "./engine/tokenCalibration";

package/lib/typescript/providers/problem.d.ts

@@ -1,10 +1,17 @@
-export type ProblemKind = "throttled" | "overflow" | "auth" | "other";
+import { type HostedErrorBody } from "../hosted/protocol";
+/**
+ * `blocked` is a hosted gateway refusal whose action is not a retry (out of
+ * credits, not signed in, paused…): reported at once, never sent again.
+ */
+export type ProblemKind = "throttled" | "overflow" | "auth" | "blocked" | "other";
 export interface StreamProblem {
     kind: ProblemKind;
     /** HTTP status, when the failure was an HTTP response. */
     status?: number;
     /** A `Retry-After` the endpoint sent, in ms — honoured over the backoff. */
     retryAfterMs?: number;
+    /** The hosted gateway's own error (hosted/protocol.ts), when it sent one. */
+    hosted?: HostedErrorBody;
 }
 export interface ClassifyInput {
     status?: number;
@@ -13,6 +20,8 @@ export interface ClassifyInput {
     message: string;
     /** Raw `Retry-After` header value — seconds, or an HTTP date. */
     retryAfter?: string | null;
+    /** The hosted gateway's error body. Its code decides, ahead of every guess below. */
+    hosted?: HostedErrorBody;
 }
 export declare function classifyProblem(input: ClassifyInput): StreamProblem;
 /**
@@ -27,4 +36,10 @@ export declare function parseRetryAfter(value: string | null | undefined): numbe
  * anything that is not that shape; the message phrases still apply.
  */
 export declare function errorTypeOf(body: string): string | undefined;
+/**
+ * The hosted gateway's error, from a JSON body or a stream frame's `error`
+ * object. Undefined for anything else, including another provider's errors
+ * that happen to have a `code`.
+ */
+export declare function hostedErrorOf(value: string | Record<string, unknown> | null | undefined): HostedErrorBody | undefined;
 //# sourceMappingURL=problem.d.ts.map

package/lib/typescript/providers/types.d.ts

@@ -85,6 +85,7 @@ export type StreamOutcome =
  * two are this side deciding the response cannot be trusted.
  */
 import type { StreamProblem } from "./problem";
+import type { HostedBuoyFrame } from "../hosted/protocol";
 export type StreamErrorKind = 
 /** The provider reported it: HTTP error, or an `error` event on a 200. */
 "provider"
@@ -105,6 +106,11 @@ export type StreamEvent = {
     type: "thinking";
     block: ThinkingBlock;
 }
+/** Credits and the request id, from the hosted gateway's own frames. */
+ | {
+    type: "meter";
+    frame: HostedBuoyFrame;
+}
 /** Mid-stream provider error. Anthropic can emit these on a committed 200. */
  | {
     type: "error";
@@ -148,6 +154,18 @@ export interface TokenUsage {
     cacheRead?: number;
     cacheWrite?: number;
 }
+/**
+ * Which call this is, for a gateway that meters per ask (the hosted Ask Buoy
+ * gateway sends these as X-Buoy-Ask / -Round / -Attempt; see hosted/protocol.ts).
+ */
+export interface RequestMeta {
+    /** One id for the whole turn. */
+    askId: string;
+    /** Model round within the turn, from 1. */
+    round: number;
+    /** Try number for this round, from 1. */
+    attempt: number;
+}
 export interface ProviderRequest {
     messages: AgentMessage[];
     system: string;
@@ -162,6 +180,7 @@ export interface ProviderRequest {
     model: string;
     maxTokens: number;
     signal?: AbortSignal;
+    meta?: RequestMeta;
 }
 export interface ProviderConfig {
     /** The org's gateway, or the provider's own URL for the dev-only direct mode. */
@@ -170,9 +189,15 @@ export interface ProviderConfig {
      * Fresh headers per request, so short-lived tokens from the host app's own
      * session work. This is why Buoy stores no credential of its own.
      */
-    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    headers?: (meta?: RequestMeta) => Record<string, string> | Promise<Record<string, string>>;
     /** Dev-only direct mode. Never for a distributed build. */
     apiKey?: string;
+    /**
+     * The endpoint is Buoy's hosted gateway (ai.buoy.gg, hosted/protocol.ts).
+     * Only then are its error codes and `buoy` frames trusted: your own
+     * endpoint could send a lookalike code and change what the engine retries.
+     */
+    hosted?: boolean;
     model: string;
     maxTokens?: number;
     /** Anthropic API version header. Ignored by the OpenAI adapter. */