@oneshot-agent/sdk 0.61.0 → 0.63.0

package/dist/types.d.ts

@@ -219,6 +219,7 @@ export interface ToolOptions {
         idempotencyKey?: string;
     }) => void;
     maxCost?: number;
+    /** Polling limit in seconds. Overrides a tool's manifest timeout or its existing default. */
     timeout?: number;
     signal?: AbortSignal;
     onStatusUpdate?: StatusUpdateFn;
@@ -287,39 +288,19 @@ export interface EmailToolOptions extends ToolOptions {
     reply_to_email_id?: string;
     from_domain?: string;
     /**
-     * Sender mailbox / local-part. Defaults to `agent` (i.e. agent@from_domain).
-     * Requires `from_domain` to be set - pinning `from_mailbox` alone throws a
-     * `ValidationError` (there is no default domain to attach it to). You may
-     * use any local-part - a new address is auto-provisioned on first use
-     * (and starts unwarmed, building reputation over time). See the email
-     * "list domains" tool for each domain's `default_from` and existing `addresses`.
+     * Sender address / local-part on `from_domain`. Defaults to the domain's main
+     * address (its `default_from` in `listDomains()`). Requires `from_domain` -
+     * pinning `from_mailbox` alone throws a `ValidationError`. The address must be
+     * one the domain has: an address it does not have answers
+     * `status: 'confirmation_required'` with the quote that adds it (see
+     * `quoteDomain`), and nothing is sent.
      */
     from_mailbox?: string;
     /**
-     * How this domain sends (provider-neutral):
-     *  - `'relay'` (default) - header/relay send; any from-address works with nothing
-     *    provisioned per address (no mailbox fee).
-     *  - `'mailbox'` - a real per-address mailbox; each new from-address provisions +
-     *    warms a dedicated mailbox (one-time `mailbox_provisioning_fee` on the quote).
-     * Only honored when the domain is first set up - an already-provisioned domain
-     * keeps the mode it was created with. Use `'mailbox'` on a new `from_domain`.
-     *
-     * Which means omitting this is NOT a way to avoid the fee: a domain created in
-     * mailbox mode bills `mailbox_provisioning_fee` for every address that isn't
-     * already `active` on it - the default `agent@` included - whatever you pass
-     * here, and `from_mailbox` doesn't change that either. Read `mailbox_mode` per
-     * domain from `listDomains()` to see which of yours charge.
-     */
-    mailbox_mode?: 'relay' | 'mailbox';
-    /**
-     * Only meaningful when `from_domain` is a domain the agent doesn't own yet.
-     * A call with such a `from_domain` always stops after quoting - no charge,
-     * no send - and returns `status: 'confirmation_required'` with the exact
-     * total and its `quote_id`. Pass that `quote_id` here on the repeat call to
-     * register the domain, pay exactly that quote's total, and send in one call:
-     * the SDK sends against the stored quote instead of quoting again, so the
-     * amount charged is the amount shown. A bare `true` names no amount
-     * and only re-quotes. An expired or used quote is refused by the server.
+     * Accept the exact setup quote (a new domain, or an address added to one).
+     * Buys setup only; no email is sent. Wait for setup to finish, then call
+     * email again without this option. A bare true is not confirmation; expired
+     * or used quotes are refused.
      */
     confirmNewDomain?: string;
     /** Display name shown to the recipient, e.g. "Jane Doe" → "Jane Doe <jane@domain>". */
@@ -491,13 +472,17 @@ export interface ProductFindOptions extends ToolOptions {
 export interface WebSearchOptions extends ToolOptions {
     query: string;
     max_results?: number;
+    /** Only results published within the last day, week, month or year. */
+    published_within?: 'day' | 'week' | 'month' | 'year';
 }
 export interface WebSearchResult {
     query: string;
+    /** `published_at` is the publication date (YYYY-MM-DD) when the provider gives one, otherwise null. */
     results: Array<{
         url: string;
         title: string;
         description: string;
+        published_at: string | null;
     }>;
     result_count: number;
     memo?: string;
@@ -514,6 +499,7 @@ export interface WebReadResult extends UntrustedContent {
     receipt_id?: string;
     url: string;
     markdown: string;
+    /** Private org artifacts: authenticated GET returns download_url/expires_at; GET that URL with the same org session within five minutes. */
     screenshot_url?: string;
     metadata?: {
         title: string;
@@ -642,11 +628,100 @@ export interface ResearchResult {
     memo?: string;
     cost?: number;
 }
+/**
+ * How a domain's addresses work, chosen when the domain is bought and fixed after:
+ *  - `relay` (default): each address sends and receives through the platform, with no hosted inbox. Free per address.
+ *  - `mailbox`: each address is a hosted inbox, warmed before it joins rotation. Each carries a one-time per-address fee.
+ */
+export type MailboxMode = 'relay' | 'mailbox';
+/** What to buy with a domain: its mode and the addresses it has. */
+export interface DomainSetupChoice {
+    /** Defaults to `relay`. On a domain the agent already has, the domain's own mode applies. */
+    mailbox_mode?: MailboxMode;
+    /**
+     * Local parts, such as `['sales', 'support']`: 1 to 10, lowercased, unique. The first is the main
+     * address that rotation and goals send from. Defaults to `['agent']`. The domain has exactly these
+     * addresses: mail to any other is dropped, and a send from one is refused with `address_not_set_up`.
+     * On a verified domain the agent already has, the quote prices only the addresses it does not have yet.
+     */
+    addresses?: string[];
+}
+export interface DomainSetupQuote {
+    domain: string;
+    /** Absent on an address purchase for a domain the agent already has. */
+    available?: boolean;
+    premium?: boolean;
+    purchasable: boolean;
+    reason?: string;
+    /** `sending_domain` buys the domain; `domain_addresses` adds addresses to one the agent already has. */
+    setup?: 'sending_domain' | 'domain_addresses';
+    mailbox_mode?: MailboxMode;
+    /** The local parts this quote buys. */
+    addresses?: string[];
+    /** Named addresses the domain already has; not charged. */
+    already_set_up?: string[];
+    registration_fee?: number;
+    /** The per-address fee times the number of addresses; 0 on relay. */
+    mailbox_provisioning_fee?: number;
+    quote_id?: string;
+    total_cost?: number;
+    currency?: string;
+    expires_at?: string;
+    billing?: {
+        one_time: boolean;
+        term_years: number;
+        renewal_charged: boolean;
+        summary: string;
+    };
+}
+export interface DomainSetupPurchase {
+    request_id?: string;
+    receipt_id?: string;
+    /** Present on the queued response; completed job results report domain_status instead. */
+    status?: string;
+    setup?: 'sending_domain' | 'domain_addresses';
+    domain?: string;
+    mailbox_mode?: MailboxMode;
+    addresses?: string[];
+    domain_status?: string | null;
+    registered?: boolean | null;
+    message?: string;
+}
+/** Account setup a call needs before it can run, as `/email/quote` reports it. */
+export interface SetupRequirement {
+    kind: string;
+    state: string;
+    action_url?: string;
+    setup?: {
+        price: number;
+        currency: 'USD';
+        estimated: boolean;
+        choice?: 'domain_name';
+        choices?: Array<'domain_name' | 'mailbox_mode' | 'addresses'>;
+        domain?: string;
+        addresses?: string[];
+        alternatives?: Array<{
+            action_url: string;
+            price: number;
+            currency: 'USD';
+            choice: 'domain_name';
+            choices?: Array<'domain_name' | 'mailbox_mode' | 'addresses'>;
+        }>;
+    };
+    [key: string]: unknown;
+}
 export interface EmailResult {
+    /** Account setup is separate from this email; inspect its quote or purchase result. */
+    setup?: DomainSetupQuote | DomainSetupPurchase;
+    /**
+     * On `status: 'setup_required'` or `'setup_pending'`: the setup the send needs, from the server's
+     * `no_sending_domain` or `address_not_set_up` answer. Nothing was charged.
+     */
+    requirements?: SetupRequirement[];
     request_id?: string;
     /** On `status: 'confirmation_required'`: the quote to pass back as `confirmNewDomain` to accept exactly this cost. */
     quote_id?: string;
-    /** On `status: 'confirmation_required'`: the explanation to relay, with the exact cost and the confirming call. */
+    /** On `status: 'confirmation_required'`: the setup instructions; the exact cost and billing terms are in setup. */
     message?: string;
     /** Receipt id (`rcpt_…`) for this call. Pass to `tagReceiptValue` to annotate value later. */
     receipt_id?: string;
@@ -657,8 +732,8 @@ export interface EmailResult {
      * Non-blocking advisory from the server. Values:
      * - `pinned_domain_warming` - a pinned sender's domain is still warming (low warmup score)
      * - `pinned_over_limit` - a pinned sender's domain is over its daily_send_limit
-     * The send still proceeds; read this to back off / defer. (Note: an un-pinned
-     * send with no eligible owned domain is a hard `400 no_sending_domain`, not a
+     * The send still proceeds; read this to back off / defer. (A send with no
+     * verified domain answers `status: 'setup_required'` with `requirements`, not a
      * warning - there is no shared fallback sender.)
      */
     warning?: string;
@@ -675,47 +750,37 @@ export interface EmailResult {
     memo?: string;
     cost?: number;
 }
-/** Reputation health, orthogonal to rotation eligibility. */
-export type DomainWarmupState = 'warming' | 'warmed' | 'degraded';
+/**
+ * Reputation health, orthogonal to rotation eligibility. `not_warmed`: a relay domain or address, which is
+ * never warmed and joins rotation at once on a daily limit that rises with the domain's age.
+ */
+export type DomainWarmupState = 'warming' | 'warmed' | 'degraded' | 'not_warmed';
 /** Why a domain is out of rotation (null when active). 'low_reputation' auto-recovers; 'manual' needs a resume. */
 export type DomainPauseReason = 'warming' | 'low_reputation' | 'manual' | null;
-/** A mailbox already provisioned on a domain (from `/email/domains` `addresses[]`). */
+/** An address on a domain (from `/email/domains` `addresses[]`). */
 export interface DomainAddressEntry {
     /** Full email address, lowercased - e.g. `sales@yourdomain.com`. */
     address: string;
-    /** Mailbox provisioning state. Only `active` counts as already-provisioned (free to send from). */
+    /** Only `active` addresses send and receive. `provisioning` is being set up; `failed` was refunded and can be bought again. */
     status: 'active' | 'provisioning' | 'failed';
-    /** Per-address reputation health (each provisioned address is warmed individually). */
+    /** Per-address reputation health: mailbox addresses are warmed one by one; relay addresses are `not_warmed`. */
     warmup_state: DomainWarmupState;
 }
 export interface DomainPoolEntry {
     domain: string;
-    /**
-     * Canonical sending address for this domain (e.g. `agent@yourdomain.com`) - the
-     * default mailbox when you don't pick one. Like any address, the first send from
-     * it incurs the one-time `mailbox_provisioning_fee`; free once it's `active`.
-     */
+    /** The domain's main address (e.g. `agent@yourdomain.com`): rotation and goals send from it. */
     default_from: string;
     /**
-     * Mailboxes already provisioned on this domain. Empty = none yet; you can still
-     * send from any address - a new one is provisioned (and billed
-     * `mailbox_provisioning_fee`) on first use.
+     * The addresses this domain has. It sends and receives only at these; add more with
+     * `quoteDomain(domain, { addresses })` and `buyDomain`.
      */
     addresses: DomainAddressEntry[];
     /**
-     * Which side of the provisioning fee this domain sits on.
-     *
-     * `mailbox` - a real mailbox is provisioned per address, so every address
-     * that isn't already `active` in `addresses[]` bills the one-time
-     * `mailbox_provisioning_fee` on its first send. That includes the canonical
-     * `default_from`; nothing is exempt.
-     * `relay` - header-only send, nothing provisioned, no per-address fee.
-     *
-     * This is a property of the DOMAIN, fixed when it was set up - not of the
-     * call. Omitting `mailbox_mode` on a quote does not make the send relay; the
-     * domain's own mode always wins. Check here before you quote.
+     * The domain's mode, fixed when it was bought. `mailbox`: each address is a hosted inbox, with a
+     * one-time per-address fee when it is added. `relay`: addresses send and receive with no hosted
+     * inbox, free to add.
      */
-    mailbox_mode: 'relay' | 'mailbox';
+    mailbox_mode: MailboxMode;
     /** Rotation eligibility - the selector only picks `active`. */
     pool_status: 'active' | 'paused' | 'removed';
     /** Reputation health - a domain can be `paused` AND still `warming`/recovering. */
@@ -1222,7 +1287,7 @@ export interface InboundCallsOptions {
 export interface Notification {
     id: string;
     agentId: string;
-    type: 'job_completed' | 'job_failed' | 'voice_completed' | 'sms_completed' | 'credit_issued' | 'domain_expiring' | 'phone_expiring';
+    type: 'job_completed' | 'job_failed' | 'voice_completed' | 'sms_completed' | 'credit_issued' | 'domain_expiring' | 'phone_expiring' | 'goal_awaiting_budget' | 'goal_budget_warning';
     title: string;
     body?: string;
     metadata?: Record<string, unknown>;
@@ -1606,6 +1671,17 @@ export interface ComputeOptions extends ToolOptions {
      * sandbox default-deny on gets the same for all its goals.
      */
     egress_allowlist?: string[];
+    /**
+     * Your reading of the goal: the unit, how a unit starts, what each unit needs, the overhead, the
+     * volume and what no price list covers. It replaces the quote's reading and is priced again in
+     * code; a tool the goal cannot call is refused. Omit it and the quote proposes one.
+     */
+    scope?: ComputeGoalScope;
+    /**
+     * Called with the quote before anything is paid: read `quote.scope`, `quote.price` and
+     * `quote.done_check` there, and throw to stop without paying. `maxCost` still caps the total.
+     */
+    onQuote?: (quote: ComputeQuote) => void;
 }
 export type ComputeDoneCheck = 
 /** At least `at_least` calls of `tool` that reached `status` (default `completed`). */
@@ -1638,20 +1714,44 @@ export type ComputeDoneCheck =
     equals?: string | number | boolean;
     at_least?: number;
 }
-/** Every case of the goal is in one of `finished_states` (a state in `owner_required_for` also needs an owner in the record). With no cases the check is not met. */
+/** Every case of the goal is in one of `finished_states` (a state in `owner_required_for` also needs an owner in the record). `unreached` always counts as finished and is reported on its own. With no cases the check is not met. */
  | {
     kind: 'cases';
     finished_states: string[];
     owner_required_for?: string[];
     min_cases?: number;
 }
+/**
+ * A named person accepts proof the agent submits (a document, photo, link or extracted fields). `verifier` needs an
+ * email or a phone number. With `fields`, the proof's document is read first and a field that is missing or breaks
+ * its constraint means the verifier is not asked.
+ */
+ | {
+    kind: 'evidence';
+    verifier: {
+        name: string;
+        email?: string;
+        phone?: string;
+        timezone?: string;
+    };
+    accepts: string;
+    fields?: Array<{
+        name: string;
+        description: string;
+        type: 'string' | 'number' | 'boolean';
+        equals?: string | number | boolean;
+        one_of?: string[];
+        at_least?: number;
+        at_most?: number;
+    }>;
+}
 /** No check can be written: you confirm with `confirmComputeGoal`. */
  | {
     kind: 'owner';
 };
 /** What an evaluation of the done-check found. */
 export interface ComputeCheckResult {
-    kind: 'count' | 'tool_result' | 'cases' | 'owner';
+    kind: 'count' | 'tool_result' | 'cases' | 'evidence' | 'owner';
     /** `null` while waiting for the owner. */
     passed: boolean | null;
     observed?: unknown;
@@ -1660,16 +1760,16 @@ export interface ComputeCheckResult {
     evaluated_at: string;
     attempt?: number;
 }
-export type ComputeEndReason = 'check_passed' | 'owner_confirmed' | 'check_failed' | 'budget_exhausted' | 'deadline_passed' | 'planner_failed' | 'impossible' | 'impossible_unverified' | 'connection_timeout';
+export type ComputeEndReason = 'check_passed' | 'owner_confirmed' | 'check_failed' | 'budget_exhausted' | 'deadline_passed' | 'planner_failed' | 'impossible' | 'impossible_unverified' | 'connection_timeout' | 'tool_timeout' | 'setup_timeout' | 'runner_retired';
 export interface ComputeApprovals {
     /** Hold any single call whose cost exceeds this many USDC. */
     spend_over_usdc?: number;
     /** Hold every call of these tools, whatever the cost (e.g. ["commerce_buy", "physical_mail", "voice", "soul_hire"]). */
     tools?: string[];
 }
-/** A connected system a goal needs, as the quote read it from the objective. */
+/** A connected system, or the agent's LinkedIn account, required by the scoped tools or read from the objective. */
 export interface ComputeRequirement {
-    family: 'crm' | 'ledger' | 'shipping' | 'tax' | 'procurement' | 'repository';
+    family: 'crm' | 'ledger' | 'shipping' | 'tax' | 'procurement' | 'meetings' | 'mailbox' | 'files' | 'field_service' | 'repository' | 'linkedin';
     /** The product the objective names (e.g. "QuickBooks"); null when only the kind of system was named. */
     product: string | null;
     /** The system can be connected on OneShot right now. */
@@ -1687,7 +1787,7 @@ export interface ComputeRequirement {
 export interface ComputeFeasibility {
     verdict: 'accept' | 'hold' | 'refuse';
     reasons: {
-        code: 'system_unsupported' | 'deadline_in_past' | 'infeasible_input' | 'connection_checked_at_payment';
+        code: 'system_unsupported' | 'deadline_in_past' | 'infeasible_input' | 'verifier_unreachable' | 'connection_checked_at_payment';
         message: string;
         conflicts?: {
             constraints: {
@@ -1699,15 +1799,89 @@ export interface ComputeFeasibility {
         }[];
     }[];
     warnings: {
-        code: 'no_tool_matched' | 'tight_deadline' | 'finish_line_unknowable' | 'product_unverified' | 'similar_goal_was_impossible';
+        code: 'need_limit_exceeded' | 'no_tool_matched' | 'tight_deadline' | 'finish_line_unknowable' | 'product_unverified' | 'similar_goal_was_impossible';
         message: string;
     }[];
     finish_line?: {
         kind: 'measurable' | 'needs_owner' | 'unknowable';
         done_check?: ComputeDoneCheck;
     };
+    /** What the goal needs that no tool does, as the estimate read it; each is a `no_tool_matched` warning, and the quote is still issued. */
+    missing?: {
+        entity: string;
+        attribute?: string;
+        action?: string;
+        operation: 'lookup' | 'list' | 'act';
+        purpose: string;
+    }[];
+}
+/** One tool use inside a unit of a goal's scope. */
+export interface ComputeScopeUse {
+    tool: string;
+    qty: number;
+    max_attempts: number;
+    /** Request sizes (recipients, segments, pages, minutes, problem size); never prices. */
+    drivers?: Record<string, number | boolean | string>;
+    /** Whom or what the use is pointed at, in your words. */
+    target?: string;
+    persistence?: {
+        max_attempts: number;
+        spacing_seconds: number;
+        escalate_to?: string;
+        then: 'owner' | 'give_up';
+    };
+}
+/** A goal's scope: the unit the goal works in, what one unit takes, and how many units there are. */
+export interface ComputeGoalScope {
+    unit: {
+        name: string;
+        starts_on: 'list' | 'event' | 'schedule' | 'once';
+    };
+    per_unit: {
+        uses: ComputeScopeUse[];
+        step_allowance: number;
+        done: string[];
+    };
+    overhead: {
+        uses: Pick<ComputeScopeUse, 'tool' | 'qty' | 'max_attempts' | 'drivers'>[];
+        step_allowance: number;
+    };
+    volume: {
+        kind: 'list';
+        count: number;
+    } | {
+        kind: 'open';
+    };
+    unpriced: {
+        name: string;
+        reason: 'connection' | 'quoted_tool';
+        assumption?: string;
+    }[];
+}
+/** What a quote prices: one unit, the overhead, the whole goal or the units a budget covers, and what it cannot price. */
+export interface ComputeScopePrice {
+    per_unit: {
+        expected: number;
+        ceiling: number;
+    };
+    overhead: {
+        expected: number;
+        ceiling: number;
+    };
+    /** A listed volume: the whole goal. */
+    total?: {
+        expected: number;
+        ceiling: number;
+    };
+    /** An open volume with a budget: whole units after overhead; null for a zero-cost unit. */
+    units_covered?: number | null;
+    unpriced: ComputeGoalScope['unpriced'];
+    unmeasured: string[];
 }
 export interface ComputeQuote {
+    /** Account prerequisites, observed without reserving capacity. Setup is purchased separately. */
+    requirements: ComputeToolRequirement[];
+    connection_requirements: ComputeRequirement[];
     quote_id: string;
     objective_summary: string;
     estimated_phases: number;
@@ -1717,6 +1891,11 @@ export interface ComputeQuote {
     /** One entry per connected system the goal needs. */
     requires: ComputeRequirement[];
     feasibility: ComputeFeasibility;
+    /** The recipe the goal is held to: yours, or the quote's reading. */
+    scope: ComputeGoalScope;
+    price: ComputeScopePrice;
+    /** The done check the goal is held to: yours, else the proposed one; null means you confirm. */
+    done_check: ComputeDoneCheck | null;
     total_budget: string;
     expires_at: string;
     schedule_cron?: string;
@@ -1724,8 +1903,35 @@ export interface ComputeQuote {
     max_runs?: number;
     projected_runs?: number;
 }
+export interface ComputeToolRequirement {
+    kind: 'sending_domain' | 'caller_number' | 'browser_login' | 'connection';
+    family?: ComputeRequirement['family'];
+    product?: string | null;
+    state: 'ready' | 'setup' | 'owner';
+    checked_at_payment?: boolean;
+    action_url?: string;
+    /** Account setup the owner completes at `action_url`. With no `choice`, code picks what is bought. */
+    setup?: {
+        price: number;
+        currency: 'USD';
+        estimated: boolean;
+        choice?: 'domain_name';
+        alternatives?: {
+            action_url: string;
+            price: number;
+            currency: 'USD';
+            choice: 'domain_name';
+        }[];
+    };
+    limit?: {
+        daily: number;
+        remaining: number;
+        requested: number;
+        warming: boolean;
+    };
+}
 export interface ComputeGoalResult {
-    requires?: ComputeRequirement[];
+    requires?: Array<ComputeRequirement | ComputeToolRequirement>;
     goal_id: string;
     request_id: string;
     receipt_id?: string;
@@ -1743,10 +1949,35 @@ export interface ComputeGoalResult {
         next_run_at?: string;
     };
 }
-export type GoalStatus = 'active' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'awaiting_confirmation' | 'awaiting_connection';
+export type GoalStatus = 'active' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'awaiting_confirmation' | 'awaiting_connection' | 'awaiting_budget' | 'awaiting_tool' | 'awaiting_setup';
+export interface ComputeGoalClaimSource {
+    tool: string;
+    input_summary: string;
+    /** Source-reported time, or null when the tool did not report it. */
+    as_of: string | null;
+    retrieved_at: string;
+    call_id: string | null;
+}
+export interface ComputeGoalClaim {
+    text: string;
+    kind: 'observed' | 'inferred';
+    sources: ComputeGoalClaimSource[];
+    /** Zero-based indices of earlier claims. Inference rules are stated in text. */
+    basis?: number[];
+}
 export interface ComputeGoalStatus {
     id: string;
     status: GoalStatus;
+    tool_requests: Array<{
+        id: string;
+        need: string;
+        status: 'open' | 'queued' | 'filed' | 'building' | 'shipped' | 'declined' | 'matched_existing' | 'duplicate';
+        tool_name?: string;
+    }>;
+    setup_hold?: {
+        since: string;
+        requires: ComputeToolRequirement[];
+    } | null;
     connection_hold?: {
         since: string;
         requires: ComputeRequirement[];
@@ -1767,11 +1998,20 @@ export interface ComputeGoalStatus {
     done_check?: ComputeDoneCheck | null;
     /** The latest evaluation of the done-check. */
     check_result?: ComputeCheckResult | null;
-    /** Why the goal ended. A goal that ran out of budget is `budget_exhausted`, never completed. */
+    /** Progress and code-priced funding estimate while waiting for budget. */
+    budget_hold?: {
+        since: string;
+        units_done: number;
+        units_left?: number;
+        cost_to_finish?: number;
+        price_per_unit?: number;
+    } | null;
+    /** Why the goal ended. Budget exhaustion holds for 7 days before ending `budget_exhausted`. */
     end_reason?: ComputeEndReason | null;
     /** The goal's answer in the planner's words, written when it finished. What its tasks produced: `getComputeOutputs`. */
     result?: string | null;
     result_at?: string | null;
+    claims?: ComputeGoalClaim[];
     started_at: string | null;
     completed_at: string | null;
     last_wake_at: string | null;
@@ -1828,6 +2068,19 @@ export interface ComputeTask {
     completed_at: string | null;
     created_at: string;
 }
+export interface ComputeTaskListOptions {
+    /** Only tasks with this status. */
+    status?: 'pending' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled';
+    /** Tasks per page, 1 to 500 (default 100). */
+    limit?: number;
+    /** The `next_cursor` of the previous page. */
+    cursor?: string;
+}
+export interface ComputeTaskPage {
+    tasks: ComputeTask[];
+    /** Pass as `cursor` for the next page; null on the last one. */
+    next_cursor: string | null;
+}
 export interface ComputeBudgetStatus {
     budgetId: string;
     goalId: string;
@@ -2434,9 +2687,11 @@ export interface AgentConnection {
     account_label: string | null;
     /** Only an `active` connection can be read. */
     status: 'pending' | 'active' | 'expired' | 'revoked';
+    /** `region` is the data center named at start, for a system that runs several (Zoho Books). */
     scope: {
         repositories: string[];
         accountId?: string;
+        region?: string;
         oauthScopes?: string[];
     };
     credential?: 'stored';