@runtypelabs/sdk 9.3.0 → 9.3.1

package/dist/index.cjs

@@ -375,10 +375,7 @@ function createFlowEventTranslator() {
             pageOrigin: data.pageOrigin
           })
         ];
-      // Channels/markers/tool-family/approval/skip/source/state/custom/ping the
-      // flow consumer never read → no callback event. (A non-terminal `error` is
-      // only produced on agent streams; dropping it here avoids a false
-      // flow_error.)
+      // WHY(docs/why/packages/client/src.md#default-case-drops-events-the-flow-consumer-neve): Default case drops events the flow consumer never reads; a non-terminal error is agent-only, dropped here.
       default:
         return [];
     }
@@ -550,9 +547,7 @@ function createAgentEventTranslator() {
             toolName: data.toolName,
             success: data.success,
             result: data.result,
-            // A failure's reason travels on the frame's `error` field — the
-            // only carrier for complete-only failures like the MCP discovery
-            // connection pseudo-tool, which no longer emits an `error` frame.
+            // WHY(docs/why/packages/client/src.md#a-failures-reason-travels-on-error-the-only-carr): A failure's reason travels on `error`, the only carrier for complete-only MCP discovery failures.
             error: str(data.error),
             executionTime: data.executionTime
           })
@@ -689,10 +684,7 @@ function createAgentEventTranslator() {
         ];
       case "ping":
         return [compact({ type: "agent_ping", executionId, seq, timestamp: data.timestamp })];
-      // turn/text/reasoning open+close markers, step_*, artifact_*, source,
-      // state_snapshot/state_delta (agent-state channel with no stable SDK
-      // callback), custom (fallback beat / routing), and the skill-fold result
-      // envelope the SDK never consumed → no callback event.
+      // WHY(docs/why/packages/client/src.md#default-case-lists-every-channel-type-the-sdk-ca): Default case lists every channel type the SDK callback surface never consumed, so it maps to nothing.
       default:
         return [];
     }
@@ -1247,9 +1239,6 @@ var FlowBuilder = class {
     );
     return this;
   }
-  // ============================================================================
-  // Step Methods
-  // ============================================================================
   /**
    * Add a prompt step
    */
@@ -1748,9 +1737,6 @@ var FlowBuilder = class {
   memorySummary(config) {
     return this.addRawStep("memory-summary", config);
   }
-  // ============================================================================
-  // Subagent Helpers
-  // ============================================================================
   /**
    * Attach a subagent runtime tool to the most recent prompt step.
    *
@@ -1845,9 +1831,6 @@ var FlowBuilder = class {
     lastStep.config.tools = { ...existingTools, subagentConfig: opts };
     return this;
   }
-  // ============================================================================
-  // Build Method
-  // ============================================================================
   /**
    * Build the final dispatch request configuration
    */
@@ -1938,9 +1921,6 @@ var FlowBuilder = class {
     if (lastStep) lastStep.when = expression;
     return this;
   }
-  // ============================================================================
-  // Private Helpers
-  // ============================================================================
   addRawStep(type, config) {
     const { name, enabled, when, ...stepConfig } = config;
     this.addStep(type, name, stepConfig, enabled, when);
@@ -2144,7 +2124,6 @@ var CHECK_GRADER_KINDS = /* @__PURE__ */ new Set([
   "length",
   "latency",
   "no_error",
-  // Trace checks.
   "called_tool",
   "not_called_tool",
   "used_no_tools",
@@ -2428,7 +2407,8 @@ function normalizeCaseInput(input, where) {
       const mock = { toolName: m.toolName, output: m.output };
       if (m.input !== void 0) mock.input = m.input;
       if (typeof m.isError === "boolean") mock.isError = m.isError;
-      if (typeof m.sourceToolExecutionId === "string") mock.sourceToolExecutionId = m.sourceToolExecutionId;
+      if (typeof m.sourceToolExecutionId === "string")
+        mock.sourceToolExecutionId = m.sourceToolExecutionId;
       if (typeof m.truncated === "boolean") mock.truncated = m.truncated;
       return mock;
     });
@@ -2533,7 +2513,7 @@ async function computeEvalContentHash(definition) {
       name: c.name,
       input: normalizeForHash(c.input),
       ...c.expected !== void 0 ? { expected: normalizeForHash(c.expected) } : {},
-      // Grader order preserved on purpose (it maps to the result index).
+      // INVARIANT: Grader order is preserved on purpose; it maps to the result index.
       expect: c.expect.map((g) => normalizeForHash(g))
     }))
   };
@@ -2739,8 +2719,7 @@ function defineFlow(input) {
     return {
       type: step.type,
       name: step.name,
-      // Explicit 1-based order (the flow builder's convention) so the local
-      // probe hash agrees with the server's persisted step order.
+      // WHY(docs/why/packages/client/src.md#explicit-1-based-order-matches-the-flow-builders): Explicit 1-based order matches the flow builder's convention so the local hash agrees with the server
       order: typeof step.order === "number" ? step.order : index + 1,
       ...step.enabled !== void 0 ? { enabled: step.enabled } : {},
       ...typeof step.when === "string" ? { when: step.when } : {},
@@ -3042,9 +3021,6 @@ var RuntypeFlowBuilder = class {
       this.flowConfig = { name: "Untitled Flow" };
     }
   }
-  // ============================================================================
-  // Configuration Methods
-  // ============================================================================
   /**
    * Set the record configuration
    */
@@ -3088,9 +3064,6 @@ var RuntypeFlowBuilder = class {
     );
     return this;
   }
-  // ============================================================================
-  // Step Methods
-  // ============================================================================
   /**
    * Add a prompt step
    */
@@ -3874,9 +3847,6 @@ var RuntypeFlowBuilder = class {
       "Use Runtype.flows.virtual(...) or Runtype.flows.upsert(...) with inline steps to validate a flow before saving."
     );
   }
-  // ============================================================================
-  // Private Helpers
-  // ============================================================================
   /**
    * Persisted flow protocol (APQ-style): send hash-only first, retry with
    * full definition on FLOW_DEFINITION_REQUIRED. For non-upsert modes,
@@ -6239,9 +6209,6 @@ var RuntypeClient = class {
   }
 };
 var Runtype = class {
-  // ============================================================================
-  // Global Configuration
-  // ============================================================================
   /**
    * Configure the global Runtype client
    *
@@ -6279,9 +6246,6 @@ var Runtype = class {
   static createClient(config) {
     return new RuntypeClient({ ...globalConfig, ...config });
   }
-  // ============================================================================
-  // Static Namespaces
-  // ============================================================================
   /**
    * Flows namespace - Build and execute flows
    *
@@ -6523,7 +6487,7 @@ var Runtype = class {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "9.3.0".length > 0 ? "9.3.0" : FALLBACK_VERSION;
+var SDK_VERSION = "9.3.1".length > 0 ? "9.3.1" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 
@@ -6617,8 +6581,7 @@ function withDetachedReconnect(response, reattach, options = {}) {
           if (cancelled) break;
           current = await reattach({
             executionId: observed.executionId,
-            // `'0'` replays the whole turn — the fail-open answer for a leg
-            // that produced no cursor at all.
+            // WHY(docs/why/packages/client/src.md#0-replays-the-whole-turn-the-fail-open-answer-fo): '0' replays the whole turn, the fail-open answer for a leg that produced no cursor.
             after: observed.lastId ?? "0",
             signal: abort.signal
           });
@@ -6939,11 +6902,7 @@ function attachRuntimeToolsToDispatchRequest(request6, runtimeTools, options = {
     ...request6,
     flow: {
       ...flow,
-      // `clonedSteps` is a structural clone of `request.flow.steps` (already
-      // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
-      // merged, so every step's `type` discriminant is preserved. The clone is
-      // intentionally built as loose records to merge tool config opaquely, so
-      // re-narrow to the typed step shape at this boundary.
+      // WHY(docs/why/packages/client/src.md#clonedsteps-preserves-each-steps-type-discrimina): clonedSteps preserves each step's type discriminant; re-narrow from loose records here
       steps: clonedSteps
     }
   };
@@ -8207,13 +8166,7 @@ function ensureDefaultWorkflowHooks() {
 }
 var defaultWorkflowConfig = {
   name: "default",
-  // Empty-session escalation. The counter only counts tool actions, so
-  // narration-only sessions ("I'll create the files now" with no tool calls)
-  // escalate here even though the phase recovery conditions keyed on
-  // hadTextOutput skip them: nudge after the first actionless session, signal
-  // model escalation after the second (a no-op unless the caller configured a
-  // fallback model), and stop as 'stalled' after the third — the same total
-  // session budget as before stallPolicy existed.
+  // WHY(docs/why/packages/client/src/workflows.md#empty-session-escalation-preserves-legacy-behavi): empty-session escalation preserves legacy behavior: nudge, then escalate, then stall after three
   stallPolicy: { nudgeAfter: 1, escalateModelAfter: 2, stopAfter: 3 },
   classifyVariant: "builtin:classify-task-variant",
   bootstrap: "builtin:repo-bootstrap-discovery",
@@ -8241,16 +8194,14 @@ var defaultWorkflowConfig = {
       transitionSummary: "builtin:planning-transition-summary",
       recovery: "builtin:planning-recovery",
       forceEndTurn: "builtin:planning-force-end-turn"
-      // canAcceptCompletion intentionally absent: the hand-written planning
-      // phase never defined it, and the SDK accepts completion when the slot
-      // is undefined. Keep parity.
+      // WHY(docs/why/packages/client/src/workflows.md#canacceptcompletion-is-intentionally-absent-for): canAcceptCompletion is intentionally absent for planning to keep parity with the hand-written phase
     },
     {
       name: "execution",
       description: "Execute the plan by editing target files",
       instructions: "builtin:execution-instructions",
       toolGuidance: "builtin:execution-tool-guidance",
-      // Execution never auto-advances; completion is agent-driven via TASK_COMPLETE
+      // WHY(needs-review): execution never auto-advances; completion is agent-driven via TASK_COMPLETE
       completionCriteria: { type: "never" },
       intercept: "builtin:execution-guard",
       recovery: "builtin:execution-recovery",
@@ -8420,11 +8371,11 @@ var deployWorkflow = {
   name: "deploy",
   phases: [scaffoldPhase, deployPhase],
   classifyVariant: classifyVariant2,
-  // No bootstrap context needed — we're not searching the repo
+  // WHY(needs-review): no bootstrap context needed; this workflow doesn't search the repo
   async generateBootstrapContext() {
     return void 0;
   },
-  // No candidate block — we're not editing repo files
+  // WHY(needs-review): no candidate block; this workflow doesn't edit repo files
   buildCandidateBlock() {
     return "";
   }
@@ -9795,9 +9746,7 @@ var ClientTokensEndpoint = class {
     if (params?.limit !== void 0) {
       return {
         clientTokens: response.clientTokens,
-        // The API always includes pagination when limit is supplied; the
-        // fallback mirrors the server's own envelope math so the paged
-        // overload stays total against older API deployments.
+        // WHY(docs/why/packages/client/src.md#the-fallback-mirrors-the-servers-own-envelope-ma): The fallback mirrors the server's own envelope math so paging stays correct against older API deployments.
         pagination: response.pagination ?? {
           limit: params.limit,
           offset: params.offset ?? 0,
@@ -10549,8 +10498,7 @@ var _AgentsEndpoint = class _AgentsEndpoint {
             iterations: 1,
             stopReason: "end_turn",
             completedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            // Carry the spend observed so far so the interrupted session's
-            // cost still lands in marathon totals and budget accounting
+            // WHY(docs/why/packages/client/src.md#carries-accumulated-spend-so-an-interrupted-sess): Carries accumulated spend so an interrupted session's cost still lands in totals
             totalCost: lastKnownCost,
             ...lastKnownTokens ? { totalTokens: lastKnownTokens } : {},
             finalOutput: [
@@ -10604,7 +10552,6 @@ var _AgentsEndpoint = class _AgentsEndpoint {
       return null;
     }
   }
-  // ─── Long-Task Agent Execution ───────────────────────────────────────
   createEmptyToolTrace() {
     return {
       entries: [],
@@ -13379,12 +13326,7 @@ var RuntypeClient2 = class {
     this.timeout = config.timeout === void 0 ? 3e4 : config.timeout;
     this.headers = {
       "Content-Type": "application/json",
-      // Advertise client identity + version so the API can attribute SDK traffic
-      // (see detectActorSource in apps/api/src/lib/audit-log.ts). Defaults come
-      // first so callers that wrap this client with their own attribution — the
-      // CLI sends `X-Runtype-Client: cli` + `runtype-cli/<v>` — override them.
-      // `User-Agent` is a forbidden header in browsers and is silently dropped
-      // there; `X-Runtype-Client` is the reliable cross-environment signal.
+      // WHY(docs/why/packages/client/src.md#user-agent-is-a-forbidden-header-in-browsers-and): User-Agent is a forbidden header in browsers and is silently dropped; X-Runtype-Client is the reliable
       "X-Runtype-Client": RUNTYPE_CLIENT_KIND,
       "User-Agent": SDK_USER_AGENT,
       ...config.headers || {}
@@ -13445,8 +13387,7 @@ var RuntypeClient2 = class {
       {
         dispatch: (config) => this.dispatch.executeStream(config),
         runWithLocalTools: (config, tools, callbacks, opts) => this.runWithLocalTools(config, tools, callbacks, opts),
-        // Validation capability for ClientFlowBuilder.validate() — reuses the
-        // client's JSON POST transport (zero new HTTP plumbing).
+        // WHY(docs/why/packages/client/src.md#clientflowbuilder-validate-reuses-the-clients-js): ClientFlowBuilder.validate() reuses the client's JSON POST transport instead of new HTTP plumbing.
         post: (path, data) => this.post(path, data)
       },
       name
@@ -13700,8 +13641,7 @@ var RuntypeClient2 = class {
     const response = await this.makeRequest(url, {
       method: "POST",
       headers,
-      // TS 5.7 types Uint8Array over ArrayBufferLike, which no longer
-      // overlaps DOM BodyInit; the runtime value is a valid fetch body.
+      // WORKAROUND(docs/why/packages/client/src.md#ts-5-7-types-uint8array-over-arraybufferlike-whi): TS 5.7 types Uint8Array over ArrayBufferLike, which no longer overlaps DOM BodyInit, though the
       body
     });
     return transformResponse(response);