@namzu/sdk 62.5.0 → 62.6.1

package/src/sandbox/glob-segment.ts

@@ -0,0 +1,285 @@
+/**
+ * Compiles one path segment of a glob (no `/` in it) to the regular expression
+ * the file walk tests names with, in the same dialect the sandbox guest runs.
+ * It covers `*`, `?`, `[...]` classes (with `!`/`^` negation, ranges and POSIX
+ * classes), the five extglob forms and `\` escapes. A segment with no magic in
+ * it comes back as the plain name to compare against.
+ */
+
+// Written for the `u` flag, which every compiled expression carries.
+const POSIX_CLASSES: Record<string, string> = {
+	alnum: '\\p{L}\\p{Nl}\\p{Nd}',
+	alpha: '\\p{L}\\p{Nl}',
+	ascii: '\\x00-\\x7f',
+	blank: '\\p{Zs}\\t',
+	cntrl: '\\p{Cc}',
+	digit: '\\p{Nd}',
+	graph: '\\x21-\\x7e',
+	lower: '\\p{Ll}',
+	print: '\\x20-\\x7e',
+	punct: '\\p{P}\\p{S}',
+	space: '\\s',
+	upper: '\\p{Lu}',
+	word: '\\p{L}\\p{Nl}\\p{Nd}_',
+	xdigit: '0-9a-fA-F',
+}
+
+export interface CompiledSegment {
+	/** Set when the segment has no magic: the exact name it matches. */
+	literal: string | null
+	/** Source of an expression anchored with `^` and `$`, for a segment with magic. */
+	source: string
+}
+
+/**
+ * Raised for a segment that repeats a group (`*( )` or `+( )`) which could match
+ * the same text more than one way. Such a group backtracks exponentially on a
+ * name that nearly matches, and glob patterns come from untrusted input.
+ */
+export class GlobTooComplexError extends Error {
+	readonly segment: string
+	constructor(segment: string, reason: 'ambiguous' | 'stretch' = 'ambiguous') {
+		super(
+			reason === 'stretch'
+				? `The pattern '${segment}' has more than three wildcards that can stretch; split it across folders or use fewer *.`
+				: `The pattern '${segment}' repeats a group that can match the same text more than one way; use ** or {a,b} instead.`,
+		)
+		this.name = 'GlobTooComplexError'
+		this.segment = segment
+	}
+}
+
+const escapeRegex = (text: string) => text.replace(/[\\^$.*+?()[\]{}|/]/g, '\\$&')
+const escapeInClass = (text: string) => text.replace(/[\\^\]\[/-]/g, '\\$&')
+
+interface Parsed {
+	source: string
+	literal: string
+	magic: boolean
+	/** Unbounded runs: each `*` (consecutive ones collapsed), `*( )` and `+( )`. */
+	runs: number
+}
+
+/** Index of the `)` closing the group opened just before `from`, or -1. */
+function closeGroup(text: string, from: number): number {
+	let depth = 1
+	for (let index = from; index < text.length; index += 1) {
+		const ch = text[index]
+		if (ch === '\\') index += 1
+		else if (ch === '[') {
+			const end = classEnd(text, index)
+			if (end > 0) index = end
+		} else if (ch === '(') depth += 1
+		else if (ch === ')' && --depth === 0) return index
+	}
+	return -1
+}
+
+/** Index of the `]` closing the class opened at `start`, or -1 when it never closes. */
+function classEnd(text: string, start: number): number {
+	let index = start + 1
+	if (text[index] === '!' || text[index] === '^') index += 1
+	if (text[index] === ']') index += 1
+	for (; index < text.length; index += 1) {
+		const ch = text[index]
+		if (ch === '\\') index += 1
+		else if (ch === '[' && text[index + 1] === ':') {
+			const end = text.indexOf(':]', index + 2)
+			if (end > 0 && POSIX_CLASSES[text.slice(index + 2, end)]) index = end + 1
+		} else if (ch === ']') return index
+	}
+	return -1
+}
+
+function splitAlternatives(body: string): string[] {
+	const parts: string[] = []
+	let depth = 0
+	let current = ''
+	for (let index = 0; index < body.length; index += 1) {
+		const ch = body[index] as string
+		if (ch === '\\') {
+			current += ch + (body[index + 1] ?? '')
+			index += 1
+			continue
+		}
+		if (ch === '[') {
+			const end = classEnd(body, index)
+			if (end > 0) {
+				current += body.slice(index, end + 1)
+				index = end
+				continue
+			}
+		}
+		if (ch === '(') depth += 1
+		if (ch === ')') depth -= 1
+		if (ch === '|' && depth === 0) {
+			parts.push(current)
+			current = ''
+		} else current += ch
+	}
+	parts.push(current)
+	return parts
+}
+
+function classSource(body: string): string {
+	let index = 0
+	let negate = false
+	if (body[0] === '!' || body[0] === '^') {
+		negate = true
+		index = 1
+	}
+	let out = ''
+	for (; index < body.length; index += 1) {
+		const ch = body[index] as string
+		if (ch === '[' && body[index + 1] === ':') {
+			const end = body.indexOf(':]', index + 2)
+			const name = end > 0 ? body.slice(index + 2, end) : ''
+			if (POSIX_CLASSES[name]) {
+				out += POSIX_CLASSES[name]
+				index = end + 1
+				continue
+			}
+		}
+		if (ch === '\\' && index + 1 < body.length) {
+			index += 1
+			out += escapeInClass(body[index] as string)
+		} else if (ch === '-' && out !== '' && index + 1 < body.length) out += '-'
+		else out += escapeInClass(ch)
+	}
+	const source = `[${negate ? '^' : ''}${out}]`
+	try {
+		new RegExp(source, 'u')
+	} catch {
+		// An out-of-order range such as `[z-a]` matches no name rather than failing the walk.
+		return '(?!)'
+	}
+	return source
+}
+
+/** `guard`, when set, is put before each alternative of a group at the very start that does not itself spell out a leading `.`. */
+function parse(text: string, guard = ''): Parsed {
+	let source = ''
+	let literal = ''
+	let magic = false
+	let runs = 0
+	for (let index = 0; index < text.length; index += 1) {
+		const ch = text[index] as string
+		const next = text[index + 1]
+		if (ch === '\\') {
+			if (next === undefined) {
+				source += '\\\\'
+				literal += '\\'
+			} else {
+				source += escapeRegex(next)
+				literal += next
+				index += 1
+			}
+		} else if (ch === '*' && next !== '(') {
+			while (text[index + 1] === '*') index += 1
+			source += '[^/]*?'
+			runs += 1
+			magic = true
+		} else if (ch === '?' && next !== '(') {
+			source += '[^/]'
+			magic = true
+		} else if (ch === '[') {
+			const end = classEnd(text, index)
+			if (end < 0) {
+				source += '\\['
+				literal += '['
+			} else {
+				source += classSource(text.slice(index + 1, end))
+				magic = true
+				index = end
+			}
+		} else if ('?*+@!'.includes(ch) && next === '(') {
+			const end = closeGroup(text, index + 2)
+			if (end < 0) {
+				source += escapeRegex(ch)
+				literal += ch
+				continue
+			}
+			const parts = splitAlternatives(text.slice(index + 2, end)).map((a) => ({
+				a,
+				parsed: parse(a),
+			}))
+			// A repeated group is linear only when each repetition can be read one way:
+			// plain literal alternatives, none a prefix of another (and none empty).
+			if (ch === '*' || ch === '+') {
+				const literals = parts.map((part) => part.parsed.literal)
+				// A lone class is one character wide, so each repetition has one reading.
+				const lone = parts.length === 1 && isOneClass(parts[0]?.a ?? '')
+				const plain = lone || parts.every((part) => !part.parsed.magic)
+				const prefixFree =
+					lone ||
+					literals.every(
+						(one, i) =>
+							one !== '' && literals.every((other, j) => i === j || !other.startsWith(one)),
+					)
+				if (!plain || !prefixFree) throw new GlobTooComplexError(text)
+			}
+			const alternatives = parts.map(
+				({ a, parsed }) => (index === 0 && !startsWithDot(a) ? guard : '') + parsed.source,
+			)
+			const group = `(?:${alternatives.join('|')})`
+			runs +=
+				parts.reduce((sum, part) => sum + part.parsed.runs, 0) + (ch === '*' || ch === '+' ? 1 : 0)
+			magic = true
+			if (ch === '!') {
+				const tail = parse(text.slice(end + 1))
+				const rest = tail.source
+				source += `(?:(?!${group}${rest}$)[^/]*?)${rest}`
+				return { source, literal, magic, runs: runs + 1 + tail.runs }
+			}
+			source += ch === '@' ? group : `${group}${ch === '?' ? '?' : ch === '*' ? '*' : '+'}`
+			index = end
+		} else {
+			source += escapeRegex(ch)
+			literal += ch
+		}
+	}
+	return { source, literal, magic, runs }
+}
+
+/** Whether the text is exactly one closed `[...]` class. */
+function isOneClass(text: string): boolean {
+	return text.startsWith('[') && classEnd(text, 0) === text.length - 1
+}
+
+/** Whether every name this segment can match begins with a literal `.` the pattern spells out. */
+function startsWithDot(text: string): boolean {
+	if (text.startsWith('.') || text.startsWith('\\.')) return true
+	if (text.startsWith('[')) {
+		const end = classEnd(text, 0)
+		return end > 0 && text.slice(1, end) === '.'
+	}
+	return false
+}
+
+/** Whether the segment is a single `?(`, `*(`, `@(` or `+(` group, whose alternatives carry the leading-dot guard themselves. */
+function isOneGroup(text: string): boolean {
+	return (
+		'?*@+'.includes(text[0] ?? '') && text[1] === '(' && closeGroup(text, 2) === text.length - 1
+	)
+}
+
+/**
+ * `dot` lets a wildcard match a name that starts with `.`; without it only a
+ * segment that itself begins with a literal `.` can.
+ */
+export function compileSegment(segment: string, dot: boolean): CompiledSegment {
+	const guard = dot ? '' : '(?!\\.)'
+	let parsed: Parsed
+	try {
+		parsed = parse(segment, guard)
+	} catch (error) {
+		throw error instanceof GlobTooComplexError
+			? new GlobTooComplexError(segment, 'ambiguous')
+			: error
+	}
+	if (parsed.runs > 3) throw new GlobTooComplexError(segment, 'stretch')
+	if (!parsed.magic) return { literal: parsed.literal, source: `^${parsed.source}$` }
+	const grouped = (segment.startsWith('@(') || segment.startsWith('+(')) && !dot
+	const lead = grouped || dot || startsWithDot(segment) || isOneGroup(segment) ? '' : guard
+	return { literal: null, source: `^${lead}(?:${parsed.source})$` }
+}

package/src/types/common/index.ts

@@ -50,6 +50,42 @@ export interface TokenUsage {
 	 * unreported.
 	 */
 	speed?: import('../provider/chat.js').InferenceSpeed
+
+	/**
+	 * Hosted web searches the provider ran for this call and bills per request.
+	 * Unlike the per-call facts below it IS a count of work done, so it is
+	 * summed across calls. Absent means the provider did not report one.
+	 */
+	webSearchRequests?: number
+
+	/**
+	 * The service tier the provider says served this call (`standard`,
+	 * `priority`, `batch`). A per-call fact, never summed. Absent means
+	 * unreported.
+	 */
+	serviceTier?: string
+
+	/** The region the provider says ran this call, when it says. Per call, never summed. */
+	inferenceGeo?: string
+
+	/**
+	 * Why the provider's prompt cache did not serve a prefix it had before, when
+	 * it explains. Per call, never summed. Absent means no miss was explained: the
+	 * provider reported nothing, a pending answer, or a hit.
+	 */
+	cacheMiss?: CacheMiss
+}
+
+/** A prompt-cache miss as the provider explains it. See {@link TokenUsage.cacheMiss}. */
+export interface CacheMiss {
+	/**
+	 * The provider's own reason, e.g. `model_changed`, `system_changed`,
+	 * `tools_changed`, `messages_changed`, `previous_message_not_found`,
+	 * `unavailable`.
+	 */
+	reason: string
+	/** Input tokens that missed the cache because of it, when the provider counts them. */
+	missedTokens?: number
 }
 
 export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage): TokenUsage {
@@ -66,8 +102,12 @@ export function accumulateTokenUsage(current: TokenUsage, addition: TokenUsage):
 		...(current.reasoningTokens !== undefined || addition.reasoningTokens !== undefined
 			? { reasoningTokens: (current.reasoningTokens ?? 0) + (addition.reasoningTokens ?? 0) }
 			: {}),
-		// `cacheTtlMs` and `cacheWriteTtlTokens` are per-call facts and are
-		// deliberately not carried into a sum.
+		...(current.webSearchRequests !== undefined || addition.webSearchRequests !== undefined
+			? { webSearchRequests: (current.webSearchRequests ?? 0) + (addition.webSearchRequests ?? 0) }
+			: {}),
+		// `cacheTtlMs`, `cacheWriteTtlTokens`, `speed`, `serviceTier`,
+		// `inferenceGeo` and `cacheMiss` are per-call facts and are deliberately
+		// not carried into a sum.
 	}
 }
 
@@ -112,6 +152,18 @@ export function mergeTokenUsage(current: TokenUsage, next: TokenUsage): TokenUsa
 		...(next.speed !== undefined || current.speed !== undefined
 			? { speed: next.speed ?? current.speed }
 			: {}),
+		...(next.webSearchRequests !== undefined || current.webSearchRequests !== undefined
+			? { webSearchRequests: Math.max(current.webSearchRequests ?? 0, next.webSearchRequests ?? 0) }
+			: {}),
+		...(next.serviceTier !== undefined || current.serviceTier !== undefined
+			? { serviceTier: next.serviceTier ?? current.serviceTier }
+			: {}),
+		...(next.inferenceGeo !== undefined || current.inferenceGeo !== undefined
+			? { inferenceGeo: next.inferenceGeo ?? current.inferenceGeo }
+			: {}),
+		...(next.cacheMiss !== undefined || current.cacheMiss !== undefined
+			? { cacheMiss: next.cacheMiss ?? current.cacheMiss }
+			: {}),
 	}
 }
 

package/src/types/session/events.ts

@@ -926,6 +926,13 @@ type CoreSessionEvent =
 			 * absent means unknown, and a host must not assume one.
 			 */
 			cache?: { ttlMs: number; touched: boolean }
+			/**
+			 * Why the provider says the latest model call did not read the cache
+			 * prefix it had before, when it explains one. Absent means no miss was
+			 * explained: nothing reported, a pending answer, or a hit. A host that
+			 * shows it should do so quietly; a miss after an edit is ordinary.
+			 */
+			cacheMiss?: { reason: string; missedTokens?: number }
 			/**
 			 * How large the CONTEXT is right now, and how large it may get.
 			 *

package/src/utils/cost.ts

@@ -48,6 +48,12 @@ export interface ModelPricing {
 	 * charged at the standard rate, which would under-report it.
 	 */
 	fastMultiplier?: number
+	/**
+	 * What the vendor charges per 1,000 hosted web searches
+	 * (`TokenUsage.webSearchRequests`). Absent means no published search price:
+	 * searches are then not part of the total, as before this field existed.
+	 */
+	webSearchCostPer1000?: number
 }
 
 export { ZERO_COST }
@@ -61,6 +67,26 @@ interface Priced {
 }
 
 function priceUsage(usage: TokenUsage, pricing: ModelPricing): Priced {
+	const tokens = priceTokens(usage, pricing)
+	const searches = usage.webSearchRequests ?? 0
+	if (searches === 0 || pricing.webSearchCostPer1000 === undefined) return tokens
+	// Per request, so no speed or tier multiple applies to it.
+	return { ...tokens, cost: tokens.cost + (searches / 1000) * pricing.webSearchCostPer1000 }
+}
+
+/**
+ * Tiers with a published per-token price (anything but `priority` and `batch`; a compatible endpoint may report `default` or `auto`). The vendor lists none for `priority`
+ * (a capacity commitment) or `batch` (a different endpoint), so tokens served
+ * on one are unpriced rather than charged at the standard rate.
+ */
+function isStandardTier(tier: string | undefined): boolean {
+	return tier !== 'priority' && tier !== 'batch'
+}
+
+function priceTokens(usage: TokenUsage, pricing: ModelPricing): Priced {
+	if (!isStandardTier(usage.serviceTier)) {
+		return { cost: 0, cacheDiscount: 0, unpriced: usage.totalTokens }
+	}
 	if (usage.speed === 'fast') {
 		const multiplier = pricing.fastMultiplier
 		if (multiplier === undefined) {