@namzu/sdk 3.3.0 → 5.0.0

package/src/types/common/index.ts

@@ -10,6 +10,19 @@ export interface TokenUsage {
 	totalTokens: number
 	cachedTokens: number
 	cacheWriteTokens: number
+
+	/**
+	 * Output tokens the model spent on internal reasoning.
+	 *
+	 * A SUBSET of `completionTokens`, not an addition to it — reasoning is
+	 * billed as output, so adding these to a total would double-count. Present
+	 * so a caller can see what share of a turn went to thinking, which is the
+	 * question budgeting and cost attribution actually ask.
+	 *
+	 * Optional because most drivers do not report it. Absent means unknown,
+	 * not zero.
+	 */
+	reasoningTokens?: number
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -19,6 +32,13 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		totalTokens: current.totalTokens + addition.totalTokens,
 		cachedTokens: current.cachedTokens + addition.cachedTokens,
 		cacheWriteTokens: current.cacheWriteTokens + addition.cacheWriteTokens,
+		// Summed only when at least one side reported it. Coercing absent to
+		// zero would turn 'this driver does not tell us' into 'it spent none',
+		// and a run mixing a reporting driver with a silent one would read as
+		// though the silent turns did no thinking.
+		...(current.reasoningTokens !== undefined || addition.reasoningTokens !== undefined
+			? { reasoningTokens: (current.reasoningTokens ?? 0) + (addition.reasoningTokens ?? 0) }
+			: {}),
 	}
 }
 

package/src/types/provider/chat.ts

@@ -76,19 +76,75 @@ export interface ChatCompletionParams {
 	 * Drivers that do not support it ignore the field.
 	 */
 	thinking?: ThinkingConfig
+
+	/**
+	 * How much work to put into the response. See {@link ReasoningEffort}.
+	 *
+	 * Drivers that do not support it ignore the field.
+	 */
+	effort?: ReasoningEffort
 }
 
 export interface ThinkingConfig {
-	type: 'enabled' | 'disabled'
-	/** Token allowance for the thinking pass. */
+	/**
+	 * Which thinking mode to ask for.
+	 *
+	 * `'adaptive'` lets the model decide whether and how deeply to think per
+	 * request; depth is steered by {@link ChatCompletionParams.effort} rather
+	 * than a token budget. `'enabled'` is the older manual mode, where
+	 * {@link budgetTokens} fixes the depth and the model thinks on every
+	 * request.
+	 *
+	 * **These are not interchangeable, and a driver must not guess.** Vendors
+	 * reject the wrong one for a given model outright rather than degrading:
+	 * newer models refuse `'enabled'`, older ones refuse `'adaptive'`, and
+	 * some refuse `'disabled'` because they cannot stop thinking at all. A
+	 * driver that sends a mode the model does not accept produces a failed
+	 * request, not a worse answer — which is why this is a declared intent
+	 * that each driver resolves against the model it is about to call.
+	 */
+	type: 'adaptive' | 'enabled' | 'disabled'
+
+	/**
+	 * Token allowance for the thinking pass. Manual mode only — the adaptive
+	 * mode has no budget, and depth is set by `effort`.
+	 */
 	budgetTokens?: number
+
 	/**
-	 * Whether the provider should return full thinking text or a summary.
-	 * Purely a request hint; the runtime stores whatever comes back.
+	 * Whether the thinking text comes back or only its signature.
+	 *
+	 * `'omitted'` returns the blocks with an empty body and a signature, which
+	 * is enough to replay them on the next turn (see `replayReasoning`) while
+	 * keeping the text out of the response. `'summarized'` returns a summary
+	 * of the reasoning.
+	 *
+	 * Worth setting explicitly. This defaults to `'omitted'` on newer models,
+	 * so a caller that wants to show reasoning and does not ask for it gets
+	 * thinking blocks whose text is empty and no indication why.
+	 *
+	 * The values were `'full' | 'summarized'` here, and `'full'` was never a
+	 * value any vendor accepted — a declared option that could only ever have
+	 * been rejected, next to a real one that was missing.
 	 */
-	display?: 'full' | 'summarized'
+	display?: 'summarized' | 'omitted'
 }
 
+/**
+ * How much work the model should put into a response.
+ *
+ * A sibling of {@link ChatCompletionParams.thinking}, not a field inside it,
+ * because it is not exclusively a thinking control: it shapes the whole
+ * response, and at least one manual-mode model accepts it alongside a token
+ * budget, where effort shapes the answer and the budget sets thinking depth.
+ * Nesting it under `thinking` would have made that combination unsayable.
+ *
+ * In adaptive mode it is the primary depth lever — low effort may skip
+ * thinking entirely on easy input. In manual mode `budgetTokens` sets depth
+ * and effort does not move it.
+ */
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+
 export interface ChatCompletionResponse {
 	id: string
 	model: string

package/src/types/provider/index.ts

@@ -4,6 +4,7 @@ export type {
 	CacheControl,
 	ChatCompletionParams,
 	ChatCompletionResponse,
+	ReasoningEffort,
 	ThinkingConfig,
 } from './chat.js'
 export type { StreamChunk } from './stream.js'

package/src/types/sandbox/index.ts

@@ -110,6 +110,16 @@ export interface SandboxExecOptions {
 	 * Without it a Stop (or a per-tool deadline) could only ever abandon
 	 * the *wait* — the sandboxed process kept running after the host
 	 * believed the run had been cancelled.
+	 *
+	 * **Who honours it.** The in-process local sandbox does: the signal is
+	 * merged with the call's own deadline and reaches `spawn`, so the child
+	 * dies. The remote backends do not, and deliberately: their wire has no
+	 * cancel op, so aborting the request would abandon the wait and leave the
+	 * command running — the failure above, wearing the appearance of a fix.
+	 * They will honour it when their protocols carry a cancel.
+	 *
+	 * Passing it is therefore always safe and never harmful; whether it takes
+	 * effect depends on the backend.
 	 */
 	readonly signal?: AbortSignal
 }

package/src/types/toolset/index.ts

@@ -1,23 +1,5 @@
 import type { LLMToolSchema, ToolDefinition, ToolPermission } from '../tool/index.js'
 
-/**
- * @deprecated Slated for removal in the next major. Nothing produces or
- * reads it — no code constructs any member, and `ToolsetPolicy.surfaces`,
- * the only field that carries it, is never consulted.
- *
- * It is also the wrong axis. Which tools a run may use is already
- * expressible four ways, all of them per-run and dynamic where this is
- * fixed at definition: `allowedTools` on the query, `ToolAvailability`
- * (`active` / `deferred` / `suspended`) with mid-run activation,
- * `runtimeToolOverrides`, and capability negotiation stripping tools a
- * driver cannot carry. Prefer `allowedTools`.
- *
- * The member names encode deployment shapes this kernel does not own,
- * which is the deeper reason not to keep them: a host's surfaces are the
- * host's to name.
- */
-export type ToolCatalogSurface = 'chat' | 'supervised' | 'managed-agent' | 'worker' | 'code'
-
 export type ToolSourceKind =
 	| 'host_tool'
 	| 'provider_builtin'
@@ -57,13 +39,6 @@ export interface ToolsetPolicy {
 	readonly enabled?: boolean
 	readonly loading?: ToolLoadingMode
 	readonly preferred?: boolean
-	/**
-	 * @deprecated Slated for removal in the next major. Never read by
-	 * anything — setting it has no effect today. Use `allowedTools` on the
-	 * query to bound which tools a run may use; it says the same thing per
-	 * run instead of per definition. See {@link ToolCatalogSurface}.
-	 */
-	readonly surfaces?: readonly ToolCatalogSurface[]
 	readonly providerConfig?: Record<string, unknown>
 }