@runtypelabs/sdk 10.1.4 → 10.2.0

package/dist/index.cjs

@@ -14149,7 +14149,7 @@ function transformQueryParams(params) {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "10.1.4".length > 0 ? "10.1.4" : FALLBACK_VERSION;
+var SDK_VERSION = "10.2.0".length > 0 ? "10.2.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 

package/dist/index.d.cts

@@ -8682,7 +8682,7 @@ interface paths {
                         };
                     };
                 };
-                /** @description Forbidden. Either the client token is inactive or the origin is not allowed, or the tenancy lock-down refused the execution: the agent requires an end-user scope and no valid `identityProof` was supplied (`end_user_scope_required`), or this session's conversation record belongs to a different signed-in end user (`conversation_scope_mismatch`; start a new conversation). */
+                /** @description Forbidden. Either the client token is inactive or the origin is not allowed, or the tenancy lock-down refused the execution: the agent requires an end-user scope and no valid `identityProof` was supplied (`end_user_scope_required`), or this session's conversation record belongs to a different signed-in end user (`conversation_scope_mismatch`; start a new conversation), or a Claude Managed target's conversation is not owned by the visitor making the request (`CLIENT_CONVERSATION_NOT_VISITOR_OWNED`; initialize with `durableRecovery: true` and send `X-Visitor-Token`). */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -8700,7 +8700,7 @@ interface paths {
                         "application/json": components["schemas"]["Error"];
                     };
                 };
-                /** @description Conflict. Either the client tools registry fingerprint was not found (`client_tools_resend_required`; resend the full `clientTools[]` with the fingerprint), or this turn was superseded by a newer interrupting turn before it could start (`turn_superseded`). The body carries `error` alone. */
+                /** @description Conflict. Either the client tools registry fingerprint was not found (`client_tools_resend_required`; resend the full `clientTools[]` with the fingerprint), this turn was superseded by a newer interrupting turn before it could start (`turn_superseded`), or a Claude Managed target was refused because the caller has not opted into durable turns (`CLAUDE_MANAGED_DURABLE_TURNS_REQUIRED`; `hint` names the exact opt-in) or the session carries no conversation record (`CLAUDE_MANAGED_CONVERSATION_REQUIRED`). A join refusal uses `JOIN_UNAVAILABLE`. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -8977,8 +8977,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Stop a native durable client execution
-         * @description Cancel the specified execution without starting a replacement. Pending inputs become not applied. Requires the exact visitor and session bound to the conversation.
+         * Stop a durable client execution
+         * @description Cancel the specified execution without starting a replacement. For a native agent, pending inputs become not applied; for a Claude Managed agent, the hosted session is interrupted and stays resumable. Requires the exact visitor and session bound to the conversation.
          */
         post: {
             parameters: {
@@ -9047,6 +9047,7 @@ interface paths {
                         "application/json": {
                             accepted: boolean;
                             executionId: string;
+                            reason?: string;
                         };
                     };
                 };
@@ -9736,7 +9737,7 @@ interface paths {
                             conversationRevision: string;
                             /** @description Returned when the request negotiates `durableRecovery`. Older servers omit it; clients must then keep ordinary streaming behavior. */
                             durableRecovery?: {
-                                /** @description Whether this initialized client-token session has the visitor credential and surface policy needed to use the durable execution reconnect route. Reporting only: individual turns still self-identify as durable through replay cursors. */
+                                /** @description Whether this initialized client-token session has the visitor credential and the durable-turns opt-in needed to use the durable execution reconnect route. The opt-in is the chat surface `behavior.durableTurns.enabled` for a surface-bound token and `config.durableTurns.enabled` for a standalone token. Reporting only: individual turns still self-identify as durable through replay cursors. */
                                 enabled: boolean;
                                 /** @description Whether the native durable target supports non-interrupting user-message delivery. */
                                 join?: boolean;
@@ -25156,7 +25157,7 @@ interface paths {
         };
         /**
          * Query customer logs
-         * @description Query persisted customer logs via R2 SQL with filtering, pagination, and search.
+         * @description Query persisted customer logs with filtering, pagination, and search. When `data.live` is present the page came from the span store: one entry is one execution seam, so sub-seam rows (step skips, sources, context notices, artifacts, state snapshots, custom events) are not listed, a start/complete pair is one row carrying a duration, runs still in progress appear once they finish, and `search` matches a span's message, name, operation, tool name or error class. Otherwise each entry is one event. Requests naming `audit` or `schedule`, and an audit-entitled unfiltered read, are always served from the event tier.
          */
         get: {
             parameters: {
@@ -25169,9 +25170,9 @@ interface paths {
                     startTime?: string;
                     /** @description Alias for to. Ignored when to is also given. */
                     endTime?: string;
-                    /** @description Comma-separated log levels (debug,info,warn,error) */
+                    /** @description Comma-separated log levels (debug,info,warn,error). An unknown value is rejected with 400. */
                     level?: string;
-                    /** @description Comma-separated categories */
+                    /** @description Comma-separated categories (execution,agent,tool,model,system,error,schedule,batch,audit). An unknown value is rejected with 400. */
                     category?: string;
                     /** @description Filter by flow ID */
                     flowId?: string;
@@ -25213,8 +25214,18 @@ interface paths {
                                 entries: {
                                     [key: string]: unknown;
                                 }[];
+                                /** @description Present only when the page was served from the span store. Runs still in progress appear once they finish; the minutes above the cut-line come from the live tier when it answers in time. Absent otherwise. */
+                                live?: {
+                                    /** @description Entries at or below this instant came from the span store; newer ones from the live tier. */
+                                    cutline: string;
+                                    /** @enum {string} */
+                                    reason?: "hot_tier_failed" | "outside_window";
+                                    served: boolean;
+                                };
                                 pagination: {
                                     cursor: string | null;
+                                    /** @description True when the supplied cursor could not be honoured and the read restarted at page one. A paging client must stop rather than follow the fresh cursor. Absent otherwise. */
+                                    cursorReset?: boolean;
                                     hasMore: boolean;
                                 };
                             };
@@ -25348,15 +25359,19 @@ interface paths {
         };
         /**
          * Read one log entry in full
-         * @description Returns a single log entry addressed by its execution and timestamp, including the model-call transcript the paged list projection omits. Bounded to one millisecond of one execution, so a detail read never costs a page.
+         * @description Returns a single log entry, including the model-call transcript the paged list projection omits. Address it either by the span key (traceId, spanId and timestamp) or by the legacy triple (executionId and timestamp, optionally narrowed by requestId, seq or eventName). Bounded to one millisecond of one execution, so a detail read never costs a page.
          */
         get: {
             parameters: {
                 query: {
-                    /** @description Runtime execution_id / executionSessionId the entry belongs to */
-                    executionId: string;
+                    /** @description Runtime execution_id / executionSessionId the entry belongs to. Required unless traceId and spanId are given. */
+                    executionId?: string;
                     /** @description The entry's exact timestamp (ISO 8601) */
                     timestamp: string;
+                    /** @description Trace the span belongs to. Required with spanId; a span id is unique only within its trace. */
+                    traceId?: string;
+                    /** @description Span to read, from a list row’s otlpSpanId. Requires traceId. */
+                    spanId?: string;
                     /** @description Narrow to one request */
                     requestId?: string;
                     /** @description Narrow to one sequence number */
@@ -25445,9 +25460,9 @@ interface paths {
                     startTime?: string;
                     /** @description Alias for to. Ignored when to is also given. */
                     endTime?: string;
-                    /** @description Comma-separated log levels (debug,info,warn,error) */
+                    /** @description Comma-separated log levels (debug,info,warn,error). An unknown value is rejected with 400. */
                     level?: string;
-                    /** @description Comma-separated categories */
+                    /** @description Comma-separated categories (execution,agent,tool,model,system,error,schedule,batch,audit). An unknown value is rejected with 400. */
                     category?: string;
                     /** @description Filter by flow ID */
                     flowId?: string;
@@ -30805,6 +30820,8 @@ interface paths {
                                         budgetExhausted?: boolean | null;
                                         /** @description Cancel request. Absent means the overlay did not answer, which is not false and not null. */
                                         cancelRequestedAt?: string | null;
+                                        /** @description How many runs name this one as their parent. The unscoped feed returns roots only, so this is the size of the fold underneath a row; read the children with parentExecutionId=<executionId>. It is populated on a resource-scoped page too, where nothing is folded, so a surface can still offer the same expansion. WHICH children are counted depends on the arm that served the row: the span store counts every child, agent and nested-flow alike, while the legacy control-plane fallback counts agent children only, so on that arm a parent whose only child is a nested flow reports 0. That is deliberate — the fallback arm cannot enumerate a nested-flow child either, so counting one would advertise a fold that opens on nothing. It counts only children the CALLER may read: a credential holding one execution family (AGENTS:READ or FLOWS:READ alone) counts the children of that family and no others, so a count never discloses a run the same credential could not list. NULL means the arm cannot count children at all, which is not zero. */
+                                        childCount: number | null;
                                         /**
                                          * @description Storage completeness; null on a row the control-plane arm served.
                                          * @enum {string|null}
@@ -30842,7 +30859,7 @@ interface paths {
                                         /** @description Last heartbeat. Absent means the overlay did not answer, which is not false and not null. */
                                         lastHeartbeatAt?: string | null;
                                         /**
-                                         * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field: dashboard for a Clerk session, api for a management API key, internal for a Runtype worker. NULL means the header states nothing about it, which is not "unknown caller": headers written before this field shipped, lanes that never see an auth principal, and every backfilled row carry no origin stamp.
+                                         * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field. ANY entrance that resolves a principal stamps it: a Clerk session answers dashboard; a management API key answers api, which includes the Runtype MCP server's tools and Code Mode, since both reach dispatch with a management key; and Runtype's own internal caller answers internal, for example the hosted /v1/mcp proxy. A lane that resolves NO principal carries NULL BY DESIGN: schedule, webhook, messaging, A2A, an agent exposed AS an MCP surface, subagent, nested flow, a client-token product surface (an end user is none of the three origins) and an ingested OTLP run. So NULL says "no authenticated principal at this entrance" rather than "unknown caller". The one NULL that is not a statement about the lane is a row whose header predates the field or came from the backfill: it stamps nothing even for a run that did resolve a principal.
                                          * @enum {string|null}
                                          */
                                         origin: "dashboard" | "api" | "internal" | null;
@@ -40059,7 +40076,7 @@ interface paths {
         };
         /**
          * List runs
-         * @description Every agent and flow run in the span store, newest start first, including runs that write no control-plane row. Each row carries `origin` (dashboard | api | internal | null), read from the caller's authenticated principal, and `test` as its derived alias for `origin === "dashboard"`; both are null when the header states nothing. `overlay=live` adds live control-plane fields; the overlay never adds, drops or reorders a row. Returns 404 with `code: "run_history_unavailable"` when neither plane can serve the page, which a client renders as "no run history here" rather than as a failed read.
+         * @description Every agent and flow run in the span store, newest start first, including runs that write no control-plane row. The UNSCOPED feed is ROOT runs only: a subagent or nested-flow run folds under its parent, `childCount` says how many are folded there, and `parentExecutionId=<id>` reads them. Pass `includeChildren=true` for the flat enumeration. Any resource-scoped filter (`agentId`, `flowId`, `conversationId`, `surfaceId`, `recordId`, `batchExecutionId`, `parentExecutionId`, `rootExecutionId`, `executionId`) is already an explicit selection and never folds, so an agent that only ever runs as a subagent still lists under `agentId`. Each row carries `origin` (dashboard | api | internal | null), read from the caller's authenticated principal, and `test` as its derived alias for `origin === "dashboard"`; any entrance that resolves a principal stamps origin, including the Runtype MCP server tools and Code Mode (`api`) and the hosted `/v1/mcp` proxy (`internal`). A lane with no principal answers null for both by design: schedule, webhook, messaging, A2A, an agent exposed as an MCP surface, subagent, nested flow, a client-token product surface, an ingested run, and any row whose header predates the field. `overlay=live` adds live control-plane fields; the overlay never adds, drops or reorders a row. Returns 404 with `code: "run_history_unavailable"` when neither plane can serve the page, which a client renders as "no run history here" rather than as a failed read.
          */
         get: {
             parameters: {
@@ -40082,6 +40099,8 @@ interface paths {
                     parentExecutionId?: string;
                     /** @description Runs in this execution tree. */
                     rootExecutionId?: string;
+                    /** @description true restores the flat enumeration on the UNSCOPED feed, in which a subagent run and a nested-flow run list beside their parent. The unscoped feed is roots only by default: a row whose parentExecutionId is set folds under its parent and is read with parentExecutionId=<executionId>. Any filter that scopes to a resource — agentId, flowId, conversationId, surfaceId, recordId, batchExecutionId, parentExecutionId, rootExecutionId or executionId — is already an explicit selection and never folds, so an agent that only ever runs as a subagent still lists under agentId. This parameter changes nothing on a scoped request. */
+                    includeChildren?: "true" | "false";
                     /** @description Read specific runs by id; at most 100 per request. */
                     executionId?: string | string[];
                     /** @description Filter by producing lane. */
@@ -50955,6 +50974,8 @@ interface components {
             budgetExhausted?: boolean | null;
             /** @description Cancel request. Absent means the overlay did not answer, which is not false and not null. */
             cancelRequestedAt?: string | null;
+            /** @description How many runs name this one as their parent. The unscoped feed returns roots only, so this is the size of the fold underneath a row; read the children with parentExecutionId=<executionId>. It is populated on a resource-scoped page too, where nothing is folded, so a surface can still offer the same expansion. WHICH children are counted depends on the arm that served the row: the span store counts every child, agent and nested-flow alike, while the legacy control-plane fallback counts agent children only, so on that arm a parent whose only child is a nested flow reports 0. That is deliberate — the fallback arm cannot enumerate a nested-flow child either, so counting one would advertise a fold that opens on nothing. It counts only children the CALLER may read: a credential holding one execution family (AGENTS:READ or FLOWS:READ alone) counts the children of that family and no others, so a count never discloses a run the same credential could not list. NULL means the arm cannot count children at all, which is not zero. */
+            childCount: number | null;
             /**
              * @description Storage completeness; null on a row the control-plane arm served.
              * @enum {string|null}
@@ -50992,7 +51013,7 @@ interface components {
             /** @description Last heartbeat. Absent means the overlay did not answer, which is not false and not null. */
             lastHeartbeatAt?: string | null;
             /**
-             * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field: dashboard for a Clerk session, api for a management API key, internal for a Runtype worker. NULL means the header states nothing about it, which is not "unknown caller": headers written before this field shipped, lanes that never see an auth principal, and every backfilled row carry no origin stamp.
+             * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field. ANY entrance that resolves a principal stamps it: a Clerk session answers dashboard; a management API key answers api, which includes the Runtype MCP server's tools and Code Mode, since both reach dispatch with a management key; and Runtype's own internal caller answers internal, for example the hosted /v1/mcp proxy. A lane that resolves NO principal carries NULL BY DESIGN: schedule, webhook, messaging, A2A, an agent exposed AS an MCP surface, subagent, nested flow, a client-token product surface (an end user is none of the three origins) and an ingested OTLP run. So NULL says "no authenticated principal at this entrance" rather than "unknown caller". The one NULL that is not a statement about the lane is a row whose header predates the field or came from the backfill: it stamps nothing even for a run that did resolve a principal.
              * @enum {string|null}
              */
             origin: "dashboard" | "api" | "internal" | null;
@@ -57927,6 +57948,18 @@ interface RunListRow {
     parentExecutionId: string | null;
     parentToolCallId: string | null;
     rootExecutionId: string | null;
+    /**
+     * How many runs name this one as their parent. The unscoped feed returns
+     * roots only, so this is the size of the fold underneath a row; read the
+     * children with `parentExecutionId`. It is populated on a resource-scoped
+     * page too. The span store counts agent and nested-flow children alike; the
+     * legacy control-plane fallback counts agent children only, so a
+     * nested-flow-only parent reports 0 there — that arm cannot enumerate such a
+     * child either. It counts only children the caller may read, so a
+     * single-family credential never learns the other family's children exist.
+     * NULL when the serving arm cannot count at all.
+     */
+    childCount: number | null;
     source: 'hosted' | 'ingested';
     fidelityTier: string | null;
     completeness: 'partial' | 'complete' | 'conflicted' | 'expired' | 'deleted' | null;
@@ -57938,8 +57971,9 @@ interface RunListRow {
     selfReportedCost: string | null;
     /**
      * Where the run was dispatched from, taken from the caller's authenticated
-     * principal and never from a request field. NULL means the header states
-     * nothing about it: a lane that sees no principal, or a backfilled row.
+     * principal and never from a request field. Any entrance that resolves a
+     * principal stamps it (MCP tools and Code Mode answer `api`, the hosted
+     * `/v1/mcp` proxy `internal`); a lane with none carries NULL by design.
      */
     origin: 'dashboard' | 'api' | 'internal' | null;
     /**
@@ -57996,6 +58030,13 @@ interface RunListParams {
     parentExecutionId?: string;
     rootExecutionId?: string;
     executionId?: string | string[];
+    /**
+     * `'true'` restores the flat enumeration on the unscoped feed, which is roots
+     * only by default: a subagent or nested-flow run folds under its parent. Any
+     * resource-scoped filter is already an explicit selection and never folds, so
+     * this changes nothing there.
+     */
+    includeChildren?: 'true' | 'false';
     source?: 'hosted' | 'ingested';
     /**
      * `running`, `completed` or `failed` only. `queued`, `awaiting` and
@@ -59430,6 +59471,14 @@ interface ClientTokenConfig {
     theme?: ClientWidgetTheme;
     /** Custom data passed to flows */
     customData?: Record<string, unknown>;
+    /**
+     * Durable-turn opt-in for a token with no product surface. A surface-bound
+     * token reads the surface's `behavior.durableTurns` instead and ignores this.
+     */
+    durableTurns?: {
+        /** Defaults to false when absent. */
+        enabled?: boolean;
+    };
 }
 /**
  * Client token data returned from the API

package/dist/index.d.ts

@@ -8682,7 +8682,7 @@ interface paths {
                         };
                     };
                 };
-                /** @description Forbidden. Either the client token is inactive or the origin is not allowed, or the tenancy lock-down refused the execution: the agent requires an end-user scope and no valid `identityProof` was supplied (`end_user_scope_required`), or this session's conversation record belongs to a different signed-in end user (`conversation_scope_mismatch`; start a new conversation). */
+                /** @description Forbidden. Either the client token is inactive or the origin is not allowed, or the tenancy lock-down refused the execution: the agent requires an end-user scope and no valid `identityProof` was supplied (`end_user_scope_required`), or this session's conversation record belongs to a different signed-in end user (`conversation_scope_mismatch`; start a new conversation), or a Claude Managed target's conversation is not owned by the visitor making the request (`CLIENT_CONVERSATION_NOT_VISITOR_OWNED`; initialize with `durableRecovery: true` and send `X-Visitor-Token`). */
                 403: {
                     headers: {
                         [name: string]: unknown;
@@ -8700,7 +8700,7 @@ interface paths {
                         "application/json": components["schemas"]["Error"];
                     };
                 };
-                /** @description Conflict. Either the client tools registry fingerprint was not found (`client_tools_resend_required`; resend the full `clientTools[]` with the fingerprint), or this turn was superseded by a newer interrupting turn before it could start (`turn_superseded`). The body carries `error` alone. */
+                /** @description Conflict. Either the client tools registry fingerprint was not found (`client_tools_resend_required`; resend the full `clientTools[]` with the fingerprint), this turn was superseded by a newer interrupting turn before it could start (`turn_superseded`), or a Claude Managed target was refused because the caller has not opted into durable turns (`CLAUDE_MANAGED_DURABLE_TURNS_REQUIRED`; `hint` names the exact opt-in) or the session carries no conversation record (`CLAUDE_MANAGED_CONVERSATION_REQUIRED`). A join refusal uses `JOIN_UNAVAILABLE`. */
                 409: {
                     headers: {
                         [name: string]: unknown;
@@ -8977,8 +8977,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Stop a native durable client execution
-         * @description Cancel the specified execution without starting a replacement. Pending inputs become not applied. Requires the exact visitor and session bound to the conversation.
+         * Stop a durable client execution
+         * @description Cancel the specified execution without starting a replacement. For a native agent, pending inputs become not applied; for a Claude Managed agent, the hosted session is interrupted and stays resumable. Requires the exact visitor and session bound to the conversation.
          */
         post: {
             parameters: {
@@ -9047,6 +9047,7 @@ interface paths {
                         "application/json": {
                             accepted: boolean;
                             executionId: string;
+                            reason?: string;
                         };
                     };
                 };
@@ -9736,7 +9737,7 @@ interface paths {
                             conversationRevision: string;
                             /** @description Returned when the request negotiates `durableRecovery`. Older servers omit it; clients must then keep ordinary streaming behavior. */
                             durableRecovery?: {
-                                /** @description Whether this initialized client-token session has the visitor credential and surface policy needed to use the durable execution reconnect route. Reporting only: individual turns still self-identify as durable through replay cursors. */
+                                /** @description Whether this initialized client-token session has the visitor credential and the durable-turns opt-in needed to use the durable execution reconnect route. The opt-in is the chat surface `behavior.durableTurns.enabled` for a surface-bound token and `config.durableTurns.enabled` for a standalone token. Reporting only: individual turns still self-identify as durable through replay cursors. */
                                 enabled: boolean;
                                 /** @description Whether the native durable target supports non-interrupting user-message delivery. */
                                 join?: boolean;
@@ -25156,7 +25157,7 @@ interface paths {
         };
         /**
          * Query customer logs
-         * @description Query persisted customer logs via R2 SQL with filtering, pagination, and search.
+         * @description Query persisted customer logs with filtering, pagination, and search. When `data.live` is present the page came from the span store: one entry is one execution seam, so sub-seam rows (step skips, sources, context notices, artifacts, state snapshots, custom events) are not listed, a start/complete pair is one row carrying a duration, runs still in progress appear once they finish, and `search` matches a span's message, name, operation, tool name or error class. Otherwise each entry is one event. Requests naming `audit` or `schedule`, and an audit-entitled unfiltered read, are always served from the event tier.
          */
         get: {
             parameters: {
@@ -25169,9 +25170,9 @@ interface paths {
                     startTime?: string;
                     /** @description Alias for to. Ignored when to is also given. */
                     endTime?: string;
-                    /** @description Comma-separated log levels (debug,info,warn,error) */
+                    /** @description Comma-separated log levels (debug,info,warn,error). An unknown value is rejected with 400. */
                     level?: string;
-                    /** @description Comma-separated categories */
+                    /** @description Comma-separated categories (execution,agent,tool,model,system,error,schedule,batch,audit). An unknown value is rejected with 400. */
                     category?: string;
                     /** @description Filter by flow ID */
                     flowId?: string;
@@ -25213,8 +25214,18 @@ interface paths {
                                 entries: {
                                     [key: string]: unknown;
                                 }[];
+                                /** @description Present only when the page was served from the span store. Runs still in progress appear once they finish; the minutes above the cut-line come from the live tier when it answers in time. Absent otherwise. */
+                                live?: {
+                                    /** @description Entries at or below this instant came from the span store; newer ones from the live tier. */
+                                    cutline: string;
+                                    /** @enum {string} */
+                                    reason?: "hot_tier_failed" | "outside_window";
+                                    served: boolean;
+                                };
                                 pagination: {
                                     cursor: string | null;
+                                    /** @description True when the supplied cursor could not be honoured and the read restarted at page one. A paging client must stop rather than follow the fresh cursor. Absent otherwise. */
+                                    cursorReset?: boolean;
                                     hasMore: boolean;
                                 };
                             };
@@ -25348,15 +25359,19 @@ interface paths {
         };
         /**
          * Read one log entry in full
-         * @description Returns a single log entry addressed by its execution and timestamp, including the model-call transcript the paged list projection omits. Bounded to one millisecond of one execution, so a detail read never costs a page.
+         * @description Returns a single log entry, including the model-call transcript the paged list projection omits. Address it either by the span key (traceId, spanId and timestamp) or by the legacy triple (executionId and timestamp, optionally narrowed by requestId, seq or eventName). Bounded to one millisecond of one execution, so a detail read never costs a page.
          */
         get: {
             parameters: {
                 query: {
-                    /** @description Runtime execution_id / executionSessionId the entry belongs to */
-                    executionId: string;
+                    /** @description Runtime execution_id / executionSessionId the entry belongs to. Required unless traceId and spanId are given. */
+                    executionId?: string;
                     /** @description The entry's exact timestamp (ISO 8601) */
                     timestamp: string;
+                    /** @description Trace the span belongs to. Required with spanId; a span id is unique only within its trace. */
+                    traceId?: string;
+                    /** @description Span to read, from a list row’s otlpSpanId. Requires traceId. */
+                    spanId?: string;
                     /** @description Narrow to one request */
                     requestId?: string;
                     /** @description Narrow to one sequence number */
@@ -25445,9 +25460,9 @@ interface paths {
                     startTime?: string;
                     /** @description Alias for to. Ignored when to is also given. */
                     endTime?: string;
-                    /** @description Comma-separated log levels (debug,info,warn,error) */
+                    /** @description Comma-separated log levels (debug,info,warn,error). An unknown value is rejected with 400. */
                     level?: string;
-                    /** @description Comma-separated categories */
+                    /** @description Comma-separated categories (execution,agent,tool,model,system,error,schedule,batch,audit). An unknown value is rejected with 400. */
                     category?: string;
                     /** @description Filter by flow ID */
                     flowId?: string;
@@ -30805,6 +30820,8 @@ interface paths {
                                         budgetExhausted?: boolean | null;
                                         /** @description Cancel request. Absent means the overlay did not answer, which is not false and not null. */
                                         cancelRequestedAt?: string | null;
+                                        /** @description How many runs name this one as their parent. The unscoped feed returns roots only, so this is the size of the fold underneath a row; read the children with parentExecutionId=<executionId>. It is populated on a resource-scoped page too, where nothing is folded, so a surface can still offer the same expansion. WHICH children are counted depends on the arm that served the row: the span store counts every child, agent and nested-flow alike, while the legacy control-plane fallback counts agent children only, so on that arm a parent whose only child is a nested flow reports 0. That is deliberate — the fallback arm cannot enumerate a nested-flow child either, so counting one would advertise a fold that opens on nothing. It counts only children the CALLER may read: a credential holding one execution family (AGENTS:READ or FLOWS:READ alone) counts the children of that family and no others, so a count never discloses a run the same credential could not list. NULL means the arm cannot count children at all, which is not zero. */
+                                        childCount: number | null;
                                         /**
                                          * @description Storage completeness; null on a row the control-plane arm served.
                                          * @enum {string|null}
@@ -30842,7 +30859,7 @@ interface paths {
                                         /** @description Last heartbeat. Absent means the overlay did not answer, which is not false and not null. */
                                         lastHeartbeatAt?: string | null;
                                         /**
-                                         * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field: dashboard for a Clerk session, api for a management API key, internal for a Runtype worker. NULL means the header states nothing about it, which is not "unknown caller": headers written before this field shipped, lanes that never see an auth principal, and every backfilled row carry no origin stamp.
+                                         * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field. ANY entrance that resolves a principal stamps it: a Clerk session answers dashboard; a management API key answers api, which includes the Runtype MCP server's tools and Code Mode, since both reach dispatch with a management key; and Runtype's own internal caller answers internal, for example the hosted /v1/mcp proxy. A lane that resolves NO principal carries NULL BY DESIGN: schedule, webhook, messaging, A2A, an agent exposed AS an MCP surface, subagent, nested flow, a client-token product surface (an end user is none of the three origins) and an ingested OTLP run. So NULL says "no authenticated principal at this entrance" rather than "unknown caller". The one NULL that is not a statement about the lane is a row whose header predates the field or came from the backfill: it stamps nothing even for a run that did resolve a principal.
                                          * @enum {string|null}
                                          */
                                         origin: "dashboard" | "api" | "internal" | null;
@@ -40059,7 +40076,7 @@ interface paths {
         };
         /**
          * List runs
-         * @description Every agent and flow run in the span store, newest start first, including runs that write no control-plane row. Each row carries `origin` (dashboard | api | internal | null), read from the caller's authenticated principal, and `test` as its derived alias for `origin === "dashboard"`; both are null when the header states nothing. `overlay=live` adds live control-plane fields; the overlay never adds, drops or reorders a row. Returns 404 with `code: "run_history_unavailable"` when neither plane can serve the page, which a client renders as "no run history here" rather than as a failed read.
+         * @description Every agent and flow run in the span store, newest start first, including runs that write no control-plane row. The UNSCOPED feed is ROOT runs only: a subagent or nested-flow run folds under its parent, `childCount` says how many are folded there, and `parentExecutionId=<id>` reads them. Pass `includeChildren=true` for the flat enumeration. Any resource-scoped filter (`agentId`, `flowId`, `conversationId`, `surfaceId`, `recordId`, `batchExecutionId`, `parentExecutionId`, `rootExecutionId`, `executionId`) is already an explicit selection and never folds, so an agent that only ever runs as a subagent still lists under `agentId`. Each row carries `origin` (dashboard | api | internal | null), read from the caller's authenticated principal, and `test` as its derived alias for `origin === "dashboard"`; any entrance that resolves a principal stamps origin, including the Runtype MCP server tools and Code Mode (`api`) and the hosted `/v1/mcp` proxy (`internal`). A lane with no principal answers null for both by design: schedule, webhook, messaging, A2A, an agent exposed as an MCP surface, subagent, nested flow, a client-token product surface, an ingested run, and any row whose header predates the field. `overlay=live` adds live control-plane fields; the overlay never adds, drops or reorders a row. Returns 404 with `code: "run_history_unavailable"` when neither plane can serve the page, which a client renders as "no run history here" rather than as a failed read.
          */
         get: {
             parameters: {
@@ -40082,6 +40099,8 @@ interface paths {
                     parentExecutionId?: string;
                     /** @description Runs in this execution tree. */
                     rootExecutionId?: string;
+                    /** @description true restores the flat enumeration on the UNSCOPED feed, in which a subagent run and a nested-flow run list beside their parent. The unscoped feed is roots only by default: a row whose parentExecutionId is set folds under its parent and is read with parentExecutionId=<executionId>. Any filter that scopes to a resource — agentId, flowId, conversationId, surfaceId, recordId, batchExecutionId, parentExecutionId, rootExecutionId or executionId — is already an explicit selection and never folds, so an agent that only ever runs as a subagent still lists under agentId. This parameter changes nothing on a scoped request. */
+                    includeChildren?: "true" | "false";
                     /** @description Read specific runs by id; at most 100 per request. */
                     executionId?: string | string[];
                     /** @description Filter by producing lane. */
@@ -50955,6 +50974,8 @@ interface components {
             budgetExhausted?: boolean | null;
             /** @description Cancel request. Absent means the overlay did not answer, which is not false and not null. */
             cancelRequestedAt?: string | null;
+            /** @description How many runs name this one as their parent. The unscoped feed returns roots only, so this is the size of the fold underneath a row; read the children with parentExecutionId=<executionId>. It is populated on a resource-scoped page too, where nothing is folded, so a surface can still offer the same expansion. WHICH children are counted depends on the arm that served the row: the span store counts every child, agent and nested-flow alike, while the legacy control-plane fallback counts agent children only, so on that arm a parent whose only child is a nested flow reports 0. That is deliberate — the fallback arm cannot enumerate a nested-flow child either, so counting one would advertise a fold that opens on nothing. It counts only children the CALLER may read: a credential holding one execution family (AGENTS:READ or FLOWS:READ alone) counts the children of that family and no others, so a count never discloses a run the same credential could not list. NULL means the arm cannot count children at all, which is not zero. */
+            childCount: number | null;
             /**
              * @description Storage completeness; null on a row the control-plane arm served.
              * @enum {string|null}
@@ -50992,7 +51013,7 @@ interface components {
             /** @description Last heartbeat. Absent means the overlay did not answer, which is not false and not null. */
             lastHeartbeatAt?: string | null;
             /**
-             * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field: dashboard for a Clerk session, api for a management API key, internal for a Runtype worker. NULL means the header states nothing about it, which is not "unknown caller": headers written before this field shipped, lanes that never see an auth principal, and every backfilled row carry no origin stamp.
+             * @description Where the run was dispatched from, taken from the caller's authenticated principal and never from a request field. ANY entrance that resolves a principal stamps it: a Clerk session answers dashboard; a management API key answers api, which includes the Runtype MCP server's tools and Code Mode, since both reach dispatch with a management key; and Runtype's own internal caller answers internal, for example the hosted /v1/mcp proxy. A lane that resolves NO principal carries NULL BY DESIGN: schedule, webhook, messaging, A2A, an agent exposed AS an MCP surface, subagent, nested flow, a client-token product surface (an end user is none of the three origins) and an ingested OTLP run. So NULL says "no authenticated principal at this entrance" rather than "unknown caller". The one NULL that is not a statement about the lane is a row whose header predates the field or came from the backfill: it stamps nothing even for a run that did resolve a principal.
              * @enum {string|null}
              */
             origin: "dashboard" | "api" | "internal" | null;
@@ -57927,6 +57948,18 @@ interface RunListRow {
     parentExecutionId: string | null;
     parentToolCallId: string | null;
     rootExecutionId: string | null;
+    /**
+     * How many runs name this one as their parent. The unscoped feed returns
+     * roots only, so this is the size of the fold underneath a row; read the
+     * children with `parentExecutionId`. It is populated on a resource-scoped
+     * page too. The span store counts agent and nested-flow children alike; the
+     * legacy control-plane fallback counts agent children only, so a
+     * nested-flow-only parent reports 0 there — that arm cannot enumerate such a
+     * child either. It counts only children the caller may read, so a
+     * single-family credential never learns the other family's children exist.
+     * NULL when the serving arm cannot count at all.
+     */
+    childCount: number | null;
     source: 'hosted' | 'ingested';
     fidelityTier: string | null;
     completeness: 'partial' | 'complete' | 'conflicted' | 'expired' | 'deleted' | null;
@@ -57938,8 +57971,9 @@ interface RunListRow {
     selfReportedCost: string | null;
     /**
      * Where the run was dispatched from, taken from the caller's authenticated
-     * principal and never from a request field. NULL means the header states
-     * nothing about it: a lane that sees no principal, or a backfilled row.
+     * principal and never from a request field. Any entrance that resolves a
+     * principal stamps it (MCP tools and Code Mode answer `api`, the hosted
+     * `/v1/mcp` proxy `internal`); a lane with none carries NULL by design.
      */
     origin: 'dashboard' | 'api' | 'internal' | null;
     /**
@@ -57996,6 +58030,13 @@ interface RunListParams {
     parentExecutionId?: string;
     rootExecutionId?: string;
     executionId?: string | string[];
+    /**
+     * `'true'` restores the flat enumeration on the unscoped feed, which is roots
+     * only by default: a subagent or nested-flow run folds under its parent. Any
+     * resource-scoped filter is already an explicit selection and never folds, so
+     * this changes nothing there.
+     */
+    includeChildren?: 'true' | 'false';
     source?: 'hosted' | 'ingested';
     /**
      * `running`, `completed` or `failed` only. `queued`, `awaiting` and
@@ -59430,6 +59471,14 @@ interface ClientTokenConfig {
     theme?: ClientWidgetTheme;
     /** Custom data passed to flows */
     customData?: Record<string, unknown>;
+    /**
+     * Durable-turn opt-in for a token with no product surface. A surface-bound
+     * token reads the surface's `behavior.durableTurns` instead and ignores this.
+     */
+    durableTurns?: {
+        /** Defaults to false when absent. */
+        enabled?: boolean;
+    };
 }
 /**
  * Client token data returned from the API

package/dist/index.mjs

@@ -13934,7 +13934,7 @@ function transformQueryParams(params) {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "10.1.4".length > 0 ? "10.1.4" : FALLBACK_VERSION;
+var SDK_VERSION = "10.2.0".length > 0 ? "10.2.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/sdk",
-  "version": "10.1.4",
+  "version": "10.2.0",
   "type": "module",
   "description": "TypeScript SDK for the Runtype API with fluent methods. Use it to quickly realize AI products, agents, and workflows.",
   "main": "dist/index.cjs",
@@ -24,7 +24,7 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@runtypelabs/shared": "3.58.1",
+    "@runtypelabs/shared": "3.59.0",
     "openapi-typescript": "^7.13.0",
     "tsup": "^8.0.2",
     "typescript": "^6.0.3",