@namzu/sdk 58.1.1 → 59.0.0

package/src/account/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Accounts: more than one credential for one provider, chosen per session.
+ *
+ * An account is a provider plus a label. Today's single sign-in for each
+ * provider is the account labelled `default`; it is read exactly as before and
+ * is never stored here. Further accounts are one of two kinds: a private
+ * Codex home directory that holds its own `auth.json`, or a labelled API key.
+ *
+ * @experimental
+ */
+
+/** `<provider>:<label>`. The label is `[a-z0-9-]{1,32}`; `default` is reserved for today's sign-in. */
+export type AccountId = string
+
+/** The label of the account that wraps a provider's existing sign-in. */
+export const DEFAULT_ACCOUNT_LABEL = 'default'
+
+/** Where an account's credential comes from. */
+export type AccountSource =
+	/** The provider's existing sign-in, read the way it was before accounts existed. Synthesised, never stored. */
+	| { readonly kind: 'existing-default' }
+	/** A private Codex home: `dir/auth.json` was written by `codex login` run with `CODEX_HOME=dir`. */
+	| { readonly kind: 'codex-home'; readonly dir: string }
+	/** A labelled API key. `keyRef` names a slot in the registry's secret map; the key itself is never in a log. */
+	| { readonly kind: 'api-key'; readonly keyRef: string }
+
+export interface Account {
+	readonly id: AccountId
+	readonly provider: string
+	readonly label: string
+	readonly source: AccountSource
+	readonly createdAt: string
+	/** A short human tag such as the tail of the provider's account id. Never a token. */
+	readonly display?: string
+	/** API-key accounts only: the endpoint this key belongs to. A different endpoint is a different account. */
+	readonly baseUrl?: string
+	/** API-key accounts only: the model a session on this account starts with. */
+	readonly defaultModel?: string
+}
+
+/** What `add` accepts. The id, the creation time and the key slot are assigned by the registry. */
+export type NewAccount =
+	| {
+			readonly provider: string
+			readonly label: string
+			readonly kind: 'api-key'
+			readonly apiKey: string
+			readonly display?: string
+			/** An http(s) endpoint without embedded credentials. */
+			readonly baseUrl?: string
+			readonly defaultModel?: string
+	  }
+	| {
+			readonly provider: 'codex'
+			readonly label: string
+			readonly kind: 'codex-home'
+			/** Defaults to `<home>/accounts/codex/<label>`; must stay inside `<home>/accounts`. */
+			readonly dir?: string
+			readonly display?: string
+	  }
+
+/** A credential ready to put on a request. Never logged. */
+export interface ResolvedAccountCredential {
+	readonly kind: 'api-key' | 'oauth'
+	readonly accessToken: string
+	/** Set for an API-key account that names its own endpoint. */
+	readonly baseUrl?: string
+	/** Set for an API-key account that names a starting model. */
+	readonly defaultModel?: string
+	/** The provider-side account identity some drivers send as a header. */
+	readonly accountId?: string
+	/** Epoch milliseconds, when the credential expires. */
+	readonly expiresAt?: number
+}
+
+/** The credential behind an account is gone or unusable; the caller should offer another account. */
+export class CredentialWithdrawnError extends Error {
+	override readonly name = 'CredentialWithdrawnError'
+	constructor(
+		readonly accountId: AccountId,
+		message: string,
+	) {
+		super(message)
+	}
+}
+
+/** A registry mutation was refused: bad label, duplicate, unknown account, unreadable store. */
+export class AccountRegistryError extends Error {
+	override readonly name = 'AccountRegistryError'
+}
+
+/** Another owner holds the lock for a store or an account's credential file. */
+export class AccountLockError extends Error {
+	override readonly name = 'AccountLockError'
+	constructor(
+		readonly lockPath: string,
+		message: string,
+	) {
+		super(message)
+	}
+}
+
+/**
+ * Source-specific readers. The registry owns the bookkeeping; the code that
+ * knows how a provider's sign-in is discovered or refreshed lives with the
+ * provider and is handed in here.
+ */
+export interface AccountCredentialReaders {
+	/** Read the provider's existing sign-in. Throws {@link CredentialWithdrawnError} when there is none. */
+	readonly existingDefault?: (
+		provider: string,
+		signal: AbortSignal,
+	) => Promise<ResolvedAccountCredential>
+	/**
+	 * Read, and refresh when due, the credential in a private Codex home. An
+	 * implementation holds `withAccountRefreshLock` across the read-refresh-write
+	 * so two processes never spend one refresh token twice.
+	 */
+	readonly codexHome?: (
+		account: Account & { readonly source: { readonly kind: 'codex-home'; readonly dir: string } },
+		signal: AbortSignal,
+	) => Promise<ResolvedAccountCredential>
+}
+
+export interface AccountRegistry {
+	/** Stored accounts plus the synthesised `default` of each known provider. Defaults first, then creation order. */
+	list(provider?: string): Account[]
+	get(id: AccountId): Account | undefined
+	add(account: NewAccount): Account
+	/** Change an account's label; its id changes with it. Sessions bound to the old id fall back to `default`. */
+	rename(id: AccountId, label: string): Account
+	/** Remove a stored account and its secret or private Codex directory. The `default` account cannot be removed. */
+	remove(id: AccountId): void
+	resolve(id: AccountId, signal: AbortSignal): Promise<ResolvedAccountCredential>
+	/** The next account of `provider` not in `excluding`, for the "continue with another account" picker. */
+	next(provider: string, excluding: readonly AccountId[]): Account | undefined
+}

package/src/peers/record.ts

@@ -43,9 +43,27 @@ export const PeerRecordSchema = z
 		token: z.string().min(1),
 		protocol: z.literal(PEER_PROTOCOL_VERSION),
 		cliVersion: z.string(),
+		/** The slot a spaces host gave this terminal at launch; how the host finds its own sessions. */
+		hostSlot: z.string().min(1).max(128).optional(),
+		/** The conversation this terminal is on, once it has one. */
+		conversationId: z.string().min(1).optional(),
+		/** The label of the non-default account the conversation is bound to; absent for the default. */
+		account: z.string().min(1).optional(),
+		/** True while the bound account is out of allowance and the terminal is waiting for a choice. */
+		limited: z.boolean().optional(),
+		/** When the allowance is expected back (epoch ms); absent when the provider did not say. */
+		limitedUntil: z.number().int().positive().optional(),
 	})
 	.strict()
 
+/**
+ * The reader's view of a record: the same fields, but a key this build does
+ * not know is dropped instead of failing the whole record. A record written by
+ * a newer build (extra optional fields) stays visible to an older reader.
+ * Writers keep using the strict `PeerRecordSchema`.
+ */
+export const PeerRecordReaderSchema = PeerRecordSchema.strip()
+
 export type PeerRecord = z.infer<typeof PeerRecordSchema>
 
 const PEER_REF_HEX_LENGTH = 6

package/src/peers/registry.ts

@@ -20,7 +20,7 @@ import {
 import { basename, dirname, join } from 'node:path'
 import { parsePeerAddress } from './address.js'
 import { pingPeer } from './client.js'
-import { type PeerRecord, PeerRecordSchema } from './record.js'
+import { type PeerRecord, PeerRecordReaderSchema, PeerRecordSchema } from './record.js'
 
 const RECORD_FILE_MODE = 0o600
 
@@ -75,7 +75,7 @@ function parseRecordText(text: string): PeerRecord | undefined {
 	} catch {
 		return undefined
 	}
-	const result = PeerRecordSchema.safeParse(parsed)
+	const result = PeerRecordReaderSchema.safeParse(parsed)
 	return result.success ? result.data : undefined
 }
 

package/src/provider/errors.ts

@@ -33,6 +33,7 @@ import { LOG_SECRET_PATTERNS } from '../constants/secret-patterns.js'
 import type { ProviderErrorKind, ProviderRequestErrorInit } from '../types/provider/error.js'
 import {
 	type TransportCause,
+	isUsageLimitSignal,
 	readCertificateFailure,
 	readTransportCause,
 } from '../types/provider/errors.js'
@@ -130,6 +131,31 @@ function providerCode(value: unknown): string | undefined {
 	return safeProviderCode(record.code ?? nested)
 }
 
+/**
+ * A vendor can name a spent allowance in `type` instead of `code`
+ * (`{"error":{"type":"usage_limit_reached"}}`, `{"error":{"type":"billing_error"}}`).
+ * Only those identifiers are lifted to a provider code; any other `type` is a
+ * category and stays where it was.
+ */
+function usageLimitTypeOf(error: unknown): string | undefined {
+	if (typeof error !== 'object' || error === null) return undefined
+	const outer = error as { type?: unknown; error?: unknown }
+	const inner =
+		typeof outer.error === 'object' && outer.error !== null
+			? (outer.error as { type?: unknown; error?: unknown })
+			: undefined
+	const innermost =
+		typeof inner?.error === 'object' && inner.error !== null
+			? (inner.error as { type?: unknown })
+			: undefined
+	for (const candidate of [outer.type, inner?.type, innermost?.type]) {
+		if (typeof candidate === 'string' && isUsageLimitSignal(candidate, undefined)) {
+			return safeProviderCode(candidate)
+		}
+	}
+	return undefined
+}
+
 /**
  * Credential shapes to scrub before a provider's words are kept.
  *
@@ -524,7 +550,7 @@ export function providerVendorError(input: {
 }): ProviderRequestError {
 	const { error } = input
 	const status = vendorErrorStatus(error)
-	const exactProviderCode = providerCode(error)
+	const exactProviderCode = providerCode(error) ?? usageLimitTypeOf(error)
 	const name = error instanceof Error ? error.name : ''
 	const message = error instanceof Error ? error.message : ''
 

package/src/provider/token-budget.ts

@@ -29,9 +29,14 @@ function rejectedBeforeGeneration(error: unknown): boolean {
 			[400, 401, 403, 404, 413, 422, 429].includes(classified.status))
 	return (
 		explicitRejection &&
-		['auth', 'rate_limit', 'context_length_exceeded', 'invalid_request', 'not_found'].includes(
-			classified.code,
-		)
+		[
+			'auth',
+			'rate_limit',
+			'usage_limit',
+			'context_length_exceeded',
+			'invalid_request',
+			'not_found',
+		].includes(classified.code)
 	)
 }
 
@@ -96,6 +101,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 					![
 						'auth',
 						'rate_limit',
+						'usage_limit',
 						'context_length_exceeded',
 						'invalid_request',
 						'not_found',

package/src/public-runtime.ts

@@ -1869,6 +1869,23 @@ export {
 	udsPeerAddress,
 	writePeerRecord,
 } from './peers/index.js'
+export {
+	ACCOUNTS_FILE_NAME,
+	ACCOUNTS_FILE_VERSION,
+	AccountLockError,
+	AccountRegistryError,
+	CredentialWithdrawnError,
+	DEFAULT_ACCOUNT_LABEL,
+	accountBoundPayload,
+	accountId,
+	codexRefreshLockPath,
+	createAccountRegistry,
+	parseAccountId,
+	resolveBoundAccount,
+	withAccountLock,
+	withAccountLockSync,
+	withAccountRefreshLock,
+} from './account/index.js'
 export { DiskPalStore, PalConflictError } from './pals/store.js'
 export { PalRuntime, PalUnavailableError } from './pals/runtime.js'
 export { buildPalSystemPrompt, palConversationGreeting } from './pals/prompt.js'

package/src/public-types.ts

@@ -800,6 +800,21 @@ export type {
 	ResolvePeerRuntimeDirOptions,
 } from './peers/dir.js'
 export type { PeerRecord } from './peers/record.js'
+export type { AccountBoundRecord } from './types/session/records.js'
+export type {
+	Account,
+	AccountBoundReason,
+	AccountCredentialReaders,
+	AccountId,
+	AccountLockOptions,
+	AccountLockSyncOptions,
+	AccountRegistry,
+	AccountRegistryOptions,
+	AccountSource,
+	BoundAccount,
+	NewAccount,
+	ResolvedAccountCredential,
+} from './account/index.js'
 export type {
 	ListLivePeersOptions,
 	PeerLivenessOptions,

package/src/runtime/query/executor.ts

@@ -13,6 +13,7 @@ import { buildProbeContext } from '../../probe/context.js'
 import { ProbeVetoError } from '../../probe/errors.js'
 import { probe as defaultProbeRegistry } from '../../probe/registry.js'
 import type { ProbeEnforcement } from '../../probe/registry.js'
+import { ToolResultHalted } from '../../registry/tool/screen.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import {
 	effectiveBashWorkingDirectory,
@@ -3131,11 +3132,16 @@ export class ToolExecutor {
 	}
 
 	/**
-	 * One execution attempt, with a throw materialized as an error result.
+	 * One execution attempt, with a throw materialized as an error result —
+	 * except `ToolResultHalted`, which this deliberately lets through.
 	 *
 	 * an unhandled throw from `tools.execute(...)` used to
 	 * propagate up to `result.ts` as `turn_failed` without emitting a
-	 * terminal `tool_completed`, leaving UI cards stuck in `executing`.
+	 * terminal `tool_completed`, leaving UI cards stuck in `executing`. That
+	 * is still right for a tool that merely broke. It is wrong for a screen
+	 * that said `halt`: `screen.ts` throws `ToolResultHalted` instead of
+	 * returning it so a catch this generic cannot flatten it into a failed
+	 * `ToolResult` the model reads and works around.
 	 *
 	 * The return is the full `ToolResult`, not a narrowed literal: the
 	 * narrow version silently DROPPED `content`, so a tool returning an
@@ -3151,6 +3157,8 @@ export class ToolExecutor {
 		try {
 			return await this.executeWithDeadline(toolName, input, toolContext, prepared)
 		} catch (err) {
+			if (err instanceof ToolResultHalted) throw err
+
 			const message = toErrorMessage(err)
 			this.log.warn('Tool execution threw', {
 				[NAMZU.TURN_ID]: this.config.turnId,

package/src/types/errors/catalog.ts

@@ -164,6 +164,12 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		message: 'The provider rejected the credentials for this turn.',
 		hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
 	},
+	{
+		id: 'provider.usage_limit',
+		when: (facts) => facts.code === 'usage_limit',
+		message: 'The account has used up its allowance until the limit resets.',
+		hint: 'Waiting inside this turn cannot help. Continue on another account or provider, or resume after the reset time the provider reported.',
+	},
 	{
 		id: 'provider.rate_limit',
 		when: (facts) => facts.code === 'rate_limit' || facts.status === 429,

package/src/types/provider/errors.ts

@@ -15,6 +15,12 @@
 export type ProviderErrorCode =
 	/** 429. Back off; honour `retryAfterMs` when the server sent one. */
 	| 'rate_limit'
+	/**
+	 * The account's usage allowance is spent until a later reset, as opposed to
+	 * a momentary burst limit. Waiting inside this turn cannot help, so it is
+	 * not retried; a host may offer another account instead.
+	 */
+	| 'usage_limit'
 	/** 529 / 503 — the model is up but saturated. Back off. */
 	| 'overloaded'
 	/** Any other 5xx. Back off. */
@@ -487,7 +493,10 @@ const STRUCTURAL_CODES: Readonly<Record<string, ProviderErrorCode>> = {
 	string_above_max_length: 'context_length_exceeded',
 	rate_limit_exceeded: 'rate_limit',
 	rate_limit_error: 'rate_limit',
-	insufficient_quota: 'rate_limit',
+	insufficient_quota: 'usage_limit',
+	usage_limit_reached: 'usage_limit',
+	usage_limit_exceeded: 'usage_limit',
+	billing_error: 'usage_limit',
 	overloaded_error: 'overloaded',
 	content_filter: 'content_filter',
 	content_policy_violation: 'content_filter',
@@ -497,6 +506,24 @@ const STRUCTURAL_CODES: Readonly<Record<string, ProviderErrorCode>> = {
 	model_not_found: 'not_found',
 }
 
+/**
+ * Is this exact provider code, or the provider's own complaint, a spent
+ * allowance? The codes are the vendors' identifiers (`insufficient_quota`,
+ * `usage_limit_reached`, `usage_limit_exceeded`, `billing_error`); the
+ * sentences are the two vendors that word it only in prose: an exhausted
+ * prepaid balance and an exhausted plan allowance.
+ */
+const USAGE_LIMIT_DETAIL: readonly RegExp[] = [
+	/credit balance is too low/i,
+	/exceeded your current quota/i,
+	/usage limit (?:has been )?(?:reached|exceeded)/i,
+]
+
+export function isUsageLimitSignal(code: string | undefined, detail: string | undefined): boolean {
+	if (code !== undefined && STRUCTURAL_CODES[code.toLowerCase()] === 'usage_limit') return true
+	return detail !== undefined && USAGE_LIMIT_DETAIL.some((re) => re.test(detail))
+}
+
 function codeFromStructure(err: unknown): ProviderErrorCode | undefined {
 	for (const link of causeChain(err)) {
 		for (const field of [link.code, link.type, (link.error as { type?: unknown })?.type]) {
@@ -556,6 +583,8 @@ function classifyFromProviderRequestError(
 	const candidate = err as Error & {
 		kind?: unknown
 		providerId?: unknown
+		providerCode?: unknown
+		detail?: unknown
 		status?: unknown
 		retryAfterMs?: unknown
 		shouldRetry?: unknown
@@ -563,15 +592,23 @@ function classifyFromProviderRequestError(
 	if (typeof candidate.kind !== 'string') return undefined
 	const mapped = KIND_TO_CODE[candidate.kind]
 	if (!mapped) return undefined
+	// A throttle or an invalid request that says the allowance is spent is not
+	// a burst limit: resending the same request cannot succeed.
+	const spent =
+		(candidate.kind === 'throttle' || candidate.kind === 'bad_request') &&
+		isUsageLimitSignal(
+			typeof candidate.providerCode === 'string' ? candidate.providerCode : undefined,
+			typeof candidate.detail === 'string' ? candidate.detail : undefined,
+		)
 
 	const retryAfterMs =
 		typeof candidate.retryAfterMs === 'number' ? candidate.retryAfterMs : readRetryAfterMs(err, now)
 
 	return new ProviderError({
-		code: mapped.code,
+		code: spent ? 'usage_limit' : mapped.code,
 		message: err.message,
 		// The provider saying "do not resend" beats the kind's own verdict.
-		retryable: candidate.shouldRetry === false ? false : mapped.retryable,
+		retryable: spent || candidate.shouldRetry === false ? false : mapped.retryable,
 		cause: err,
 		...(typeof candidate.providerId === 'string'
 			? { providerId: candidate.providerId }

package/src/types/session/records.ts

@@ -576,6 +576,19 @@ export const BudgetBoundRecordSchema = inTurn('budget_bound', {
 	accountId: text.min(1),
 })
 
+/**
+ * The account a session's provider calls run under. Written when a session is
+ * bound to an account other than the provider's `default`, and again on each
+ * switch; never inside an open turn's work, only between turns. Replay reads
+ * the last one. A build that predates this record refuses a log holding it, so
+ * a session that never leaves the default account never writes one.
+ */
+export const AccountBoundRecordSchema = recordSchema('account_bound', {
+	accountId: text.min(1),
+	provider: text.min(1),
+	reason: z.enum(['start', 'user_switch', 'limit_switch']),
+})
+
 export const LogRepairedRecordSchema = recordSchema('log_repaired', {
 	truncatedBytes: positive,
 	lastGoodSeq: positive,
@@ -612,6 +625,7 @@ const RECORD_ONLY_SCHEMAS = {
 	child_session_ended: ChildSessionEndedRecordSchema,
 	audit: AuditRecordSchema,
 	budget_bound: BudgetBoundRecordSchema,
+	account_bound: AccountBoundRecordSchema,
 	log_repaired: LogRepairedRecordSchema,
 } as const
 
@@ -982,6 +996,7 @@ export type CompactionRecord = z.infer<typeof CompactionRecordSchema>
 export type ChildSessionEndedRecord = z.infer<typeof ChildSessionEndedRecordSchema>
 export type AuditRecord = z.infer<typeof AuditRecordSchema>
 export type BudgetBoundRecord = z.infer<typeof BudgetBoundRecordSchema>
+export type AccountBoundRecord = z.infer<typeof AccountBoundRecordSchema>
 export type LogRepairedRecord = z.infer<typeof LogRepairedRecordSchema>
 
 export type SessionRecordOnly =
@@ -998,6 +1013,7 @@ export type SessionRecordOnly =
 	| ChildSessionEndedRecord
 	| AuditRecord
 	| BudgetBoundRecord
+	| AccountBoundRecord
 	| LogRepairedRecord
 
 /** One line of a session log. */