@namzu/sdk 45.0.0 → 45.1.0

package/src/tools/schedules/types.ts

@@ -0,0 +1,197 @@
+/**
+ * The host side of the `schedule` and `session_loop` tools.
+ *
+ * The SDK holds the tool's contract with the model — its schema, its refusals
+ * and its confirmation rule — and nothing about where jobs are stored or how
+ * a confirmation is drawn. The host supplies both, and it computes every
+ * field a person is asked to confirm: the model's own words are never what
+ * the confirmation shows as fact.
+ */
+
+/** A rule effect, in the vocabulary of the CLI's `[permissions]` table. */
+export type ScheduleRuleEffect = 'allow' | 'ask' | 'deny'
+
+/** What the model proposes. Validated by the tool's schema, then by the host. */
+export interface ScheduleJobDraft {
+	readonly name: string
+	readonly prompt: string
+	/** Schedule words: `every 30m`, `0 9 * * 1-5`, `at 09:00`, `in 2h`. */
+	readonly when: string
+	/** Folder the job runs in. Absent: the session's working directory. */
+	readonly folder?: string
+	/** IANA zone for a cron expression or a local time. Absent: the host's. */
+	readonly tz?: string
+	readonly permissions: {
+		readonly preset?: 'read-only' | 'edit-in-folder'
+		/**
+		 * What happens to a call no rule covers. The model may choose `park`
+		 * (wait for the operator) or `deny`; running uncovered calls without
+		 * asking is an operator decision the tool cannot propose.
+		 */
+		readonly unmatched: 'park' | 'deny'
+		readonly execution?: 'host' | 'sandbox'
+		readonly rules?: Readonly<
+			Record<string, ScheduleRuleEffect | Readonly<Record<string, ScheduleRuleEffect>>>
+		>
+		/**
+		 * Browser access for the run. Absent: the `browser` and `browser_act`
+		 * tools are denied. Present: only the listed sites are reachable, at
+		 * the listed level, and every other site is denied — there is no
+		 * catch-all key. The tool refuses this block unless the host sets
+		 * {@link ScheduleToolHost.browserGrants}.
+		 */
+		readonly browser?: ScheduleBrowserGrant
+	}
+	readonly budget?: {
+		readonly maxIterations?: number
+		readonly tokenBudget?: number
+		readonly timeoutMs?: number
+	}
+}
+
+/**
+ * How far a scheduled run may go on one site. `read`: open and read pages,
+ * never change them. `ask`: open and change pages, each change parked for the
+ * operator. `act`: open and change pages without asking.
+ */
+export type ScheduleBrowserSiteLevel = 'read' | 'ask' | 'act'
+
+/** A scheduled job's browser grant. */
+export interface ScheduleBrowserGrant {
+	/** The browser profile the run uses; the operator's, signed in beforehand. */
+	readonly profile: string
+	/**
+	 * Canonical site key (`https://github.com`, `https://*.example.com`,
+	 * `http://localhost:*`) to level. The tool canonicalises the keys the
+	 * model wrote (see `canonicalizeBrowserSitePattern`) before the host sees
+	 * them. Unlisted sites are denied.
+	 */
+	readonly sites: Readonly<Record<string, ScheduleBrowserSiteLevel>>
+	/** Show the browser window during the run. Default: no window. */
+	readonly headed?: boolean
+}
+
+/** What the person confirming is shown. Every field is the host's own computation. */
+export interface ScheduleJobPreview {
+	readonly name: string
+	/** The canonical folder the job would run in. */
+	readonly folder: string
+	/** True when `folder` is outside the session's working directory and added directories. */
+	readonly outsideSessionRoots: boolean
+	readonly prompt: string
+	/** The schedule in words, with its zone. */
+	readonly schedule: string
+	/** The next fire times, ISO-8601 UTC. */
+	readonly nextFireTimes: readonly string[]
+	/** The permission set expanded to one line per rule, config denies included. */
+	readonly rules: readonly string[]
+	readonly unmatched: 'park' | 'deny' | 'allow'
+	readonly execution: 'host' | 'sandbox'
+	/** A rule lets the run reach the network. */
+	readonly networkAccess: boolean
+	readonly budget: {
+		readonly maxIterations: number
+		readonly tokenBudget: number
+		readonly timeoutMs: number
+	}
+	/** Runs per day at most, times the token budget. Absent for a one-shot. */
+	readonly dailyTokenCeiling?: number
+	/** Provider and model the job is pinned to. */
+	readonly model: string
+	/** Where the run's credential comes from, in words. */
+	readonly credentialSource?: string
+	/** Anything the host wants said in the warning colour. */
+	readonly warnings: readonly string[]
+}
+
+/** A job as the `list` action reports it. */
+export interface ScheduleJobSummary {
+	readonly name: string
+	readonly folder: string
+	readonly state: string
+	readonly schedule: string
+	readonly nextFireAt?: string
+	readonly lastStatus?: string
+	/** Present only for jobs in the session's own folder. */
+	readonly prompt?: string
+}
+
+/** What the person answered to a proposed job. */
+export type ScheduleConfirmAnswer = 'create' | 'create-paused' | 'cancel'
+
+export interface ScheduleConfirmRequest {
+	readonly preview: ScheduleJobPreview
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool: the banner says it was not the operator. */
+	readonly proposedBy: 'model'
+}
+
+export interface ScheduleToolHost {
+	/**
+	 * The host can store and enforce {@link ScheduleJobDraft.permissions}
+	 * `.browser`. Absent or false: the tool refuses a draft carrying one,
+	 * rather than let the host drop it and confirm a job the model believes
+	 * can use the browser.
+	 */
+	readonly browserGrants?: boolean
+	/** Validate the draft and compute what the person will be shown. Throws with a message on a refusal. */
+	preview(draft: ScheduleJobDraft): Promise<ScheduleJobPreview>
+	/**
+	 * Ask the person. Anything but `create` or `create-paused` — `cancel`, a
+	 * thrown error, a closed screen — means no job.
+	 *
+	 * `signal` fires when the tool's own confirmation deadline elapses or the
+	 * turn is aborted; a host that draws a screen closes it then rather than
+	 * leaving it live after the tool has given up on the answer.
+	 */
+	confirm(request: ScheduleConfirmRequest, signal?: AbortSignal): Promise<ScheduleConfirmAnswer>
+	/**
+	 * Create the job the person confirmed. `note`, when given, is appended to
+	 * what the model is told, for what the person must still do before the
+	 * job runs (install a scheduler, say): the model reports the job as set
+	 * up otherwise.
+	 */
+	create(
+		draft: ScheduleJobDraft,
+		preview: ScheduleJobPreview,
+		options: { readonly paused: boolean },
+	): Promise<{ readonly name: string; readonly note?: string }>
+	/** Jobs, the session folder's in full, other folders' without their prompts. */
+	list(options: { readonly allFolders: boolean }): Promise<readonly ScheduleJobSummary[]>
+	/** A job by name or id prefix, or undefined. */
+	find(job: string): Promise<ScheduleJobSummary | undefined>
+	/** Ask the person to confirm resuming or deleting a job. See `confirm` on `signal`. */
+	confirmAction(
+		job: ScheduleJobSummary,
+		action: 'resume' | 'delete',
+		signal?: AbortSignal,
+	): Promise<boolean>
+	pause(job: string): Promise<void>
+	resume(job: string): Promise<void>
+	delete(job: string): Promise<void>
+}
+
+/** A prompt the session re-sends to itself on an interval. */
+export interface SessionLoop {
+	readonly id: string
+	/** The interval in words. */
+	readonly schedule: string
+	readonly prompt: string
+	readonly createdAt: string
+	readonly expiresAt?: string
+	readonly lastFiredAt?: string
+	readonly createdBy: 'operator' | 'model'
+}
+
+export interface SessionLoopHost {
+	/** Throws with a message when the interval is not usable or the loop limit is reached. */
+	create(request: {
+		readonly interval: string
+		readonly prompt: string
+		readonly createdBy: 'model'
+	}): Promise<SessionLoop>
+	list(): readonly SessionLoop[]
+	/** Stop one loop by id, or every loop with `all`. Returns how many stopped. */
+	delete(id: string): Promise<number>
+}

package/src/types/authorization/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { MAX_CUSTOM_PATTERN_LENGTH } from '../../constants/authorization/index.js'
+import type { ShellDialect, ToolDefinition } from '../tool/index.js'
 
 export type GateDecision = 'allow' | 'deny' | 'review'
 
@@ -81,9 +82,56 @@ export type AuthorizationRule =
 			/** The argument key, at the top level of the tool's input. */
 			argument: string
 			pattern: string
-			decision: 'allow' | 'deny'
+			/**
+			 * `review` sends a matching call to the review policy — a person,
+			 * or the turn's mode — instead of deciding it here. It matches as
+			 * `deny` does (any segment of a command line), because it is a
+			 * restriction: a rule that asks before `git push` must also ask
+			 * before `true; git push`.
+			 */
+			decision: 'allow' | 'deny' | 'review'
 	  }
 	| { type: 'allow_by_tier'; tiers: string[] }
+	| {
+			/**
+			 * A decision the host computes in code, in its place in the list.
+			 *
+			 * A pattern is the wrong tool for a rule about what a command line
+			 * DOES: a regular expression over its text has to re-implement the
+			 * shell's quoting, and every form it misses (`$'…'`, a line
+			 * continuation, a quoted separator) is a way past the rule. A host
+			 * that needs such a rule reads the line with `lexShellCommandLine`
+			 * and decides on the words bash will pass, here.
+			 *
+			 * `decide` returns a decision, or `null` to let the next rule
+			 * decide. A `decide` that throws is read as `deny`: a rule that
+			 * could not reach a verdict must not let the call through.
+			 */
+			type: 'predicate'
+			/**
+			 * What the rule refuses or allows, in words. It is the reason the
+			 * gate reports when this rule decides, so it should tell a model
+			 * whether a different input could fare better.
+			 */
+			description: string
+			decide: AuthorizationPredicate
+	  }
+
+/** The call an `AuthorizationRule` of type `predicate` is asked about. */
+export interface AuthorizationPredicateCall {
+	readonly toolName: string
+	readonly toolInput: unknown
+	readonly toolDef: ToolDefinition | undefined
+	/**
+	 * The shell a command line in this call runs in: the caller's
+	 * (`ToolCallContext.commandDialect`), or `sh` when it did not say, which
+	 * is the reading that holds whichever shell runs it.
+	 */
+	readonly commandDialect: ShellDialect
+}
+
+/** The code behind an `AuthorizationRule` of type `predicate`. */
+export type AuthorizationPredicate = (call: AuthorizationPredicateCall) => GateDecision | null
 
 const AllowReadOnlySchema = z.object({
 	type: z.literal('allow_read_only'),
@@ -121,12 +169,21 @@ const ArgumentPatternSchema = z.object({
 	// fail-open shape this rule type exists to remove.
 	argument: z.string().min(1),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
-	decision: z.enum(['allow', 'deny']),
+	decision: z.enum(['allow', 'deny', 'review']),
 })
 const AllowByTierSchema = z.object({
 	type: z.literal('allow_by_tier'),
 	tiers: z.array(z.string()),
 })
+const PredicateSchema = z.object({
+	type: z.literal('predicate'),
+	// A rule that says nothing about itself produces a refusal nobody can
+	// reason about.
+	description: z.string().min(1),
+	decide: z.custom<AuthorizationPredicate>((value) => typeof value === 'function', {
+		message: 'decide must be a function',
+	}),
+})
 
 export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowReadOnlySchema,
@@ -137,6 +194,7 @@ export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	CustomPatternSchema,
 	ArgumentPatternSchema,
 	AllowByTierSchema,
+	PredicateSchema,
 ])
 
 export const AuthorizationGateConfigSchema = z.object({

package/src/types/browser/index.ts

@@ -0,0 +1,341 @@
+// ---------------------------------------------------------------------------
+// The browser contract: what a browser host does for the `browser` and
+// `browser_act` tools. The SDK owns the model-facing tools and this
+// interface; a host package (for example `@namzu/browser`) owns the engine.
+// ---------------------------------------------------------------------------
+
+/** Every action the `browser` tool (observe and navigate) can ask for. */
+export type BrowserObserveActionName =
+	| 'navigate'
+	| 'back'
+	| 'forward'
+	| 'reload'
+	| 'snapshot'
+	| 'screenshot'
+	| 'scroll'
+	| 'wait_for'
+	| 'tabs'
+
+/** Every action the `browser_act` tool (change the page) can ask for. */
+export type BrowserActActionName =
+	| 'click'
+	| 'type'
+	| 'fill_form'
+	| 'select'
+	| 'press'
+	| 'hover'
+	| 'upload'
+	| 'dialog'
+
+export type BrowserActionName = BrowserObserveActionName | BrowserActActionName
+
+export type BrowserScrollDirection = 'up' | 'down' | 'left' | 'right'
+
+export type BrowserTabsOp = 'list' | 'select' | 'close' | 'new'
+
+// ---------------------------------------------------------------------------
+// Capabilities — frozen at host construction; the model reads them through
+// the tools' descriptions and schemas.
+// ---------------------------------------------------------------------------
+
+export interface BrowserCapabilities {
+	/** Which engine drives the browser, in words: `local-chromium`, `windows-cdp`. */
+	readonly engine: string
+	/** The browser window is not shown. */
+	readonly headless: boolean
+	/** `screenshot` can return an image. */
+	readonly screenshot: boolean
+	/** `upload` can attach a local file to a file input. */
+	readonly upload: boolean
+	/**
+	 * Exact action subset when known. Absent: every action whose broad flag
+	 * above allows it. Actions outside the subset are removed from the model
+	 * schema and refused before the host is called.
+	 */
+	readonly supportedActions?: readonly BrowserActionName[]
+	/**
+	 * The most snapshot text one call returns. The tool cuts anything longer.
+	 * Absent: {@link BROWSER_SNAPSHOT_MAX_CHARS}.
+	 */
+	readonly snapshotMaxChars?: number
+	/**
+	 * Why the browser cannot be used at all — the engine is not installed,
+	 * the profile is missing. Present, both tools stay mounted, say this in
+	 * their descriptions and refuse every call with it, so the model reads
+	 * the reason once and tells the user instead of retrying.
+	 */
+	readonly unavailableReason?: string
+}
+
+/** Default and ceiling of snapshot text per call, in characters. */
+export const BROWSER_SNAPSHOT_MAX_CHARS = 20_000
+
+/** Longest `wait_for` the tool accepts, in milliseconds. */
+export const BROWSER_WAIT_MAX_MS = 30_000
+
+/** Most fields one `fill_form` call may set. */
+export const BROWSER_FILL_FORM_MAX_FIELDS = 20
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * What the `browser` tool asks of the host. Every URL here has already been
+ * canonicalised by the tool (see `canonicalizeBrowserUrl`): only http, https
+ * or `about:blank`, no credentials, never a cloud metadata address.
+ */
+export type BrowserObserveAction =
+	| { readonly action: 'navigate'; readonly url: string }
+	| { readonly action: 'back' }
+	| { readonly action: 'forward' }
+	| { readonly action: 'reload' }
+	| { readonly action: 'snapshot'; readonly ref?: string; readonly cursor?: string }
+	| { readonly action: 'screenshot'; readonly ref?: string; readonly fullPage?: boolean }
+	| {
+			readonly action: 'scroll'
+			readonly direction: BrowserScrollDirection
+			readonly ref?: string
+			/** Screens to scroll; the host's default when absent. */
+			readonly amount?: number
+	  }
+	| {
+			readonly action: 'wait_for'
+			readonly text?: string
+			readonly textGone?: string
+			readonly timeMs?: number
+	  }
+	| {
+			readonly action: 'tabs'
+			readonly op: BrowserTabsOp
+			/** `select` and `close`: the tab id from `list` or a page header. */
+			readonly tab?: string
+			/** `new`: the address to open; `about:blank` when absent. */
+			readonly url?: string
+	  }
+
+export interface BrowserFormField {
+	readonly ref: string
+	/** Text for a text box; `true`/`false` for a checkbox; the option's label for a select. */
+	readonly value: string
+}
+
+/** The change a `browser_act` call makes. */
+export type BrowserActOperation =
+	| { readonly action: 'click'; readonly ref: string; readonly doubleClick?: boolean }
+	| {
+			readonly action: 'type'
+			readonly ref: string
+			readonly text: string
+			/** Press Enter after typing. */
+			readonly submit?: boolean
+	  }
+	| { readonly action: 'fill_form'; readonly fields: readonly BrowserFormField[] }
+	| { readonly action: 'select'; readonly ref: string; readonly values: readonly string[] }
+	| { readonly action: 'press'; readonly key: string; readonly ref?: string }
+	| { readonly action: 'hover'; readonly ref: string }
+	| { readonly action: 'upload'; readonly ref: string; readonly path: string }
+	| { readonly action: 'dialog'; readonly accept: boolean; readonly promptText?: string }
+
+/**
+ * What the `browser_act` tool asks of the host.
+ *
+ * `origin` is the page origin the model read from the snapshot header
+ * (`Page: <origin> — …`), canonicalised by the tool. **The host MUST compare
+ * it with the live origin of the page it is about to act on, immediately
+ * before acting, and throw a {@link BrowserOriginMismatch} without acting
+ * when they differ.** That comparison is what binds an approval of "click
+ * Place order on shop.example.com" to shop.example.com: a redirect between
+ * the snapshot and the click must not carry the click to another site.
+ */
+export type BrowserActAction = BrowserActOperation & {
+	readonly origin: string
+	/** Return a snapshot of the page after the action. */
+	readonly snapshot?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+/** The page an action left the browser on, as the host observed it. */
+export interface BrowserPageInfo {
+	/** Canonical origin (`https://github.com`), or `null` for `about:blank`. */
+	readonly origin: string
+	readonly url: string
+	/** The document title. Page-controlled: the tool quotes and cuts it. */
+	readonly title: string
+	/** The tab's id, e.g. `t1`. */
+	readonly tab: string
+}
+
+export interface BrowserTabInfo extends BrowserPageInfo {
+	readonly active: boolean
+}
+
+export interface BrowserSnapshot {
+	readonly page: BrowserPageInfo
+	/**
+	 * The accessibility tree as text, one element per line, each actionable
+	 * element carrying `[ref=eN]`. Page-controlled: the tool wraps it as
+	 * untrusted content.
+	 */
+	readonly text: string
+	/** Present when more text follows; pass it back as `cursor`. */
+	readonly nextCursor?: string
+}
+
+export interface BrowserScreenshot {
+	readonly page: BrowserPageInfo
+	readonly data: Uint8Array
+	readonly mimeType: 'image/png' | 'image/jpeg'
+	readonly width: number
+	readonly height: number
+}
+
+/**
+ * What an action produced. Every field is optional because actions differ;
+ * the tool renders whichever are present.
+ */
+export interface BrowserResult {
+	/** The page after the action. */
+	readonly page?: BrowserPageInfo
+	/**
+	 * The host's own note, in the host's words — "download of report.pdf
+	 * cancelled", "dialog accepted". Never page text: the tool shows it
+	 * outside the untrusted envelope.
+	 */
+	readonly message?: string
+	readonly snapshot?: BrowserSnapshot
+	readonly screenshot?: BrowserScreenshot
+	readonly tabs?: readonly BrowserTabInfo[]
+}
+
+/** What a snapshot said about one ref, for labelling a call before it runs. */
+export interface BrowserRefDescription {
+	/** ARIA role: `button`, `link`, `textbox`. */
+	readonly role: string
+	/** Accessible name. Page-controlled. */
+	readonly name?: string
+}
+
+/** Who and where, for labels and reviews. May change between calls. */
+export interface BrowserSessionInfo {
+	/** The profile the browser runs under. */
+	readonly profile?: string
+	/** Canonical origin of the active tab, when the host knows it. */
+	readonly origin?: string
+}
+
+// ---------------------------------------------------------------------------
+// Structural errors. Hosts throw values carrying these shapes; the tools
+// recognise them by shape, so a separately installed host and SDK need not
+// share an error class.
+// ---------------------------------------------------------------------------
+
+/** The live page is not on the origin a `browser_act` call named. Nothing was done. */
+export interface BrowserOriginMismatch {
+	readonly code: 'browser_origin_mismatch'
+	readonly expected: string
+	readonly actual: string
+	readonly message: string
+}
+
+/** The ref is not on the current page: it came from an older snapshot. Nothing was done. */
+export interface BrowserStaleRef {
+	readonly code: 'browser_stale_ref'
+	readonly ref: string
+	readonly message: string
+}
+
+/** Why the page needs a person. */
+export type BrowserHumanRequiredReason =
+	| 'sign-in'
+	| 'two-factor'
+	| 'captcha'
+	| 'bot-block'
+	| 'http-auth'
+	| 'credential-field'
+
+/**
+ * The page needs a person: a sign-in, a second factor, a CAPTCHA, a bot
+ * wall, or a field that takes a password or one-time code. The agent must
+ * stop and hand over; it never signs in, solves or types a credential.
+ */
+export interface BrowserHumanRequired {
+	readonly code: 'browser_human_required'
+	readonly reason: BrowserHumanRequiredReason
+	readonly origin: string
+	readonly message: string
+	readonly profile?: string
+	/** The command that opens a visible window on this profile, e.g. `namzu browser login work https://…`. */
+	readonly loginCommand?: string
+}
+
+/**
+ * A page-changing action started and did not report a clean completion. The
+ * page may already have changed, so replaying it is unsafe.
+ */
+export interface BrowserOutcomeUnknown {
+	readonly code: 'browser_outcome_unknown'
+	readonly action: BrowserActionName
+	readonly outcome: 'unknown'
+	readonly retrySafety: 'unsafe'
+	readonly message: string
+}
+
+/** The site policy does not allow this origin at the level the call needs. */
+export interface BrowserSiteDenied {
+	readonly code: 'browser_site_denied'
+	readonly origin: string
+	readonly message: string
+}
+
+export type BrowserHostError =
+	| BrowserOriginMismatch
+	| BrowserStaleRef
+	| BrowserHumanRequired
+	| BrowserOutcomeUnknown
+	| BrowserSiteDenied
+
+// ---------------------------------------------------------------------------
+// Host
+// ---------------------------------------------------------------------------
+
+export interface BrowserCallOptions {
+	/** Fires when the call is cancelled or times out. */
+	readonly signal?: AbortSignal
+}
+
+/**
+ * A browser the tools drive. Implementations live outside `@namzu/sdk`.
+ *
+ * The host is where the site policy is enforced after the fact: whatever the
+ * gate approved, the host re-checks the page a navigation, redirect or popup
+ * actually landed on, and the live origin before every `act`.
+ */
+export interface BrowserHost {
+	readonly id: string
+	readonly capabilities: BrowserCapabilities
+
+	/** Observe or navigate. Throws a {@link BrowserHostError} shape to refuse. */
+	observe(action: BrowserObserveAction, options?: BrowserCallOptions): Promise<BrowserResult>
+	/**
+	 * Change the page. MUST check `action.origin` against the live page first
+	 * (see {@link BrowserActAction}). Throws a {@link BrowserHostError} shape
+	 * to refuse.
+	 */
+	act(action: BrowserActAction, options?: BrowserCallOptions): Promise<BrowserResult>
+
+	/**
+	 * What the most recent snapshot said about `ref`, synchronously and
+	 * without touching the page, for the label a person approves. Undefined
+	 * when the ref is unknown.
+	 */
+	describeRef?(ref: string): BrowserRefDescription | undefined
+	/** The current profile and page, synchronously, for labels. */
+	session?(): BrowserSessionInfo
+
+	initialize?(): Promise<void>
+	dispose?(): Promise<void>
+}

package/src/types/session/events.ts

@@ -534,6 +534,12 @@ type CoreSessionEvent =
 			providerError?: import('../provider/error.js').ProviderErrorInfo
 			/** Curated operator copy, absent when no catalog rule matched. */
 			explanation?: { id: string; message: string; hint: string }
+			/**
+			 * Present when a tool asked for a person: its `ToolResult.handoff`.
+			 * The results of the batch are already committed; resuming the turn
+			 * calls the model with them.
+			 */
+			handoff?: import('../tool/index.js').ToolHandoff
 	  }
 	/** A paused turn continues from its checkpoint, under the same `turnId`. */
 	| {

package/src/types/session/records.ts

@@ -201,6 +201,15 @@ const providerError = z
 
 const explanation = z.object({ id: text, message: text, hint: text }).strict()
 
+/** A tool's request for a person, as `turn_paused` carries it. */
+const toolHandoff = z
+	.object({
+		kind: z.literal('human-required'),
+		reason: text,
+		detail: z.record(text).optional(),
+	})
+	.strict()
+
 const stopReason = z.enum([
 	'end_turn',
 	'token_budget',
@@ -361,6 +370,7 @@ export const TurnPausedRecordSchema = inTurn('turn_paused', {
 	providerError: providerError.optional(),
 	explanation: explanation.optional(),
 	budget: tokenBudgetSummary.optional(),
+	handoff: toolHandoff.optional(),
 })
 
 export const TurnResumingRecordSchema = inTurn('turn_resuming', {