@namzu/sdk 62.6.0 → 62.7.0

package/src/types/session/records.ts

@@ -25,6 +25,7 @@ import {
 	type SessionEvent,
 	type SessionEventType,
 } from './events.js'
+import type { TurnSettlement } from './turn.js'
 
 /**
  * The session log: one append-only, hash-chained JSONL file per session, the
@@ -594,6 +595,49 @@ export const AccountBoundRecordSchema = recordSchema('account_bound', {
 	reason: z.enum(['start', 'user_switch', 'limit_switch']),
 })
 
+/**
+ * The three records below carry the turn's outcome record
+ * (`docs/sdk/turn-outcome.md`). Each is `ignorable: true`: a release that does
+ * not know the type keeps it in the hash chain and skips it (see
+ * `IgnorableRecordSchema`), so a log written with them still reads there and
+ * loses only the outcome. None of them may become a field of a record that
+ * existed before them, because a release that validates that record strictly
+ * would refuse the whole log. The body is checked only for being an object
+ * here; `TurnOutcomeSchema` judges it where it is read back, so a later
+ * release may widen it without making this one refuse the log.
+ */
+const outcomeBody = z.custom<Readonly<Record<string, unknown>>>(isPlainObject, {
+	message: 'expected an object',
+})
+
+/** A turn's final outcome, written just before its `turn_completed` or `turn_failed`. */
+export const TurnOutcomeRecordedRecordSchema = inTurn('turn_outcome_recorded', {
+	ignorable: z.literal(true),
+	outcome: outcomeBody,
+})
+
+/**
+ * A delegated child's outcome, written in the parent's log just before the
+ * child's `child_session_ended`. Carries the spawning turn's id only while that
+ * turn is open, as `child_session_ended` does.
+ */
+export const ChildOutcomeRecordedRecordSchema = recordSchema('child_outcome_recorded', {
+	ignorable: z.literal(true),
+	childSessionId: sessionId,
+	outcome: outcomeBody,
+})
+
+/**
+ * What the turn's outcome record had gathered when a checkpoint was written,
+ * so a resume can restore it. Written just before the `checkpoint_written`
+ * record of the same `checkpointId`.
+ */
+export const OutcomeProgressWrittenRecordSchema = inTurn('outcome_progress_written', {
+	ignorable: z.literal(true),
+	checkpointId,
+	progress: outcomeBody,
+})
+
 export const LogRepairedRecordSchema = recordSchema('log_repaired', {
 	truncatedBytes: positive,
 	lastGoodSeq: positive,
@@ -632,6 +676,9 @@ const RECORD_ONLY_SCHEMAS = {
 	budget_bound: BudgetBoundRecordSchema,
 	account_bound: AccountBoundRecordSchema,
 	log_repaired: LogRepairedRecordSchema,
+	turn_outcome_recorded: TurnOutcomeRecordedRecordSchema,
+	child_outcome_recorded: ChildOutcomeRecordedRecordSchema,
+	outcome_progress_written: OutcomeProgressWrittenRecordSchema,
 } as const
 
 export type SessionRecordOnlyType = keyof typeof RECORD_ONLY_SCHEMAS
@@ -1006,8 +1053,21 @@ type EventOf<T extends SessionEventType> = Extract<SessionEvent, { type: T }>
  */
 export type SessionEventRecord<T extends PersistedSessionEventType = PersistedSessionEventType> =
 	T extends PersistedSessionEventType
-		? Omit<EventOf<T>, 'sessionId' | 'turnId' | 'lineage' | 'v' | 'seq' | 'generation'> &
+		? Omit<
+				EventOf<T>,
+				| 'sessionId'
+				| 'turnId'
+				| 'lineage'
+				| 'v'
+				| 'seq'
+				| 'generation'
+				// The live settlement carries the outcome record; the log's does not.
+				| (T extends 'turn_completed' | 'turn_failed' ? 'settlement' : never)
+			> &
 				RecordEnvelope &
+				(T extends 'turn_completed' | 'turn_failed'
+					? { readonly settlement: TurnSettlement }
+					: unknown) &
 				(T extends 'tool_completed'
 					? {
 							readonly structuredResultSpill?: z.infer<typeof structuredResultSpill>
@@ -1036,6 +1096,9 @@ 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 TurnOutcomeRecordedRecord = z.infer<typeof TurnOutcomeRecordedRecordSchema>
+export type ChildOutcomeRecordedRecord = z.infer<typeof ChildOutcomeRecordedRecordSchema>
+export type OutcomeProgressWrittenRecord = z.infer<typeof OutcomeProgressWrittenRecordSchema>
 
 export type SessionRecordOnly =
 	| SessionStartedRecord
@@ -1053,6 +1116,9 @@ export type SessionRecordOnly =
 	| BudgetBoundRecord
 	| AccountBoundRecord
 	| LogRepairedRecord
+	| TurnOutcomeRecordedRecord
+	| ChildOutcomeRecordedRecord
+	| OutcomeProgressWrittenRecord
 
 /** One line of a session log. */
 export type SessionRecord = SessionEventRecord | SessionRecordOnly

package/src/types/session/turn.ts

@@ -11,6 +11,7 @@ import type {
 import type { Message } from '../message/index.js'
 import type { ProviderErrorInfo } from '../provider/index.js'
 import type { TurnConfig } from './config.js'
+import type { TurnOutcome } from './outcome.js'
 import type { StepResult } from './step.js'
 import type { StopReason } from './stop-reason.js'
 
@@ -151,6 +152,22 @@ export interface TurnSettlement {
 	readonly abandonedJobIds: readonly string[]
 }
 
+/**
+ * The settlement a live `turn_completed` or `turn_failed` event carries: the
+ * persisted {@link TurnSettlement} plus the turn's outcome record. The record
+ * is in memory only here. The session log keeps it in its own records
+ * (`turn_outcome_recorded`), never in the settlement, so a release that
+ * validates the settlement strictly still reads the log.
+ */
+export interface LiveTurnSettlement extends TurnSettlement {
+	/**
+	 * What the turn changed and what checked it, from its own tool calls. Absent
+	 * for a turn that never ran the loop and one resumed from a checkpoint that
+	 * did not keep the record.
+	 */
+	readonly outcome?: TurnOutcome
+}
+
 /** Metadata of one turn: who ran it, with what, and where it sits in the session tree. */
 export interface TurnMetadata {
 	/** This turn's owner, independent of a shared ancestor token account. */
@@ -216,6 +233,8 @@ export interface Turn {
 	abandonedTaskIds?: readonly string[]
 	/** Background jobs the model awaited that were still running when this turn ended. */
 	abandonedJobIds?: readonly string[]
+	/** What the turn changed and what checked it; see {@link LiveTurnSettlement.outcome}. */
+	outcome?: TurnOutcome
 	/** Present on a child session's turn. */
 	parentSessionId?: SessionId
 	/** Present on a child session's turn. */

package/src/types/tool/index.ts

@@ -331,6 +331,25 @@ export interface FileReadTracker {
 	 * chain is cleared. Pass ToolContext.toolUseId only after the edit succeeded.
 	 */
 	recordEdit?(key: string, content: string, callId: string): void
+	/**
+	 * Optional: the fingerprint of the content the agent itself last put in
+	 * the file at `key` through a full write or an edit, if it did. A file the
+	 * agent only read, or never touched, has none. Shell redirection is not
+	 * seen here: such a file is of unknown authorship. Used by the auto-mode
+	 * classifier to tell a script the agent wrote from one it did not.
+	 */
+	authoredFingerprint?(key: string): string | undefined
+	/** Optional: when this ledger began, in milliseconds since the epoch. */
+	readonly startedAt?: number
+	/**
+	 * Optional: the ledger a delegated child starts with. Its own read record,
+	 * empty, because what a child has read is not what its parent or a sibling
+	 * has, and the stale-write refusal compares the disk to the reader's own
+	 * reads. What the family authored ({@link authoredFingerprint},
+	 * {@link startedAt}) is shared with it. A tracker without this is not
+	 * handed to a child.
+	 */
+	forChild?(): FileReadTracker
 	/**
 	 * Optional witness of a read that returned the file WHOLE, with the
 	 * fingerprint of the rendering it returned.
@@ -1364,6 +1383,17 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * explicitly still bounds this tool's result by it.
 	 */
 	selfLimitingOutput?: boolean
+	/**
+	 * A tighter model-visible cap, in characters, for THIS tool's result.
+	 *
+	 * The turn's cap (`maxToolOutputChars`, 40,000 by default) still applies;
+	 * the smaller of the two wins, including when a host turned the turn cap
+	 * off with `0`. A result over it is kept in the session's tool-results
+	 * folder and shown as a head-and-tail preview that names the file, the same
+	 * way any other oversized result is. Use it for a tool whose results are
+	 * foreign text that should cost less of the window than a file read does.
+	 */
+	maxOutputChars?: number
 }
 
 /**