@oneshot-agent/sdk 0.60.0 → 0.62.0

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { UntrustedContent } from './untrusted-content';
 import type { WalletProvider } from './wallet-provider';
 export interface TokenInfo {
     address: string;
@@ -53,17 +54,17 @@ export type LoggerFn = (message: string) => void;
  */
 export type StatusUpdateFn = (status: string, requestId: string) => void;
 export interface OneShotConfig {
-    /** Option A: Raw private key (existing behavior) */
+    /** Raw private key for wallet authentication. */
     privateKey?: string;
-    /** Option B: Use Coinbase CDP Server Wallet (reads CDP_* env vars). Pass true or { address } to reuse existing. */
+    /** Use Coinbase CDP Server Wallet (reads CDP_* env vars). Pass true or { address } to reuse existing. */
     cdp?: boolean | {
         address?: string;
     };
-    /** Option C: Bring your own WalletProvider implementation */
+    /** Bring your own WalletProvider implementation */
     walletProvider?: WalletProvider;
     /**
-     * Option D: an agent access token (`oneshot_<64 hex>`), for code that runs
-     * where the wallet key cannot be — hosted MCP clients, cloud runners. The
+     * An agent access token (`oneshot_<64 hex>`), for code that runs
+     * where the wallet key cannot be - hosted MCP clients, cloud runners. The
      * session identifies the agent with the token, pays every call from the
      * agent's prepaid credit balance, and never signs x402: a shortfall throws
      * `InsufficientCreditsError`. Budgets are read-only in this mode (set them
@@ -92,7 +93,7 @@ export interface OneShotConfig {
     /**
      * Payment currency: "USDC" (default, no swap) or "ETH". In ETH mode the SDK
      * checks the wallet's USDC before each payment and only swaps ETH→USDC (Uniswap
-     * V3, Base mainnet) when it does not cover the charge — buying a buffer so one
+     * V3, Base mainnet) when it does not cover the charge - buying a buffer so one
      * swap covers many calls. See `swapBufferMultiplier`.
      */
     currency?: 'USDC' | 'ETH';
@@ -110,7 +111,7 @@ export interface OneShotConfig {
     swapBufferMultiplier?: number;
     /**
      * Spend budget for this agent. Synced to the server once, before the first
-     * paid call, and enforced there against the receipts ledger — so the daily
+     * paid call, and enforced there against the receipts ledger - so the daily
      * figure is a real per-agent total, shared across every process and restart
      * running this wallet, not a per-instance counter.
      *
@@ -169,7 +170,7 @@ export interface AgentBudgetStatus {
 }
 /**
  * Structured decision context for a tool call. Machine-readable metadata
- * that explains WHY this tool was called — consumed by auditor agents
+ * that explains WHY this tool was called - consumed by auditor agents
  * and programmatic oversight. Open schema: known fields are typed,
  * extra keys are allowed.
  */
@@ -218,11 +219,12 @@ 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;
     wait?: boolean;
-    /** Optional value tag for RoCS tracking — stored in the receipt at creation time */
+    /** Optional value tag for RoCS tracking - stored in the receipt at creation time */
     valueTag?: {
         type: string;
         amount?: number;
@@ -235,7 +237,7 @@ export interface ToolOptions {
      */
     memo?: string;
     /**
-     * Structured decision context — goal linkage, alternatives considered,
+     * Structured decision context - goal linkage, alternatives considered,
      * confidence score. Machine-readable counterpart to memo. Stored alongside
      * the receipt for programmatic auditing by supervisor agents.
      */
@@ -263,9 +265,9 @@ export interface ToolOptions {
      * is optional with a 24h cached-response replay window; personProfile /
      * personEmail / personEmailStatus are honored when durable enrichment is enabled
      * on the server AND the session authenticates with a wallet, not an
-     * `accessToken` — an access-token session skips the durable-replay check
+     * `accessToken` - an access-token session skips the durable-replay check
      * on these three routes entirely and always dispatches a fresh job, even
-     * with durable enrichment on (no expiry otherwise — backed by a durable
+     * with durable enrichment on (no expiry otherwise - backed by a durable
      * row, not a cache); physical-mail/send is mandatory and likewise never
      * expires. Save the key before submission.
      */
@@ -287,37 +289,37 @@ export interface EmailToolOptions extends ToolOptions {
     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
+     * 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
+     * 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`.
      */
     from_mailbox?: string;
     /**
      * How this domain sends (provider-neutral):
-     *  - `'relay'` (default) — header/relay send; any from-address works with nothing
+     *  - `'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 +
+     *  - `'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
+     * 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
+     * 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
+     * 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 (#1070). A bare `true` names no amount
+     * 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.
      */
     confirmNewDomain?: string;
@@ -330,11 +332,28 @@ export interface EmailToolOptions extends ToolOptions {
         content_type?: string;
     }>;
 }
+/**
+ * The shared lookup cache's bypass. Every person, company and business lookup is served from
+ * OneShot's store when the same subject (or the same search) was looked up within its freshness window
+ * (profiles, dossiers, social accounts, email finds, company profiles and resolves 30 days; email status
+ * and searches 7 days; posts, articles, followers and interests 3 days); a stored record costs the same.
+ */
+export interface FreshLookupOption {
+    /** Look the record up again instead of using OneShot's stored copy, and refresh that copy. Off by default. */
+    fresh?: boolean;
+}
+/** What a person, company or business result says about where it came from. */
+export interface CachedRecordFields {
+    /** True when the record came from OneShot's store of earlier lookups. */
+    cached?: boolean;
+    /** When the record was obtained from its source, ISO 8601 UTC. */
+    fetched_at?: string;
+}
 export interface ResearchToolOptions extends ToolOptions {
     topic: string;
     depth?: 'deep' | 'quick';
 }
-export interface PersonFindOptions extends ToolOptions {
+export interface PersonFindOptions extends ToolOptions, FreshLookupOption {
     /** Off by default. Adds the per-person add-on on the pricing page × requested limit (default 100) for up to that many people; no phone hit guaranteed. */
     includePhone?: boolean;
     job_titles?: string[];
@@ -353,7 +372,7 @@ export interface PersonFindOptions extends ToolOptions {
     /** Max rows to return, 1-500 (server default 100). Large requests are
      * paginated server-side, so one response can hold up to `limit` rows.
      * The search runs under a time limit: if it is reached, the response holds
-     * the rows found so far (possibly fewer than `limit`) — continue with
+     * the rows found so far (possibly fewer than `limit`) - continue with
      * `offset`. With `include_phone`, every row reports its `phone_lookup`
      * outcome (see `PersonResult.phone_lookup`); a row whose lookup did not
      * finish in time is `not_attempted` or `unavailable`, never silently empty. */
@@ -365,7 +384,7 @@ export interface PersonFindOptions extends ToolOptions {
     offset?: number;
 }
 /**
- * What a caller knows about one person (#1899). Every single-person tool takes
+ * What a caller knows about one person. Every single-person tool takes
  * these same optional fields; at least one of `name`, `email`, `phone` or
  * `profile_url` is required. The API resolves the rest (a LinkedIn URL from a
  * name and company or an email, the other handles, the employer).
@@ -384,7 +403,7 @@ export interface PersonIdentity {
     /** Same as `profile_url` (older name). */
     social_media_url?: string;
 }
-export interface PersonProfileOptions extends ToolOptions, PersonIdentity {
+export interface PersonProfileOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
     /** Off by default. Adds the per-person add-on on the pricing page for up to one person; no phone hit guaranteed. */
     includePhone?: boolean;
     /** Employer domain (older name; `company` takes a name or a domain). */
@@ -392,7 +411,7 @@ export interface PersonProfileOptions extends ToolOptions, PersonIdentity {
     /** Employer name (older name; `company` takes a name or a domain). */
     company_name?: string;
 }
-export interface CompanyFindOptions extends ToolOptions {
+export interface CompanyFindOptions extends ToolOptions, FreshLookupOption {
     name?: string;
     domain?: string;
     industry?: string[];
@@ -404,13 +423,13 @@ export interface CompanyFindOptions extends ToolOptions {
     tags?: string[];
     limit?: number;
 }
-export interface CompanyProfileOptions extends ToolOptions {
+export interface CompanyProfileOptions extends ToolOptions, FreshLookupOption {
     domain?: string;
     name?: string;
     linkedin_url?: string;
     ticker?: string;
 }
-export interface PersonEmailOptions extends ToolOptions, PersonIdentity {
+export interface PersonEmailOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
     /** Same as `name` (older name). */
     full_name?: string;
     first_name?: string;
@@ -420,26 +439,26 @@ export interface PersonEmailOptions extends ToolOptions, PersonIdentity {
     /** Employer name (older name; `company` takes a name or a domain). */
     company_name?: string;
 }
-export interface PersonEmailStatusOptions extends ToolOptions {
+export interface PersonEmailStatusOptions extends ToolOptions, FreshLookupOption {
     email: string;
 }
-export interface PersonDossierOptions extends ToolOptions, PersonIdentity {
+export interface PersonDossierOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
     /** Off by default. Adds the per-person add-on on the pricing page for up to one person; no phone hit guaranteed. */
     includePhone?: boolean;
 }
-export interface PersonSocialAccountsOptions extends ToolOptions, PersonIdentity {
+export interface PersonSocialAccountsOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
 }
-export interface PersonArticlesOptions extends ToolOptions {
+export interface PersonArticlesOptions extends ToolOptions, FreshLookupOption {
     name: string;
     company: string;
     sort?: 'recent' | 'popular';
     limit?: number;
 }
-export interface PersonPostsOptions extends ToolOptions, PersonIdentity {
+export interface PersonPostsOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
 }
-export interface PersonInterestsOptions extends ToolOptions, PersonIdentity {
+export interface PersonInterestsOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
 }
-export interface PersonFollowersOptions extends ToolOptions, PersonIdentity {
+export interface PersonFollowersOptions extends ToolOptions, PersonIdentity, FreshLookupOption {
     type?: 'replies' | 'followers' | 'following' | 'followers,following';
     max_results?: number;
 }
@@ -473,13 +492,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;
@@ -489,7 +512,8 @@ export interface WebReadOptions extends ToolOptions {
     /** URL of the web page to read */
     url: string;
 }
-export interface WebReadResult {
+export interface WebReadResult extends UntrustedContent {
+    hidden_removed: number;
     request_id?: string;
     /** Receipt id (`rcpt_…`) for this call. Pass to `tagReceiptValue` to annotate value later. */
     receipt_id?: string;
@@ -557,7 +581,7 @@ export interface Education {
 /**
  * A normalized person record. The worker returns every scalar field below and
  * uses `null`, not a missing key, for a value the provider did not have; the
- * declared person_dossier schema requires exactly that shape (#1789).
+ * declared person_dossier schema requires exactly that shape.
  */
 export interface PersonResult {
     company_address?: BusinessAddress | null;
@@ -592,7 +616,7 @@ export interface PersonResult {
      * person twice: it returns the number already found. */
     phone_lookup?: 'found' | 'none' | 'not_attempted' | 'unavailable' | 'pending';
 }
-export interface PersonFindResult {
+export interface PersonFindResult extends CachedRecordFields {
     status: string;
     results: PersonResult[];
     total_found: number;
@@ -636,11 +660,11 @@ export interface EmailResult {
     error?: string;
     /**
      * 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
+     * - `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
-     * warning — there is no shared fallback sender.)
+     * warning - there is no shared fallback sender.)
      */
     warning?: string;
     email?: {
@@ -662,7 +686,7 @@ export type DomainWarmupState = 'warming' | 'warmed' | 'degraded';
 export type DomainPauseReason = 'warming' | 'low_reputation' | 'manual' | null;
 /** A mailbox already provisioned on a domain (from `/email/domains` `addresses[]`). */
 export interface DomainAddressEntry {
-    /** Full email address, lowercased — e.g. `sales@yourdomain.com`. */
+    /** Full email address, lowercased - e.g. `sales@yourdomain.com`. */
     address: string;
     /** Mailbox provisioning state. Only `active` counts as already-provisioned (free to send from). */
     status: 'active' | 'provisioning' | 'failed';
@@ -672,34 +696,34 @@ export interface DomainAddressEntry {
 export interface DomainPoolEntry {
     domain: string;
     /**
-     * Canonical sending address for this domain (e.g. `agent@yourdomain.com`) — the
+     * 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`.
      */
     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
+     * send from any address - a new one is provisioned (and billed
      * `mailbox_provisioning_fee`) on first use.
      */
     addresses: DomainAddressEntry[];
     /**
      * Which side of the provisioning fee this domain sits on.
      *
-     * `mailbox` — a real mailbox is provisioned per address, so every address
+     * `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.
+     * `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
+     * 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.
      */
     mailbox_mode: 'relay' | 'mailbox';
-    /** Rotation eligibility — the selector only picks `active`. */
+    /** Rotation eligibility - the selector only picks `active`. */
     pool_status: 'active' | 'paused' | 'removed';
-    /** Reputation health — a domain can be `paused` AND still `warming`/recovering. */
+    /** Reputation health - a domain can be `paused` AND still `warming`/recovering. */
     warmup_state: DomainWarmupState;
     pause_reason: DomainPauseReason;
     provisioning_status: string;
@@ -730,7 +754,7 @@ export interface DossierSection<T> {
     state: 'found' | 'none' | 'unavailable';
     data: T;
 }
-export interface PersonProfileResult {
+export interface PersonProfileResult extends CachedRecordFields {
     status: string;
     profile: PersonResult & {
         social_accounts: SocialAccount[];
@@ -764,7 +788,7 @@ export interface CompanyResult {
     linkedin_url?: string;
     [key: string]: unknown;
 }
-export interface CompanyFindResult {
+export interface CompanyFindResult extends CachedRecordFields {
     status: string;
     results: CompanyResult[];
     total_found: number;
@@ -776,7 +800,7 @@ export interface CompanyFindResult {
     memo?: string;
     cost?: number;
 }
-export interface CompanyProfileResult {
+export interface CompanyProfileResult extends CachedRecordFields {
     status: string;
     company: CompanyResult;
     request_id?: string;
@@ -786,7 +810,7 @@ export interface CompanyProfileResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonEmailResult {
+export interface PersonEmailResult extends CachedRecordFields {
     status: string;
     email: string | null;
     found: boolean;
@@ -855,7 +879,7 @@ export type PersonDossierPost = Omit<PersonPostsResult['result'][number], 'platf
     url?: string | null;
     posted_at?: string | null;
 };
-export interface PersonDossierResult {
+export interface PersonDossierResult extends CachedRecordFields {
     status: string;
     result: {
         profile: {
@@ -882,7 +906,7 @@ export interface PersonDossierResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonSocialAccountsResult {
+export interface PersonSocialAccountsResult extends CachedRecordFields {
     status: string;
     result: Record<string, {
         url?: string;
@@ -895,7 +919,7 @@ export interface PersonSocialAccountsResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonArticlesResult {
+export interface PersonArticlesResult extends CachedRecordFields {
     status: string;
     result: Array<{
         title?: string;
@@ -909,7 +933,7 @@ export interface PersonArticlesResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonPostsResult {
+export interface PersonPostsResult extends CachedRecordFields {
     status: string;
     result: Array<{
         platform?: string;
@@ -925,7 +949,7 @@ export interface PersonPostsResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonInterestsResult {
+export interface PersonInterestsResult extends CachedRecordFields {
     status: string;
     result: Record<string, unknown>;
     request_id: string;
@@ -933,7 +957,7 @@ export interface PersonInterestsResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonFollowersResult {
+export interface PersonFollowersResult extends CachedRecordFields {
     status: string;
     result: {
         followers?: Array<Record<string, unknown>>;
@@ -945,7 +969,7 @@ export interface PersonFollowersResult {
     memo?: string;
     cost?: number;
 }
-export interface PersonEmailStatusResult {
+export interface PersonEmailStatusResult extends CachedRecordFields {
     status: string;
     email: string;
     valid: boolean;
@@ -959,7 +983,9 @@ export interface PersonEmailStatusResult {
     memo?: string;
     cost?: number;
 }
-export interface InboxEmail {
+export interface InboxEmail extends UntrustedContent {
+    hidden_removed: number;
+    authenticated: boolean;
     id: string;
     from: string;
     subject: string;
@@ -974,7 +1000,8 @@ export interface InboxEmail {
         content?: string;
     }>;
 }
-export interface InboxListResult {
+export interface InboxListResult extends UntrustedContent {
+    hidden_removed: number;
     emails: InboxEmail[];
     count: number;
     has_more: boolean;
@@ -1027,13 +1054,6 @@ export interface VoiceQuote {
     quote_id: string;
     target_numbers: string[];
     conference_mode: boolean;
-    /** @deprecated The API stopped emitting a paraphrased objective summary
-     *  when the voice prompt pipeline switched to verbatim assembly. Field
-     *  retained for type-back-compat; will be removed in the next major. */
-    objective_summary?: string;
-    /** @deprecated See objective_summary — the LLM rewrite that produced these
-     *  bullets is gone. The full objective is in the call's system prompt. */
-    talking_points?: string[];
     success_criteria: string[];
     estimated_duration_minutes: number;
     complexity_score: number;
@@ -1207,7 +1227,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>;
@@ -1342,14 +1362,12 @@ export interface BrowserTaskOptions extends ToolOptions {
     output_schema?: Record<string, unknown>;
     /** Initial URL to navigate to */
     start_url?: string;
-    /** Instruct the agent to stay within these domains; not a network firewall. */
+    /** Stay within these domains (subdomains included). Checked after each recorded navigation, not a network block: one outside the list ends the task with `browser_domain_not_allowed`. */
     allowed_domains?: string[];
     /** Reuse an existing browser session */
     session_id?: string;
     /** Persistent browser profile ID for reusing cookies/localStorage across sessions */
     profile_id?: string;
-    /** @deprecated Unsupported. Import cookies/storage_state when creating a profile. */
-    secrets?: Record<string, string>;
     /** Legacy step-derived budget allowance (default: 50, supported: 25–100); not an exact action limit. */
     max_steps?: number;
 }
@@ -1554,7 +1572,7 @@ export interface ComputeSchedule {
     cron: string;
     /** USDC budget per run */
     budget_per_run: number;
-    /** Maximum number of runs (optional — runs indefinitely if omitted) */
+    /** Maximum number of runs (optional - runs indefinitely if omitted) */
     max_runs?: number;
 }
 export interface ComputeOptions extends ToolOptions {
@@ -1586,6 +1604,24 @@ export interface ComputeOptions extends ToolOptions {
      * approval covers exactly one call: that tool, those params, at most that amount.
      */
     approvals?: ComputeApprovals;
+    /**
+     * Hosts the goal's sandboxes may reach besides OneShot's API: hostnames, IPv4
+     * addresses or IPv4 ranges, at most 50. Setting it (even to []) limits every
+     * sandbox of the goal to OneShot's API and these hosts; an organization with
+     * 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`). */
@@ -1618,7 +1654,7 @@ 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[];
@@ -1640,13 +1676,122 @@ export interface ComputeCheckResult {
     evaluated_at: string;
     attempt?: number;
 }
-export type ComputeEndReason = 'check_passed' | 'owner_confirmed' | 'check_failed' | 'budget_exhausted' | 'deadline_passed' | 'planner_failed';
+export type ComputeEndReason = 'check_passed' | 'owner_confirmed' | 'check_failed' | 'budget_exhausted' | 'deadline_passed' | 'planner_failed' | 'impossible' | 'impossible_unverified' | 'connection_timeout' | 'tool_timeout';
 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. */
+export interface ComputeRequirement {
+    family: 'crm' | 'ledger' | 'shipping' | 'tax' | 'procurement' | 'meetings' | 'mailbox' | 'files' | 'repository';
+    /** 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. */
+    available: boolean;
+    /** The goal owner has an active connection to it. null for a caller that has not proven it holds the agent wallet (access token or signed proof). */
+    connected: boolean | null;
+    /** Where the owner connects a system; only for a caller proven to hold the agent wallet. */
+    connect_url?: string;
+}
+/**
+ * Whether a goal can be done, as the quote judged it. `refuse` comes only with a proof and no quote;
+ * `hold` means a supported system is not connected yet (the quote is still issued); an unproven caller instead gets
+ * `accept` with the reason `connection_checked_at_payment`. Warnings never change the verdict.
+ */
+export interface ComputeFeasibility {
+    verdict: 'accept' | 'hold' | 'refuse';
+    reasons: {
+        code: 'system_unsupported' | 'deadline_in_past' | 'infeasible_input' | 'connection_checked_at_payment';
+        message: string;
+        conflicts?: {
+            constraints: {
+                family: string;
+                ref: string;
+                label: string;
+            }[];
+            explanation: string;
+        }[];
+    }[];
+    warnings: {
+        code: '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;
+    /** 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'>[];
+        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 {
     quote_id: string;
     objective_summary: string;
@@ -1654,6 +1799,14 @@ export interface ComputeQuote {
     estimated_tasks: number;
     estimated_duration_days: number;
     budget_breakdown: Record<string, string>;
+    /** 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;
@@ -1662,6 +1815,7 @@ export interface ComputeQuote {
     projected_runs?: number;
 }
 export interface ComputeGoalResult {
+    requires?: ComputeRequirement[];
     goal_id: string;
     request_id: string;
     receipt_id?: string;
@@ -1679,9 +1833,35 @@ export interface ComputeGoalResult {
         next_run_at?: string;
     };
 }
+export type GoalStatus = 'active' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'awaiting_confirmation' | 'awaiting_connection' | 'awaiting_budget' | 'awaiting_tool';
+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: string;
+    status: GoalStatus;
+    tool_requests: Array<{
+        id: string;
+        need: string;
+        status: 'open' | 'queued' | 'filed' | 'building' | 'shipped' | 'declined' | 'matched_existing' | 'duplicate';
+        tool_name?: string;
+    }>;
+    connection_hold?: {
+        since: string;
+        requires: ComputeRequirement[];
+    } | null;
     name: string;
     objective: string;
     current_phase: number | null;
@@ -1698,11 +1878,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;
@@ -1773,7 +1962,7 @@ export interface ComputeBudgetStatus {
         created_at: string;
     }>;
 }
-export interface BusinessFindOptions extends ToolOptions {
+export interface BusinessFindOptions extends ToolOptions, FreshLookupOption {
     /** Business categories, e.g. ['hvac contractor', 'dental practice']. category or keywords required. */
     category?: string[];
     /** Free-text keywords (alternative to category). */
@@ -1791,7 +1980,7 @@ export interface BusinessFindOptions extends ToolOptions {
     /** 1-500, default 100. Effective max is bounded by the vendor-call cap; see `truncated`. */
     limit?: number;
 }
-export interface BusinessResolveOptions extends ToolOptions {
+export interface BusinessResolveOptions extends ToolOptions, FreshLookupOption {
     name: string;
     address?: string;
     city?: string;
@@ -1824,7 +2013,7 @@ export interface LocalResult {
     latitude: number | null;
     longitude: number | null;
 }
-export interface BusinessFindResult {
+export interface BusinessFindResult extends CachedRecordFields {
     status: string;
     results: LocalResult[];
     total_found: number;
@@ -1838,9 +2027,9 @@ export interface BusinessFindResult {
     memo?: string;
     cost?: number;
 }
-export interface BusinessResolveResult {
+export interface BusinessResolveResult extends CachedRecordFields {
     status: string;
-    /** false is a completed job, not an error — the same contract as personEmail. */
+    /** false is a completed job, not an error - the same contract as personEmail. */
     found: boolean;
     /** 0..1 confidence of the best candidate (0 when nothing was returned). */
     confidence: number;
@@ -1864,7 +2053,7 @@ export type GovNoticeTypeCode = 'r' | 'p' | 'o' | 'k' | 's' | 'a' | 'u' | 'i' |
 export interface RecordSolicitationsFindOptions extends ToolOptions {
     /** 6-digit NAICS codes, 1-20. Required. */
     naics: string[];
-    /** Default ['r', 'p'] — Sources Sought + Presolicitation, the window where the requirement is still being written. */
+    /** Default ['r', 'p'] - Sources Sought + Presolicitation, the window where the requirement is still being written. */
     notice_types?: GovNoticeTypeCode[];
     /** Look-back window on posted date, 1-365. Default 30. */
     since_days?: number;
@@ -1934,7 +2123,7 @@ export interface RecordSolicitationsFindResult {
     description_fetches: number;
     /**
      * ISO timestamp of the data snapshot behind `results`: the publish time of
-     * SAM.gov's daily extract when served from it (the common case — same-day
+     * SAM.gov's daily extract when served from it (the common case - same-day
      * postings appear the next morning), or the request time when the live
      * SAM.gov API answered.
      */
@@ -1947,13 +2136,11 @@ export interface RecordSolicitationsFindResult {
     memo?: string;
     cost?: number;
 }
-/** Interactive profile login (#1889). setup_url is a secret for the account's owner; do not log or persist it. */
+/** Interactive profile login. setup_url is a secret for the account's owner; do not log or persist it. */
 export interface BrowserProfileSetup {
     profile_id: string;
     session_id?: string;
     status: string;
-    /** @deprecated Use setup_url. Removed in the next release. */
-    live_url?: string | null;
     /** The OneShot page the account's owner opens to sign in. Opens once; a fresh one comes from createBrowserProfileSetupLink. Returned by start and link. */
     setup_url?: string;
     /** When setup_url stops opening (10 minutes after it was minted, or when the setup expires). */
@@ -2181,7 +2368,7 @@ export interface LinkedInConversationsOptions {
 export interface LinkedInMessagesOptions {
     accountId: string;
     conversationId?: string;
-    /** `inbound` = the human received it — use with `since` as a reply watermark. */
+    /** `inbound` = the human received it - use with `since` as a reply watermark. */
     direction?: 'inbound' | 'outbound';
     /** ISO time: only messages sent after this. */
     since?: string;
@@ -2356,7 +2543,7 @@ export type DiscoverToolsResult = {
     message?: string;
     searchedCategories?: string[];
 };
-/** One of the agent's connections (`GET /v1/connections`, #2403). A read of a connected system takes its `id` as `connection_id`. */
+/** One of the agent's connections (`GET /v1/connections`). A read of a connected system takes its `id` as `connection_id`. */
 export interface AgentConnection {
     id: string;
     name: string;
@@ -2367,9 +2554,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';