cyberdesk 2.1.20 → 2.2.0

package/dist/client/types.gen.d.ts

@@ -166,6 +166,10 @@ export type MachineResponse = {
     is_available: boolean;
     reserved_session_id?: string | null;
     linked_keepalive_machine_id?: string | null;
+    /**
+     * Fly machine ID hosting the WebSocket connection
+     */
+    physical_server_id?: string | null;
     created_at: string;
     last_seen: string;
     pools?: Array<PoolResponse> | null;
@@ -592,7 +596,7 @@ export type RunCreate = {
  * These are optional fields beyond the essential identifiers that are always returned
  * (id, workflow_id, machine_id, status, created_at).
  */
-export type RunField = 'user_id' | 'organization_id' | 'error' | 'output_data' | 'input_attachment_ids' | 'output_attachment_ids' | 'run_message_history' | 'input_values' | 'pool_ids' | 'sensitive_input_aliases' | 'session_id' | 'session_alias' | 'release_session_after' | 'machine_id';
+export type RunField = 'user_id' | 'organization_id' | 'error' | 'output_data' | 'input_attachment_ids' | 'output_attachment_ids' | 'run_message_history' | 'input_values' | 'pool_ids' | 'sensitive_input_aliases' | 'session_id' | 'session_alias' | 'release_session_after' | 'started_at' | 'ended_at' | 'machine_id';
 /**
  * Run response schema
  */
@@ -623,6 +627,8 @@ export type RunResponse = {
     session_alias?: string | null;
     release_session_after?: boolean | null;
     created_at: string;
+    started_at?: string | null;
+    ended_at?: string | null;
 };
 /**
  * Options for retrying an existing run in-place (same run_id).
@@ -687,6 +693,8 @@ export type RunUpdate = {
     input_values?: {
         [key: string]: unknown;
     } | null;
+    started_at?: string | null;
+    ended_at?: string | null;
 };
 /**
  * Schema for creating a trajectory

package/dist/index.d.ts

@@ -52,7 +52,8 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
          * @param params.limit - Maximum number of items to return
          * @param params.status - Filter by machine status
          * @returns Paginated list of machines. Each machine includes desktop parameters
-         *          (machine_parameters, machine_sensitive_parameters) if configured.
+         *          (machine_parameters, machine_sensitive_parameters) if configured,
+         *          plus the current physical_server_id when connected to WebSockets.
          */
         list: (params?: {
             skip?: number;
@@ -100,6 +101,7 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
          *          - Basic info: id, name, status, fingerprint, etc.
          *          - machine_parameters: Dict of desktop parameters (if configured)
          *          - machine_sensitive_parameters: Dict of sensitive parameter aliases (if configured)
+         *          - physical_server_id: Fly machine ID currently hosting the WebSocket connection
          *          - pools: List of pools this machine belongs to
          */
         get: (machineId: string) => Promise<({
@@ -148,6 +150,8 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
          * @remarks
          * - linked_keepalive_machine_id is not writable; it is managed by
          *   Cyberdriver link events and will be set/cleared automatically.
+         * - physical_server_id is read-only; it is set automatically when the machine
+         *   connects to a WebSocket server and cleared on disconnect.
          * - For machine_sensitive_parameters, provide actual secret values.
          *   They will be stored securely in Basis Theory and only aliases stored in DB.
          */
@@ -479,6 +483,9 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
         /**
          * List runs with optional filtering
          *
+         * Runs are ordered by: RUNNING (by started_at DESC) first, then all others (by ended_at DESC).
+         * This surfaces active work and recent completions.
+         *
          * @param params - Optional query parameters
          * @param params.skip - Number of items to skip (for pagination)
          * @param params.limit - Maximum number of items to return
@@ -486,7 +493,12 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
          * @param params.workflow_id - Filter by workflow ID
          * @param params.machine_id - Filter by machine ID
          * @param params.session_id - Filter by session ID
-         * @returns Paginated list of runs
+         * @param params.fields - Optional list of fields to include per run (projection). Available fields include:
+         *                        started_at, ended_at, error, output_data, input_values, and more.
+         * @returns Paginated list of runs including timing fields:
+         *          - created_at: When run was created
+         *          - started_at: When run execution started (null for SCHEDULING runs)
+         *          - ended_at: When run completed (null for RUNNING/SCHEDULING runs)
          */
         list: (params?: {
             skip?: number;
@@ -622,7 +634,10 @@ export declare function createCyberdeskClient(apiKey: string, baseUrl?: string):
          * Get a specific run by ID
          *
          * @param runId - The ID of the run
-         * @returns Run details including status, output, and attachments
+         * @returns Run details including timing information:
+         *          - created_at: When run was created
+         *          - started_at: When run execution started (null if not started)
+         *          - ended_at: When run completed (null if not finished)
          */
         get: (runId: string) => Promise<({
             data: undefined;

package/dist/index.js

@@ -111,7 +111,8 @@ function createCyberdeskClient(apiKey, baseUrl) {
              * @param params.limit - Maximum number of items to return
              * @param params.status - Filter by machine status
              * @returns Paginated list of machines. Each machine includes desktop parameters
-             *          (machine_parameters, machine_sensitive_parameters) if configured.
+             *          (machine_parameters, machine_sensitive_parameters) if configured,
+             *          plus the current physical_server_id when connected to WebSockets.
              */
             list: (params) => __awaiter(this, void 0, void 0, function* () {
                 const query = {
@@ -149,6 +150,7 @@ function createCyberdeskClient(apiKey, baseUrl) {
              *          - Basic info: id, name, status, fingerprint, etc.
              *          - machine_parameters: Dict of desktop parameters (if configured)
              *          - machine_sensitive_parameters: Dict of sensitive parameter aliases (if configured)
+             *          - physical_server_id: Fly machine ID currently hosting the WebSocket connection
              *          - pools: List of pools this machine belongs to
              */
             get: (machineId) => __awaiter(this, void 0, void 0, function* () {
@@ -193,6 +195,8 @@ function createCyberdeskClient(apiKey, baseUrl) {
              * @remarks
              * - linked_keepalive_machine_id is not writable; it is managed by
              *   Cyberdriver link events and will be set/cleared automatically.
+             * - physical_server_id is read-only; it is set automatically when the machine
+             *   connects to a WebSocket server and cleared on disconnect.
              * - For machine_sensitive_parameters, provide actual secret values.
              *   They will be stored securely in Basis Theory and only aliases stored in DB.
              */
@@ -469,6 +473,9 @@ function createCyberdeskClient(apiKey, baseUrl) {
             /**
              * List runs with optional filtering
              *
+             * Runs are ordered by: RUNNING (by started_at DESC) first, then all others (by ended_at DESC).
+             * This surfaces active work and recent completions.
+             *
              * @param params - Optional query parameters
              * @param params.skip - Number of items to skip (for pagination)
              * @param params.limit - Maximum number of items to return
@@ -476,7 +483,12 @@ function createCyberdeskClient(apiKey, baseUrl) {
              * @param params.workflow_id - Filter by workflow ID
              * @param params.machine_id - Filter by machine ID
              * @param params.session_id - Filter by session ID
-             * @returns Paginated list of runs
+             * @param params.fields - Optional list of fields to include per run (projection). Available fields include:
+             *                        started_at, ended_at, error, output_data, input_values, and more.
+             * @returns Paginated list of runs including timing fields:
+             *          - created_at: When run was created
+             *          - started_at: When run execution started (null for SCHEDULING runs)
+             *          - ended_at: When run completed (null for RUNNING/SCHEDULING runs)
              */
             list: (params) => __awaiter(this, void 0, void 0, function* () {
                 var _a, _b, _c, _d;
@@ -595,7 +607,10 @@ function createCyberdeskClient(apiKey, baseUrl) {
              * Get a specific run by ID
              *
              * @param runId - The ID of the run
-             * @returns Run details including status, output, and attachments
+             * @returns Run details including timing information:
+             *          - created_at: When run was created
+             *          - started_at: When run execution started (null if not started)
+             *          - ended_at: When run completed (null if not finished)
              */
             get: (runId) => __awaiter(this, void 0, void 0, function* () {
                 return (0, sdk_gen_1.getRunV1RunsRunIdGet)({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberdesk",
-  "version": "2.1.20",
+  "version": "2.2.0",
   "description": "The official TypeScript SDK for Cyberdesk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",