@m8tes/sdk 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Normalizer, M8tesStreamEvent, ConversationState } from './protocol/index.cjs';
-export { APIError, Accumulator, ApiErrorFields, ApprovalRequestEvent, ApprovalResolvedEvent, AuthenticationError, BaseEvent, BillingError, CompactBoundaryEvent, CompactPart, ConflictError, ErrorFromResponseOptions, M8tesApiError, M8tesStreamEventType, MateMessage, MatePart, MateStatus, MessageEndEvent, MessageStartEvent, NotFoundError, NoticeEvent, NoticePart, PROTOCOL_VERSION, PermissionDeniedError, PlanDeltaEvent, PlanEndEvent, PlanStartEvent, ProtocolVersion, QuestionEvent, QuestionItem, QuestionOption, RateLimitError, ReasoningDeltaEvent, ReasoningEndEvent, ReasoningStartEvent, RunCancelledEvent, RunErrorCode, RunErrorEvent, RunFailedError, RunFinishEvent, RunMetricsEvent, RunNotStreamingError, RunStartEvent, RunStatus, RunStatusEvent, SandboxPart, SandboxStatusEvent, SseParserOptions, TERMINAL_EVENT_TYPES, TerminalEventType, TextDeltaEvent, TextEndEvent, TextLikeKind, TextPart, TextStartEvent, ToolInputAvailableEvent, ToolInputDeltaEvent, ToolInputStartEvent, ToolOutputAvailableEvent, ToolPart, ToolState, UnknownEvent, ValidationError, accumulate, createAccumulator, createNormalizer, createSseDecoder, errorClassForStatus, errorFromResponse, initialConversationState, isTerminalEvent, parseErrorEnvelope, parseRetryAfter, parseSse, splitConcatenatedJson } from './protocol/index.cjs';
+export { APIError, Accumulator, ApiErrorFields, ApprovalRequestEvent, ApprovalResolvedEvent, AuthenticationError, BaseEvent, BillingError, CompactBoundaryEvent, CompactPart, ConflictError, ErrorFromResponseOptions, M8tesApiError, M8tesStreamEventType, MateMessage, MatePart, MateStatus, MessageEndEvent, MessageStartEvent, NotFoundError, NoticeEvent, NoticePart, PROTOCOL_VERSION, PermissionDeniedError, PlanDeltaEvent, PlanEndEvent, PlanStartEvent, ProtocolVersion, QuestionEvent, QuestionItem, QuestionOption, RateLimitError, ReasoningDeltaEvent, ReasoningEndEvent, ReasoningStartEvent, RunCancelledEvent, RunErrorCode, RunErrorEvent, RunFailedError, RunFinishEvent, RunMetricsEvent, RunNotStreamingError, RunStartEvent, RunStatus, RunStatusEvent, SandboxPart, SandboxStatusEvent, SseParserOptions, TERMINAL_EVENT_TYPES, TerminalEventType, TextDeltaEvent, TextEndEvent, TextLikeKind, TextPart, TextStartEvent, ToolInputAvailableEvent, ToolInputDeltaEvent, ToolInputStartEvent, ToolOutputAvailableEvent, ToolPart, ToolState, UnknownEvent, ValidationError, accumulate, createAccumulator, createNormalizer, createSseDecoder, errorClassForStatus, errorFromResponse, initialConversationState, isTerminalEvent, parseErrorEnvelope, parseRetryAfter, parseSse, seg, splitConcatenatedJson } from './protocol/index.cjs';
 
 /**
  * Server-side transport for the m8tes V2 API.
@@ -13,9 +13,11 @@ export { APIError, Accumulator, ApiErrorFields, ApprovalRequestEvent, ApprovalRe
  * two languages behave the same under load:
  *   - 3 attempts total, 0.5s initial backoff, doubling
  *   - retry only 429/500/502/503/504
- *   - retry only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS). A POST that
- *     timed out may already have started a billable run, so re-sending it could
- *     double-charge; those fail immediately and let the caller decide.
+ *   - retry GET/HEAD/PUT/DELETE/OPTIONS always, and a POST only when it carries
+ *     an `Idempotency-Key`. Without one, a POST that timed out may already have
+ *     started a billable run, so re-sending it could double-charge; with one, the
+ *     server replays the run it already created, which is why the run-creating
+ *     calls mint a key on every request.
  *   - honour `Retry-After` on 429
  */
 
@@ -41,10 +43,31 @@ interface RequestOptions {
     query?: string;
     signal?: AbortSignal;
     headers?: Record<string, string>;
+    /**
+     * Send as multipart/form-data instead of JSON. Used by the file-upload route.
+     * `fetch` sets its own `content-type` with the boundary, so we must NOT set
+     * one — a hand-written header omits the boundary and the server cannot parse
+     * the body.
+     */
+    form?: FormData;
 }
 interface StreamRequestOptions extends RequestOptions {
     /** Reuse a normalizer across reconnects so its dedupe ledger persists. */
     normalizer?: Normalizer;
+    /**
+     * Called instead of decoding the body when the server answers a run-creating
+     * POST with `Idempotent-Replay: true`.
+     *
+     * A replay is JSON (the run), not SSE — a run that already exists has no fresh
+     * stream to emit — so the caller decides what to do with it, in practice
+     * joining that run's own stream. It lives here rather than in the resource
+     * because this is the only place the Response object exists; by the time
+     * `stream()` yields, the headers are gone.
+     */
+    onReplay?: (run: {
+        id: number;
+        status: string;
+    }) => AsyncGenerator<M8tesStreamEvent, void, unknown>;
 }
 interface Http {
     baseUrl: string;
@@ -166,7 +189,13 @@ interface Run {
     updated_at: string | null;
     task_id?: number | null;
     permission_mode?: string | null;
+    /** Reply-to address when the run's agent has an email inbox. */
+    email_address?: string | null;
     error_code?: string | null;
+    /** Credential route used for this run. */
+    auth_method?: string | null;
+    /** Provider behind an OAuth subscription route: claude, openai, xai, or gemini. */
+    auth_provider?: string | null;
     retryable?: boolean;
     retry_of_run_id?: number | null;
     retry_count?: number;
@@ -276,6 +305,18 @@ interface EndUserUsage {
     period_end: string;
     rate_per_minute?: number | null;
 }
+/**
+ * One saved memory. `user_id` is the scope: your end-user's id, or `null` for an
+ * account-level memory. `source` says who wrote it — `"api"` for ones you create
+ * here, versus memories an agent saved for itself during a run.
+ */
+interface Memory {
+    id: number;
+    user_id: string | null;
+    content: string;
+    source: string;
+    created_at: string;
+}
 interface App {
     name: string;
     display_name: string;
@@ -294,6 +335,52 @@ interface AppConnectionResult {
     connected?: boolean;
     message?: string | null;
 }
+/**
+ * USD price per MILLION tokens, from the same table that bills your runs.
+ *
+ * `cache_read_per_mtok` / `cache_write_per_mtok` are the prompt-cache rates: on
+ * Anthropic models cache reads are discounted and cache writes carry a premium;
+ * on providers without prompt caching both equal the input rate, so an estimate
+ * built from these numbers never under-counts.
+ */
+interface ModelPricing {
+    input_per_mtok: number;
+    output_per_mtok: number;
+    cache_read_per_mtok: number;
+    cache_write_per_mtok: number;
+    currency: string;
+}
+/** A selectable model. Pass its `id` as `model` on an agent or a run. */
+interface Model {
+    id: string;
+    name: string;
+    description: string;
+    /** Who serves it — `"anthropic"`, `"openai"`, … */
+    provider: string;
+    /** True for the model used when `model` is omitted or null. */
+    default: boolean;
+    /** Highest effort tier this model accepts (`"max"` on Claude, `"high"` on
+     *  others). A higher requested effort is clamped, never rejected. */
+    max_effort: string;
+    /** Absent on older backends that predate pricing on this route. */
+    pricing?: ModelPricing | null;
+    /**
+     * At least one provider behind this model supports zero data retention.
+     *
+     * Read that precisely: it does NOT promise your particular request avoids a
+     * retaining provider. Routing can still land on one unless the account is
+     * constrained. Treat `true` as "ZDR is available here", not "ZDR is in
+     * effect" — see `zdr_providers` and `retention_note`, and confirm the account
+     * constraint before sending regulated data.
+     */
+    zdr_supported?: boolean;
+    /** Deprecated alias of `zdr_supported`. Still sent, so still typed. */
+    zdr?: boolean;
+    /** Which providers behind this route carry ZDR. */
+    zdr_providers?: string[];
+    /** Human-readable retention caveat, when there is one. */
+    retention_note?: string | null;
+}
 interface Webhook {
     id: number;
     url: string;
@@ -304,6 +391,23 @@ interface Webhook {
     created_at: string;
     updated_at?: string | null;
 }
+/**
+ * The full account data dump from `client.account.export()`.
+ *
+ * Deliberately untyped JSON: the document is a GDPR/CCPA access export whose
+ * shape follows whatever the account happens to hold (agents, tasks, runs,
+ * documents, memories, integration metadata), and the API grows it without a
+ * version bump. The Python SDK returns a bare `dict[str, Any]` for the same
+ * reason — typing fields here would invent a contract neither SDK has. Secrets
+ * are never included.
+ */
+type AccountExport = JsonObject;
+/**
+ * The status payload from `client.account.delete()`.
+ *
+ * Untyped for parity with the Python SDK, which returns the API's raw dict.
+ */
+type AccountDeletion = JsonObject;
 interface WebhookDelivery {
     id: number;
     webhook_endpoint_id: number;
@@ -317,6 +421,115 @@ interface WebhookDelivery {
     next_retry_at: string | null;
     created_at: string;
 }
+/** A standing tool permission policy: one pre-approved tool for one end-user.
+ *  Note the asymmetry — you create it with `tool`, the API returns it as
+ *  `tool_name`. */
+interface PermissionPolicy {
+    id: number;
+    user_id: string;
+    tool_name: string;
+    created_at: string;
+}
+/**
+ * Billing usage and limits for the current period.
+ *
+ * The overage fields describe the opt-in usage overage (see
+ * `client.billing.setOverage`) and are all zero/false on accounts that never
+ * enabled it. Cost fields are USD strings, not numbers, so they survive a round
+ * trip without float drift.
+ */
+interface Usage {
+    plan: string;
+    runs_used: number;
+    runs_limit: number;
+    cost_used: string;
+    cost_limit: string;
+    period_end: string;
+    subscription_status: string | null;
+    overage_enabled: boolean;
+    overage_used_cents: number;
+    /** Ceiling on overage spend per period. Runs stop billing overage once reached. */
+    overage_cap_cents: number;
+    overage_rate_cents: number;
+    trial_ends_at?: string | null;
+}
+/** Token + USD totals over a usage-timeseries window. `cost_usd` is a string. */
+interface UsageTotals {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_creation_tokens: number;
+    total_tokens: number;
+    cost_usd: string;
+}
+/** One model's share of a day bucket. `"unknown"` covers pre-attribution history. */
+interface UsageModelSlice extends UsageTotals {
+    model: string;
+}
+/** One UTC-day bucket of token + USD usage. */
+interface UsageBucket extends UsageTotals {
+    /** ISO date, e.g. `"2026-07-01"`. */
+    date: string;
+    /** Per-model slices — present only when the series was requested with
+     *  `group_by: "model"`; `null` otherwise. */
+    models?: UsageModelSlice[] | null;
+}
+/** Daily usage buckets, zero-filled across `[start_date, end_date]` (UTC days). */
+interface UsageTimeseries {
+    start_date: string;
+    end_date: string;
+    buckets: UsageBucket[];
+    totals: UsageTotals;
+}
+/** One prepaid top-up. `receipt_url` is `null` when the underlying Stripe
+ *  checkout session is no longer retrievable. */
+interface Receipt {
+    id: number;
+    amount_cents: number;
+    currency: string;
+    description: string | null;
+    receipt_url: string | null;
+    created_at: string;
+}
+/** A public (paid) plan from the canonical catalog. All prices in cents. */
+interface Plan {
+    slug: string;
+    display_name: string;
+    included_runs: number;
+    monthly_price_cents: number;
+    annual_price_cents: number;
+    overage_rate_cents: number;
+    /** Per-period model-spend fair-use cap; `0` on servers that predate the field. */
+    fair_use_cost_limit_cents: number;
+}
+/** One prepaid token-balance ledger entry. Micro-USD; debits are negative. */
+interface TokenTransaction {
+    type: string;
+    amount_micros: number;
+    balance_after_micros: number;
+    run_id: number | null;
+    description: string | null;
+    created_at: string;
+}
+/**
+ * Prepaid token balance plus a recent ledger (prepaid-billed accounts).
+ *
+ * Balances are micro-USD (1e-6 USD); `balance_usd` is a rounded display string.
+ * Runs debit this balance at official provider prices.
+ */
+interface Balance {
+    balance_micros: number;
+    balance_usd: string;
+    currency: string;
+    /** Configurable low-balance warning level (micro-USD). */
+    low_balance_threshold_micros: number;
+    /** Fixed at 20% of the low threshold; depletion is 0. */
+    critical_balance_threshold_micros: number;
+    transactions: TokenTransaction[];
+    auto_reload_enabled: boolean;
+    auto_reload_threshold_cents?: number | null;
+    auto_reload_amount_cents?: number | null;
+}
 
 /**
  * `client.agents` — the reusable agent personas runs execute as.
@@ -396,12 +609,21 @@ interface AgentsResource {
     delete(agentId: number, params?: {
         user_id?: string;
     }): Promise<void>;
-    /** Turn on the webhook trigger; returns the URL to POST to. */
-    enableWebhook(agentId: number): Promise<WebhookToggle>;
-    disableWebhook(agentId: number): Promise<void>;
+    /** Turn on the webhook trigger; returns the URL to POST to.
+     *  `user_id` scopes to one end-user (404 on mismatch), like get/update/delete. */
+    enableWebhook(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<WebhookToggle>;
+    disableWebhook(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
     /** Turn on the agent's email inbox; returns the address that starts runs. */
-    enableEmailInbox(agentId: number): Promise<EmailInbox>;
-    disableEmailInbox(agentId: number): Promise<void>;
+    enableEmailInbox(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<EmailInbox>;
+    disableEmailInbox(agentId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
 }
 
 /**
@@ -459,6 +681,509 @@ interface AppsResource {
     }): Promise<void>;
 }
 
+/**
+ * `client.account` — the two operations that act on the whole account rather
+ * than anything inside it: take your data out, and shut the account down.
+ *
+ * Both exist to satisfy the GDPR/CCPA rights to access and to erasure, so they
+ * are here for compliance flows you have to be able to run programmatically —
+ * a data-subject request you are forwarding, or an offboarding path in your own
+ * product. Neither takes parameters: they always apply to the account behind
+ * the API key you authenticated with, and there is no `user_id` scoping. To
+ * remove one end-user's data instead, use `client.users.delete()`.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/account.py`.
+ */
+
+interface AccountResource {
+    /**
+     * Hand a customer (or a regulator) everything the account holds — the
+     * GDPR/CCPA right to access.
+     *
+     * The document covers the account's agents, tasks, runs, documents, memories,
+     * and integration metadata. Credentials and other secrets are never included,
+     * so an export is safe to forward but is NOT a backup you can restore from.
+     * It is a single JSON body, not a stream: a large account produces a large
+     * response, so allow for it in your request timeout.
+     */
+    export(): Promise<AccountExport>;
+    /**
+     * Close the account — the GDPR/CCPA right to erasure.
+     *
+     * Soft-delete, and it takes effect at once: sessions and the API key are
+     * revoked, billing is canceled, and all automation stops, with the data
+     * erased after a grace period. In other words the key you just called this
+     * with is dead afterwards, so nothing else in the SDK will work.
+     */
+    delete(): Promise<AccountDeletion>;
+}
+declare function createAccountResource(http: Http): AccountResource;
+
+/**
+ * `client.users` — your end-users, the multi-tenancy boundary.
+ *
+ * `user_id` is YOUR identifier for a customer; the platform stores it as
+ * `end_user_id` and isolates that person's memory, run history, and tool
+ * connections strictly. There is no fallback to account-level data.
+ *
+ * Registering an end-user here is optional — passing `user_id` on a run creates
+ * them implicitly. Do it explicitly when you want per-user budgets and rate
+ * limits. Mirrors `sdk/py/m8tes/_resources/users.py`.
+ */
+
+interface EndUserCreateParams {
+    /** Your id for this person. Any stable string. */
+    user_id: string;
+    name?: string;
+    email?: string;
+    company?: string;
+    metadata?: JsonObject;
+    /** Cap this end-user's runs per billing period. */
+    run_limit?: number;
+    /** Cap this end-user's spend per billing period, in cents. */
+    cost_limit_cents?: number;
+    /** Cap this end-user's runs per minute. Exceeding it returns 429. */
+    rate_per_minute?: number;
+}
+/** `null` CLEARS a cap (inherit the account default); omitting leaves it alone. */
+interface EndUserUpdateParams {
+    name?: string | null;
+    email?: string | null;
+    company?: string | null;
+    metadata?: JsonObject | null;
+    run_limit?: number | null;
+    cost_limit_cents?: number | null;
+    rate_per_minute?: number | null;
+}
+interface PageParams {
+    limit?: number;
+    starting_after?: number;
+}
+interface UsersResource {
+    create(params: EndUserCreateParams): Promise<EndUser>;
+    list(params?: PageParams): Promise<Page<EndUser>>;
+    get(userId: string): Promise<EndUser>;
+    update(userId: string, params: EndUserUpdateParams): Promise<EndUser>;
+    delete(userId: string): Promise<void>;
+    /** Per-end-user token, run, and cost usage against their limits. */
+    usage(params?: PageParams & {
+        user_id?: string;
+    }): Promise<Page<EndUserUsage>>;
+}
+
+/**
+ * `client.billing` — what you have spent, what you may spend, and the ceiling.
+ *
+ * This is the resource you reach for when cost is a product requirement rather
+ * than an afterthought: read current-period usage (runs, model spend, accrued
+ * overage), break spend down by day / end-user / agent / model, fetch the public
+ * plan catalog, and set the caps — the monthly overage cap on plan accounts, and
+ * on prepaid accounts the token balance, top-ups, auto-reload, and the
+ * low-balance alert threshold.
+ *
+ * An embed developer capping what their own customers can burn lives here: pair
+ * `usageTimeseries({ user_id })` with the per-end-user limits on `client.users`
+ * to meter each tenant, and `setOverage` / `setAutoReload` to bound the account
+ * as a whole.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/billing.py`.
+ */
+
+interface UsageTimeseriesParams {
+    /** Inclusive ISO date (`"2026-07-01"`), UTC days. Defaults to 30 days ago. */
+    start_date?: string;
+    /** Inclusive ISO date. Defaults to today. */
+    end_date?: string;
+    /** Scope to one end-user. */
+    user_id?: string;
+    /** Scope to one agent. */
+    agent_id?: number;
+    /** Permanent legacy alias for `agent_id` — the same wire field. */
+    teammate_id?: number;
+    /** Creation stamp: `"api"` embedding, `"platform"` first-party. Not settlement. */
+    surface?: "api" | "platform";
+    /** Where the run settled: `"wallet"` is the prepaid ledger. */
+    settled_meter?: "wallet" | "plan" | "released" | "own_sub";
+    /** `"model"` adds per-model slices to every bucket's `models`. The route
+     *  accepts this one value only, so it is a literal rather than a string. */
+    group_by?: "model";
+}
+interface OverageParams {
+    enabled: boolean;
+    /** Hard ceiling on overage spend per period, in cents. */
+    monthly_cap_cents: number;
+}
+interface TopupParams {
+    /** Cents to add. $5 minimum, $1M maximum. */
+    amount_cents: number;
+}
+/**
+ * Enabling auto-reload REQUIRES both amounts; disabling takes neither. Modelled
+ * as a union so `{ enabled: true }` alone is a compile error rather than a 422.
+ */
+type AutoReloadParams = {
+    enabled: true;
+    /** Reload when the balance drops below this, in cents. */
+    threshold_cents: number;
+    /** Cents to charge per reload. $5–$10,000. */
+    amount_cents: number;
+} | {
+    enabled: false;
+    /** Amounts may still be updated while disabled; the API applies them. */
+    threshold_cents?: number;
+    amount_cents?: number;
+};
+interface AlertThresholdParams {
+    /** Balance (cents) at which the low-balance warning fires. `0` warns only on depletion. */
+    low_balance_threshold_cents: number;
+}
+interface BillingResource {
+    /** Where you stand this period: plan, runs used vs included, model spend, and overage state. */
+    usage(): Promise<Usage>;
+    /**
+     * Spend broken down by UTC day — the series to chart, alert on, or reconcile
+     * against an invoice. Buckets are zero-filled across the whole window, so the
+     * array is safe to plot without gap-handling. Cost matches `usage().cost_used`
+     * semantics, so the series always reconciles with period totals. With
+     * `group_by: "model"`, runs that predate model attribution fold
+     * into a `"unknown"` slice rather than disappearing.
+     */
+    usageTimeseries(params?: UsageTimeseriesParams): Promise<UsageTimeseries>;
+    /**
+     * Proof of payment for finance: one row per paid prepaid top-up, newest first.
+     * `receipt_url` can be `null` when Stripe can no longer retrieve the session.
+     */
+    receipts(params?: PageParams): Promise<Page<Receipt>>;
+    /** What the paid plans include and cost — for your own pricing page or upgrade
+     *  prompt. Public (paid) plans only, straight from the canonical catalog, and
+     *  returned as a plain array rather than a page. */
+    plans(): Promise<Plan[]>;
+    /**
+     * Decide whether runs may continue past your plan's included allotment, and how
+     * far. Off by default; once enabled, extra runs bill at the per-run overage rate
+     * until `monthly_cap_cents` is reached. Returns the refreshed usage so you can
+     * confirm the new state without a second call.
+     */
+    setOverage(params: OverageParams): Promise<Usage>;
+    /** How much prepaid credit is left, and where it went (prepaid-billed accounts).
+     *  Amounts are micro-USD; `balance_usd` is a rounded display string. */
+    balance(): Promise<Balance>;
+    /**
+     * Add credit when a human is present to pay. Returns a Stripe Checkout URL to
+     * send the buyer to — nothing is credited until they complete payment.
+     */
+    topup(params: TopupParams): Promise<string>;
+    /**
+     * Keep credit topped up without a human, so runs never stop for an empty wallet:
+     * a balance below `threshold_cents` charges `amount_cents` to the saved card
+     * off-session. Enabling requires a saved payment method (any completed top-up
+     * Checkout saves one) — without it this throws a billing error with code
+     * `NO_SAVED_PAYMENT_METHOD`. Disabling needs only `enabled: false`. At most one
+     * reload fires per 6-hour window. Returns the refreshed balance.
+     */
+    setAutoReload(params: AutoReloadParams): Promise<Balance>;
+    /**
+     * Choose when you want to hear about a draining balance. The critical tier is
+     * fixed at 20% of the value you set, and `0` warns only on depletion. Warnings
+     * arrive by email and as `balance.low` / `balance.critical` / `balance.depleted`
+     * webhook events. Returns the refreshed balance.
+     */
+    setAlertThreshold(params: AlertThresholdParams): Promise<Balance>;
+}
+declare function createBillingResource(http: Http): BillingResource;
+
+/**
+ * `client.memories` — pre-load what an agent already knows about someone.
+ *
+ * A run starts cold unless it has memories to draw on. Writing them here lets you
+ * seed an end-user's context from data you already hold (plan, timezone, past
+ * decisions, preferences) so the first run behaves like the tenth, instead of
+ * waiting for the agent to learn it over several conversations.
+ *
+ * `user_id` is the scope, and the scopes never mix: with it, the memory belongs to
+ * that one end-user and is visible only to runs carrying the same `user_id`;
+ * without it, the memory is account-level and visible only to runs that carry no
+ * `user_id`. There is no inheritance between the two — an account-level memory is
+ * NOT a fallback for an end-user run.
+ *
+ * Documented at `/docs/users`. Mirrors `sdk/py/m8tes/_resources/memories.py`.
+ */
+
+interface MemoryCreateParams {
+    /** The fact to remember, in plain language. */
+    content: string;
+    /** Scope it to one end-user. Omit for an account-level memory. */
+    user_id?: string;
+}
+interface MemoryListParams {
+    /** Scope to read. Omit to read account-level memories. */
+    user_id?: string;
+    /**
+     * Keyword filter on content (case-insensitive substring). It only narrows the
+     * chosen scope — it never reaches across into the other one — and paging
+     * applies to the filtered set.
+     */
+    query?: string;
+    limit?: number;
+    starting_after?: number;
+}
+interface MemoryUpdateParams {
+    /** Replaces the stored text outright. */
+    content: string;
+    /** The scope the memory lives in. Must match, or the memory is not found. */
+    user_id?: string;
+}
+interface MemoriesResource {
+    /**
+     * Teach an agent a fact up front, before anyone runs it.
+     *
+     * Throws a `ConflictError` (409) when the scope is already at its memory
+     * capacity, or when identical content is already stored in it — so this is
+     * safe to call repeatedly only if you handle that error.
+     */
+    create(params: MemoryCreateParams): Promise<Memory>;
+    /** Audit or display what an agent knows about one end-user (or the account). */
+    list(params?: MemoryListParams): Promise<Page<Memory>>;
+    /** Correct a fact that changed, keeping its id — rather than delete + re-create. */
+    update(memoryId: number, params: MemoryUpdateParams): Promise<Memory>;
+    /** Make an agent forget something, e.g. on an end-user's erasure request. */
+    delete(memoryId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
+}
+declare function createMemoriesResource(http: Http): MemoriesResource;
+
+/**
+ * `client.models` — find out which `model` values are actually valid, and what
+ * they cost, instead of guessing from the docs.
+ *
+ * `model` is a plain string everywhere in this SDK, which keeps new models
+ * usable the day they're enabled but means a typo is only caught by the API. Ask
+ * this route instead: it returns the models your account can select right now
+ * (Anthropic and not — the set grows without an SDK release), which one is the
+ * default, and the per-million-token prices the platform bills you at, so you
+ * can estimate spend before starting a run.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/models.py`.
+ */
+
+interface ModelsResource {
+    /**
+     * The models you can pass as `model` on an agent or a run, with USD pricing
+     * per million tokens.
+     *
+     * Omit `model` on an agent/run to get the entry flagged `default: true` — that
+     * flag is per-viewer, so the default you see here is the default you'd get.
+     *
+     * Takes no arguments and has no cursor: `GET /models/` returns the whole
+     * catalog in one response. A `Page` is still returned so `for await` works the
+     * same as on every other list, but it never fetches a second page.
+     */
+    /**
+     * The model catalog. Check `zdr_supported` before sending customer data: a
+     * non-ZDR model is allowed on the API but may retain inputs and outputs.
+     */
+    list(): Promise<Page<Model>>;
+}
+declare function createModelsResource(http: Http): ModelsResource;
+
+/** Account-level OAuth subscriptions used by the Claude Code execution harness. */
+
+type ModelConnectionProvider = "claude" | "openai" | "xai" | "gemini";
+type AuthorizableModelConnectionProvider = "openai" | "xai" | "gemini";
+type DeviceModelConnectionProvider = "openai" | "xai";
+type CodeModelConnectionProvider = "gemini";
+interface ModelConnection {
+    provider: ModelConnectionProvider;
+    display_name: string;
+    connected: boolean;
+    status?: string | null;
+    account_label?: string | null;
+    expires_at?: string | null;
+}
+interface ModelAuthorization {
+    provider: AuthorizableModelConnectionProvider;
+    state: string;
+    status: "pending" | "connected";
+    authorization_url?: string | null;
+    user_code?: string | null;
+    expires_at?: string | null;
+    interval_seconds: number;
+}
+interface ModelConnectionsResource {
+    /** List supported providers. Credential material is never returned. */
+    list(): Promise<ModelConnection[]>;
+    /** Start provider-native authorization; show the returned URL and device code when used. */
+    authorize(provider: AuthorizableModelConnectionProvider): Promise<ModelAuthorization>;
+    /** Poll once; successful device authorization is saved automatically. */
+    authorizationStatus(provider: DeviceModelConnectionProvider, state: string): Promise<ModelAuthorization>;
+    /** Exchange a pasted authorization code and store the connection. */
+    completeAuthorization(provider: CodeModelConnectionProvider, state: string, params: {
+        code: string;
+    }): Promise<ModelAuthorization>;
+    /** Cancel a short-lived provider authorization session. */
+    cancelAuthorization(provider: AuthorizableModelConnectionProvider, state: string): Promise<void>;
+    /** Delete m8tes' encrypted copy of the provider credentials. */
+    disconnect(provider: ModelConnectionProvider): Promise<ModelConnection>;
+}
+declare function createModelConnectionsResource(http: Http): ModelConnectionsResource;
+
+/**
+ * `client.permissions` — standing tool allow-lists, one end-user at a time.
+ *
+ * A run pauses whenever the agent reaches for a tool that is not pre-approved,
+ * and stays paused until somebody answers. That is the right default for a first
+ * run and the wrong one for a tool your product has already decided is fine. A
+ * policy here says "this end-user's runs may use this tool" once, so their runs
+ * stop stopping.
+ *
+ * Scope: policies are per end-user (`user_id` is required on every call — there
+ * is no account-wide policy) and outlive the run, unlike `runs.answerPermission()`
+ * which unblocks a single gate. `/docs/users` documents this surface; mirrors
+ * `sdk/py/m8tes/_resources/permissions.py`.
+ */
+
+interface PermissionCreateParams {
+    /** The end-user whose runs this policy applies to. Required — policies never span end-users. */
+    user_id: string;
+    /** The tool to pre-approve, e.g. `"Bash"` or an `mcp__*` tool name. */
+    tool: string;
+}
+interface PermissionListParams extends PageParams {
+    /** Required: you list one end-user's policies, never the account's. */
+    user_id: string;
+}
+interface PermissionsResource {
+    /**
+     * Pre-approve a tool so this end-user's runs no longer pause on it.
+     * Idempotent — re-approving the same tool returns the existing policy rather
+     * than erroring or duplicating. Send `tool`; the policy comes back as `tool_name`.
+     */
+    create(params: PermissionCreateParams): Promise<PermissionPolicy>;
+    /** Audit what an end-user's runs are allowed to do without asking. */
+    list(params: PermissionListParams): Promise<Page<PermissionPolicy>>;
+    /**
+     * Revoke a pre-approval, so the tool gates again on the next run.
+     * `user_id` is required and scopes the delete — an id alone will not resolve.
+     */
+    delete(permissionId: number, params: {
+        user_id: string;
+    }): Promise<void>;
+}
+declare function createPermissionsResource(http: Http): PermissionsResource;
+
+/**
+ * Wait for a run to finish.
+ *
+ * Streaming is the good path: you see the work as it happens. But plenty of
+ * integrations are a queue worker or a cron job that just wants the answer, and
+ * without this every one of them hand-rolls the same loop — with its own idea of
+ * which statuses are terminal, its own backoff, and usually no timeout. That is
+ * the single most common thing a developer had to build themselves.
+ *
+ * Mirrors `sdk/py/m8tes/_resources/runs.py` (`poll`, `wait`): same terminal set,
+ * same 2s interval and 300s default timeout, same "a transient API error is not
+ * a failure, keep polling until the deadline" behaviour.
+ */
+
+/**
+ * A run is done when it reaches one of these.
+ *
+ * Mirrors `TERMINAL_RUN_STATUSES` in `fastapi/app/models/run.py`, which is the
+ * canonical set — including `"closed"` (a user-closed chat that cannot resume).
+ * Both SDKs previously omitted it, so a closed run polled until the timeout.
+ * The backend's own comment on that set warns these lists drift and that "a
+ * 'closed' chat run burned tokens too". `archived` is deliberately NOT here:
+ * it is a display state applied to already-terminal runs.
+ */
+declare const TERMINAL_STATUSES: Set<string>;
+interface PollOptions {
+    /** Seconds between polls. Default 2. */
+    interval?: number;
+    /** Seconds before giving up. Default 300. */
+    timeout?: number;
+    /** Abort the wait early. The in-flight request is cancelled with it. */
+    signal?: AbortSignal;
+}
+interface WaitOptions extends PollOptions {
+    /**
+     * Called when a tool needs a decision. Return "allow" or "deny".
+     * Without it, a run that pauses for a tool throws rather than hanging until
+     * the timeout — silence would look identical to a slow run.
+     */
+    onApproval?: (request: PermissionRequest) => "allow" | "deny" | Promise<"allow" | "deny">;
+    /**
+     * Called when the agent asks a question. Return `{ [question text]: answer }`.
+     * The keys must be the exact `question` strings from the request.
+     */
+    onQuestion?: (request: PermissionRequest) => Record<string, string> | Promise<Record<string, string>>;
+}
+/** Thrown when a run does not reach a terminal status before the deadline. */
+declare class RunTimeoutError extends Error {
+    readonly runId: number;
+    readonly timeoutSeconds: number;
+    /** The last error seen while polling, if any. Without it a timeout hides the
+     *  transient failure that actually caused it. */
+    readonly cause?: unknown;
+    /** The run's status when the deadline hit, when one was ever observed. */
+    readonly lastStatus?: string;
+    constructor(runId: number, timeoutSeconds: number, cause?: unknown, lastStatus?: string);
+}
+/**
+ * Thrown when a run pauses for a human and no handler was supplied. Better than
+ * waiting out the full timeout, which gives the caller no idea what happened.
+ */
+declare class RunPausedError extends Error {
+    readonly runId: number;
+    readonly request: PermissionRequest;
+    constructor(runId: number, request: PermissionRequest, hint: string);
+}
+/** True for an AskUserQuestion pause carrying a plan for approval (plan mode). */
+declare function isPlanApproval(request: PermissionRequest): boolean;
+/** The proposed plan text, for a plan-approval pause. Null otherwise. */
+declare function planText(request: PermissionRequest): string | null;
+/**
+ * Injected by the runs resource so this module stays free of transport concerns.
+ * Every call takes the caller's `signal`, so an abort cancels the in-flight HTTP
+ * request instead of only shortening the next sleep.
+ */
+interface PollDeps {
+    get(runId: number, signal?: AbortSignal): Promise<Run>;
+    permissions(runId: number, signal?: AbortSignal): Promise<PermissionRequest[]>;
+    approve(runId: number, params: {
+        request_id: string;
+        decision: "allow" | "deny";
+    }, signal?: AbortSignal): Promise<unknown>;
+    answer(runId: number, params: {
+        answers: Record<string, string>;
+    }, signal?: AbortSignal): Promise<unknown>;
+}
+/** Thrown when the caller aborts the wait. */
+declare class RunWaitAbortedError extends Error {
+    /**
+     * The run being waited on — `undefined` when the abort landed BEFORE any run
+     * was created, which is the one case where there is nothing to go back to.
+     * Previously this path passed a literal 0, producing "Waiting on run 0 was
+     * aborted" and pointing the reader at a run that never existed.
+     */
+    readonly runId?: number;
+    constructor(runId?: number);
+}
+/**
+ * Poll until the run is terminal.
+ *
+ * A run that pauses for a human never becomes terminal, so this would spin until
+ * the timeout — `waitForRun` handles that case. `poll` is for autonomous runs.
+ */
+declare function pollRun(deps: PollDeps, runId: number, options?: PollOptions): Promise<Run>;
+/**
+ * Wait for a run, answering human-in-the-loop pauses through callbacks.
+ *
+ * Same loop as `pollRun`, plus: on `awaiting_approval`, resolve every pending
+ * request and let the run continue.
+ */
+declare function waitForRun(deps: PollDeps, runId: number, options?: WaitOptions): Promise<Run>;
+
 /**
  * `RunStream` — the developer-facing view of a streaming run.
  *
@@ -481,6 +1206,13 @@ interface RunStreamOptions {
      * Defaults to false, matching the Python SDK.
      */
     raiseOnError?: boolean;
+    /**
+     * Reuse this key to retry the same call safely — the server replays the run the
+     * first attempt produced instead of starting (and billing) a second one. One is
+     * minted per call automatically; supply your own only when a retry must survive
+     * a process restart. Sent as the `Idempotency-Key` header.
+     */
+    idempotencyKey?: string;
 }
 declare class RunStream implements AsyncIterable<M8tesStreamEvent> {
     private readonly source;
@@ -548,6 +1280,40 @@ interface RunCreateParams {
     output_schema?: JsonObject;
     /** Give this run's agent an email inbox. */
     email_inbox?: boolean;
+    /**
+     * Reuse this key to retry the same create safely — the server returns the run
+     * the first attempt made instead of starting (and billing) a second one.
+     *
+     * One is minted per call automatically, which is what makes the SDK's own
+     * retries safe. Supply your own only when a retry must survive a process
+     * restart: a job runner re-driving the same unit of work should pass its job
+     * id. Sent as the `Idempotency-Key` header; never part of the request body.
+     */
+    idempotencyKey?: string;
+    /**
+     * Files the agent can read: a CSV to analyze, a PDF to summarize. Each is a
+     * `{ name, data }` pair; `data` accepts anything `FormData` takes (Blob,
+     * Uint8Array, ArrayBuffer, string). Sending files switches the request to the
+     * multipart `/runs/with-files` endpoint; every other option behaves the same.
+     *
+     * Attachments require sandbox execution (the agent reads them with its file
+     * tools from the run's working directory).
+     */
+    files?: RunFileInput[];
+}
+/** One attachment for `runs.create({ files })`. */
+interface RunFileInput {
+    /** Filename the agent will see. Its extension determines the content type. */
+    name: string;
+    /** Contents. `Blob`/`File` pass straight through; bytes and strings are wrapped. */
+    data: Blob | ArrayBuffer | ArrayBufferView | string;
+    /**
+     * Content type, if the extension does not imply it. The upload endpoint
+     * validates against an allowlist and rejects the batch on a miss, so this is
+     * inferred from `name` by default rather than defaulting to
+     * `application/octet-stream` (which the server refuses).
+     */
+    type?: string;
 }
 interface RunListParams {
     user_id?: string;
@@ -580,6 +1346,27 @@ interface RunsResource {
     create(params: RunCreateParams, options?: RunStreamOptions): RunStream;
     /** Start a run and return immediately; poll `get()` or use a webhook for the result. */
     createAsync(params: RunCreateParams): Promise<Run>;
+    /**
+     * Start a run and wait for the result. The batch/cron counterpart to `create()`.
+     * Pass `onApproval`/`onQuestion` to answer human-in-the-loop pauses inline;
+     * without them a paused run throws `RunPausedError` rather than hanging.
+     */
+    createAndWait(params: RunCreateParams, options?: WaitOptions): Promise<Run>;
+    /** Poll an existing run until it is terminal. Throws `RunTimeoutError` on deadline. */
+    poll(runId: number, options?: PollOptions): Promise<Run>;
+    /** Like `poll`, but resolves human-in-the-loop pauses through callbacks. */
+    wait(runId: number, options?: WaitOptions): Promise<Run>;
+    /**
+     * Retry a failed or cancelled run. Returns a NEW run — poll that one's id, the
+     * original stays failed. Idempotent: an in-flight retry is returned as-is.
+     *
+     * If the run already did something visible (sent a message, changed data), the
+     * API refuses with a 409 `retry_needs_confirmation`; pass `confirm: true` to
+     * proceed. Check `run.retryable` first to avoid a guaranteed conflict.
+     */
+    retry(runId: number, params?: {
+        confirm?: boolean;
+    }): Promise<Run>;
     /** Join a run already in flight. Throws `RunNotStreamingError` if it has finished. */
     stream(runId: number, options?: RunStreamOptions): RunStream;
     /** Continue the conversation on an existing run, streaming the reply. */
@@ -743,17 +1530,35 @@ interface TriggerCreateParams {
 }
 interface TriggersResource {
     create(taskId: number, params: TriggerCreateParams): Promise<Trigger>;
-    list(taskId: number): Promise<Trigger[]>;
+    list(taskId: number, params?: {
+        user_id?: string;
+    }): Promise<Trigger[]>;
     /** Only the schedule shape and the enabled flag are mutable — a trigger's
      *  `type`/`app`/`trigger_name` are fixed at creation and are silently ignored
-     *  on PATCH. Delete and recreate to change those. */
+     *  on PATCH. Delete and recreate to change those. `user_id` scopes to one
+     *  end-user (404 on mismatch). */
     update(taskId: number, triggerId: number, params: {
         cron?: string;
         interval_seconds?: number;
         timezone?: string;
         enabled?: boolean;
+        user_id?: string;
     }): Promise<Trigger>;
-    delete(taskId: number, triggerId: number): Promise<void>;
+    delete(taskId: number, triggerId: number, params?: {
+        user_id?: string;
+    }): Promise<void>;
+}
+interface TaskRunParams {
+    /** Run on behalf of this end-user. */
+    user_id?: string;
+    /**
+     * Reuse this key to retry the same call safely — the server returns the run the
+     * first attempt made instead of starting (and billing) a second one. One is
+     * minted per call automatically; supply your own (e.g. a scheduler's job id)
+     * only when a retry must survive a process restart. Sent as the
+     * `Idempotency-Key` header, never in the body.
+     */
+    idempotencyKey?: string;
 }
 interface TasksResource {
     triggers: TriggersResource;
@@ -769,67 +1574,16 @@ interface TasksResource {
         user_id?: string;
     }): Promise<void>;
     /** Run the task now, streaming it. */
-    run(taskId: number, params?: {
-        user_id?: string;
-    }, options?: RunStreamOptions): RunStream;
+    run(taskId: number, params?: TaskRunParams, options?: RunStreamOptions): RunStream;
     /** Run the task now without streaming; poll `runs.get()` for the result. */
-    runAsync(taskId: number, params?: {
+    runAsync(taskId: number, params?: TaskRunParams): Promise<Run>;
+    /** `user_id` scopes to one end-user (404 on mismatch), like get/update/delete. */
+    enableWebhook(taskId: number, params?: {
         user_id?: string;
-    }): Promise<Run>;
-    enableWebhook(taskId: number): Promise<WebhookToggle>;
-    disableWebhook(taskId: number): Promise<void>;
-}
-
-/**
- * `client.users` — your end-users, the multi-tenancy boundary.
- *
- * `user_id` is YOUR identifier for a customer; the platform stores it as
- * `end_user_id` and isolates that person's memory, run history, and tool
- * connections strictly. There is no fallback to account-level data.
- *
- * Registering an end-user here is optional — passing `user_id` on a run creates
- * them implicitly. Do it explicitly when you want per-user budgets and rate
- * limits. Mirrors `sdk/py/m8tes/_resources/users.py`.
- */
-
-interface EndUserCreateParams {
-    /** Your id for this person. Any stable string. */
-    user_id: string;
-    name?: string;
-    email?: string;
-    company?: string;
-    metadata?: JsonObject;
-    /** Cap this end-user's runs per billing period. */
-    run_limit?: number;
-    /** Cap this end-user's spend per billing period, in cents. */
-    cost_limit_cents?: number;
-    /** Cap this end-user's runs per minute. Exceeding it returns 429. */
-    rate_per_minute?: number;
-}
-/** `null` CLEARS a cap (inherit the account default); omitting leaves it alone. */
-interface EndUserUpdateParams {
-    name?: string | null;
-    email?: string | null;
-    company?: string | null;
-    metadata?: JsonObject | null;
-    run_limit?: number | null;
-    cost_limit_cents?: number | null;
-    rate_per_minute?: number | null;
-}
-interface PageParams {
-    limit?: number;
-    starting_after?: number;
-}
-interface UsersResource {
-    create(params: EndUserCreateParams): Promise<EndUser>;
-    list(params?: PageParams): Promise<Page<EndUser>>;
-    get(userId: string): Promise<EndUser>;
-    update(userId: string, params: EndUserUpdateParams): Promise<EndUser>;
-    delete(userId: string): Promise<void>;
-    /** Per-end-user token, run, and cost usage against their limits. */
-    usage(params?: PageParams & {
+    }): Promise<WebhookToggle>;
+    disableWebhook(taskId: number, params?: {
         user_id?: string;
-    }): Promise<Page<EndUserUsage>>;
+    }): Promise<void>;
 }
 
 /**
@@ -918,7 +1672,7 @@ interface WebhooksResource {
  */
 
 /** Kept in lockstep with package.json "version" — guarded by test/version.test.ts. */
-declare const M8TES_SDK_VERSION = "0.1.0-alpha.1";
+declare const M8TES_SDK_VERSION = "0.1.0-alpha.2";
 declare class M8tes {
     readonly runs: RunsResource;
     readonly agents: AgentsResource;
@@ -929,9 +1683,15 @@ declare class M8tes {
     readonly apps: AppsResource;
     readonly webhooks: WebhooksResource;
     readonly settings: SettingsResource;
+    readonly memories: MemoriesResource;
+    readonly permissions: PermissionsResource;
+    readonly models: ModelsResource;
+    readonly modelConnections: ModelConnectionsResource;
+    readonly billing: BillingResource;
+    readonly account: AccountResource;
     /** The underlying transport. Use it to call an endpoint this version does not wrap yet. */
     readonly http: Http;
     constructor(options?: ClientOptions);
 }
 
-export { type AccountSettings, type AccountSettingsUpdateParams, type Agent, type AgentCreateParams, type AgentListParams, type AgentUpdateParams, type AgentsResource, type App, type AppConnectionInitiation, type AppConnectionResult, type AppsResource, type ClientOptions, ConversationState, DEFAULT_BASE_URL, type EmailInbox, type EndUser, type EndUserCreateParams, type EndUserUpdateParams, type EndUserUsage, type FetchLike, type Http, type JsonObject, type ListResponse, M8TES_SDK_VERSION, M8tes, M8tesStreamEvent, Normalizer, Page, type PageParams, type PermissionMode, type PermissionRequest, type Run, type RunCreateParams, type RunFile, type RunListParams, type RunOutcome, RunStream, type RunStreamOptions, type RunUsage, type RunsResource, type SettingsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TasksResource, type Teammate, type Trigger, type TriggerCreateParams, type TriggerType, type TriggersResource, type UsersResource, type VerifySignatureOptions, type Webhook, type WebhookDelivery, type WebhookToggle, type WebhooksResource, createHttp, verifySignature };
+export { type AccountDeletion, type AccountExport, type AccountResource, type AccountSettings, type AccountSettingsUpdateParams, type Agent, type AgentCreateParams, type AgentListParams, type AgentUpdateParams, type AgentsResource, type AlertThresholdParams, type App, type AppConnectionInitiation, type AppConnectionResult, type AppsResource, type AuthorizableModelConnectionProvider, type AutoReloadParams, type Balance, type BillingResource, type ClientOptions, type CodeModelConnectionProvider, ConversationState, DEFAULT_BASE_URL, type DeviceModelConnectionProvider, type EmailInbox, type EndUser, type EndUserCreateParams, type EndUserUpdateParams, type EndUserUsage, type FetchLike, type Http, type JsonObject, type ListResponse, M8TES_SDK_VERSION, M8tes, M8tesStreamEvent, type MemoriesResource, type Memory, type MemoryCreateParams, type MemoryListParams, type MemoryUpdateParams, type Model, type ModelAuthorization, type ModelConnection, type ModelConnectionProvider, type ModelConnectionsResource, type ModelPricing, type ModelsResource, Normalizer, type OverageParams, Page, type PageParams, type PermissionCreateParams, type PermissionListParams, type PermissionMode, type PermissionPolicy, type PermissionRequest, type PermissionsResource, type Plan, type PollOptions, type Receipt, type Run, type RunCreateParams, type RunFile, type RunListParams, type RunOutcome, RunPausedError, RunStream, type RunStreamOptions, RunTimeoutError, type RunUsage, RunWaitAbortedError, type RunsResource, type SettingsResource, TERMINAL_STATUSES, type Task, type TaskCreateParams, type TaskListParams, type TaskRunParams, type TaskUpdateParams, type TasksResource, type Teammate, type TokenTransaction, type TopupParams, type Trigger, type TriggerCreateParams, type TriggerType, type TriggersResource, type Usage, type UsageBucket, type UsageModelSlice, type UsageTimeseries, type UsageTimeseriesParams, type UsageTotals, type UsersResource, type VerifySignatureOptions, type WaitOptions, type Webhook, type WebhookDelivery, type WebhookToggle, type WebhooksResource, createAccountResource, createBillingResource, createHttp, createMemoriesResource, createModelConnectionsResource, createModelsResource, createPermissionsResource, isPlanApproval, planText, pollRun, verifySignature, waitForRun };