@theokit/sdk 4.53.0 → 4.54.0

package/dist/cron-DxxeQ-sK.d.cts

@@ -0,0 +1,240 @@
+import { Workflow, WorkflowRun } from './workflow.cjs';
+import { ad as SDKUserMessage, b as Run } from './run-BYSHf58D.cjs';
+import { A as AgentOptions, d as ListResult } from './agent-CIUgz7cN.cjs';
+
+/**
+ * Runtime hosting a cron job. Mirrors the agent runtime split.
+ *
+ * - `local` — the in-process scheduler activated via `Cron.start()` fires the
+ *   job while the host process is alive.
+ * - `cloud` — Theo PaaS schedules the job server-side; fires independent of
+ *   any SDK process.
+ *
+ * @public
+ */
+type CronRuntime = "local" | "cloud";
+/**
+ * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
+ *
+ * @public
+ */
+type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
+/**
+ * Persistent cron-scheduled invocation of the Theo agent or a workflow.
+ *
+ * Exactly one target is set: {@link CronJob.agent} (ephemeral agent created on
+ * each fire), {@link CronJob.agentId} (bound to an existing agent for context
+ * continuity), or {@link CronJob.workflow} (a committed workflow run per fire;
+ * SE35). Agent targets carry a `message`; a workflow target carries `inputData`.
+ *
+ * @public
+ */
+interface CronJob {
+    id: string;
+    name?: string;
+    /** Standard 5-field POSIX cron expression or shorthand (`@hourly`, `@daily`, ...). */
+    cron: string;
+    /** IANA timezone identifier. Defaults to `"UTC"`. */
+    timezone?: string;
+    /** Message sent to the agent on each fire. Present for agent targets; absent for a workflow target. */
+    message?: string | SDKUserMessage;
+    /** Ephemeral agent options. Mutually exclusive with `agentId`/`workflow`. */
+    agent?: AgentOptions;
+    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`/`workflow`. */
+    agentId?: string;
+    /**
+     * SE35 — a committed {@link Workflow} run on each fire (`workflow.run(inputData)`).
+     * Mutually exclusive with `agent`/`agentId`. Held in-memory (local runtime only —
+     * a workflow instance cannot cross the cloud process boundary). ADR 0014.
+     */
+    workflow?: Workflow;
+    /** SE35 — input passed to `workflow.run(inputData)` on each fire. Workflow targets only. */
+    inputData?: unknown;
+    /** Whether the scheduler will fire this job on schedule. */
+    enabled: boolean;
+    /** Current status. */
+    status: CronJobStatus;
+    /** Runtime that hosts this job. Inferred from `agent`/`agentId`/`workflow` at create time (a `workflow` target is always `local`). */
+    runtime: CronRuntime;
+    /** Unix ms of the last successful fire, if any. */
+    lastRunAt?: number;
+    /** Unix ms of the next scheduled fire, computed by the scheduler. */
+    nextRunAt?: number;
+    /** Unix ms when the job was created. */
+    createdAt: number;
+}
+/**
+ * Options for `Cron.create()`.
+ *
+ * Pass exactly ONE target: `agent` (ephemeral agent fresh per fire), `agentId`
+ * (reuse an existing agent — preserves conversation context), or `workflow`
+ * (SE35 — run a committed workflow per fire). Agent targets REQUIRE `message`;
+ * a workflow target takes `inputData` and MUST NOT set `message`. Violations are
+ * a `ConfigurationError`.
+ *
+ * @public
+ */
+interface CronCreateOptions {
+    cron: string;
+    /** Message for an agent target. Required with `agent`/`agentId`; forbidden with `workflow`. */
+    message?: string | SDKUserMessage;
+    agent?: AgentOptions;
+    agentId?: string;
+    /** SE35 — a committed {@link Workflow} to run per fire. Mutually exclusive with `agent`/`agentId`. */
+    workflow?: Workflow;
+    /** SE35 — input for `workflow.run(inputData)`. Workflow targets only. */
+    inputData?: unknown;
+    name?: string;
+    timezone?: string;
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Falls back to `THEOKIT_API_KEY`. */
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.list()`.
+ *
+ * @public
+ */
+type CronListOptions = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    runtime?: undefined;
+} | {
+    runtime: "local";
+    cwd?: string;
+} | {
+    runtime: "cloud";
+    apiKey?: string;
+});
+/**
+ * Options for `Cron.get()`.
+ *
+ * @public
+ */
+interface CronGetOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
+ *
+ * @public
+ */
+interface CronOperationOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.run()` — manually trigger a job off-schedule.
+ *
+ * @public
+ */
+interface CronRunOptions {
+    cwd?: string;
+    apiKey?: string;
+}
+/**
+ * Options for `Cron.start()` — activates the in-process scheduler for local
+ * jobs.
+ *
+ * @public
+ */
+interface CronStartOptions {
+    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Override the env API key. */
+    apiKey?: string;
+}
+/**
+ * Snapshot of the local scheduler returned by `Cron.status()`.
+ *
+ * @public
+ */
+interface CronSchedulerStatus {
+    /** Whether the in-process scheduler is currently running. */
+    running: boolean;
+    /** Number of jobs loaded into the scheduler. */
+    jobCount: number;
+    /** Unix ms of the next scheduled fire across all jobs, if any. */
+    nextFireAt?: number;
+    /** Last error observed in the scheduler, if any. */
+    lastError?: {
+        jobId: string;
+        message: string;
+        at: number;
+    };
+}
+
+/**
+ * Static façade for scheduling Theo agent runs on a cron expression.
+ *
+ * @public
+ */
+declare class Cron {
+    private constructor();
+    /**
+     * Create and persist a cron job.
+     *
+     * @public
+     */
+    static create(options: CronCreateOptions): Promise<CronJob>;
+    /**
+     * List cron jobs (local, cloud, or both).
+     *
+     * @public
+     */
+    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
+    /**
+     * Get a single cron job by ID.
+     *
+     * @public
+     */
+    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
+    /**
+     * Delete a cron job permanently.
+     *
+     * @public
+     */
+    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
+    /**
+     * Re-enable a paused cron job.
+     *
+     * @public
+     */
+    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Pause a cron job without deleting it.
+     *
+     * @public
+     */
+    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
+    /**
+     * Manually trigger a cron job off-schedule. Returns the resulting `Run`
+     * (agent target) or `WorkflowRun` (workflow target — SE35).
+     *
+     * @public
+     */
+    static run(jobId: string, _options?: CronRunOptions): Promise<Run | WorkflowRun>;
+    /**
+     * Activate the in-process scheduler for local cron jobs.
+     *
+     * @public
+     */
+    static start(options?: CronStartOptions): Promise<void>;
+    /**
+     * Stop the in-process scheduler. Jobs are preserved.
+     *
+     * @public
+     */
+    static stop(): Promise<void>;
+    /**
+     * Snapshot of the local scheduler.
+     *
+     * @public
+     */
+    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
+}
+
+export { Cron as C, type CronCreateOptions as a, type CronGetOptions as b, type CronJob as c, type CronJobStatus as d, type CronListOptions as e, type CronOperationOptions as f, type CronRunOptions as g, type CronRuntime as h, type CronSchedulerStatus as i, type CronStartOptions as j };

package/dist/cron.cjs

@@ -1,60 +1,62 @@
 'use strict';
 
-var chunkQN5N3ZVT_cjs = require('./chunk-QN5N3ZVT.cjs');
-require('./chunk-2VFZQEDW.cjs');
-require('./chunk-2QMK627M.cjs');
-require('./chunk-3YYDHUNH.cjs');
+var chunkTTHBHAJI_cjs = require('./chunk-TTHBHAJI.cjs');
+require('./chunk-UFAO4T7Z.cjs');
+require('./chunk-5BJV5UPY.cjs');
+require('./chunk-5UOVYM3P.cjs');
+require('./chunk-53CBTBWO.cjs');
 require('./chunk-BV2MWEMV.cjs');
-require('./chunk-6DCTL32L.cjs');
+require('./chunk-NGESVVJN.cjs');
 require('./chunk-BUUUWQMB.cjs');
-require('./chunk-T5ZWI3MC.cjs');
-require('./chunk-DM6Y5B2G.cjs');
-require('./chunk-RAACTJ7C.cjs');
-require('./chunk-4JBHSLQO.cjs');
-require('./chunk-3R4ZCQAZ.cjs');
-require('./chunk-EQMLJ52C.cjs');
-require('./chunk-BBZYXVLZ.cjs');
-require('./chunk-OKLYRPKL.cjs');
-require('./chunk-CZHPR2G7.cjs');
-require('./chunk-ADVZIC43.cjs');
-require('./chunk-E3OCRJU6.cjs');
-require('./chunk-2RW7K6FN.cjs');
+require('./chunk-EI2Q7SJ5.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-YPJ5NH5N.cjs');
+require('./chunk-UNDROG5N.cjs');
+require('./chunk-F3YZMOAU.cjs');
+require('./chunk-4OTIXDMU.cjs');
+require('./chunk-DQKERTND.cjs');
+require('./chunk-CTCGWIUD.cjs');
+require('./chunk-2ZPEDVLM.cjs');
+require('./chunk-Q47R5E2X.cjs');
+require('./chunk-U2AC6JUP.cjs');
 require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-WJVHMTKB.cjs');
 require('./chunk-6JSIEDKL.cjs');
 require('./chunk-FRITRLZQ.cjs');
-require('./chunk-B4YA6BRS.cjs');
+require('./chunk-4O5TGQBW.cjs');
 require('./chunk-NINIJCHU.cjs');
-require('./chunk-L5YO6PWL.cjs');
+require('./chunk-3YJNUKYN.cjs');
+require('./chunk-ZNW6V4Y6.cjs');
 require('./chunk-VJ26EKGJ.cjs');
-require('./chunk-KNZU4YO5.cjs');
-require('./chunk-NFATC6ZF.cjs');
-require('./chunk-T6QUCG7L.cjs');
-require('./chunk-ECPL5RV6.cjs');
-require('./chunk-TR4V2LHV.cjs');
-require('./chunk-QLAWEGTZ.cjs');
-require('./chunk-YLQQX5W2.cjs');
-require('./chunk-7HQVDLFI.cjs');
-require('./chunk-WJVHMTKB.cjs');
-require('./chunk-2CFEET3Y.cjs');
-require('./chunk-RTLUZKDL.cjs');
-require('./chunk-AMYY3JHQ.cjs');
-require('./chunk-VYHJZVL5.cjs');
-require('./chunk-BC5EUG7R.cjs');
-require('./chunk-33L2NVTJ.cjs');
-require('./chunk-NUEL6RCZ.cjs');
-require('./chunk-C6Y6CWYD.cjs');
-require('./chunk-FUASIT3E.cjs');
-require('./chunk-YTO5BRBD.cjs');
+require('./chunk-R3UPQFKK.cjs');
 require('./chunk-VKJ7V7EB.cjs');
-require('./chunk-44IISBRZ.cjs');
-require('./chunk-2YGIBOUH.cjs');
-require('./chunk-SXSPMRSV.cjs');
+require('./chunk-ILCGLTSA.cjs');
+require('./chunk-CQGYNZ3K.cjs');
+require('./chunk-4I55V454.cjs');
+require('./chunk-JHPGF3FP.cjs');
+require('./chunk-SKXBJ2NU.cjs');
+require('./chunk-2ADR2GSO.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-2C72DXQF.cjs');
+require('./chunk-I6TGFUCO.cjs');
+require('./chunk-HJBMA5MB.cjs');
+require('./chunk-IWBGCBR6.cjs');
+require('./chunk-XSX2UU6Y.cjs');
+require('./chunk-3EE6LVWT.cjs');
+require('./chunk-3KGLRRFC.cjs');
+require('./chunk-RM7Y65IG.cjs');
+require('./chunk-5USCYPPI.cjs');
+require('./chunk-BVZW2B5V.cjs');
+require('./chunk-52NKC5HT.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
 
 
 
 Object.defineProperty(exports, "Cron", {
   enumerable: true,
-  get: function () { return chunkQN5N3ZVT_cjs.Cron; }
+  get: function () { return chunkTTHBHAJI_cjs.Cron; }
 });
 //# sourceMappingURL=cron.cjs.map
 //# sourceMappingURL=cron.cjs.map

package/dist/cron.d.cts

@@ -1,4 +1,6 @@
-export { C as Cron } from './cron-DgHJnMAK.cjs';
-import './run-C8FBAC8o.cjs';
-import './agent-Zta1kvGH.cjs';
+import './workflow.cjs';
+import './run-BYSHf58D.cjs';
+import './agent-CIUgz7cN.cjs';
+export { C as Cron } from './cron-DxxeQ-sK.cjs';
 import 'zod';
+import './sdk-agent-DEoKhA8a.cjs';

package/dist/cron.d.ts

@@ -1,4 +1,6 @@
-export { C as Cron } from './cron-DyWQsEG6.js';
-import './run-C8FBAC8o.js';
-import './agent-BiCINq25.js';
+import './workflow.js';
+import './run-BYSHf58D.js';
+import './agent-DSec-E0c.js';
+export { C as Cron } from './cron-CRwy2JBF.js';
 import 'zod';
+import './sdk-agent-D8qJVkuV.js';

package/dist/cron.js

@@ -1,51 +1,53 @@
-export { Cron } from './chunk-3SHW7XKK.js';
-import './chunk-NZOR3N4E.js';
-import './chunk-I5OTK2RP.js';
-import './chunk-OIBHY6JQ.js';
+export { Cron } from './chunk-AGSBJD2L.js';
+import './chunk-TPTZA6NI.js';
+import './chunk-DUIF54UP.js';
+import './chunk-DAPSQZT4.js';
+import './chunk-YMA4S2WO.js';
 import './chunk-2SFBB54R.js';
-import './chunk-7TB5U7RK.js';
+import './chunk-SUKXXLWD.js';
 import './chunk-K2BQQ445.js';
-import './chunk-634YVZLU.js';
-import './chunk-2Y5NO2SY.js';
-import './chunk-DHVNJYTO.js';
-import './chunk-4QEC4CCS.js';
-import './chunk-UJ3SXRZZ.js';
-import './chunk-NOS7PTKP.js';
-import './chunk-AM2CNBKE.js';
-import './chunk-34XOCZJO.js';
-import './chunk-L7EGRCKJ.js';
-import './chunk-EFXJ5C7X.js';
-import './chunk-OZXPA3ME.js';
-import './chunk-OXNYIMZZ.js';
+import './chunk-XN7NOENA.js';
+import './chunk-H73MEMQB.js';
+import './chunk-GJ6RK75E.js';
+import './chunk-VDEWG5TV.js';
+import './chunk-3E77SX4H.js';
+import './chunk-WTMU7J4U.js';
+import './chunk-5JLFFPCH.js';
+import './chunk-BMAZLQQ4.js';
+import './chunk-HKCKOAIO.js';
+import './chunk-5PHVENFV.js';
+import './chunk-UPRJR6IP.js';
 import './chunk-FD2UT76F.js';
+import './chunk-4VPXM6UU.js';
 import './chunk-U54XCYG3.js';
 import './chunk-NAF4L3T6.js';
-import './chunk-RP5HQVLD.js';
+import './chunk-RNB4APBZ.js';
 import './chunk-6X6ID4MO.js';
-import './chunk-4NAKHID5.js';
+import './chunk-4ERPXIVB.js';
+import './chunk-GTKFV7O5.js';
 import './chunk-7AD3ZTZL.js';
-import './chunk-ITQ4NO4P.js';
-import './chunk-ZSJPRPN7.js';
-import './chunk-R7TKOQMJ.js';
-import './chunk-C4EU627W.js';
-import './chunk-HTK54K2J.js';
-import './chunk-W4FV7JBH.js';
-import './chunk-2XLKLVVR.js';
-import './chunk-JJZ4NIAG.js';
-import './chunk-4VPXM6UU.js';
-import './chunk-CHVSMEKM.js';
-import './chunk-XGYI2KQH.js';
-import './chunk-KIX45IKP.js';
-import './chunk-X2FR4OIT.js';
-import './chunk-2YWWPCGX.js';
-import './chunk-XRI6DXPZ.js';
-import './chunk-23VZBRDQ.js';
-import './chunk-5NBUH3NO.js';
-import './chunk-BXVSBYGW.js';
-import './chunk-XWCTBGYK.js';
+import './chunk-QARJGQSA.js';
 import './chunk-RIAM53CP.js';
-import './chunk-5XXUYU3M.js';
-import './chunk-HI4ZW62S.js';
-import './chunk-4X3SBHPK.js';
+import './chunk-UC3HT2S4.js';
+import './chunk-OC4NTGMN.js';
+import './chunk-44JAAH4X.js';
+import './chunk-DZBSJX6J.js';
+import './chunk-CQ2TQ32Y.js';
+import './chunk-CV7XMBHP.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-RUDY2GTT.js';
+import './chunk-VF7EWVDG.js';
+import './chunk-2QKTVKH3.js';
+import './chunk-AG5JPQIY.js';
+import './chunk-F7AQV62G.js';
+import './chunk-R7WIIPUR.js';
+import './chunk-SSQZA3DZ.js';
+import './chunk-FXEUP75G.js';
+import './chunk-44MBDIHG.js';
+import './chunk-UQGQFBRL.js';
+import './chunk-3OR54XG4.js';
+import './chunk-IDCKSLYH.js';
+import './chunk-T7XEKOVW.js';
+import './chunk-T7O6K6PX.js';
 //# sourceMappingURL=cron.js.map
 //# sourceMappingURL=cron.js.map

package/dist/define-tool.d.ts

@@ -2,12 +2,6 @@ import type { z as ZodNamespace, ZodType } from "zod";
 import type { SanitizeOptions } from "./sanitize/types.js";
 import type { CustomTool } from "./types/agent.js";
 import type { ToolResultContentBlock } from "./types/content-blocks.js";
-/**
- * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
- * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
- *
- * @public
- */
 /**
  * SE16 — the handler's return type. With no `outputSchema` the tool returns a
  * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
@@ -15,6 +9,20 @@ import type { ToolResultContentBlock } from "./types/content-blocks.js";
  * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
  */
 type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : ZodNamespace.infer<O>;
+/**
+ * Spec accepted by {@link Tool.create}. `inputSchema` is a Zod schema; the `handler` argument type
+ * is inferred via `z.infer<T>` — no `as` casts.
+ *
+ * The two optional output fields do different jobs and compose. `outputSchema` changes what the
+ * handler must RETURN (a structured value instead of a string) and validates it; `toModelOutput`
+ * changes only what the MODEL sees in the tool result, while observability still receives the full
+ * handler output. Set neither and the handler returns a plain string that goes to both.
+ *
+ * `zod` is referenced as a type only, so a consumer that never calls `Tool.create` does not need it
+ * installed.
+ *
+ * @public
+ */
 export interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
     /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
     name: string;

package/dist/{errors-CHllybaU.d.ts → errors-BgJH9PHi.d.cts}

@@ -1,4 +1,4 @@
-import { Q as RunOperation } from './run-C8FBAC8o.js';
+import { Q as RunOperation } from './run-BYSHf58D.cjs';
 
 /**
  * Public type contract for the Budget enforcement primitive
@@ -98,10 +98,14 @@ interface BudgetSnapshot {
  */
 type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
 /**
- * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).
+ * T1.1 — closed literal union for `AgentRunError.code`. The previous
+ * `(string & {})` escape hatch let arbitrary strings slip into the type
+ * surface and defeated exhaustive `switch (code)` discrimination. This is
+ * the canonical closed form. `AgentRunErrorCode` is re-aliased below for
+ * source-level back-compat.
  *
- * Superset of {@link ErrorCode} extended with codes that do NOT originate
- * from a provider HTTP response:
+ * Superset of {@link ErrorCode}, extended with codes that do NOT originate from a
+ * provider HTTP response (Production-Readiness #3, ADR D311):
  *
  * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)
  * - `tool_runtime_error` — custom tool handler threw inside dispatch
@@ -110,19 +114,6 @@ type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" |
  * - `safety_blocked` — provider safety filter blocked req or resp
  * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary
  *
- * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while
- * accepting any string for forward compatibility with constructor calls
- * that pass arbitrary code values (legacy callers).
- *
- * @public
- */
-/**
- * T1.1 — closed literal union for `AgentRunError.code`. The previous
- * `(string & {})` escape hatch let arbitrary strings slip into the type
- * surface and defeated exhaustive `switch (code)` discrimination. This is
- * the canonical closed form. `AgentRunErrorCode` is re-aliased below for
- * source-level back-compat.
- *
  * Adding a new code: append the literal here AND audit every `switch (err.code)`
  * in callers. Type-checker enforces the audit via the `default: assertNever(code)`
  * convention.
@@ -138,6 +129,22 @@ type KnownAgentRunErrorCode = ErrorCode | "quota_exceeded" | "tool_runtime_error
  * @public
  */
 type AgentRunErrorCode = KnownAgentRunErrorCode;
+/**
+ * T1.1 boundary helper — coerce an arbitrary string (typically arriving from
+ * a downstream `RunErrorDetail.code` or a deserialized cloud response) into a
+ * `KnownAgentRunErrorCode`.
+ *
+ * A string that is not one of the known codes collapses to `"unknown"`, and so
+ * does `undefined` — the parameter is optional precisely so a caller can forward
+ * an absent `code` without a guard. The closed type contract therefore holds at
+ * the boundary without forcing every caller to switch.
+ *
+ * This is the migration path the 4.x release notes point at for code that used
+ * to rely on `AgentRunErrorCode` being an open string union.
+ *
+ * @public
+ */
+declare function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode;
 /**
  * Structured context for errors that originated from a provider HTTP
  * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
@@ -486,12 +493,6 @@ declare class BudgetExceededError extends TheokitAgentError {
         cause?: unknown;
     });
 }
-/**
- * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud
- * budget surface waits for Theo PaaS GA.
- *
- * @public
- */
 /**
  * T1.6 — Thrown when a consumer calls `agent.send()` or any method
  * on an agent that has already been `dispose()`d. Pre-T1.6 this was
@@ -505,6 +506,20 @@ declare class AgentDisposedError extends TheokitAgentError {
     readonly agentId: string;
     constructor(agentId: string);
 }
+/**
+ * Thrown when a budget operation is requested on a `CloudAgent` (D388). The cloud budget surface
+ * waits for Theo PaaS GA, so the operation is not merely failing — it does not exist yet.
+ *
+ * Not retryable: `isRetryable` is `false`, and retrying cannot change the outcome until the
+ * feature ships. Catch it by `instanceof`, or by `code === "budget_op_unsupported"` when the
+ * error has crossed a serialization boundary that dropped the prototype. `operation` carries the
+ * name that was refused and is interpolated into the message.
+ *
+ * The local agent does not raise this — the same call against a local agent runs the budget path
+ * normally.
+ *
+ * @public
+ */
 declare class UnsupportedBudgetOperationError extends TheokitAgentError {
     readonly name: string;
     readonly operation: string;
@@ -513,4 +528,4 @@ declare class UnsupportedBudgetOperationError extends TheokitAgentError {
     });
 }
 
-export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, type ErrorMetadata as E, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, TheokitAgentError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, type ErrorCode as m, InvalidTaskIdError as n, type MemoryAdapterErrorCode as o, TaskNotFoundError as p, UnsupportedBudgetOperationError as q, UnsupportedRunOperationError as r, UnsupportedTaskOperationError as s, isTransientError as t, CredentialPoolExhaustedError as u };
+export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, type ErrorMetadata as E, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, TheokitAgentError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, type ErrorCode as m, InvalidTaskIdError as n, type MemoryAdapterErrorCode as o, TaskNotFoundError as p, UnsupportedBudgetOperationError as q, UnsupportedRunOperationError as r, UnsupportedTaskOperationError as s, isTransientError as t, CredentialPoolExhaustedError as u, coerceToKnownAgentRunErrorCode as v };