@puku-ai/sdk 4.0.0 → 4.0.2

package/dist/vendor/resources/beta/sessions/sessions.d.ts

@@ -0,0 +1,866 @@
+import { APIResource } from '../../../core/resource';
+import * as BetaAPI from '../beta';
+import * as AgentsAPI from '../agents/agents';
+import * as EventsAPI from './events';
+import { BetaManagedAgentsAgentCustomToolUseEvent, BetaManagedAgentsAgentMCPToolResultEvent, BetaManagedAgentsAgentMCPToolUseEvent, BetaManagedAgentsAgentMessageEvent, BetaManagedAgentsAgentThinkingEvent, BetaManagedAgentsAgentThreadContextCompactedEvent, BetaManagedAgentsAgentThreadMessageReceivedEvent, BetaManagedAgentsAgentThreadMessageSentEvent, BetaManagedAgentsAgentToolResultEvent, BetaManagedAgentsAgentToolUseEvent, BetaManagedAgentsBase64DocumentSource, BetaManagedAgentsBase64ImageSource, BetaManagedAgentsBillingError, BetaManagedAgentsCredentialHostUnreachableError, BetaManagedAgentsDocumentBlock, BetaManagedAgentsEventParams, BetaManagedAgentsFileDocumentSource, BetaManagedAgentsFileImageSource, BetaManagedAgentsFileRubric, BetaManagedAgentsFileRubricParams, BetaManagedAgentsImageBlock, BetaManagedAgentsMCPAuthenticationFailedError, BetaManagedAgentsMCPConnectionFailedError, BetaManagedAgentsModelOverloadedError, BetaManagedAgentsModelRateLimitedError, BetaManagedAgentsModelRequestFailedError, BetaManagedAgentsPlainTextDocumentSource, BetaManagedAgentsRedactedBlock, BetaManagedAgentsRetryStatusExhausted, BetaManagedAgentsRetryStatusRetrying, BetaManagedAgentsRetryStatusTerminal, BetaManagedAgentsSearchResultBlock, BetaManagedAgentsSearchResultCitations, BetaManagedAgentsSearchResultContent, BetaManagedAgentsSendSessionEvents, BetaManagedAgentsSessionBudgetReached, BetaManagedAgentsSessionDeletedEvent, BetaManagedAgentsSessionEndTurn, BetaManagedAgentsSessionErrorEvent, BetaManagedAgentsSessionEvent, BetaManagedAgentsSessionEventsPageCursor, BetaManagedAgentsSessionRequiresAction, BetaManagedAgentsSessionRetriesExhausted, BetaManagedAgentsSessionStatusIdleEvent, BetaManagedAgentsSessionStatusRescheduledEvent, BetaManagedAgentsSessionStatusRunningEvent, BetaManagedAgentsSessionStatusTerminatedEvent, BetaManagedAgentsSessionThreadCreatedEvent, BetaManagedAgentsSessionThreadStatusIdleEvent, BetaManagedAgentsSessionThreadStatusRescheduledEvent, BetaManagedAgentsSessionThreadStatusRunningEvent, BetaManagedAgentsSessionThreadStatusTerminatedEvent, BetaManagedAgentsSessionUsageSnapshot, BetaManagedAgentsSpanModelRequestEndEvent, BetaManagedAgentsSpanModelRequestStartEvent, BetaManagedAgentsSpanModelUsage, BetaManagedAgentsSpanOutcomeEvaluationEndEvent, BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent, BetaManagedAgentsSpanOutcomeEvaluationStartEvent, BetaManagedAgentsStreamSessionEvents, BetaManagedAgentsSystemMessageEventParams, BetaManagedAgentsTextBlock, BetaManagedAgentsTextRubric, BetaManagedAgentsTextRubricParams, BetaManagedAgentsURLDocumentSource, BetaManagedAgentsURLImageSource, BetaManagedAgentsUnknownError, BetaManagedAgentsUserCustomToolResultEvent, BetaManagedAgentsUserCustomToolResultEventParams, BetaManagedAgentsUserDefineOutcomeEvent, BetaManagedAgentsUserDefineOutcomeEventParams, BetaManagedAgentsUserInterruptEvent, BetaManagedAgentsUserInterruptEventParams, BetaManagedAgentsUserMessageEvent, BetaManagedAgentsUserMessageEventParams, BetaManagedAgentsUserToolConfirmationEvent, BetaManagedAgentsUserToolConfirmationEventParams, BetaManagedAgentsUserToolResultEventParams, EventListParams, EventSendParams, EventStreamParams, Events } from './events';
+import * as ResourcesAPI from './resources';
+import { BetaManagedAgentsDeleteSessionResource, BetaManagedAgentsFileResource, BetaManagedAgentsGitHubRepositoryResource, BetaManagedAgentsMemoryStoreResource, BetaManagedAgentsSessionResource, BetaManagedAgentsSessionResourcesPageCursor, ResourceAddParams, ResourceDeleteParams, ResourceListParams, ResourceRetrieveParams, ResourceRetrieveResponse, ResourceUpdateParams, ResourceUpdateResponse, Resources } from './resources';
+import * as ThreadsAPI from './threads/threads';
+import { BetaManagedAgentsSessionThread, BetaManagedAgentsSessionThreadStats, BetaManagedAgentsSessionThreadStatus, BetaManagedAgentsSessionThreadUsage, BetaManagedAgentsSessionThreadsPageCursor, BetaManagedAgentsStreamSessionThreadEvents, ThreadArchiveParams, ThreadListParams, ThreadRetrieveParams, Threads } from './threads/threads';
+import { APIPromise } from '../../../core/api-promise';
+import { BidirectionalPageCursor, type BidirectionalPageCursorParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
+export declare class Sessions extends APIResource {
+    events: EventsAPI.Events;
+    resources: ResourcesAPI.Resources;
+    threads: ThreadsAPI.Threads;
+    /**
+     * Create Session
+     *
+     * @example
+     * ```ts
+     * const betaManagedAgentsSession =
+     *   await client.beta.sessions.create({
+     *     agent: 'agent_011CZkYpogX7uDKUyvBTophP',
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   });
+     * ```
+     */
+    create(params: SessionCreateParams, options?: RequestOptions): APIPromise<BetaManagedAgentsSession>;
+    /**
+     * Get Session
+     *
+     * @example
+     * ```ts
+     * const betaManagedAgentsSession =
+     *   await client.beta.sessions.retrieve(
+     *     'sesn_011CZkZAtmR3yMPDzynEDxu7',
+     *   );
+     * ```
+     */
+    retrieve(sessionID: string, params?: SessionRetrieveParams | null | undefined, options?: RequestOptions): APIPromise<BetaManagedAgentsSession>;
+    /**
+     * Update Session
+     *
+     * @example
+     * ```ts
+     * const betaManagedAgentsSession =
+     *   await client.beta.sessions.update(
+     *     'sesn_011CZkZAtmR3yMPDzynEDxu7',
+     *   );
+     * ```
+     */
+    update(sessionID: string, params: SessionUpdateParams, options?: RequestOptions): APIPromise<BetaManagedAgentsSession>;
+    /**
+     * List Sessions
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const betaManagedAgentsSession of client.beta.sessions.list()) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(params?: SessionListParams | null | undefined, options?: RequestOptions): PagePromise<BetaManagedAgentsSessionsBidirectionalPageCursor, BetaManagedAgentsSession>;
+    /**
+     * Delete Session
+     *
+     * @example
+     * ```ts
+     * const betaManagedAgentsDeletedSession =
+     *   await client.beta.sessions.delete(
+     *     'sesn_011CZkZAtmR3yMPDzynEDxu7',
+     *   );
+     * ```
+     */
+    delete(sessionID: string, params?: SessionDeleteParams | null | undefined, options?: RequestOptions): APIPromise<BetaManagedAgentsDeletedSession>;
+    /**
+     * Archive Session
+     *
+     * @example
+     * ```ts
+     * const betaManagedAgentsSession =
+     *   await client.beta.sessions.archive(
+     *     'sesn_011CZkZAtmR3yMPDzynEDxu7',
+     *   );
+     * ```
+     */
+    archive(sessionID: string, params?: SessionArchiveParams | null | undefined, options?: RequestOptions): APIPromise<BetaManagedAgentsSession>;
+}
+export type BetaManagedAgentsSessionsBidirectionalPageCursor = BidirectionalPageCursor<BetaManagedAgentsSession>;
+/**
+ * Platform advisor roster entry: a model the session's primary thread may consult
+ * mid-turn. At most one per roster; the entry occupies the roster name
+ * `puku.advisor`.
+ */
+export interface BetaManagedAgentsAdvisorParams {
+    /**
+     * A Puku model id. The model must be permitted as an advisor for this agent's
+     * model — see the sessions/threads/advisor spec.
+     */
+    model: string;
+    type: 'advisor';
+}
+export interface BetaManagedAgentsAgentMessagePreview {
+    /**
+     * The id the buffered agent.message will carry if it is emitted. Matches the
+     * event_id on this preview's event_delta events.
+     */
+    id: string;
+    type: 'agent.message';
+}
+/**
+ * Specification for an Agent. Provide a specific `version` or use the short-form
+ * `agent="agent_id"` for the most recent version
+ */
+export interface BetaManagedAgentsAgentParams {
+    /**
+     * The `agent` ID.
+     */
+    id: string;
+    type: 'agent';
+    /**
+     * The specific `agent` version to use. Omit to use the latest version. Must be at
+     * least 1 if specified.
+     */
+    version?: number;
+}
+export interface BetaManagedAgentsAgentThinkingPreview {
+    /**
+     * The id the buffered agent.thinking will carry if it is emitted. Start-only — no
+     * event_delta events follow.
+     */
+    id: string;
+    type: 'agent.thinking';
+}
+/**
+ * Reference to an `agent` plus optional configuration overrides. Each provided
+ * field replaces the agent's value for the caller's use; the agent resource is
+ * unchanged.
+ */
+export interface BetaManagedAgentsAgentWithOverridesParams {
+    /**
+     * The `agent` ID.
+     */
+    id: string;
+    type: 'agent_with_overrides';
+    /**
+     * Replacement MCP server list. Full replacement: the provided array becomes the
+     * MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
+     */
+    mcp_servers?: Array<AgentsAPI.BetaManagedAgentsURLMCPServerParams>;
+    /**
+     * Replacement model. Accepts the model string, e.g. `puku-opus-5`, or a
+     * `model_config` object. Omit to use the agent's model.
+     */
+    model?: AgentsAPI.BetaManagedAgentsModel | AgentsAPI.BetaManagedAgentsModelConfigParams;
+    /**
+     * Replacement skill list. Full replacement: the provided array becomes the skills.
+     * Send an empty array to clear; omit to preserve the agent's skills.
+     */
+    skills?: Array<AgentsAPI.BetaManagedAgentsSkillParams>;
+    /**
+     * Replacement system prompt. Up to 100,000 characters. Set to null to clear the
+     * agent's system prompt; omit to preserve it.
+     */
+    system?: string | null;
+    /**
+     * Replacement tool list. Full replacement: the provided array becomes the tool
+     * configuration. Send an empty array to clear; omit to preserve the agent's tools.
+     */
+    tools?: Array<AgentsAPI.BetaManagedAgentsAgentToolset20260401Params | AgentsAPI.BetaManagedAgentsMCPToolsetParams | AgentsAPI.BetaManagedAgentsCustomToolParams>;
+    /**
+     * The specific `agent` version to use. Omit to use the latest version.
+     */
+    version?: number;
+}
+export interface BetaManagedAgentsBranchCheckout {
+    /**
+     * Branch name to check out.
+     */
+    name: string;
+    type: 'branch';
+}
+/**
+ * A hard spend ceiling. The session stops issuing new model requests once the
+ * tracked list cost reaches `max_list_cost`.
+ */
+export interface BetaManagedAgentsBudgetLimit {
+    /**
+     * A monetary amount in a specific currency.
+     */
+    max_list_cost: BetaAPI.BetaMonetaryAmount;
+    type: 'limit';
+}
+/**
+ * Prompt-cache creation token usage broken down by cache lifetime.
+ */
+export interface BetaManagedAgentsCacheCreationUsage {
+    /**
+     * Tokens used to create 1-hour ephemeral cache entries.
+     */
+    ephemeral_1h_input_tokens?: number;
+    /**
+     * Tokens used to create 5-minute ephemeral cache entries.
+     */
+    ephemeral_5m_input_tokens?: number;
+}
+export interface BetaManagedAgentsCommitCheckout {
+    /**
+     * Full commit SHA to check out.
+     */
+    sha: string;
+    type: 'commit';
+}
+/**
+ * Confirmation that a `session` has been permanently deleted.
+ */
+export interface BetaManagedAgentsDeletedSession {
+    id: string;
+    type: 'session_deleted';
+}
+export interface BetaManagedAgentsDeltaContent {
+    /**
+     * Regular text content.
+     */
+    content: EventsAPI.BetaManagedAgentsTextBlock;
+    type: 'content_delta';
+    /**
+     * Which entry in the previewed event's content array this fragment lands in.
+     * Insert content as that entry when the index is new; append to the existing entry
+     * otherwise.
+     */
+    index?: number;
+}
+/**
+ * An incremental update to an event that is still being streamed. Deltas are
+ * best-effort and may stop early; when the buffered event with id == event_id is
+ * produced it carries the complete content. A model request that ends early (an
+ * error or interrupt) produces no buffered event — its terminal
+ * span.model_request_end closes the preview. Only sent on stream connections that
+ * opt in via event_deltas; never appears in event history.
+ */
+export interface BetaManagedAgentsDeltaEvent {
+    /**
+     * One fragment of the previewed event. The delta type is named for the previewed
+     * event's field it streams into: agent.message events stream content_delta
+     * fragments, each a partial element of the content array.
+     */
+    delta: BetaManagedAgentsDeltaContent;
+    /**
+     * The id of the event being previewed. Matches event.id on the corresponding
+     * event_start and the buffered event that reconciles the preview.
+     */
+    event_id: string;
+    type: 'event_delta';
+}
+/**
+ * EventDeltaType enum
+ */
+export type BetaManagedAgentsDeltaType = 'agent.message' | 'agent.thinking';
+/**
+ * Mount a file uploaded via the Files API into the session.
+ */
+export interface BetaManagedAgentsFileResourceParams {
+    /**
+     * ID of a previously uploaded file.
+     */
+    file_id: string;
+    type: 'file';
+    /**
+     * Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
+     */
+    mount_path?: string | null;
+}
+/**
+ * Mount a GitHub repository into the session's container.
+ */
+export interface BetaManagedAgentsGitHubRepositoryResourceParams {
+    /**
+     * GitHub authorization token used to clone the repository.
+     */
+    authorization_token: string;
+    type: 'github_repository';
+    /**
+     * Github URL of the repository
+     */
+    url: string;
+    /**
+     * Branch or commit to check out. Defaults to the repository's default branch.
+     */
+    checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null;
+    /**
+     * Mount path in the container. Defaults to `/workspace/<repo-name>`.
+     */
+    mount_path?: string | null;
+}
+/**
+ * Parameters for attaching a memory store to an agent session.
+ */
+export interface BetaManagedAgentsMemoryStoreResourceParam {
+    /**
+     * The memory store ID (memstore\_...). Must belong to the caller's organization
+     * and workspace.
+     */
+    memory_store_id: string;
+    type: 'memory_store';
+    /**
+     * Access mode for an attached memory store.
+     */
+    access?: 'read_write' | 'read_only' | null;
+    /**
+     * Per-attachment guidance for the agent on how to use this store. Rendered into
+     * the memory section of the system prompt. Max 4096 chars.
+     */
+    instructions?: string | null;
+}
+/**
+ * Resolved coordinator topology with a concrete agent roster.
+ */
+export interface BetaManagedAgentsMultiagent {
+    /**
+     * Agents the coordinator may spawn as session threads, each resolved to a specific
+     * version.
+     */
+    agents: Array<AgentsAPI.BetaManagedAgentsAgentReference | AgentsAPI.BetaManagedAgentsAdvisor>;
+    type: 'coordinator';
+}
+/**
+ * A coordinator topology: the session's primary thread orchestrates work by
+ * spawning session threads, each running an agent drawn from the `agents` roster.
+ */
+export interface BetaManagedAgentsMultiagentParams {
+    /**
+     * Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is
+     * an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or
+     * `{"type":"self"}` to allow recursive self-invocation. Entries must reference
+     * distinct agents (after resolving `self` and string forms); at most one `self`.
+     * Referenced agents must exist, must not be archived, and must not themselves have
+     * `multiagent` set (depth limit 1).
+     */
+    agents: Array<BetaManagedAgentsMultiagentRosterEntryParams>;
+    type: 'coordinator';
+}
+/**
+ * An entry in a multiagent roster: an agent ID string, a versioned agent
+ * reference, or `self`.
+ */
+export type BetaManagedAgentsMultiagentRosterEntryParams = string | BetaManagedAgentsAgentParams | AgentsAPI.BetaManagedAgentsMultiagentSelfParams | BetaManagedAgentsAdvisorParams;
+/**
+ * Evaluation state for a single outcome defined via a `define_outcome` event.
+ */
+export interface BetaManagedAgentsOutcomeEvaluationResource {
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    completed_at: string | null;
+    /**
+     * What the agent should produce.
+     */
+    description: string;
+    /**
+     * Grader's verdict text from the most recent evaluation. For `satisfied`, explains
+     * why criteria are met; for `needs_revision` (intermediate), what's missing; for
+     * `failed`, why unrecoverable.
+     */
+    explanation: string | null;
+    /**
+     * 0-indexed revision cycle the outcome is currently on.
+     */
+    iteration: number;
+    /**
+     * Server-generated outc\_ ID for this outcome.
+     */
+    outcome_id: string;
+    /**
+     * Current evaluation state. `pending` before the agent begins work; `running`
+     * while producing or revising; `evaluating` while the grader scores;
+     * `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
+     */
+    result: string;
+    type: 'outcome_evaluation';
+}
+/**
+ * Cumulative count of server-executed tool invocations, broken down by tool.
+ */
+export interface BetaManagedAgentsServerToolUsage {
+    /**
+     * Number of server-executed web fetch requests.
+     */
+    web_fetch_requests?: number;
+    /**
+     * Number of server-executed web search requests.
+     */
+    web_search_requests?: number;
+}
+/**
+ * A Managed Agents `session`.
+ */
+export interface BetaManagedAgentsSession {
+    id: string;
+    /**
+     * Resolved `agent` definition for a `session`. Snapshot of the `agent` at
+     * `session` creation time.
+     */
+    agent: BetaManagedAgentsSessionAgent;
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    archived_at: string | null;
+    /**
+     * A hard spend ceiling. The session stops issuing new model requests once the
+     * tracked list cost reaches `max_list_cost`.
+     */
+    budget: BetaManagedAgentsBudgetLimit | null;
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    created_at: string;
+    environment_id: string;
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * Per-outcome evaluation state. One entry per `define_outcome` event sent to the
+     * session.
+     */
+    outcome_evaluations: Array<BetaManagedAgentsOutcomeEvaluationResource>;
+    resources: Array<ResourcesAPI.BetaManagedAgentsSessionResource>;
+    /**
+     * Timing statistics for a session.
+     */
+    stats: BetaManagedAgentsSessionStats;
+    /**
+     * SessionStatus enum
+     */
+    status: 'rescheduling' | 'running' | 'idle' | 'terminated';
+    title: string | null;
+    type: 'session';
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    updated_at: string;
+    /**
+     * Cumulative token usage for a session across all turns.
+     */
+    usage: BetaManagedAgentsSessionUsage;
+    /**
+     * Vault IDs attached to the session at creation. Empty when no vaults were
+     * supplied.
+     */
+    vault_ids: Array<string>;
+    /**
+     * Deployment ID when the session was created from a deployment reference. Null
+     * otherwise.
+     */
+    deployment_id?: string | null;
+}
+/**
+ * Resolved `agent` definition for a `session`. Snapshot of the `agent` at
+ * `session` creation time.
+ */
+export interface BetaManagedAgentsSessionAgent {
+    id: string;
+    description: string | null;
+    mcp_servers: Array<AgentsAPI.BetaManagedAgentsMCPServerURLDefinition>;
+    /**
+     * Model identifier and configuration.
+     */
+    model: AgentsAPI.BetaManagedAgentsModelConfig;
+    /**
+     * Resolved coordinator topology with full agent definitions for each roster
+     * member.
+     */
+    multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null;
+    name: string;
+    skills: Array<AgentsAPI.BetaManagedAgentsPukuSkill | AgentsAPI.BetaManagedAgentsCustomSkill>;
+    system: string | null;
+    tools: Array<AgentsAPI.BetaManagedAgentsAgentToolset20260401 | AgentsAPI.BetaManagedAgentsMCPToolset | AgentsAPI.BetaManagedAgentsCustomTool>;
+    type: 'agent';
+    version: number;
+}
+/**
+ * Mid-session agent configuration update. Only `tools` and `mcp_servers` are
+ * updatable. Full replacement: the provided array becomes the new value. To
+ * preserve existing entries, GET the session, modify the array, and POST it back.
+ */
+export interface BetaManagedAgentsSessionAgentUpdate {
+    /**
+     * Replacement MCP server list. Full replacement: the provided array becomes the
+     * new value. Send an empty array to clear; omit to preserve.
+     */
+    mcp_servers?: Array<AgentsAPI.BetaManagedAgentsURLMCPServerParams>;
+    /**
+     * Replacement tool list. Full replacement: the provided array becomes the new
+     * value. Send an empty array to clear; omit to preserve.
+     */
+    tools?: Array<AgentsAPI.BetaManagedAgentsAgentToolset20260401Params | AgentsAPI.BetaManagedAgentsMCPToolsetParams | AgentsAPI.BetaManagedAgentsCustomToolParams>;
+}
+/**
+ * Resolved coordinator topology with full agent definitions for each roster
+ * member.
+ */
+export interface BetaManagedAgentsSessionMultiagentCoordinator {
+    /**
+     * Full `agent` definitions the coordinator may spawn as session threads.
+     */
+    agents: Array<AgentsAPI.BetaManagedAgentsSessionThreadAgent | AgentsAPI.BetaManagedAgentsAdvisor>;
+    type: 'coordinator';
+}
+/**
+ * Timing statistics for a session.
+ */
+export interface BetaManagedAgentsSessionStats {
+    /**
+     * Cumulative time in seconds the session spent in `running` status. Excludes idle
+     * time.
+     */
+    active_seconds?: number;
+    /**
+     * Elapsed time since session creation in seconds. For terminated sessions, frozen
+     * at the final update.
+     */
+    duration_seconds?: number;
+}
+/**
+ * Emitted when an UpdateSession request changed at least one field. Carries only
+ * the fields that changed; absent fields were not part of the update. The new
+ * configuration applies from the next turn.
+ */
+export interface BetaManagedAgentsSessionUpdatedEvent {
+    /**
+     * Unique identifier for this event.
+     */
+    id: string;
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    processed_at: string;
+    type: 'session.updated';
+    /**
+     * Resolved `agent` definition for a `session`. Snapshot of the `agent` at
+     * `session` creation time.
+     */
+    agent?: BetaManagedAgentsSessionAgent | null;
+    /**
+     * A hard spend ceiling. The session stops issuing new model requests once the
+     * tracked list cost reaches `max_list_cost`.
+     */
+    budget?: BetaManagedAgentsBudgetLimit | null;
+    /**
+     * The session's full metadata bag after the update. Present when the update set
+     * non-empty metadata; absent when metadata was unchanged or cleared to empty.
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * The session's new title. Present only when the update changed it.
+     */
+    title?: string | null;
+}
+/**
+ * Cumulative token usage for a session across all turns.
+ */
+export interface BetaManagedAgentsSessionUsage {
+    /**
+     * Cumulative time in seconds during which the session had at least one thread in
+     * running status. Overlapping activity from concurrent threads is counted once,
+     * unlike `stats.active_seconds`, which sums each thread's own active time. This is
+     * the duration the session's runtime cost is priced on.
+     */
+    active_seconds?: number;
+    /**
+     * Prompt-cache creation token usage broken down by cache lifetime.
+     */
+    cache_creation?: BetaManagedAgentsCacheCreationUsage;
+    /**
+     * Total tokens read from prompt cache.
+     */
+    cache_read_input_tokens?: number;
+    /**
+     * Total input tokens consumed across all turns.
+     */
+    input_tokens?: number;
+    /**
+     * A monetary amount in a specific currency.
+     */
+    list_cost?: BetaAPI.BetaMonetaryAmount | null;
+    /**
+     * Total output tokens generated across all turns.
+     */
+    output_tokens?: number;
+    /**
+     * Cumulative count of server-executed tool invocations, broken down by tool.
+     */
+    server_tool_use?: BetaManagedAgentsServerToolUsage | null;
+}
+/**
+ * Periodic snapshot of the session's cumulative usage and tracked list cost.
+ */
+export interface BetaManagedAgentsSessionUsageEvent {
+    /**
+     * Unique identifier for this event.
+     */
+    id: string;
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    processed_at: string;
+    type: 'session.usage';
+    /**
+     * Point-in-time snapshot of a session's cumulative usage.
+     */
+    usage: EventsAPI.BetaManagedAgentsSessionUsageSnapshot;
+    /**
+     * A hard spend ceiling. The session stops issuing new model requests once the
+     * tracked list cost reaches `max_list_cost`.
+     */
+    budget?: BetaManagedAgentsBudgetLimit | null;
+}
+/**
+ * Opens a preview of a buffered event. Carries the previewed event's type and id
+ * only. Followed by zero or more event_delta events with the same event id,
+ * normally concluded by the buffered event carrying that id. If the producing
+ * model request ends without that event (an error or interrupt mid-stream), its
+ * terminal span.model_request_end closes the preview. Only sent on stream
+ * connections that opt in via event_deltas; never appears in event history.
+ */
+export interface BetaManagedAgentsStartEvent {
+    /**
+     * The previewed event's type and id. The event type determines which delta types
+     * the preview's event_delta events carry: agent.message events stream
+     * content_delta fragments; agent.thinking previews are start-only — no deltas
+     * follow, and the buffered agent.thinking with the same id concludes them.
+     */
+    event: BetaManagedAgentsStartEventPreview;
+    type: 'event_start';
+}
+export type BetaManagedAgentsStartEventPreview = BetaManagedAgentsAgentMessagePreview | BetaManagedAgentsAgentThinkingPreview;
+/**
+ * Regular text content.
+ */
+export interface BetaManagedAgentsSystemContentBlock {
+    /**
+     * The text content.
+     */
+    text: string;
+    type: 'text';
+}
+/**
+ * A mid-conversation system message event. Carries system-role content that is
+ * appended to the session as a `role: "system"` turn.
+ */
+export interface BetaManagedAgentsSystemMessageEvent {
+    /**
+     * Unique identifier for this event.
+     */
+    id: string;
+    /**
+     * System content blocks. Text-only.
+     */
+    content: Array<BetaManagedAgentsSystemContentBlock>;
+    type: 'system.message';
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    processed_at?: string | null;
+}
+/**
+ * Event sent by the client providing the result of an agent-toolset tool
+ * execution. Only valid on `self_hosted` environments, where sandbox-routed tools
+ * are executed by the client rather than the server.
+ */
+export interface BetaManagedAgentsUserToolResultEvent {
+    /**
+     * Unique identifier for this event.
+     */
+    id: string;
+    /**
+     * The id of the `agent.tool_use` event this result corresponds to, which can be
+     * found in the last `session.status_idle`
+     * [event's](https://platform.puku.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids)
+     * `stop_reason.event_ids` field.
+     */
+    tool_use_id: string;
+    type: 'user.tool_result';
+    /**
+     * The result content returned by the tool.
+     */
+    content?: Array<EventsAPI.BetaManagedAgentsTextBlock | EventsAPI.BetaManagedAgentsImageBlock | EventsAPI.BetaManagedAgentsDocumentBlock | EventsAPI.BetaManagedAgentsSearchResultBlock>;
+    /**
+     * Whether the tool execution resulted in an error.
+     */
+    is_error?: boolean | null;
+    /**
+     * A timestamp in RFC 3339 format
+     */
+    processed_at?: string | null;
+    /**
+     * Routes this result to a subagent thread. Copy from the `agent.tool_use` event's
+     * `session_thread_id`.
+     */
+    session_thread_id?: string | null;
+}
+export interface SessionCreateParams {
+    /**
+     * Body param: Agent identifier. Accepts the `agent` ID string, which pins the
+     * latest version for the session, or an `agent` object with both id and version
+     * specified.
+     */
+    agent: string | BetaManagedAgentsAgentParams | BetaManagedAgentsAgentWithOverridesParams;
+    /**
+     * Body param: ID of the `environment` defining the container configuration for
+     * this session.
+     */
+    environment_id: string;
+    /**
+     * Body param: A hard spend ceiling. The session stops issuing new model requests
+     * once the tracked list cost reaches `max_list_cost`.
+     */
+    budget?: BetaManagedAgentsBudgetLimit;
+    /**
+     * Body param: Initial events to send to the `session` at creation, processed in
+     * order. Supports `user.message` and `user.define_outcome` events. Maximum 50
+     * events.
+     */
+    initial_events?: Array<EventsAPI.BetaManagedAgentsUserMessageEventParams | EventsAPI.BetaManagedAgentsUserDefineOutcomeEventParams>;
+    /**
+     * Body param: Arbitrary key-value metadata attached to the session. Maximum 16
+     * pairs, keys up to 64 chars, values up to 512 chars.
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * Body param: Resources (e.g. repositories, files) to mount into the session's
+     * container.
+     */
+    resources?: Array<BetaManagedAgentsGitHubRepositoryResourceParams | BetaManagedAgentsFileResourceParams | BetaManagedAgentsMemoryStoreResourceParam>;
+    /**
+     * Body param: Human-readable session title.
+     */
+    title?: string | null;
+    /**
+     * Body param: Vault IDs for stored credentials the agent can use during the
+     * session.
+     */
+    vault_ids?: Array<string>;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface SessionRetrieveParams {
+    /**
+     * Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface SessionUpdateParams {
+    /**
+     * Body param: Mid-session agent configuration update. Only `tools` and
+     * `mcp_servers` are updatable. Full replacement: the provided array becomes the
+     * new value. To preserve existing entries, GET the session, modify the array, and
+     * POST it back.
+     */
+    agent?: BetaManagedAgentsSessionAgentUpdate;
+    /**
+     * Body param: A hard spend ceiling. The session stops issuing new model requests
+     * once the tracked list cost reaches `max_list_cost`.
+     */
+    budget?: BetaManagedAgentsBudgetLimit | null;
+    /**
+     * Body param: Metadata patch. Set a key to a string to upsert it, or to null to
+     * delete it. Omit the field to preserve.
+     */
+    metadata?: {
+        [key: string]: string | null;
+    } | null;
+    /**
+     * Body param: Human-readable session title.
+     */
+    title?: string | null;
+    /**
+     * Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported;
+     * requests setting this field are rejected. Reserved for future use.
+     */
+    vault_ids?: Array<string>;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface SessionListParams extends BidirectionalPageCursorParams {
+    /**
+     * Query param: Filter sessions created with this agent ID.
+     */
+    agent_id?: string;
+    /**
+     * Query param: Filter by agent version. Only applies when `agent_id` is also set.
+     */
+    agent_version?: number;
+    /**
+     * Query param: Return sessions created after this time (exclusive).
+     */
+    'created_at[gt]'?: string;
+    /**
+     * Query param: Return sessions created at or after this time (inclusive).
+     */
+    'created_at[gte]'?: string;
+    /**
+     * Query param: Return sessions created before this time (exclusive).
+     */
+    'created_at[lt]'?: string;
+    /**
+     * Query param: Return sessions created at or before this time (inclusive).
+     */
+    'created_at[lte]'?: string;
+    /**
+     * Query param: Filter sessions created by this deployment ID.
+     */
+    deployment_id?: string;
+    /**
+     * Query param: When true, includes archived sessions. Default: false (exclude
+     * archived).
+     */
+    include_archived?: boolean;
+    /**
+     * Query param: Filter sessions whose resources contain a `memory_store` with this
+     * memory store ID.
+     */
+    memory_store_id?: string;
+    /**
+     * Query param: Sort direction for results, ordered by `created_at`. Defaults to
+     * `desc` (newest first).
+     */
+    order?: 'asc' | 'desc';
+    /**
+     * Query param: Filter by session status. Repeat the parameter to match any of
+     * multiple statuses.
+     */
+    statuses?: Array<'rescheduling' | 'running' | 'idle' | 'terminated'>;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface SessionDeleteParams {
+    /**
+     * Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface SessionArchiveParams {
+    /**
+     * Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export declare namespace Sessions {
+    export { type BetaManagedAgentsAdvisorParams as BetaManagedAgentsAdvisorParams, type BetaManagedAgentsAgentMessagePreview as BetaManagedAgentsAgentMessagePreview, type BetaManagedAgentsAgentParams as BetaManagedAgentsAgentParams, type BetaManagedAgentsAgentThinkingPreview as BetaManagedAgentsAgentThinkingPreview, type BetaManagedAgentsAgentWithOverridesParams as BetaManagedAgentsAgentWithOverridesParams, type BetaManagedAgentsBranchCheckout as BetaManagedAgentsBranchCheckout, type BetaManagedAgentsBudgetLimit as BetaManagedAgentsBudgetLimit, type BetaManagedAgentsCacheCreationUsage as BetaManagedAgentsCacheCreationUsage, type BetaManagedAgentsCommitCheckout as BetaManagedAgentsCommitCheckout, type BetaManagedAgentsDeletedSession as BetaManagedAgentsDeletedSession, type BetaManagedAgentsDeltaContent as BetaManagedAgentsDeltaContent, type BetaManagedAgentsDeltaEvent as BetaManagedAgentsDeltaEvent, type BetaManagedAgentsDeltaType as BetaManagedAgentsDeltaType, type BetaManagedAgentsFileResourceParams as BetaManagedAgentsFileResourceParams, type BetaManagedAgentsGitHubRepositoryResourceParams as BetaManagedAgentsGitHubRepositoryResourceParams, type BetaManagedAgentsMemoryStoreResourceParam as BetaManagedAgentsMemoryStoreResourceParam, type BetaManagedAgentsMultiagent as BetaManagedAgentsMultiagent, type BetaManagedAgentsMultiagentParams as BetaManagedAgentsMultiagentParams, type BetaManagedAgentsMultiagentRosterEntryParams as BetaManagedAgentsMultiagentRosterEntryParams, type BetaManagedAgentsOutcomeEvaluationResource as BetaManagedAgentsOutcomeEvaluationResource, type BetaManagedAgentsServerToolUsage as BetaManagedAgentsServerToolUsage, type BetaManagedAgentsSession as BetaManagedAgentsSession, type BetaManagedAgentsSessionAgent as BetaManagedAgentsSessionAgent, type BetaManagedAgentsSessionAgentUpdate as BetaManagedAgentsSessionAgentUpdate, type BetaManagedAgentsSessionMultiagentCoordinator as BetaManagedAgentsSessionMultiagentCoordinator, type BetaManagedAgentsSessionStats as BetaManagedAgentsSessionStats, type BetaManagedAgentsSessionUpdatedEvent as BetaManagedAgentsSessionUpdatedEvent, type BetaManagedAgentsSessionUsage as BetaManagedAgentsSessionUsage, type BetaManagedAgentsSessionUsageEvent as BetaManagedAgentsSessionUsageEvent, type BetaManagedAgentsStartEvent as BetaManagedAgentsStartEvent, type BetaManagedAgentsStartEventPreview as BetaManagedAgentsStartEventPreview, type BetaManagedAgentsSystemContentBlock as BetaManagedAgentsSystemContentBlock, type BetaManagedAgentsSystemMessageEvent as BetaManagedAgentsSystemMessageEvent, type BetaManagedAgentsUserToolResultEvent as BetaManagedAgentsUserToolResultEvent, type BetaManagedAgentsSessionsBidirectionalPageCursor as BetaManagedAgentsSessionsBidirectionalPageCursor, type SessionCreateParams as SessionCreateParams, type SessionRetrieveParams as SessionRetrieveParams, type SessionUpdateParams as SessionUpdateParams, type SessionListParams as SessionListParams, type SessionDeleteParams as SessionDeleteParams, type SessionArchiveParams as SessionArchiveParams, };
+    export { Events as Events, type BetaManagedAgentsAgentCustomToolUseEvent as BetaManagedAgentsAgentCustomToolUseEvent, type BetaManagedAgentsAgentMCPToolResultEvent as BetaManagedAgentsAgentMCPToolResultEvent, type BetaManagedAgentsAgentMCPToolUseEvent as BetaManagedAgentsAgentMCPToolUseEvent, type BetaManagedAgentsAgentMessageEvent as BetaManagedAgentsAgentMessageEvent, type BetaManagedAgentsAgentThinkingEvent as BetaManagedAgentsAgentThinkingEvent, type BetaManagedAgentsAgentThreadContextCompactedEvent as BetaManagedAgentsAgentThreadContextCompactedEvent, type BetaManagedAgentsAgentThreadMessageReceivedEvent as BetaManagedAgentsAgentThreadMessageReceivedEvent, type BetaManagedAgentsAgentThreadMessageSentEvent as BetaManagedAgentsAgentThreadMessageSentEvent, type BetaManagedAgentsAgentToolResultEvent as BetaManagedAgentsAgentToolResultEvent, type BetaManagedAgentsAgentToolUseEvent as BetaManagedAgentsAgentToolUseEvent, type BetaManagedAgentsBase64DocumentSource as BetaManagedAgentsBase64DocumentSource, type BetaManagedAgentsBase64ImageSource as BetaManagedAgentsBase64ImageSource, type BetaManagedAgentsBillingError as BetaManagedAgentsBillingError, type BetaManagedAgentsCredentialHostUnreachableError as BetaManagedAgentsCredentialHostUnreachableError, type BetaManagedAgentsDocumentBlock as BetaManagedAgentsDocumentBlock, type BetaManagedAgentsEventParams as BetaManagedAgentsEventParams, type BetaManagedAgentsFileDocumentSource as BetaManagedAgentsFileDocumentSource, type BetaManagedAgentsFileImageSource as BetaManagedAgentsFileImageSource, type BetaManagedAgentsFileRubric as BetaManagedAgentsFileRubric, type BetaManagedAgentsFileRubricParams as BetaManagedAgentsFileRubricParams, type BetaManagedAgentsImageBlock as BetaManagedAgentsImageBlock, type BetaManagedAgentsMCPAuthenticationFailedError as BetaManagedAgentsMCPAuthenticationFailedError, type BetaManagedAgentsMCPConnectionFailedError as BetaManagedAgentsMCPConnectionFailedError, type BetaManagedAgentsModelOverloadedError as BetaManagedAgentsModelOverloadedError, type BetaManagedAgentsModelRateLimitedError as BetaManagedAgentsModelRateLimitedError, type BetaManagedAgentsModelRequestFailedError as BetaManagedAgentsModelRequestFailedError, type BetaManagedAgentsPlainTextDocumentSource as BetaManagedAgentsPlainTextDocumentSource, type BetaManagedAgentsRedactedBlock as BetaManagedAgentsRedactedBlock, type BetaManagedAgentsRetryStatusExhausted as BetaManagedAgentsRetryStatusExhausted, type BetaManagedAgentsRetryStatusRetrying as BetaManagedAgentsRetryStatusRetrying, type BetaManagedAgentsRetryStatusTerminal as BetaManagedAgentsRetryStatusTerminal, type BetaManagedAgentsSearchResultBlock as BetaManagedAgentsSearchResultBlock, type BetaManagedAgentsSearchResultCitations as BetaManagedAgentsSearchResultCitations, type BetaManagedAgentsSearchResultContent as BetaManagedAgentsSearchResultContent, type BetaManagedAgentsSendSessionEvents as BetaManagedAgentsSendSessionEvents, type BetaManagedAgentsSessionBudgetReached as BetaManagedAgentsSessionBudgetReached, type BetaManagedAgentsSessionDeletedEvent as BetaManagedAgentsSessionDeletedEvent, type BetaManagedAgentsSessionEndTurn as BetaManagedAgentsSessionEndTurn, type BetaManagedAgentsSessionErrorEvent as BetaManagedAgentsSessionErrorEvent, type BetaManagedAgentsSessionEvent as BetaManagedAgentsSessionEvent, type BetaManagedAgentsSessionRequiresAction as BetaManagedAgentsSessionRequiresAction, type BetaManagedAgentsSessionRetriesExhausted as BetaManagedAgentsSessionRetriesExhausted, type BetaManagedAgentsSessionStatusIdleEvent as BetaManagedAgentsSessionStatusIdleEvent, type BetaManagedAgentsSessionStatusRescheduledEvent as BetaManagedAgentsSessionStatusRescheduledEvent, type BetaManagedAgentsSessionStatusRunningEvent as BetaManagedAgentsSessionStatusRunningEvent, type BetaManagedAgentsSessionStatusTerminatedEvent as BetaManagedAgentsSessionStatusTerminatedEvent, type BetaManagedAgentsSessionThreadCreatedEvent as BetaManagedAgentsSessionThreadCreatedEvent, type BetaManagedAgentsSessionThreadStatusIdleEvent as BetaManagedAgentsSessionThreadStatusIdleEvent, type BetaManagedAgentsSessionThreadStatusRescheduledEvent as BetaManagedAgentsSessionThreadStatusRescheduledEvent, type BetaManagedAgentsSessionThreadStatusRunningEvent as BetaManagedAgentsSessionThreadStatusRunningEvent, type BetaManagedAgentsSessionThreadStatusTerminatedEvent as BetaManagedAgentsSessionThreadStatusTerminatedEvent, type BetaManagedAgentsSessionUsageSnapshot as BetaManagedAgentsSessionUsageSnapshot, type BetaManagedAgentsSpanModelRequestEndEvent as BetaManagedAgentsSpanModelRequestEndEvent, type BetaManagedAgentsSpanModelRequestStartEvent as BetaManagedAgentsSpanModelRequestStartEvent, type BetaManagedAgentsSpanModelUsage as BetaManagedAgentsSpanModelUsage, type BetaManagedAgentsSpanOutcomeEvaluationEndEvent as BetaManagedAgentsSpanOutcomeEvaluationEndEvent, type BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent as BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent, type BetaManagedAgentsSpanOutcomeEvaluationStartEvent as BetaManagedAgentsSpanOutcomeEvaluationStartEvent, type BetaManagedAgentsStreamSessionEvents as BetaManagedAgentsStreamSessionEvents, type BetaManagedAgentsSystemMessageEventParams as BetaManagedAgentsSystemMessageEventParams, type BetaManagedAgentsTextBlock as BetaManagedAgentsTextBlock, type BetaManagedAgentsTextRubric as BetaManagedAgentsTextRubric, type BetaManagedAgentsTextRubricParams as BetaManagedAgentsTextRubricParams, type BetaManagedAgentsUnknownError as BetaManagedAgentsUnknownError, type BetaManagedAgentsURLDocumentSource as BetaManagedAgentsURLDocumentSource, type BetaManagedAgentsURLImageSource as BetaManagedAgentsURLImageSource, type BetaManagedAgentsUserCustomToolResultEvent as BetaManagedAgentsUserCustomToolResultEvent, type BetaManagedAgentsUserCustomToolResultEventParams as BetaManagedAgentsUserCustomToolResultEventParams, type BetaManagedAgentsUserDefineOutcomeEvent as BetaManagedAgentsUserDefineOutcomeEvent, type BetaManagedAgentsUserDefineOutcomeEventParams as BetaManagedAgentsUserDefineOutcomeEventParams, type BetaManagedAgentsUserInterruptEvent as BetaManagedAgentsUserInterruptEvent, type BetaManagedAgentsUserInterruptEventParams as BetaManagedAgentsUserInterruptEventParams, type BetaManagedAgentsUserMessageEvent as BetaManagedAgentsUserMessageEvent, type BetaManagedAgentsUserMessageEventParams as BetaManagedAgentsUserMessageEventParams, type BetaManagedAgentsUserToolConfirmationEvent as BetaManagedAgentsUserToolConfirmationEvent, type BetaManagedAgentsUserToolConfirmationEventParams as BetaManagedAgentsUserToolConfirmationEventParams, type BetaManagedAgentsUserToolResultEventParams as BetaManagedAgentsUserToolResultEventParams, type BetaManagedAgentsSessionEventsPageCursor as BetaManagedAgentsSessionEventsPageCursor, type EventListParams as EventListParams, type EventSendParams as EventSendParams, type EventStreamParams as EventStreamParams, };
+    export { Resources as Resources, type BetaManagedAgentsDeleteSessionResource as BetaManagedAgentsDeleteSessionResource, type BetaManagedAgentsFileResource as BetaManagedAgentsFileResource, type BetaManagedAgentsGitHubRepositoryResource as BetaManagedAgentsGitHubRepositoryResource, type BetaManagedAgentsMemoryStoreResource as BetaManagedAgentsMemoryStoreResource, type BetaManagedAgentsSessionResource as BetaManagedAgentsSessionResource, type ResourceRetrieveResponse as ResourceRetrieveResponse, type ResourceUpdateResponse as ResourceUpdateResponse, type BetaManagedAgentsSessionResourcesPageCursor as BetaManagedAgentsSessionResourcesPageCursor, type ResourceRetrieveParams as ResourceRetrieveParams, type ResourceUpdateParams as ResourceUpdateParams, type ResourceListParams as ResourceListParams, type ResourceDeleteParams as ResourceDeleteParams, type ResourceAddParams as ResourceAddParams, };
+    export { Threads as Threads, type BetaManagedAgentsSessionThread as BetaManagedAgentsSessionThread, type BetaManagedAgentsSessionThreadStats as BetaManagedAgentsSessionThreadStats, type BetaManagedAgentsSessionThreadStatus as BetaManagedAgentsSessionThreadStatus, type BetaManagedAgentsSessionThreadUsage as BetaManagedAgentsSessionThreadUsage, type BetaManagedAgentsStreamSessionThreadEvents as BetaManagedAgentsStreamSessionThreadEvents, type BetaManagedAgentsSessionThreadsPageCursor as BetaManagedAgentsSessionThreadsPageCursor, type ThreadRetrieveParams as ThreadRetrieveParams, type ThreadListParams as ThreadListParams, type ThreadArchiveParams as ThreadArchiveParams, };
+}