@labelbox/recursion-sdk 0.0.162 → 0.0.164

package/dist/reference/resources-reference.generated.js

@@ -2977,6 +2977,7 @@ export const RESOURCE_REFERENCE = {
             'managedAgentsListSessionModelCostNodes',
             'managedAgentsListSessionModelCosts',
             'managedAgentsListSessionOutcomes',
+            'managedAgentsListSessionResourceSamples',
             'managedAgentsListSessionThreads',
             'managedAgentsListSessionUsage',
             'managedAgentsListSessions',

package/dist/reference/sdk-reference.generated.js

@@ -51295,6 +51295,12 @@ export const SDK_REFERENCE = {
                     description: 'RFC 3339 timestamp of when the agent loop last made progress. Distinct from updated_at, which any metadata write touches. Absent for sessions that run no loop.',
                     format: 'date-time',
                 },
+                {
+                    name: 'metadata',
+                    required: false,
+                    type: 'object',
+                    description: "Caller-defined string key/value pairs supplied when the session was started, e.g. ids from your own system. Immutable, present on root sessions only, and filterable with metadata=key:value or metadata_key=key on GET /v1/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters.",
+                },
                 {
                     name: 'model_ref_id',
                     required: false,
@@ -53637,6 +53643,131 @@ export const SDK_REFERENCE = {
             ],
         },
     },
+    managedAgentsListSessionResourceSamples: {
+        operationId: 'managedAgentsListSessionResourceSamples',
+        tag: 'managed-agents',
+        callPath: ['managedAgents', 'listSessionResourceSamples'],
+        namespace: 'managedAgents',
+        method: 'listSessionResourceSamples',
+        signature: 'rl.managedAgents.listSessionResourceSamples({ session_id })',
+        example: "const result = await rl.managedAgents.listSessionResourceSamples({\n  session_id: '<session_id>',\n  // optional: from, to, resolution, limit, page_token\n});",
+        cliInvocation: 'rl managed-agents list-session-resource-samples',
+        cliExample: 'rl managed-agents list-session-resource-samples \\\n  --session_id <session_id>',
+        curlExample: "curl -X GET 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/<session_id>/resource-samples' \\\n  -H 'Authorization: Bearer $LABELBOX_API_KEY'",
+        summary: 'Read sandbox CPU, memory, and GPU usage for a session tree',
+        description: "Returns the tree's sandbox attachments and one page of per-minute resource usage buckets for them, ordered by attachment then time. Each bucket carries the minute's average and peak; resolution=raw adds the individual samples as parallel arrays indexed by offsets_ms. A tree whose compute was released and revived has several attachments; follow revived_from_sandbox_id to connect them. live reports whether a sandbox is still attached, which is the cue to keep polling. An empty sandboxes list means the tree never ran in a sandbox or sampling is disabled; an attachment with sampling_source=unsupported means the sandbox could not measure itself.",
+        httpMethod: 'get',
+        path: '/managed-agents/v1/sessions/{session_id}/resource-samples',
+        requiredPermissions: ['managed-agents:read'],
+        params: [
+            {
+                name: 'from',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: 'Inclusive lower bound on bucket_start, RFC 3339. Omit for the start of the tree.',
+                format: 'date-time',
+            },
+            {
+                name: 'to',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: 'Exclusive upper bound on bucket_start, RFC 3339. Omit for now.',
+                format: 'date-time',
+            },
+            {
+                name: 'resolution',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: "minute returns per-minute summaries only; raw also includes each bucket's per-sample arrays at the producer's cadence (five seconds by default). Use raw for the window on screen and minute for the overview.",
+                enum: ['minute', 'raw'],
+                default: 'minute',
+            },
+            {
+                name: 'limit',
+                in: 'query',
+                required: false,
+                type: 'integer',
+                description: "Maximum buckets per page, across all of the tree's sandbox attachments.",
+                default: 120,
+                minimum: 1,
+                maximum: 720,
+            },
+            {
+                name: 'page_token',
+                in: 'query',
+                required: false,
+                type: 'string',
+                description: "Signed continuation token from a previous page's next_page_token. Bound to the organization, session, and filters it was issued for.",
+            },
+            {
+                name: 'session_id',
+                in: 'path',
+                required: true,
+                type: 'string',
+                description: 'Any session id (UUID) in the tree. The sandbox is shared by the whole tree, so every id in it returns the same usage.',
+                format: 'uuid',
+            },
+        ],
+        response: {
+            type: 'ManagedAgentsSessionResourceSamplesResponse',
+            description: 'Sandbox CPU, memory, and accelerator usage for a session tree, as minute buckets per sandbox attachment. Samples are what the sandbox measured of itself, drained to the control plane on tool calls and on read.',
+            fields: [
+                {
+                    name: 'as_of',
+                    required: false,
+                    type: 'string',
+                    description: 'RFC 3339 server time at which the page was read.',
+                    format: 'date-time',
+                },
+                {
+                    name: 'buckets',
+                    required: false,
+                    type: 'unknown',
+                    description: 'One page of minute buckets ordered by (sandbox_id, bucket_start). Each bucket names its attachment; join on sandboxes to place it on a lane.',
+                },
+                {
+                    name: 'live',
+                    required: false,
+                    type: 'boolean',
+                    description: 'True while a sandbox that can be sampled is still attached to the tree. A client keeps polling while this is true and stops once it turns false; an attached sandbox that cannot measure itself does not keep it true.',
+                },
+                {
+                    name: 'next_page_token',
+                    required: false,
+                    type: 'string',
+                    description: 'Present when more buckets remain. Pass as page_token with the same query to continue.',
+                },
+                {
+                    name: 'resolution',
+                    required: false,
+                    type: 'string',
+                    description: 'Resolution the buckets were read at.',
+                    enum: ['minute', 'raw'],
+                },
+                {
+                    name: 'root_session_id',
+                    required: false,
+                    type: 'string',
+                    description: 'Root of the tree the usage belongs to.',
+                },
+                {
+                    name: 'sandboxes',
+                    required: false,
+                    type: 'unknown',
+                    description: 'Every sandbox attachment the tree has had, oldest first, including ones that have since been released or closed. Empty when the tree never had a sandbox or sampling is disabled. Complete on every page.',
+                },
+                {
+                    name: 'session_id',
+                    required: false,
+                    type: 'string',
+                    description: 'Session id named in the request.',
+                },
+            ],
+        },
+    },
     managedAgentsListSessionThreads: {
         operationId: 'managedAgentsListSessionThreads',
         tag: 'managed-agents',
@@ -53721,7 +53852,7 @@ export const SDK_REFERENCE = {
         namespace: 'managedAgents',
         method: 'listSessions',
         signature: 'rl.managedAgents.listSessions()',
-        example: 'const result = await rl.managedAgents.listSessions({\n  // optional: status, kind, agent_id, tag_ids, external_source_type, external_source_id, root_only, limit\n});',
+        example: 'const result = await rl.managedAgents.listSessions({\n  // optional: status, kind, agent_id, tag_ids, external_source_type, external_source_id, metadata, metadata_key, root_only, limit\n});',
         cliInvocation: 'rl managed-agents list-sessions',
         cliExample: 'rl managed-agents list-sessions',
         curlExample: "curl -X GET 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \\\n  -H 'Authorization: Bearer $LABELBOX_API_KEY'",
@@ -53771,6 +53902,22 @@ export const SDK_REFERENCE = {
                 required: false,
                 type: 'string',
             },
+            {
+                name: 'metadata',
+                in: 'query',
+                required: false,
+                type: 'string[]',
+                description: "Exact-match filter on caller-defined session metadata as key:value, split at the first colon. Repeat the parameter to require several pairs; a session's root must carry every one (AND semantics). Children of a matching root match too, so combine with root_only to list only the roots.",
+                maxItems: 32,
+            },
+            {
+                name: 'metadata_key',
+                in: 'query',
+                required: false,
+                type: 'string[]',
+                description: 'Require the root session to carry this caller-defined metadata key with any value. Repeatable; every listed key must be present.',
+                maxItems: 32,
+            },
             {
                 name: 'root_only',
                 in: 'query',
@@ -55016,10 +55163,10 @@ export const SDK_REFERENCE = {
         method: 'startSession',
         bodyKey: 'body',
         signature: 'rl.managedAgents.startSession({ body })',
-        example: 'const result = await rl.managedAgents.startSession({\n  body: {\n    agent_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    credential_refs: [\n      {\n        credential_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        vault_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    environment_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    external_source_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    external_source_type: "example",\n    idempotency_key: "example",\n    message: "example",\n    outcome: {\n      description: "example",\n      grader_model_ref_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n      max_iterations: 1,\n      rubric: "example"\n    },\n    project_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    skip_default_outcome: true,\n    vault_ids: [\n      "example"\n    ]\n  },\n});',
+        example: 'const result = await rl.managedAgents.startSession({\n  body: {\n    agent_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    credential_refs: [\n      {\n        credential_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        vault_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    environment_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    external_source_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    external_source_type: "example",\n    idempotency_key: "example",\n    message: "example",\n    metadata: {\n      key: "example"\n    },\n    outcome: {\n      description: "example",\n      grader_model_ref_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n      max_iterations: 1,\n      rubric: "example"\n    },\n    project_id: "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    skip_default_outcome: true,\n    vault_ids: [\n      "example"\n    ]\n  },\n});',
         cliInvocation: 'rl managed-agents start-session',
         cliExample: "rl managed-agents start-session \\\n  --agent_id '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d' \\\n  --environment_id '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d' \\\n  --from-json body.json",
-        curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/sessions\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "credential_refs": [\n      {\n        "credential_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        "vault_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_type": "example",\n    "idempotency_key": "example",\n    "message": "example",\n    "outcome": {\n      "description": "example",\n      "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n      "max_iterations": 1,\n      "rubric": "example"\n    },\n    "project_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "skip_default_outcome": true,\n    "vault_ids": [\n      "example"\n    ]\n  }\'',
+        curlExample: 'curl -X POST \'https://api.recursion.labelbox.com/managed-agents/v1/sessions\' \\\n  -H \'Authorization: Bearer $LABELBOX_API_KEY\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "agent_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "credential_refs": [\n      {\n        "credential_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n        "vault_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"\n      }\n    ],\n    "environment_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "external_source_type": "example",\n    "idempotency_key": "example",\n    "message": "example",\n    "metadata": {\n      "key": "example"\n    },\n    "outcome": {\n      "description": "example",\n      "grader_model_ref_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n      "max_iterations": 1,\n      "rubric": "example"\n    },\n    "project_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",\n    "skip_default_outcome": true,\n    "vault_ids": [\n      "example"\n    ]\n  }\'',
         summary: 'Start a managed session',
         description: 'Starts a managed agent session and returns 202 with its session_id and status_path; the agent runs asynchronously, so poll getSession or subscribe with streamSessionEvents to follow it. Sandbox compute is provisioned here, which is where a session begins costing money. Send an Idempotency-Key header to make retries safe: the same key with the same body returns the original session, and with a different body is rejected.',
         httpMethod: 'post',
@@ -55093,6 +55240,13 @@ export const SDK_REFERENCE = {
                 type: 'string',
                 description: "Opening user message for the session, and the context the agent works from. Send it alongside an outcome to supply facts the agent needs without making them part of what the grader measures; the grader never sees it. Kept in the session's system prompt for the whole run, so context compaction cannot summarize it away.",
             },
+            {
+                name: 'metadata',
+                in: 'body',
+                required: false,
+                type: 'object',
+                description: "Caller-defined string key/value pairs stored on the session, e.g. ids that map it back to your own system. Write-once: they cannot be changed after start. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters without control characters. Returned as metadata on GET /v1/sessions and filterable with metadata=key:value (repeatable, AND) or metadata_key=key.",
+            },
             {
                 name: 'outcome',
                 in: 'body',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelbox/recursion-sdk",
-  "version": "0.0.162",
+  "version": "0.0.164",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",