@kindgi/client 0.1.4-rc.4 → 0.1.4

package/README.md

@@ -72,7 +72,7 @@ try {
 
 ## Exports
 
-- **`createClient(options: ClientOptions)`** — returns a `KindgiClient` with one resource client per property (see [Resources](#resources)). `ClientOptions`: `apiUrl` (no trailing slash), `auth` (`{ kind: 'apiToken', token }` or `{ kind: 'oauth', accessToken, refresh? }`), and an optional `fetch`. Creating a client opens no connections.
+- **`createClient(options: ClientOptions)`** — returns a `KindgiClient` with one resource client per property (see [Resources](#resources)). `ClientOptions`: `apiUrl` (no trailing slash), `auth` (`{ kind: 'apiToken', token }` or `{ kind: 'oauth', accessToken, refresh? }`), an optional `fetch`, and an optional `timeoutMs` (below). Creating a client opens no connections.
 - **Errors** — every method throws **`KindgiApiError`**, whose `error` is a **`KindgiError`** discriminated on `code`: `network`, `auth`, `rate-limited`, `not-found`, `conflict`, `invalid-request`, `guardrail-violation`, `server`, `not-implemented-in-preview`, `not-yet-wired`. **`fromWire(body)`** maps an API error (`{ code, message, details? }`) onto that union; wire codes it does not recognize become `server`, with the original code in `serverCode`. **`notYetWired`** and **`notImplementedInPreview`** build the two preview variants.
 - **Streaming** — **`readSse`** and **`unwrapSseData`** read a `text/event-stream` response as an `AsyncIterable`, reconnecting with exponential backoff and `Last-Event-Id`. `runs.stream`, `evalRuns.events`, `adapters.prepare` and the `secrets` rotation event stream are built on them.
 - **Types** — the input, filter, page and record types of every resource; branded ids and `Filter` / `Page` re-exported from [`@kindgi/types`](../../packages/types/); `DefineAgentSpec` and `RunStatus`.
@@ -80,6 +80,8 @@ try {
 
 The transport makes one attempt per call and does not retry. Mutating calls accept an `idempotencyKey`, sent as the `Idempotency-Key` header, so a caller's own retries are safe (see [`docs/API-ROUTE-CONVENTIONS.md`](../../docs/API-ROUTE-CONVENTIONS.md)).
 
+**Timeouts.** One request may take `timeoutMs` (30 000 ms unless `ClientOptions.timeoutMs` says otherwise); then it fails with a `network` error whose `timeoutMs` is set. Streams aren't bound by it. A waited `runs.start` answers only when the run ends, so it's bound by it too, and takes its own `timeoutMs`. When the timeout runs out there, the run may still be going and its id never arrived. Start a run that can take longer with `options: { wait: false }`, whose answer carries the run's id at once, and follow it with `runs.stream(runId)`.
+
 ## JSDoc tags
 
 - `@wire` — the method or type mirrors a route or schema in the API's `openapi.json`.

package/dist/index.cjs

@@ -2894,7 +2894,157 @@ function subscribeToRun(options) {
   });
 }
 
+// src/transport.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MUTATING = /* @__PURE__ */ new Set([
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE"
+]);
+function createTransport(options) {
+  const apiUrl = options.apiUrl.replace(/\/+$/u, "");
+  const fetchImpl = options.fetch ?? fetch;
+  const clientTimeoutMs = checkedTimeoutMs(
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    "ClientOptions.timeoutMs"
+  );
+  return {
+    apiUrl,
+    fetchImpl,
+    authHeaders() {
+      return { Authorization: `Bearer ${authTokenFor(options.auth)}` };
+    },
+    async request(input) {
+      const url = buildUrl(apiUrl, input.path, input.query);
+      const headers = buildHeaders(input, options.auth);
+      const timeoutMs = input.timeoutMs === void 0 ? clientTimeoutMs : checkedTimeoutMs(input.timeoutMs, "timeoutMs");
+      const ac = new AbortController();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        ac.abort(new Error("timeout"));
+      }, timeoutMs);
+      let response;
+      try {
+        response = await fetchImpl(url, {
+          method: input.method,
+          headers,
+          ...input.body !== void 0 && { body: JSON.stringify(input.body) },
+          signal: ac.signal
+        });
+      } catch (cause) {
+        clearTimeout(timer);
+        const err = timedOut ? {
+          code: "network",
+          message: `No answer within ${seconds(timeoutMs)}, the client's timeout (timeoutMs).`,
+          cause,
+          timeoutMs
+        } : {
+          code: "network",
+          message: cause instanceof Error ? cause.message : "network request failed",
+          cause
+        };
+        throw new KindgiApiError(err);
+      }
+      clearTimeout(timer);
+      if (response.ok) {
+        if (input.discardResponse === true || response.status === 204) {
+          try {
+            await response.arrayBuffer();
+          } catch {
+          }
+          return void 0;
+        }
+        try {
+          return await response.json();
+        } catch (cause) {
+          const err = {
+            code: "network",
+            message: "Response body was not valid JSON",
+            cause
+          };
+          throw new KindgiApiError(err);
+        }
+      }
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = void 0;
+      }
+      throw new KindgiApiError(
+        fromWire(unwrapErrorEnvelope(body, response.status), response.status)
+      );
+    }
+  };
+}
+function checkedTimeoutMs(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive number of milliseconds. Got ${String(value)}.`);
+  }
+  return value;
+}
+function seconds(ms) {
+  return `${ms / 1e3} s`;
+}
+function buildUrl(apiUrl, path, query) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const base = `${apiUrl}${normalizedPath}`;
+  if (query === void 0) return base;
+  const params = [];
+  for (const key of Object.keys(query)) {
+    const value = query[key];
+    if (value === void 0) continue;
+    const values = typeof value === "object" ? value : [String(value)];
+    for (const v of values) params.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+  }
+  return params.length === 0 ? base : `${base}?${params.join("&")}`;
+}
+function buildHeaders(input, auth) {
+  const headers = {
+    Accept: "application/json",
+    Authorization: `Bearer ${authTokenFor(auth)}`
+  };
+  if (input.body !== void 0) {
+    headers["Content-Type"] = "application/json; charset=utf-8";
+  }
+  if (input.idempotencyKey !== void 0 && MUTATING.has(input.method)) {
+    headers["Idempotency-Key"] = input.idempotencyKey;
+  }
+  if (input.headers !== void 0) {
+    for (const key of Object.keys(input.headers)) {
+      headers[key] = input.headers[key];
+    }
+  }
+  return headers;
+}
+function authTokenFor(auth) {
+  if (auth.kind === "apiToken") return auth.token;
+  return auth.accessToken;
+}
+function unwrapErrorEnvelope(body, status) {
+  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+    const inner = body.error;
+    if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
+      return inner;
+    }
+  }
+  return { code: "unknown", message: `HTTP ${status} without recognizable error envelope` };
+}
+
 // src/resources/runs.ts
+function waitedStartTimeout(e) {
+  if (!(e instanceof KindgiApiError) || e.error.code !== "network") return e;
+  const { timeoutMs } = e.error;
+  if (timeoutMs === void 0) return e;
+  return new KindgiApiError({
+    code: "network",
+    message: `The run didn't end within ${seconds(timeoutMs)}, the client's timeout (timeoutMs). A waited start answers only when the run ends, so the run may still be going, and its id didn't arrive. Start a run that can take longer with \`options: { wait: false }\`: the answer carries its id at once. Then follow it with \`runs.stream(runId)\` or \`runs.get(runId)\`. Or raise \`timeoutMs\`.`,
+    cause: e.error.cause,
+    timeoutMs
+  });
+}
 function makeRunsClient(transport) {
   return {
     async start(input) {
@@ -2913,14 +3063,19 @@ function makeRunsClient(transport) {
         input: input.input,
         ...input.options !== void 0 && { options: input.options }
       };
-      return transport.request({
-        method: "POST",
-        path: "/v1/runs",
-        body,
-        ...input.idempotencyKey !== void 0 && {
-          idempotencyKey: input.idempotencyKey
-        }
-      });
+      try {
+        return await transport.request({
+          method: "POST",
+          path: "/v1/runs",
+          body,
+          ...input.idempotencyKey !== void 0 && {
+            idempotencyKey: input.idempotencyKey
+          },
+          ...input.timeoutMs !== void 0 && { timeoutMs: input.timeoutMs }
+        });
+      } catch (e) {
+        throw input.options?.wait === false ? e : waitedStartTimeout(e);
+      }
     },
     async dryRun(_input) {
       throw new KindgiApiError(
@@ -4050,127 +4205,6 @@ function makeWebhooksClient(transport) {
   };
 }
 
-// src/transport.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
-var MUTATING = /* @__PURE__ */ new Set([
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE"
-]);
-function createTransport(options) {
-  const apiUrl = options.apiUrl.replace(/\/+$/u, "");
-  const fetchImpl = options.fetch ?? fetch;
-  const clientTimeoutMs = DEFAULT_TIMEOUT_MS;
-  return {
-    apiUrl,
-    fetchImpl,
-    authHeaders() {
-      return { Authorization: `Bearer ${authTokenFor(options.auth)}` };
-    },
-    async request(input) {
-      const url = buildUrl(apiUrl, input.path, input.query);
-      const headers = buildHeaders(input, options.auth);
-      const timeoutMs = input.timeoutMs ?? clientTimeoutMs;
-      const ac = new AbortController();
-      const timer = setTimeout(
-        () => ac.abort(new Error("timeout")),
-        timeoutMs
-      );
-      let response;
-      try {
-        response = await fetchImpl(url, {
-          method: input.method,
-          headers,
-          ...input.body !== void 0 && { body: JSON.stringify(input.body) },
-          signal: ac.signal
-        });
-      } catch (cause) {
-        clearTimeout(timer);
-        const err = {
-          code: "network",
-          message: cause instanceof Error ? cause.message : "network request failed",
-          cause
-        };
-        throw new KindgiApiError(err);
-      }
-      clearTimeout(timer);
-      if (response.ok) {
-        if (input.discardResponse === true || response.status === 204) {
-          try {
-            await response.arrayBuffer();
-          } catch {
-          }
-          return void 0;
-        }
-        try {
-          return await response.json();
-        } catch (cause) {
-          const err = {
-            code: "network",
-            message: "Response body was not valid JSON",
-            cause
-          };
-          throw new KindgiApiError(err);
-        }
-      }
-      let body;
-      try {
-        body = await response.json();
-      } catch {
-        body = void 0;
-      }
-      throw new KindgiApiError(
-        fromWire(unwrapErrorEnvelope(body, response.status), response.status)
-      );
-    }
-  };
-}
-function buildUrl(apiUrl, path, query) {
-  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  const base = `${apiUrl}${normalizedPath}`;
-  if (query === void 0) return base;
-  const params = [];
-  for (const key of Object.keys(query)) {
-    const value = query[key];
-    if (value === void 0) continue;
-    const values = typeof value === "object" ? value : [String(value)];
-    for (const v of values) params.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
-  }
-  return params.length === 0 ? base : `${base}?${params.join("&")}`;
-}
-function buildHeaders(input, auth) {
-  const headers = {
-    Accept: "application/json",
-    Authorization: `Bearer ${authTokenFor(auth)}`
-  };
-  if (input.body !== void 0) {
-    headers["Content-Type"] = "application/json; charset=utf-8";
-  }
-  if (input.idempotencyKey !== void 0 && MUTATING.has(input.method)) {
-    headers["Idempotency-Key"] = input.idempotencyKey;
-  }
-  if (input.headers !== void 0) {
-    for (const key of Object.keys(input.headers)) {
-      headers[key] = input.headers[key];
-    }
-  }
-  return headers;
-}
-function authTokenFor(auth) {
-  if (auth.kind === "apiToken") return auth.token;
-  return auth.accessToken;
-}
-function unwrapErrorEnvelope(body, status) {
-  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
-    const inner = body.error;
-    if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
-      return inner;
-    }
-  }
-  return { code: "unknown", message: `HTTP ${status} without recognizable error envelope` };
-}
-
 // src/client.ts
 function createClient(options) {
   const transport = createTransport(options);

package/dist/index.d.cts

@@ -1775,7 +1775,9 @@ export interface DefineAgentSpec {
 	 * Required capabilities the agent needs from a `ModelProvider`.
 	 * Typically one entry: `[{ needs: [{ feature: 'tool-use' }] }]`
 	 * for a tool-calling agent, `[{ needs: [{ feature: 'structured-output' }] }]`
-	 * for an agent that returns schema-constrained JSON. The router uses
+	 * for an agent that should run on a model that can follow a JSON schema
+	 * natively (its typed `output` is still checked by parse and repair, on
+	 * every model). The router uses
 	 * the first entry to pick a compatible provider from the tenant's
 	 * `ProviderRegistry`.
 	 */
@@ -3997,6 +3999,12 @@ export interface ClientOptions {
 	readonly auth: AuthConfig;
 	/** Overridable fetch impl for testing. Defaults to global `fetch`. */
 	readonly fetch?: typeof fetch;
+	/**
+	 * How long one request may take, in milliseconds, before it fails with
+	 * a `network` error. Default 30 000. Streams (`runs.stream` and the
+	 * like) aren't bound by it. `runs.start` also takes its own.
+	 */
+	readonly timeoutMs?: number;
 }
 /** The verdict of a judgment. */
 export type Verdict = "yes" | "no";
@@ -4675,6 +4683,10 @@ declare namespace Schemas {
 		 * The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.
 		 */
 		segments?: Array<ScopeSegment>;
+		/**
+		 * The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.
+		 */
+		traceId?: string;
 		/**
 		 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 		 */
@@ -4805,6 +4817,10 @@ declare namespace Schemas {
 			 * The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.
 			 */
 			segments?: Array<ScopeSegment>;
+			/**
+			 * The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.
+			 */
+			traceId?: string;
 			/**
 			 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 			 */
@@ -6901,6 +6917,19 @@ declare namespace Schemas {
 		nextCursor?: string;
 		hasMore: boolean;
 	};
+	/**
+	 * How the model thinks before it answers, so a call that wants as little as it allows (a judge's) gets it. Absent: it doesn't think, or nothing is known.
+	 */
+	export type ModelThinking = {
+		/**
+		 * `adaptive`: on unless turned down. `always`: on, and it can only be lowered.
+		 */
+		mode: "adaptive" | "always";
+		/**
+		 * The vendor's own setting for the least thinking: for Anthropic `disabled`, `between_tools` or an effort (`low`); for Gemini a thinking level (`low`, `minimal`); for OpenAI a reasoning effort (`low`, `none`).
+		 */
+		lowest: string;
+	};
 	/**
 	 * USD per 1K tokens. An adapter may take more rate fields (see the adapter's README).
 	 */
@@ -6930,6 +6959,11 @@ declare namespace Schemas {
 		 * Fallback cap on output tokens. Adapters that require `max_tokens` on every request (e.g. Anthropic) use this when `ModelCallInput.maxOutputTokens` is unset.
 		 */
 		maxOutputTokens?: number;
+		/**
+		 * Whether the model takes sampling settings (`temperature`). `false`: its API rejects a non-default value, so the call goes without one and the answer's `warnings` say so (`sampling-unsupported`). Absent: it takes them.
+		 */
+		sampling?: boolean;
+		thinking?: ModelThinking;
 		/**
 		 * Short per-model description surfaced in logs.
 		 */
@@ -6945,6 +6979,10 @@ declare namespace Schemas {
 		 * Models this connection exposes. Non-empty. `models[i].name` must be unique within the list.
 		 */
 		models: Array<ModelInfo>;
+		/**
+		 * The model to use when an agent doesn't choose: one of `models[].name`. When candidates rank equally, it comes before the provider's other models; without it, ties break by model name. A preset sets it. A runtime before 0.1.4 ignores it.
+		 */
+		defaultModel?: string;
 		/**
 		 * Soft attributes for preference-ranking (`local`, `lower-cost`, `higher-accuracy`, ...). Matched by string equality against `Preference.feature`.
 		 */
@@ -10083,8 +10121,17 @@ declare const ProviderMetadata: z.ZodObject<{
 		}, z.core.$catchall<z.ZodUnknown>>;
 		p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 		maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+		sampling: z.ZodOptional<z.ZodBoolean>;
+		thinking: z.ZodOptional<z.ZodObject<{
+			mode: z.ZodEnum<{
+				always: "always";
+				adaptive: "adaptive";
+			}>;
+			lowest: z.ZodString;
+		}, z.core.$strict>>;
 		description: z.ZodOptional<z.ZodString>;
 	}, z.core.$strict>>;
+	defaultModel: z.ZodOptional<z.ZodString>;
 	attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 	description: z.ZodOptional<z.ZodString>;
 	capabilityKind: z.ZodOptional<z.ZodString>;
@@ -10120,8 +10167,17 @@ declare const ProviderCollectionPage: z.ZodObject<{
 			}, z.core.$catchall<z.ZodUnknown>>;
 			p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 			maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+			sampling: z.ZodOptional<z.ZodBoolean>;
+			thinking: z.ZodOptional<z.ZodObject<{
+				mode: z.ZodEnum<{
+					always: "always";
+					adaptive: "adaptive";
+				}>;
+				lowest: z.ZodString;
+			}, z.core.$strict>>;
 			description: z.ZodOptional<z.ZodString>;
 		}, z.core.$strict>>;
+		defaultModel: z.ZodOptional<z.ZodString>;
 		attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 		description: z.ZodOptional<z.ZodString>;
 		capabilityKind: z.ZodOptional<z.ZodString>;
@@ -10160,8 +10216,17 @@ declare const RegisterProviderBody: z.ZodObject<{
 			}, z.core.$catchall<z.ZodUnknown>>;
 			p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 			maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+			sampling: z.ZodOptional<z.ZodBoolean>;
+			thinking: z.ZodOptional<z.ZodObject<{
+				mode: z.ZodEnum<{
+					always: "always";
+					adaptive: "adaptive";
+				}>;
+				lowest: z.ZodString;
+			}, z.core.$strict>>;
 			description: z.ZodOptional<z.ZodString>;
 		}, z.core.$strict>>;
+		defaultModel: z.ZodOptional<z.ZodString>;
 		attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 		description: z.ZodOptional<z.ZodString>;
 		capabilityKind: z.ZodOptional<z.ZodString>;
@@ -14688,6 +14753,11 @@ export interface RunsClient {
 	 * with `options.wait: false` as soon as it exists (202) — poll
 	 * `get(runId)` until it finishes.
 	 *
+	 * A waited start is bound by the client's timeout (`timeoutMs`, 30 s by
+	 * default; this call can set its own). When it runs out, the run may
+	 * still be going and its id never arrived: the `network` error says so.
+	 * Start a run that can take longer with `options.wait: false`.
+	 *
 	 * `idempotencyKey` makes retries safe: two calls with the same key
 	 * within the server's retention window return the same `Run`.
 	 *
@@ -14852,6 +14922,13 @@ export type StartRunInput = {
 	readonly input: unknown;
 	readonly options?: StartRunOptions;
 	readonly idempotencyKey?: string;
+	/**
+	 * How long to wait for the answer, in milliseconds: this call's
+	 * `ClientOptions.timeoutMs`. A waited start answers only when the run
+	 * ends, so a run that can take longer is better started with
+	 * `options: { wait: false }` and followed.
+	 */
+	readonly timeoutMs?: number;
 } | {
 	readonly flow: FlowId | string;
 	readonly flowVersion?: string;
@@ -14862,6 +14939,13 @@ export type StartRunInput = {
 	readonly input: unknown;
 	readonly options?: StartRunOptions;
 	readonly idempotencyKey?: string;
+	/**
+	 * How long to wait for the answer, in milliseconds: this call's
+	 * `ClientOptions.timeoutMs`. A waited start answers only when the run
+	 * ends, so a run that can take longer is better started with
+	 * `options: { wait: false }` and followed.
+	 */
+	readonly timeoutMs?: number;
 };
 export interface StartRunOptions {
 	/** Run with side-effects mocked; the row is marked `dryRun: true`. */
@@ -14929,6 +15013,12 @@ export interface Run {
 	readonly agent?: RunAgent;
 	/** The segment path the run was started with; a child run has its parent's. */
 	readonly segments?: readonly ScopeSegment[];
+	/**
+	 * The W3C trace id of the request that started the run (yours, when you
+	 * sent a `traceparent`). Absent for a run no request started, and from
+	 * an older runtime.
+	 */
+	readonly traceId?: string;
 }
 /**
  * What `runs.start` returns: the run, plus a public run token when the
@@ -16040,6 +16130,8 @@ export interface NetworkError {
 	readonly code: "network";
 	readonly message: string;
 	readonly cause?: unknown;
+	/** Set when the client's own timeout ended the request: that timeout, in milliseconds. */
+	readonly timeoutMs?: number;
 }
 export interface AuthError {
 	readonly code: "auth";

package/dist/index.d.ts

@@ -1775,7 +1775,9 @@ export interface DefineAgentSpec {
 	 * Required capabilities the agent needs from a `ModelProvider`.
 	 * Typically one entry: `[{ needs: [{ feature: 'tool-use' }] }]`
 	 * for a tool-calling agent, `[{ needs: [{ feature: 'structured-output' }] }]`
-	 * for an agent that returns schema-constrained JSON. The router uses
+	 * for an agent that should run on a model that can follow a JSON schema
+	 * natively (its typed `output` is still checked by parse and repair, on
+	 * every model). The router uses
 	 * the first entry to pick a compatible provider from the tenant's
 	 * `ProviderRegistry`.
 	 */
@@ -3997,6 +3999,12 @@ export interface ClientOptions {
 	readonly auth: AuthConfig;
 	/** Overridable fetch impl for testing. Defaults to global `fetch`. */
 	readonly fetch?: typeof fetch;
+	/**
+	 * How long one request may take, in milliseconds, before it fails with
+	 * a `network` error. Default 30 000. Streams (`runs.stream` and the
+	 * like) aren't bound by it. `runs.start` also takes its own.
+	 */
+	readonly timeoutMs?: number;
 }
 /** The verdict of a judgment. */
 export type Verdict = "yes" | "no";
@@ -4675,6 +4683,10 @@ declare namespace Schemas {
 		 * The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.
 		 */
 		segments?: Array<ScopeSegment>;
+		/**
+		 * The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.
+		 */
+		traceId?: string;
 		/**
 		 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 		 */
@@ -4805,6 +4817,10 @@ declare namespace Schemas {
 			 * The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.
 			 */
 			segments?: Array<ScopeSegment>;
+			/**
+			 * The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.
+			 */
+			traceId?: string;
 			/**
 			 * Only in the response to `POST /v1/runs`, when the deployment issues public run tokens: a read-only token for this run (and its descendants) to hand to a browser, for `GET /v1/runs/{runId}/progress` and its stream.
 			 */
@@ -6901,6 +6917,19 @@ declare namespace Schemas {
 		nextCursor?: string;
 		hasMore: boolean;
 	};
+	/**
+	 * How the model thinks before it answers, so a call that wants as little as it allows (a judge's) gets it. Absent: it doesn't think, or nothing is known.
+	 */
+	export type ModelThinking = {
+		/**
+		 * `adaptive`: on unless turned down. `always`: on, and it can only be lowered.
+		 */
+		mode: "adaptive" | "always";
+		/**
+		 * The vendor's own setting for the least thinking: for Anthropic `disabled`, `between_tools` or an effort (`low`); for Gemini a thinking level (`low`, `minimal`); for OpenAI a reasoning effort (`low`, `none`).
+		 */
+		lowest: string;
+	};
 	/**
 	 * USD per 1K tokens. An adapter may take more rate fields (see the adapter's README).
 	 */
@@ -6930,6 +6959,11 @@ declare namespace Schemas {
 		 * Fallback cap on output tokens. Adapters that require `max_tokens` on every request (e.g. Anthropic) use this when `ModelCallInput.maxOutputTokens` is unset.
 		 */
 		maxOutputTokens?: number;
+		/**
+		 * Whether the model takes sampling settings (`temperature`). `false`: its API rejects a non-default value, so the call goes without one and the answer's `warnings` say so (`sampling-unsupported`). Absent: it takes them.
+		 */
+		sampling?: boolean;
+		thinking?: ModelThinking;
 		/**
 		 * Short per-model description surfaced in logs.
 		 */
@@ -6945,6 +6979,10 @@ declare namespace Schemas {
 		 * Models this connection exposes. Non-empty. `models[i].name` must be unique within the list.
 		 */
 		models: Array<ModelInfo>;
+		/**
+		 * The model to use when an agent doesn't choose: one of `models[].name`. When candidates rank equally, it comes before the provider's other models; without it, ties break by model name. A preset sets it. A runtime before 0.1.4 ignores it.
+		 */
+		defaultModel?: string;
 		/**
 		 * Soft attributes for preference-ranking (`local`, `lower-cost`, `higher-accuracy`, ...). Matched by string equality against `Preference.feature`.
 		 */
@@ -10083,8 +10121,17 @@ declare const ProviderMetadata: z.ZodObject<{
 		}, z.core.$catchall<z.ZodUnknown>>;
 		p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 		maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+		sampling: z.ZodOptional<z.ZodBoolean>;
+		thinking: z.ZodOptional<z.ZodObject<{
+			mode: z.ZodEnum<{
+				always: "always";
+				adaptive: "adaptive";
+			}>;
+			lowest: z.ZodString;
+		}, z.core.$strict>>;
 		description: z.ZodOptional<z.ZodString>;
 	}, z.core.$strict>>;
+	defaultModel: z.ZodOptional<z.ZodString>;
 	attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 	description: z.ZodOptional<z.ZodString>;
 	capabilityKind: z.ZodOptional<z.ZodString>;
@@ -10120,8 +10167,17 @@ declare const ProviderCollectionPage: z.ZodObject<{
 			}, z.core.$catchall<z.ZodUnknown>>;
 			p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 			maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+			sampling: z.ZodOptional<z.ZodBoolean>;
+			thinking: z.ZodOptional<z.ZodObject<{
+				mode: z.ZodEnum<{
+					always: "always";
+					adaptive: "adaptive";
+				}>;
+				lowest: z.ZodString;
+			}, z.core.$strict>>;
 			description: z.ZodOptional<z.ZodString>;
 		}, z.core.$strict>>;
+		defaultModel: z.ZodOptional<z.ZodString>;
 		attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 		description: z.ZodOptional<z.ZodString>;
 		capabilityKind: z.ZodOptional<z.ZodString>;
@@ -10160,8 +10216,17 @@ declare const RegisterProviderBody: z.ZodObject<{
 			}, z.core.$catchall<z.ZodUnknown>>;
 			p95LatencyMs: z.ZodOptional<z.ZodNumber>;
 			maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+			sampling: z.ZodOptional<z.ZodBoolean>;
+			thinking: z.ZodOptional<z.ZodObject<{
+				mode: z.ZodEnum<{
+					always: "always";
+					adaptive: "adaptive";
+				}>;
+				lowest: z.ZodString;
+			}, z.core.$strict>>;
 			description: z.ZodOptional<z.ZodString>;
 		}, z.core.$strict>>;
+		defaultModel: z.ZodOptional<z.ZodString>;
 		attributes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 		description: z.ZodOptional<z.ZodString>;
 		capabilityKind: z.ZodOptional<z.ZodString>;
@@ -14688,6 +14753,11 @@ export interface RunsClient {
 	 * with `options.wait: false` as soon as it exists (202) — poll
 	 * `get(runId)` until it finishes.
 	 *
+	 * A waited start is bound by the client's timeout (`timeoutMs`, 30 s by
+	 * default; this call can set its own). When it runs out, the run may
+	 * still be going and its id never arrived: the `network` error says so.
+	 * Start a run that can take longer with `options.wait: false`.
+	 *
 	 * `idempotencyKey` makes retries safe: two calls with the same key
 	 * within the server's retention window return the same `Run`.
 	 *
@@ -14852,6 +14922,13 @@ export type StartRunInput = {
 	readonly input: unknown;
 	readonly options?: StartRunOptions;
 	readonly idempotencyKey?: string;
+	/**
+	 * How long to wait for the answer, in milliseconds: this call's
+	 * `ClientOptions.timeoutMs`. A waited start answers only when the run
+	 * ends, so a run that can take longer is better started with
+	 * `options: { wait: false }` and followed.
+	 */
+	readonly timeoutMs?: number;
 } | {
 	readonly flow: FlowId | string;
 	readonly flowVersion?: string;
@@ -14862,6 +14939,13 @@ export type StartRunInput = {
 	readonly input: unknown;
 	readonly options?: StartRunOptions;
 	readonly idempotencyKey?: string;
+	/**
+	 * How long to wait for the answer, in milliseconds: this call's
+	 * `ClientOptions.timeoutMs`. A waited start answers only when the run
+	 * ends, so a run that can take longer is better started with
+	 * `options: { wait: false }` and followed.
+	 */
+	readonly timeoutMs?: number;
 };
 export interface StartRunOptions {
 	/** Run with side-effects mocked; the row is marked `dryRun: true`. */
@@ -14929,6 +15013,12 @@ export interface Run {
 	readonly agent?: RunAgent;
 	/** The segment path the run was started with; a child run has its parent's. */
 	readonly segments?: readonly ScopeSegment[];
+	/**
+	 * The W3C trace id of the request that started the run (yours, when you
+	 * sent a `traceparent`). Absent for a run no request started, and from
+	 * an older runtime.
+	 */
+	readonly traceId?: string;
 }
 /**
  * What `runs.start` returns: the run, plus a public run token when the
@@ -16040,6 +16130,8 @@ export interface NetworkError {
 	readonly code: "network";
 	readonly message: string;
 	readonly cause?: unknown;
+	/** Set when the client's own timeout ended the request: that timeout, in milliseconds. */
+	readonly timeoutMs?: number;
 }
 export interface AuthError {
 	readonly code: "auth";

package/dist/index.js

@@ -2892,7 +2892,157 @@ function subscribeToRun(options) {
   });
 }
 
+// src/transport.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var MUTATING = /* @__PURE__ */ new Set([
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE"
+]);
+function createTransport(options) {
+  const apiUrl = options.apiUrl.replace(/\/+$/u, "");
+  const fetchImpl = options.fetch ?? fetch;
+  const clientTimeoutMs = checkedTimeoutMs(
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    "ClientOptions.timeoutMs"
+  );
+  return {
+    apiUrl,
+    fetchImpl,
+    authHeaders() {
+      return { Authorization: `Bearer ${authTokenFor(options.auth)}` };
+    },
+    async request(input) {
+      const url = buildUrl(apiUrl, input.path, input.query);
+      const headers = buildHeaders(input, options.auth);
+      const timeoutMs = input.timeoutMs === void 0 ? clientTimeoutMs : checkedTimeoutMs(input.timeoutMs, "timeoutMs");
+      const ac = new AbortController();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        ac.abort(new Error("timeout"));
+      }, timeoutMs);
+      let response;
+      try {
+        response = await fetchImpl(url, {
+          method: input.method,
+          headers,
+          ...input.body !== void 0 && { body: JSON.stringify(input.body) },
+          signal: ac.signal
+        });
+      } catch (cause) {
+        clearTimeout(timer);
+        const err = timedOut ? {
+          code: "network",
+          message: `No answer within ${seconds(timeoutMs)}, the client's timeout (timeoutMs).`,
+          cause,
+          timeoutMs
+        } : {
+          code: "network",
+          message: cause instanceof Error ? cause.message : "network request failed",
+          cause
+        };
+        throw new KindgiApiError(err);
+      }
+      clearTimeout(timer);
+      if (response.ok) {
+        if (input.discardResponse === true || response.status === 204) {
+          try {
+            await response.arrayBuffer();
+          } catch {
+          }
+          return void 0;
+        }
+        try {
+          return await response.json();
+        } catch (cause) {
+          const err = {
+            code: "network",
+            message: "Response body was not valid JSON",
+            cause
+          };
+          throw new KindgiApiError(err);
+        }
+      }
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = void 0;
+      }
+      throw new KindgiApiError(
+        fromWire(unwrapErrorEnvelope(body, response.status), response.status)
+      );
+    }
+  };
+}
+function checkedTimeoutMs(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive number of milliseconds. Got ${String(value)}.`);
+  }
+  return value;
+}
+function seconds(ms) {
+  return `${ms / 1e3} s`;
+}
+function buildUrl(apiUrl, path, query) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const base = `${apiUrl}${normalizedPath}`;
+  if (query === void 0) return base;
+  const params = [];
+  for (const key of Object.keys(query)) {
+    const value = query[key];
+    if (value === void 0) continue;
+    const values = typeof value === "object" ? value : [String(value)];
+    for (const v of values) params.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
+  }
+  return params.length === 0 ? base : `${base}?${params.join("&")}`;
+}
+function buildHeaders(input, auth) {
+  const headers = {
+    Accept: "application/json",
+    Authorization: `Bearer ${authTokenFor(auth)}`
+  };
+  if (input.body !== void 0) {
+    headers["Content-Type"] = "application/json; charset=utf-8";
+  }
+  if (input.idempotencyKey !== void 0 && MUTATING.has(input.method)) {
+    headers["Idempotency-Key"] = input.idempotencyKey;
+  }
+  if (input.headers !== void 0) {
+    for (const key of Object.keys(input.headers)) {
+      headers[key] = input.headers[key];
+    }
+  }
+  return headers;
+}
+function authTokenFor(auth) {
+  if (auth.kind === "apiToken") return auth.token;
+  return auth.accessToken;
+}
+function unwrapErrorEnvelope(body, status) {
+  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+    const inner = body.error;
+    if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
+      return inner;
+    }
+  }
+  return { code: "unknown", message: `HTTP ${status} without recognizable error envelope` };
+}
+
 // src/resources/runs.ts
+function waitedStartTimeout(e) {
+  if (!(e instanceof KindgiApiError) || e.error.code !== "network") return e;
+  const { timeoutMs } = e.error;
+  if (timeoutMs === void 0) return e;
+  return new KindgiApiError({
+    code: "network",
+    message: `The run didn't end within ${seconds(timeoutMs)}, the client's timeout (timeoutMs). A waited start answers only when the run ends, so the run may still be going, and its id didn't arrive. Start a run that can take longer with \`options: { wait: false }\`: the answer carries its id at once. Then follow it with \`runs.stream(runId)\` or \`runs.get(runId)\`. Or raise \`timeoutMs\`.`,
+    cause: e.error.cause,
+    timeoutMs
+  });
+}
 function makeRunsClient(transport) {
   return {
     async start(input) {
@@ -2911,14 +3061,19 @@ function makeRunsClient(transport) {
         input: input.input,
         ...input.options !== void 0 && { options: input.options }
       };
-      return transport.request({
-        method: "POST",
-        path: "/v1/runs",
-        body,
-        ...input.idempotencyKey !== void 0 && {
-          idempotencyKey: input.idempotencyKey
-        }
-      });
+      try {
+        return await transport.request({
+          method: "POST",
+          path: "/v1/runs",
+          body,
+          ...input.idempotencyKey !== void 0 && {
+            idempotencyKey: input.idempotencyKey
+          },
+          ...input.timeoutMs !== void 0 && { timeoutMs: input.timeoutMs }
+        });
+      } catch (e) {
+        throw input.options?.wait === false ? e : waitedStartTimeout(e);
+      }
     },
     async dryRun(_input) {
       throw new KindgiApiError(
@@ -4048,127 +4203,6 @@ function makeWebhooksClient(transport) {
   };
 }
 
-// src/transport.ts
-var DEFAULT_TIMEOUT_MS = 3e4;
-var MUTATING = /* @__PURE__ */ new Set([
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE"
-]);
-function createTransport(options) {
-  const apiUrl = options.apiUrl.replace(/\/+$/u, "");
-  const fetchImpl = options.fetch ?? fetch;
-  const clientTimeoutMs = DEFAULT_TIMEOUT_MS;
-  return {
-    apiUrl,
-    fetchImpl,
-    authHeaders() {
-      return { Authorization: `Bearer ${authTokenFor(options.auth)}` };
-    },
-    async request(input) {
-      const url = buildUrl(apiUrl, input.path, input.query);
-      const headers = buildHeaders(input, options.auth);
-      const timeoutMs = input.timeoutMs ?? clientTimeoutMs;
-      const ac = new AbortController();
-      const timer = setTimeout(
-        () => ac.abort(new Error("timeout")),
-        timeoutMs
-      );
-      let response;
-      try {
-        response = await fetchImpl(url, {
-          method: input.method,
-          headers,
-          ...input.body !== void 0 && { body: JSON.stringify(input.body) },
-          signal: ac.signal
-        });
-      } catch (cause) {
-        clearTimeout(timer);
-        const err = {
-          code: "network",
-          message: cause instanceof Error ? cause.message : "network request failed",
-          cause
-        };
-        throw new KindgiApiError(err);
-      }
-      clearTimeout(timer);
-      if (response.ok) {
-        if (input.discardResponse === true || response.status === 204) {
-          try {
-            await response.arrayBuffer();
-          } catch {
-          }
-          return void 0;
-        }
-        try {
-          return await response.json();
-        } catch (cause) {
-          const err = {
-            code: "network",
-            message: "Response body was not valid JSON",
-            cause
-          };
-          throw new KindgiApiError(err);
-        }
-      }
-      let body;
-      try {
-        body = await response.json();
-      } catch {
-        body = void 0;
-      }
-      throw new KindgiApiError(
-        fromWire(unwrapErrorEnvelope(body, response.status), response.status)
-      );
-    }
-  };
-}
-function buildUrl(apiUrl, path, query) {
-  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  const base = `${apiUrl}${normalizedPath}`;
-  if (query === void 0) return base;
-  const params = [];
-  for (const key of Object.keys(query)) {
-    const value = query[key];
-    if (value === void 0) continue;
-    const values = typeof value === "object" ? value : [String(value)];
-    for (const v of values) params.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
-  }
-  return params.length === 0 ? base : `${base}?${params.join("&")}`;
-}
-function buildHeaders(input, auth) {
-  const headers = {
-    Accept: "application/json",
-    Authorization: `Bearer ${authTokenFor(auth)}`
-  };
-  if (input.body !== void 0) {
-    headers["Content-Type"] = "application/json; charset=utf-8";
-  }
-  if (input.idempotencyKey !== void 0 && MUTATING.has(input.method)) {
-    headers["Idempotency-Key"] = input.idempotencyKey;
-  }
-  if (input.headers !== void 0) {
-    for (const key of Object.keys(input.headers)) {
-      headers[key] = input.headers[key];
-    }
-  }
-  return headers;
-}
-function authTokenFor(auth) {
-  if (auth.kind === "apiToken") return auth.token;
-  return auth.accessToken;
-}
-function unwrapErrorEnvelope(body, status) {
-  if (body !== null && typeof body === "object" && !Array.isArray(body)) {
-    const inner = body.error;
-    if (inner !== null && typeof inner === "object" && !Array.isArray(inner)) {
-      return inner;
-    }
-  }
-  return { code: "unknown", message: `HTTP ${status} without recognizable error envelope` };
-}
-
 // src/client.ts
 function createClient(options) {
   const transport = createTransport(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/client",
-  "version": "0.1.4-rc.4",
+  "version": "0.1.4",
   "description": "TypeScript client SDK for Kindgi™ — the sovereign AI OS. Preview: wire-generated from openapi.json via typed-openapi, ergonomic hand-authored resource clients (Transport, KindgiApiError, SSE with Last-Event-Id resume).",
   "license": "Apache-2.0",
   "repository": {
@@ -45,12 +45,12 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@kindgi/agents": "0.1.4-rc.4",
-    "@kindgi/api": "0.1.4-rc.4",
-    "@kindgi/flow": "0.1.4-rc.4",
-    "@kindgi/platform": "0.1.4-rc.4",
-    "@kindgi/runtime": "0.1.4-rc.4",
-    "@kindgi/types": "0.1.4-rc.4",
+    "@kindgi/agents": "0.1.4",
+    "@kindgi/api": "0.1.4",
+    "@kindgi/flow": "0.1.4",
+    "@kindgi/platform": "0.1.4",
+    "@kindgi/runtime": "0.1.4",
+    "@kindgi/types": "0.1.4",
     "@types/node": "^22.10.5",
     "dts-bundle-generator": "^9.5.1",
     "tsup": "^8.5.1",