@puku-ai/sdk 4.0.1 → 4.0.2

package/dist/vendor/resources/beta/environments/work.d.ts

@@ -0,0 +1,500 @@
+import { APIResource } from '../../../core/resource';
+import * as BetaAPI from '../beta';
+import { APIPromise } from '../../../core/api-promise';
+import { PageCursor, type PageCursorParams, PagePromise } from '../../../core/pagination';
+import { RequestOptions } from '../../../internal/request-options';
+import { WorkPoller, type WorkPollerOptions as RunnerWorkPollerOptions } from '../../../lib/environments/poller';
+import { EnvironmentWorker, type EnvironmentWorkerOptions as RunnerEnvironmentWorkerOptions } from '../../../lib/environments/worker';
+export declare class Work extends APIResource {
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Retrieve detailed information about a specific work item.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWork =
+     *   await client.beta.environments.work.retrieve('work_id', {
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   });
+     * ```
+     */
+    retrieve(workID: string, params: WorkRetrieveParams, options?: RequestOptions): APIPromise<BetaSelfHostedWork>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Update work item metadata with merge semantics.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWork =
+     *   await client.beta.environments.work.update('work_id', {
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *     metadata: { foo: 'string' },
+     *   });
+     * ```
+     */
+    update(workID: string, params: WorkUpdateParams, options?: RequestOptions): APIPromise<BetaSelfHostedWork>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * List work items in an environment.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const betaSelfHostedWork of client.beta.environments.work.list(
+     *   'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(environmentID: string, params?: WorkListParams | null | undefined, options?: RequestOptions): PagePromise<BetaSelfHostedWorksPageCursor, BetaSelfHostedWork>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting'
+     * and removing it from the queue.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWork =
+     *   await client.beta.environments.work.ack('work_id', {
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   });
+     * ```
+     */
+    ack(workID: string, params: WorkAckParams, options?: RequestOptions): APIPromise<BetaSelfHostedWork>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Record a heartbeat for a work item to maintain the lease.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWorkHeartbeatResponse =
+     *   await client.beta.environments.work.heartbeat('work_id', {
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   });
+     * ```
+     */
+    heartbeat(workID: string, params: WorkHeartbeatParams, options?: RequestOptions): APIPromise<BetaSelfHostedWorkHeartbeatResponse>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Long poll for work items in the queue.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWork =
+     *   await client.beta.environments.work.poll(
+     *     'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   );
+     * ```
+     */
+    poll(environmentID: string, params?: WorkPollParams | null | undefined, options?: RequestOptions): APIPromise<BetaSelfHostedWork | null>;
+    /**
+     * Get statistics about the work queue for an environment.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWorkQueueStats =
+     *   await client.beta.environments.work.stats(
+     *     'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   );
+     * ```
+     */
+    stats(environmentID: string, params?: WorkStatsParams | null | undefined, options?: RequestOptions): APIPromise<BetaSelfHostedWorkQueueStats>;
+    /**
+     * Note: these endpoints are called automatically by the pre-built environment
+     * worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted
+     * sandbox environments. They are included here as a reference; you do not need to
+     * invoke them directly.
+     *
+     * Stop a work item, initiating graceful or forced shutdown.
+     *
+     * @example
+     * ```ts
+     * const betaSelfHostedWork =
+     *   await client.beta.environments.work.stop('work_id', {
+     *     environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW',
+     *   });
+     * ```
+     */
+    stop(workID: string, params: WorkStopParams, options?: RequestOptions): APIPromise<BetaSelfHostedWork>;
+    /**
+     * Continuously claim work from a self-hosted environment, ack each item,
+     * and yield it. Posts `stop` automatically when the consumer's loop body
+     * returns or when iteration ends.
+     *
+     * @example
+     * ```ts
+     * for await (const work of client.beta.environments.work.poller({
+     *   environmentId,
+     *   environmentKey,
+     * })) {
+     *   if (work.data.type !== 'session') continue;
+     *   // ...service the work...
+     * }
+     * ```
+     */
+    poller(opts: Omit<RunnerWorkPollerOptions, 'client'>): WorkPoller;
+    /**
+     * The self-hosted environment runner: poll for work, and for each claimed
+     * session set up the workdir, download the agent's skills, run the tools while
+     * heartbeating the lease, and force-stop on exit.
+     *
+     * @example
+     * ```ts
+     * // Long-running daemon — poll, serve each session, loop:
+     * await client.beta.environments.work
+     *   .worker({ environmentId, environmentKey, workdir: '/workspace' })
+     *   .run();
+     *
+     * // Or service one already-claimed work item (e.g. inside a sandbox spawned
+     * // by `ant worker poll --on-work`) — handleItem() reads the PUKU_* env vars:
+     * await client.beta.environments.work.worker({ workdir: '/workspace' }).handleItem();
+     * ```
+     */
+    worker(opts: Omit<RunnerEnvironmentWorkerOptions, 'client' | 'unrestrictedPaths'>): EnvironmentWorker;
+    /** @deprecated `unrestrictedPaths` is no longer accepted — see {@link RunnerEnvironmentWorkerOptions.unrestrictedPaths}. */
+    worker(opts: Omit<RunnerEnvironmentWorkerOptions, 'client' | 'unrestrictedPaths'> & {
+        unrestrictedPaths: boolean;
+    }): EnvironmentWorker;
+}
+export type BetaSelfHostedWorksPageCursor = PageCursor<BetaSelfHostedWork>;
+/**
+ * Work data for environment health checks.
+ *
+ * This resource type is used for assessing the health of containers where work
+ * occurs. The data is opaque to users; the runner handles the health check by
+ * probing connectivity to required services.
+ */
+export interface BetaHealthCheckWorkData {
+    /**
+     * Health check identifier
+     */
+    id: string;
+    /**
+     * Type of work data
+     */
+    type?: 'healthcheck';
+}
+/**
+ * Work resource representing a unit of work in a self-hosted environment.
+ *
+ * Work items are queued when sessions are created or when long-dormant sessions
+ * receive new messages. The Environment Manager polls for work items and executes
+ * them on customer-hosted infrastructure.
+ */
+export interface BetaSelfHostedWork {
+    /**
+     * Work identifier (e.g., 'work\_...')
+     */
+    id: string;
+    /**
+     * RFC 3339 timestamp when work was acknowledged by Environment Manager
+     */
+    acknowledged_at: string | null;
+    /**
+     * RFC 3339 timestamp when work was created
+     */
+    created_at: string;
+    /**
+     * The actual work to be performed (session or health check)
+     */
+    data: BetaSessionWorkData | BetaHealthCheckWorkData;
+    /**
+     * Environment identifier this work belongs to (e.g., `env_...`)
+     */
+    environment_id: string;
+    /**
+     * RFC 3339 timestamp of the most recent heartbeat
+     */
+    latest_heartbeat_at: string | null;
+    /**
+     * User-provided metadata key-value pairs associated with this work item
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * Credential payload used by the environment worker to execute this work item. May
+     * be populated when polling for work; null on all other retrieval paths.
+     */
+    secret: string | null;
+    /**
+     * RFC 3339 timestamp when work execution started
+     */
+    started_at: string | null;
+    /**
+     * Current state of the work item
+     */
+    state: 'queued' | 'starting' | 'active' | 'stopping' | 'stopped';
+    /**
+     * RFC 3339 timestamp when stop was requested
+     */
+    stop_requested_at: string | null;
+    /**
+     * RFC 3339 timestamp when work execution stopped
+     */
+    stopped_at: string | null;
+    /**
+     * The type of object (always 'work')
+     */
+    type: 'work';
+}
+/**
+ * Response after recording a heartbeat for a work item.
+ */
+export interface BetaSelfHostedWorkHeartbeatResponse {
+    /**
+     * RFC 3339 timestamp of the actual heartbeat from DB
+     */
+    last_heartbeat: string;
+    /**
+     * Whether the heartbeat succeeded in extending the lease
+     */
+    lease_extended: boolean;
+    /**
+     * Current state of the work item (active/stopping/stopped)
+     */
+    state: 'queued' | 'starting' | 'active' | 'stopping' | 'stopped';
+    /**
+     * Effective TTL applied to the lease
+     */
+    ttl_seconds: number;
+    /**
+     * The type of response
+     */
+    type: 'work_heartbeat';
+}
+/**
+ * Response when listing work items with cursor-based pagination.
+ */
+export interface BetaSelfHostedWorkListResponse {
+    /**
+     * List of work items
+     */
+    data: Array<BetaSelfHostedWork>;
+    /**
+     * Opaque cursor for fetching the next page of results
+     */
+    next_page: string | null;
+}
+/**
+ * Statistics about the work queue for an environment.
+ *
+ * Uses Redis Stream consumer group metrics for O(1) queries.
+ */
+export interface BetaSelfHostedWorkQueueStats {
+    /**
+     * Number of work items waiting to be picked up (lag from consumer group)
+     */
+    depth: number;
+    /**
+     * RFC 3339 timestamp of oldest item in the work stream (includes both queued and
+     * pending items), null if stream empty
+     */
+    oldest_queued_at: string | null;
+    /**
+     * Number of work items being processed (polled but not acknowledged)
+     */
+    pending: number;
+    /**
+     * The type of object
+     */
+    type: 'work_queue_stats';
+    /**
+     * Number of workers that have polled for work in the last 30 seconds. Requires
+     * worker_id to be sent with poll requests.
+     */
+    workers_polling: number | null;
+}
+/**
+ * Request to stop a work item.
+ */
+export interface BetaSelfHostedWorkStopRequest {
+    /**
+     * If true, immediately stop work without graceful shutdown
+     */
+    force?: boolean;
+}
+/**
+ * Request to update work item metadata.
+ */
+export interface BetaSelfHostedWorkUpdateRequest {
+    /**
+     * Metadata patch. Set a key to a string to upsert it, or to null to delete it.
+     * Omit the field to preserve existing metadata.
+     */
+    metadata: {
+        [key: string]: string | null;
+    };
+}
+/**
+ * Work data for session work items.
+ *
+ * This resource type is used when work represents a session that needs to be
+ * executed in a self-hosted environment.
+ */
+export interface BetaSessionWorkData {
+    /**
+     * Session identifier (e.g., 'session\_...')
+     */
+    id: string;
+    /**
+     * Type of work data
+     */
+    type: 'session';
+}
+/**
+ * Decoded payload of the `secret` field on a self-hosted work item. The wire value
+ * of `secret` is a base64url-encoded JSON document matching this schema. SDKs that
+ * ship a runner helper for self-hosted environments use this type as the return
+ * value of their secret-decoding utility.
+ */
+export interface BetaWorkSecret {
+    /**
+     * Bearer credential the runner uses for all per-session downstream calls
+     * (heartbeat, ack, event stream, send, stop). Format: `sk-ant-req-...`.
+     */
+    sessions_token: string;
+    /**
+     * API base URL the runner should use for downstream calls. When absent the runner
+     * falls back to its default PukuAI endpoint.
+     */
+    api_base_url?: string;
+}
+export interface WorkRetrieveParams {
+    /**
+     * Path param
+     */
+    environment_id: string;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkUpdateParams {
+    /**
+     * Path param
+     */
+    environment_id: string;
+    /**
+     * Body param: Metadata patch. Set a key to a string to upsert it, or to null to
+     * delete it. Omit the field to preserve existing metadata.
+     */
+    metadata: {
+        [key: string]: string | null;
+    };
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkListParams extends PageCursorParams {
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkAckParams {
+    /**
+     * Path param
+     */
+    environment_id: string;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkHeartbeatParams {
+    /**
+     * Path param
+     */
+    environment_id: string;
+    /**
+     * Query param: Desired TTL in seconds
+     */
+    desired_ttl_seconds?: number | null;
+    /**
+     * Query param: Expected last_heartbeat for conditional update (optimistic
+     * concurrency). Use literal 'NO_HEARTBEAT' to claim an unclaimed lease (first
+     * heartbeat). For subsequent heartbeats, echo the server's previous last_heartbeat
+     * value exactly. Returns 412 Precondition Failed if the actual value doesn't
+     * match.
+     */
+    expected_last_heartbeat?: string | null;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkPollParams {
+    /**
+     * Query param: How long to wait for work to arrive before returning. Must be 1-999
+     * in milliseconds. Defaults to non-blocking (returns immediately if no work is
+     * available).
+     */
+    block_ms?: number | null;
+    /**
+     * Query param: Reclaim unacknowledged work items older than this many
+     * milliseconds. If omitted, uses the default (5000ms).
+     */
+    reclaim_older_than_ms?: number | null;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+    /**
+     * Header param: Unique identifier for the specific worker polling, used to track
+     * aggregated environment-level work metrics in Console
+     */
+    'PukuAI-Worker-ID'?: string;
+}
+export interface WorkStatsParams {
+    /**
+     * Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export interface WorkStopParams {
+    /**
+     * Path param
+     */
+    environment_id: string;
+    /**
+     * Body param: If true, immediately stop work without graceful shutdown
+     */
+    force?: boolean;
+    /**
+     * Header param: Optional header to specify the beta version(s) you want to use.
+     */
+    betas?: Array<BetaAPI.PukuBeta>;
+}
+export { WorkPoller, type WorkPollerOptions } from '../../../lib/environments/poller';
+export { EnvironmentWorker, type EnvironmentWorkerOptions } from '../../../lib/environments/worker';
+export declare namespace Work {
+    export { WorkPoller, EnvironmentWorker };
+    export { type BetaHealthCheckWorkData as BetaHealthCheckWorkData, type BetaSelfHostedWork as BetaSelfHostedWork, type BetaSelfHostedWorkHeartbeatResponse as BetaSelfHostedWorkHeartbeatResponse, type BetaSelfHostedWorkListResponse as BetaSelfHostedWorkListResponse, type BetaSelfHostedWorkQueueStats as BetaSelfHostedWorkQueueStats, type BetaSelfHostedWorkStopRequest as BetaSelfHostedWorkStopRequest, type BetaSelfHostedWorkUpdateRequest as BetaSelfHostedWorkUpdateRequest, type BetaSessionWorkData as BetaSessionWorkData, type BetaWorkSecret as BetaWorkSecret, type BetaSelfHostedWorksPageCursor as BetaSelfHostedWorksPageCursor, type WorkRetrieveParams as WorkRetrieveParams, type WorkUpdateParams as WorkUpdateParams, type WorkListParams as WorkListParams, type WorkAckParams as WorkAckParams, type WorkHeartbeatParams as WorkHeartbeatParams, type WorkPollParams as WorkPollParams, type WorkStatsParams as WorkStatsParams, type WorkStopParams as WorkStopParams, };
+}