@namzu/sdk 59.0.0 → 60.1.0

package/src/types/session/events.ts

@@ -102,7 +102,12 @@ type CoreSessionEvent =
 			/** The token ledger this turn spends from, keyed by the root turn. */
 			budget?: TurnBudgetBinding
 	  }
-	| { type: 'iteration_started'; sessionId: SessionId; turnId: TurnId; iteration: number }
+	| {
+			type: 'iteration_started'
+			sessionId: SessionId
+			turnId: TurnId
+			iteration: number
+	  }
 	/**
 	 * Who answers when this turn asks a human, changed mid-turn.
 	 *
@@ -454,6 +459,40 @@ type CoreSessionEvent =
 			 */
 			restart?: boolean
 	  }
+	/**
+	 * The model declined to answer, and what the turn did about it.
+	 *
+	 * The provider finished a reply as a refusal or a safety block. The refused
+	 * reply is kept out of the history sent next. `outcome` says what followed:
+	 *
+	 * - `'fallback'`: the request is being re-run on `fallbackModel`, which the
+	 *   rest of the turn keeps. A host that owns the session's model is expected
+	 *   to keep it for later turns too and to say so.
+	 * - `'retry'`: no other model was available and the refused reply had
+	 *   partial output, so the request is being re-run once on the same model
+	 *   with a note that the previous reply was stopped.
+	 * - `'declined'`: nothing recovered it. The turn settles with stop reason
+	 *   `'refused'`.
+	 *
+	 * Like `provider_fallback`, this is the feature's honesty: a swapped model
+	 * must be shown, not logged. It is emitted before the re-run starts.
+	 */
+	| {
+			type: 'model_refusal'
+			sessionId: SessionId
+			turnId: TurnId
+			iteration: number
+			/** The model that declined. */
+			model: string
+			providerId: string
+			outcome: 'fallback' | 'retry' | 'declined'
+			/** The model the request moves to. Set only with `outcome: 'fallback'`. */
+			fallbackModel?: string
+			/** The provider's own classification, when it gave one. */
+			category?: string
+			/** The provider's own sentence, when it gave one. Show it; do not parse it. */
+			explanation?: string
+	  }
 	| {
 			type: 'tool_completed'
 			/** Bounded result view; omitted when output was overridden or truncated. */
@@ -892,7 +931,12 @@ type CoreSessionEvent =
 			steps: PlanStep[]
 			summary?: string
 	  }
-	| { type: 'plan_approved'; sessionId: SessionId; turnId: TurnId; planId: PlanId }
+	| {
+			type: 'plan_approved'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+	  }
 	| {
 			type: 'plan_rejected'
 			sessionId: SessionId
@@ -923,7 +967,12 @@ type CoreSessionEvent =
 	 * through `onContextCreated`, so they proved the plan settled without ever
 	 * asking whether a consumer of the EVENT STREAM could see it.
 	 */
-	| { type: 'plan_completed'; sessionId: SessionId; turnId: TurnId; planId: PlanId }
+	| {
+			type: 'plan_completed'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+	  }
 	/**
 	 * The plan is over and it did not finish.
 	 *
@@ -931,7 +980,13 @@ type CoreSessionEvent =
 	 * an event that says "failed" without saying why puts the reader back
 	 * where the missing event did.
 	 */
-	| { type: 'plan_failed'; sessionId: SessionId; turnId: TurnId; planId: PlanId; reason?: string }
+	| {
+			type: 'plan_failed'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+			reason?: string
+	  }
 	| {
 			type: 'agent_pending'
 			sessionId: SessionId
@@ -1103,7 +1158,12 @@ type CoreSessionEvent =
 			exitCode: number
 			durationMs: number
 	  }
-	| { type: 'sandbox_destroyed'; sessionId: SessionId; turnId?: TurnId; sandboxId: SandboxId }
+	| {
+			type: 'sandbox_destroyed'
+			sessionId: SessionId
+			turnId?: TurnId
+			sandboxId: SandboxId
+	  }
 	// ─────────────────────────────────────────────────────────────────────
 	// v3 message + tool-input lifecycle (additive 2026-05; see
 	// ses_001-tool-stream-events). These are not yet emitted by the

package/src/types/session/records.ts

@@ -236,6 +236,7 @@ const stopReason = z.enum([
 	'step_refused',
 	'structured_output_failed',
 	'output_limit',
+	'refused',
 	'answer_rejected',
 	'input_guardrail',
 	'output_guardrail',
@@ -278,7 +279,9 @@ export const TurnSettlementSchema = z
 const completedSettlement = TurnSettlementSchema.extend({
 	status: z.enum(['completed', 'cancelled']),
 })
-const failedSettlement = TurnSettlementSchema.extend({ status: z.literal('failed') })
+const failedSettlement = TurnSettlementSchema.extend({
+	status: z.literal('failed'),
+})
 
 /** A body too large for one record, written (and fsynced) to `tool-results/` before the record. */
 const spill = z
@@ -653,6 +656,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	hosted_tool: true,
 	provider_retry: true,
 	provider_fallback: true,
+	model_refusal: true,
 	tool_completed: true,
 	user_question_asked: true,
 	user_question_answered: true,
@@ -747,6 +751,7 @@ const TURN_BOUND_OTHER_TYPE_LIST = [
 	'hosted_tool',
 	'provider_retry',
 	'provider_fallback',
+	'model_refusal',
 	'tool_completed',
 	'user_question_asked',
 	'user_question_answered',
@@ -798,6 +803,36 @@ const RECORD_OPTIONS = [
 	...z.ZodDiscriminatedUnionOption<'type'>[],
 ]
 
+/**
+ * A record of a type this reader does not know, written by a newer writer
+ * that flagged it `ignorable: true`: a promise that no reader needs it to
+ * rebuild the conversation. It is kept in the hash chain and verified like any
+ * other record, but never moves the fold. A known type never qualifies (its
+ * own schema decides), and an unknown type without the flag is still refused,
+ * so a record that does move the fold fails loudly on an older reader.
+ */
+export const IgnorableRecordSchema = z
+	.object({
+		...envelopeShape,
+		type: z
+			.string()
+			.min(1)
+			.refine((type) => !(SESSION_RECORD_TYPES as readonly string[]).includes(type), {
+				message: 'a type this reader knows is validated by its own schema',
+			}),
+		ignorable: z.literal(true),
+	})
+	.passthrough()
+	.superRefine((record, context) => {
+		if (record.seq === 1 || record.prev === null) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['type'],
+				message: 'session_started is the first record of a session log, and only the first',
+			})
+		}
+	})
+
 /** Validates one session record: envelope, discriminant, and every specified payload. */
 export const SessionRecordSchema = z
 	.discriminatedUnion('type', RECORD_OPTIONS)
@@ -973,7 +1008,9 @@ export type SessionEventRecord<T extends PersistedSessionEventType = PersistedSe
 		? Omit<EventOf<T>, 'sessionId' | 'turnId' | 'lineage' | 'v' | 'seq' | 'generation'> &
 				RecordEnvelope &
 				(T extends 'tool_completed'
-					? { readonly structuredResultSpill?: z.infer<typeof structuredResultSpill> }
+					? {
+							readonly structuredResultSpill?: z.infer<typeof structuredResultSpill>
+						}
 					: T extends 'turn_completed'
 						? {
 								readonly resultSpill?: z.infer<typeof spill>

package/src/types/session/stop-reason.ts

@@ -53,6 +53,17 @@ export type StopReason =
 	 * looking for a loop instead of at the reviewer.
 	 */
 	| 'answer_rejected'
+	/**
+	 * The model declined to answer and nothing recovered it.
+	 *
+	 * Its provider finished the reply as a refusal or a safety block, and the
+	 * one automatic retry this turn allows was not available or was refused
+	 * too. Distinct from `end_turn` so a host never reads a declined request
+	 * as a finished one, and from `error` because nothing failed: the model
+	 * answered, and the answer was no. The refused reply is not in the
+	 * history; a `model_refusal` event carries what the provider said.
+	 */
+	| 'refused'
 	/** An input guardrail refused the turn before it started. */
 	| 'input_guardrail'
 	/** An output guardrail refused the produced result. */

package/src/types/tool/index.ts

@@ -173,6 +173,8 @@ export interface BackgroundJobRegistryRef {
 		status: string
 		exitCode?: number
 		error?: string
+		/** When it last wrote output (epoch ms); absent until it has. */
+		lastOutputAt?: number
 	}
 	/**
 	 * Take over a process the caller already started and is waiting on, so a
@@ -224,7 +226,19 @@ export interface BackgroundJobRegistryRef {
 		kind?: 'monitor'
 		/** What a monitor watches. */
 		description?: string
+		/** When the job started (epoch ms). Optional for hosts that do not keep it. */
+		startedAt?: number
+		/** When it last wrote output (epoch ms); absent until it has. */
+		lastOutputAt?: number
+		/** Its last non-empty output line, flattened and clipped. */
+		lastOutputLine?: string
 	}[]
+	/**
+	 * Whether the job's process is still there, asked of the system rather than
+	 * taken from the record. Optional: a host that cannot probe omits it, and a
+	 * running job is then reported as alive on the registry's word.
+	 */
+	isAlive?(id: string): boolean
 	/**
 	 * Await this job's exit instead of reading it in a loop; resolves at
 	 * once for a job that has already stopped. Optional, and added after
@@ -259,6 +273,13 @@ export interface BackgroundJobRegistryRef {
 	 * intent, and then there is simply no hold.
 	 */
 	markAwaited?(id: string): void
+	/**
+	 * Say that this job's exit and output have just been handed to the model by
+	 * a tool result (`wait_for_job` returning the exit, `job` read of a stopped
+	 * job), so the exit notice that would announce the same exit is withdrawn
+	 * instead of repeating it. Optional for the reason `markAwaited` is.
+	 */
+	markCollected?(id: string): void
 }
 
 /**
@@ -514,6 +535,15 @@ export interface ToolContext {
 	 * directory; an absolute path inside any of these is accepted.
 	 */
 	additionalDirectories?: readonly string[]
+	/**
+	 * Whether the session's read rules deny an absolute path. The search tools
+	 * (`grep`, `glob`) call it for every file they would list or open and skip
+	 * a denied one, so a search over a folder holding a denied file succeeds
+	 * without showing or reading it. The executor supplies it from the turn's
+	 * authorization gate (what the `read` tool would be told for that path);
+	 * absent, no rules apply.
+	 */
+	readDenied?: (absolutePath: string) => boolean
 	/**
 	 * Absolute path of the directory holding THIS session's retained tool
 	 * output (the files an oversized result was saved to). The `read` tool may

package/src/types/tool/presentation.ts

@@ -175,6 +175,10 @@ export type ToolFacts =
 			readonly filesMatched?: number
 			readonly filesSearched?: number
 			readonly truncated?: boolean
+			/** A page or result cap cut the list; more results exist. */
+			readonly limited?: boolean
+			/** The search stopped before every file was examined. */
+			readonly incomplete?: boolean
 	  }
 	| {
 			readonly kind: 'list'
@@ -182,6 +186,10 @@ export type ToolFacts =
 			readonly path?: string
 			readonly count?: number
 			readonly truncated?: boolean
+			/** A result cap cut the list; more files match. */
+			readonly limited?: boolean
+			/** The search stopped before every file was examined. */
+			readonly incomplete?: boolean
 	  }
 	| {
 			readonly kind: 'edit'