@namzu/sdk 62.3.0 → 62.5.0

package/src/runtime/query/path-escalation.ts

@@ -7,6 +7,9 @@
  * - does it write a protected path (a git hook, a shell rc file, editor or
  *   tool configuration, the project's `.namzu` directory)?
  * - does its shell line remove something catastrophic?
+ * - does its call create or delete a top-level entry of the home folder or the
+ *   filesystem root (see `authorization/top-level-entries.ts`)? It is reported
+ *   as a protected path: the same question, asked the same way.
  * - does its shell line reach a path outside the turn's roots, through a
  *   command whose operands are paths or through a redirection?
  *
@@ -22,6 +25,10 @@ import { isProtectedPath } from '../../authorization/protected-paths.js'
 import { dangerousRemoval } from '../../authorization/removal.js'
 import type { ShellDialect } from '../../authorization/shell-lexer.js'
 import { readShellLine, shellPathAccess } from '../../authorization/shell-paths.js'
+import {
+	topLevelEntriesOfMovers,
+	topLevelEntryChange,
+} from '../../authorization/top-level-entries.js'
 import { canonicalize, pathOutsideRoots } from '../../tools/paths.js'
 
 /** What the escalation records carry. */
@@ -38,6 +45,12 @@ export interface PathEscalationContext {
 	readonly cwd?: string
 	/** Whether to report paths outside the roots (`outsideRootAccess: 'review'`, no sandbox). */
 	readonly reviewOutside: boolean
+	/**
+	 * Whether to report a top-level entry of the home folder or the filesystem
+	 * root the line would create or delete. Like `reviewOutside`, off in a sandbox,
+	 * where the paths are the guest's.
+	 */
+	readonly topLevel?: boolean
 }
 
 /**
@@ -137,11 +150,13 @@ function beforeGlob(path: string): string {
 export async function declaredWriteEscalation(
 	roots: readonly string[],
 	value: string,
+	topLevel = false,
 ): Promise<string | undefined> {
 	const [first] = roots
 	if (first === undefined || value === '') return undefined
 	const absolute = resolve(resolve(first), value)
-	return (await isProtectedWrite(value, absolute, roots)) ? absolute : undefined
+	if (await isProtectedWrite(value, absolute, roots)) return absolute
+	return topLevel ? topLevelEntryChange(absolute, 'write', homedir()) : undefined
 }
 
 /** What a shell line reaches. */
@@ -190,6 +205,15 @@ export async function shellEscalations(
 					for (const candidate of absolutes) {
 						if (await isProtectedWrite(spelled, candidate, context.roots))
 							protectedPaths.add(candidate)
+						else if (
+							context.topLevel === true &&
+							'path' in settled &&
+							(!use.unresolved || /^\$(?:\{HOME\}|HOME)\//.test(spelled)) &&
+							use.via !== 'mv'
+						) {
+							const entry = topLevelEntryChange(candidate, use.via, home)
+							if (entry !== undefined) protectedPaths.add(entry)
+						}
 					}
 				}
 				if (!context.reviewOutside) continue
@@ -224,6 +248,14 @@ export async function shellEscalations(
 			}
 		}
 	}
+	if (context.topLevel === true) {
+		for (const entry of topLevelEntriesOfMovers(reading, {
+			home,
+			cwd,
+			changesDirectory: access.changesDirectory,
+		}))
+			protectedPaths.add(entry)
+	}
 	const removalAt = (directory: string | undefined) =>
 		directory === undefined
 			? undefined

package/src/runtime/query/prepare-turn.ts

@@ -332,8 +332,13 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	const promptCache = params.promptCache
 	const taskScheduler = params.taskScheduler
 	const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(params.turnConfig.streamIdleTimeoutMs)
-	const maxRequestRichContentBytes = resolveMaxRequestRichContentBytes(
+	// Validated here, at the door, but only the caller's own override is kept on
+	// the turn: the provider's declaration is read where it is used (see
+	// `IterationOrchestrator.richContentBudget`), so it follows the provider
+	// that serves the turn rather than being pinned by the first one.
+	resolveMaxRequestRichContentBytes(
 		params.turnConfig.maxRequestRichContentBytes,
+		params.provider.capabilities?.maxRequestRichContentBytes,
 	)
 	const sandboxTeardownTimeoutMs = resolveSandboxTeardownTimeoutMs(params.sandboxTeardownTimeoutMs)
 	// Persist the EFFECTIVE value, not only an override. A turn replayed after a
@@ -343,7 +348,6 @@ export async function prepareTurn(params: QueryParams): Promise<PreparedTurn> {
 	const turnConfig: TurnConfig = {
 		...params.turnConfig,
 		streamIdleTimeoutMs,
-		maxRequestRichContentBytes,
 	}
 
 	// The turn's one correlated logger, built before anything below needs

package/src/runtime/query/request-rich-content.ts

@@ -12,8 +12,17 @@ export const DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES = 24 * 1024 * 1024
 
 const MAX_REQUEST_RICH_CONTENT_BYTES = Number.MAX_SAFE_INTEGER
 
-export function resolveMaxRequestRichContentBytes(value: number | undefined): number {
-	const resolved = value ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES
+/**
+ * The budget for one turn: the caller's `turnConfig.maxRequestRichContentBytes`
+ * when set, else the one the provider declares for its own wire limit
+ * (`ProviderCapabilities.maxRequestRichContentBytes`), else the kernel default.
+ * The override always wins, so a host can tighten or loosen what a driver declares.
+ */
+export function resolveMaxRequestRichContentBytes(
+	value: number | undefined,
+	providerDeclared?: number,
+): number {
+	const resolved = value ?? providerDeclared ?? DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES
 	if (
 		!Number.isSafeInteger(resolved) ||
 		resolved < 0 ||

package/src/runtime/query/review-policy.ts

@@ -293,7 +293,7 @@ export const UNKNOWN_PROGRAM_UNATTENDED_REFUSAL =
  * existed (a mode, a rule, "approve all") is not an answer about it.
  */
 export const PROTECTED_PATH_UNATTENDED_REFUSAL =
-	"Refused: this call writes a protected path (a git hook or config, a shell startup file, editor or tool configuration, or the project's .namzu directory), which needs a person to approve it each time, and nobody can be asked in this session. This call did not run; the other calls in the batch are not affected. Leave those files alone, or tell the user what change you need so they can make it."
+	"Refused: this call writes a protected path (a git hook or config, a shell startup file, editor or tool configuration, or the project's .namzu directory) or creates or deletes a top-level entry directly in the home folder or the filesystem root, which needs a person to approve it each time, and nobody can be asked in this session. This call did not run; the other calls in the batch are not affected. Work inside a project folder instead (create it first, or use an existing one), or tell the user what change you need so they can make it."
 
 /**
  * What the model is told when a batch removes something catastrophic (the

package/src/turn/index.ts

@@ -23,7 +23,7 @@ export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'
 
 export { SESSION_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
 export type { MemoryPromoterOptions, SessionMemoryCategory } from './memory-promoter.js'
-export { createMemoryRecallStep } from './memory-recall.js'
+export { createMemoryRecallStep, recalledMemoryIds } from './memory-recall.js'
 export type {
 	MemoryRecallOptions,
 	MemorySelection,

package/src/turn/memory-recall.ts

@@ -80,6 +80,12 @@ export interface MemoryRecallOptions {
 	readonly minCoverage?: number
 	/** Upper bound on the selector, in ms; the signal it is given aborts then. Default 2,500. */
 	readonly selectTimeoutMs?: number
+	/**
+	 * Ids recall must not offer, read afresh on every request. A host keeps a
+	 * set-aside list here (records a refused request carried) and lifts it when
+	 * the person restores a record. A throw reads as an empty list.
+	 */
+	readonly excluded?: () => Iterable<string> | Promise<Iterable<string>>
 }
 
 /** What a selector may know about a record: never its body. */
@@ -126,6 +132,27 @@ const OTHERS_PLURAL = (count: number): string =>
 export const RECALLED_MEMORY_ENTRY_KEY = 'memory'
 
 /** The `id@updatedAt` of every record the entries still in the history carry. */
+/**
+ * The ids of the records the `memory` entries carry, in the order they were
+ * recorded and without repeats. `entries` are bodies as `turnContextEntries`
+ * returns them.
+ */
+export function recalledMemoryIds(entries: readonly string[]): string[] {
+	const ids = new Set<string>()
+	for (const entry of entries) {
+		for (const line of entry.split('\n')) {
+			if (!line.startsWith('{')) continue
+			try {
+				const parsed = JSON.parse(line) as { id?: unknown }
+				if (typeof parsed.id === 'string') ids.add(parsed.id)
+			} catch {
+				// a line of the entry that is not a record
+			}
+		}
+	}
+	return [...ids]
+}
+
 function recordedRecords(entries: readonly string[]): Set<string> {
 	const seen = new Set<string>()
 	for (const entry of entries) {
@@ -377,8 +404,12 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 		latestUserMessage,
 		contextBudget,
 		signal,
+		withheldKeys,
 	}) => {
 		signal?.throwIfAborted()
+		// A refused request was re-run without the memories it carried; adding
+		// them again would be refused again.
+		if (withheldKeys?.includes(RECALLED_MEMORY_ENTRY_KEY)) return undefined
 		// Leave room for the current request and response. The kernel supplies
 		// an estimate; using one character per remaining token is deliberately
 		// conservative for this optional text, not a billing/tokenizer claim.
@@ -484,6 +515,14 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 		}
 		const recall = async (): Promise<Recalled> => {
 			const shown: RecalledMemory[] = []
+			let excludedIds: ReadonlySet<string> = new Set()
+			if (options.excluded) {
+				try {
+					excludedIds = new Set(await options.excluded())
+				} catch {
+					// An unreadable list excludes nothing.
+				}
+			}
 			const page = await options.store.list({
 				query: terms.join(' '),
 				status: 'active',
@@ -501,6 +540,7 @@ export function createMemoryRecallStep(options: MemoryRecallOptions): PrepareSte
 			let block = lead
 			const fresh = page.entries
 				.filter((entry) => entry.status === 'active')
+				.filter((entry) => !excludedIds.has(entry.id))
 				.filter((entry) => !known.has(`${entry.id}@${entry.updatedAt}`))
 			const candidates = fresh.slice(0, shortlist)
 			const picks = await choose(candidates)

package/src/types/agent/base.ts

@@ -226,6 +226,8 @@ export interface BaseAgentConfig {
 	 */
 	thinking?: import('../provider/index.js').ThinkingConfig
 	effort?: import('../provider/index.js').ReasoningEffort
+	/** Inference speed; see {@link import('../session/config.js').TurnConfig.speed}. */
+	speed?: import('../provider/index.js').InferenceSpeed
 	/** How the turn bounds its reasoning; see {@link import('../session/config.js').TurnConfig.reasoning}. */
 	reasoning?: import('../session/config.js').TurnConfig['reasoning']
 	/** Ask once for a check of edits before a turn ends; see {@link import('../session/config.js').TurnConfig.completionAudit}. */

package/src/types/agent/query.ts

@@ -100,6 +100,10 @@ export interface QueryAgentConfig extends BaseAgentConfig {
 	maxOutputContinuations?: QueryParams['maxOutputContinuations']
 	/** See {@link QueryParams.refusalFallback}. */
 	refusalFallback?: QueryParams['refusalFallback']
+	/** See {@link QueryParams.withholdOnRefusal}. */
+	withholdOnRefusal?: QueryParams['withholdOnRefusal']
+	/** See {@link QueryParams.withheldKeys}. */
+	withheldKeys?: QueryParams['withheldKeys']
 	maxToolOutputChars?: number
 	maxToolOutputCharsPerMessage?: number
 	retainedToolPreviewChars?: QueryParams['retainedToolPreviewChars']

package/src/types/common/index.ts

@@ -42,6 +42,14 @@ export interface TokenUsage {
 	 * {@link TokenUsage.cacheTtlMs}.
 	 */
 	cacheWriteTtlTokens?: { fiveMin?: number; oneHour?: number }
+
+	/**
+	 * The speed the provider says served this call, when it says. `'fast'` is a
+	 * premium-priced mode, so pricing reads it per call: a per-call fact like
+	 * {@link TokenUsage.cacheTtlMs}, never summed. Absent means standard or
+	 * unreported.
+	 */
+	speed?: import('../provider/chat.js').InferenceSpeed
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -101,6 +109,9 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		...(next.cacheWriteTtlTokens !== undefined || current.cacheWriteTtlTokens !== undefined
 			? { cacheWriteTtlTokens: next.cacheWriteTtlTokens ?? current.cacheWriteTtlTokens }
 			: {}),
+		...(next.speed !== undefined || current.speed !== undefined
+			? { speed: next.speed ?? current.speed }
+			: {}),
 	}
 }
 

package/src/types/hitl/index.ts

@@ -389,7 +389,9 @@ export interface ToolCallEscalation {
 	 * asked; no rule, mode or remembered approval covers it. Set for the file
 	 * tools' declared path and for the visible write targets of a shell line:
 	 * output redirections, and the operands of `cp`, `mv`, `tee`, `touch`,
-	 * `mkdir`, `rm`, `rmdir` and `sed -i`.
+	 * `mkdir`, `rm`, `rmdir` and `sed -i`. A top-level entry of the home folder or
+	 * the filesystem root that the call would create or delete is listed here
+	 * too (when the turn reviews outside paths and runs without a sandbox).
 	 */
 	protectedPaths?: readonly string[]
 	/**

package/src/types/provider/chat.ts

@@ -106,6 +106,15 @@ export interface ChatCompletionParams {
 	 * that narrower set according to their documented provider policy.
 	 */
 	effort?: ReasoningEffort
+
+	/**
+	 * Inference speed. `'fast'` asks a provider for its premium low-latency
+	 * mode, billed at a multiple of the standard rate; absent and `'standard'`
+	 * are the same request. A driver with no such mode, or a model without it,
+	 * must refuse `'fast'` rather than serve it at standard speed and let the
+	 * caller believe it was honoured.
+	 */
+	speed?: InferenceSpeed
 }
 
 export interface ThinkingConfig {
@@ -174,6 +183,9 @@ export interface ThinkingConfig {
  * transport or leave the vendor to refuse an unknown compatible-endpoint
  * extension explicitly.
  */
+/** `'fast'` is a premium low-latency mode; `'standard'` is the ordinary request. See {@link ChatCompletionParams.speed}. */
+export type InferenceSpeed = 'standard' | 'fast'
+
 export type ReasoningEffort =
 	| 'none'
 	| 'minimal'

package/src/types/provider/config.ts

@@ -170,6 +170,14 @@ export interface ProviderCapabilities {
 	 * or the lifetime is the provider's own and cannot be chosen or read).
 	 */
 	cacheTtl?: readonly ('5m' | '1h')[]
+	/**
+	 * The most base64 characters of inline images and documents this provider
+	 * will take in one request, when its wire limit differs from the kernel's
+	 * default (24 MiB). Counts the encoded value, like
+	 * `turnConfig.maxRequestRichContentBytes`, which still overrides it.
+	 * Absent means the kernel default.
+	 */
+	maxRequestRichContentBytes?: number
 }
 
 export interface ProviderFactoryResult {

package/src/types/provider/index.ts

@@ -5,6 +5,7 @@ export type {
 	ChatCompletionParams,
 	ChatCompletionResponse,
 	ProviderRefusal,
+	InferenceSpeed,
 	ReasoningEffort,
 	ThinkingConfig,
 } from './chat.js'

package/src/types/session/config.ts

@@ -69,6 +69,17 @@ export interface TurnConfig {
 	 */
 	effort?: import('../provider/index.js').ReasoningEffort
 
+	/**
+	 * Inference speed for every model call in the turn: `'fast'` asks for the
+	 * provider's premium low-latency mode (billed at a multiple of the standard
+	 * rate), absent and `'standard'` are the ordinary request. Turn-level for
+	 * the same reason as {@link TurnConfig.effort}: speeds do not share a
+	 * prompt-cache prefix, so a value that moves between steps pays for a cache
+	 * miss each time. A driver or model without the mode REFUSES `'fast'`
+	 * rather than serving it slowly.
+	 */
+	speed?: import('../provider/index.js').InferenceSpeed
+
 	/**
 	 * How the turn bounds its reasoning. On by default.
 	 *

package/src/types/session/events.ts

@@ -519,7 +519,14 @@ type CoreSessionEvent =
 			/** The model that declined. */
 			model: string
 			providerId: string
-			outcome: 'fallback' | 'retry' | 'declined'
+			outcome: 'fallback' | 'retry' | 'withheld' | 'declined'
+			/**
+			 * Set only with `outcome: 'withheld'`: the recorded-context keys the
+			 * re-run leaves out of the request (see `QueryParams.withholdOnRefusal`).
+			 */
+			withheldKeys?: string[]
+			/** With `'withheld'`: the ids of the recalled memories those entries carried. */
+			withheldMemoryIds?: string[]
 			/** The model the request moves to. Set only with `outcome: 'fallback'`. */
 			fallbackModel?: string
 			/** The provider's own classification, when it gave one. */

package/src/types/session/prepare-step.ts

@@ -98,6 +98,13 @@ export interface PrepareStepContext {
 	}
 	/** Every completed step, in order. */
 	readonly steps: readonly StepResult[]
+	/**
+	 * Recorded-context keys the request leaves out: set aside by a refused
+	 * request (`QueryParams.withholdOnRefusal`) or by the host
+	 * (`QueryParams.withheldKeys`). A stage that records text under one of
+	 * these keys should add nothing now; whatever it records is also left out.
+	 */
+	readonly withheldKeys?: readonly string[]
 
 	/**
 	 * What the stages before this one decided, when several were supplied.

package/src/utils/cost.ts

@@ -41,6 +41,13 @@ export interface ModelPricing {
 	 * part. The catalogue always supplies this.
 	 */
 	cache?: CacheRates
+	/**
+	 * The vendor's published multiple of every rate on this card for a request
+	 * served in fast mode (`TokenUsage.speed === 'fast'`). Absent means there is
+	 * no published fast price: fast usage is then counted as unpriced, never
+	 * charged at the standard rate, which would under-report it.
+	 */
+	fastMultiplier?: number
 }
 
 export { ZERO_COST }
@@ -54,6 +61,22 @@ interface Priced {
 }
 
 function priceUsage(usage: TokenUsage, pricing: ModelPricing): Priced {
+	if (usage.speed === 'fast') {
+		const multiplier = pricing.fastMultiplier
+		if (multiplier === undefined) {
+			return { cost: 0, cacheDiscount: 0, unpriced: usage.totalTokens }
+		}
+		const standard = priceStandard({ ...usage, speed: undefined }, pricing)
+		return {
+			cost: standard.cost * multiplier,
+			cacheDiscount: standard.cacheDiscount * multiplier,
+			unpriced: standard.unpriced,
+		}
+	}
+	return priceStandard(usage, pricing)
+}
+
+function priceStandard(usage: TokenUsage, pricing: ModelPricing): Priced {
 	const perMillion = (tokens: number, rate: number) => (tokens / 1_000_000) * rate
 
 	const cache = pricing.cache