@namzu/sdk 62.6.1 → 62.8.0

package/src/types/session/outcome.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod'
+
+/**
+ * How a turn came out, from the kernel's own record of its tool calls.
+ *
+ * `checked` says a recognised check passed on the workspace as the turn left
+ * it. It does not say the check covers the change.
+ */
+export type TurnOutcomeVerdict =
+	/** Nothing in the workspace differs from the start of the turn. */
+	| 'unchanged'
+	/** Changed; at least one check passed on the final state and none is left failing. */
+	| 'checked'
+	/** Changed; checks passed, but the workspace changed again after the last pass. */
+	| 'stale'
+	/** Some check's latest run did not pass. Changed or not. */
+	| 'failing'
+	/** Changed; checks ran but none established a pass (status hidden, background, timed out, or unknown freshness). */
+	| 'inconclusive'
+	/** Changed; no check ran. */
+	| 'unchecked'
+	/**
+	 * Whether anything changed cannot be told: no write tool ran, but a command
+	 * that may have changed files did, and no workspace detector answered.
+	 */
+	| 'unknown'
+
+/** What one check established. */
+export type TurnOutcomeCheckResult =
+	/** Exit status 0, and the status is the check's own. */
+	| 'passed'
+	/** Non-zero exit, refused, or errored. */
+	| 'failed'
+	/** The command line lets something else decide the exit status: a pipe, `;`, `||`, a trailing `&`. */
+	| 'masked'
+	/** Handed to a background job, continued, timed out, or its status was never seen. */
+	| 'unsettled'
+
+export interface TurnOutcomeCheck {
+	/** As run, clipped. */
+	readonly command: string
+	/** The loop step the latest run of this command finished in. */
+	readonly step: number
+	readonly result: TurnOutcomeCheckResult
+	readonly exitCode?: number
+	/**
+	 * True when the workspace is the same now as when this check finished. False
+	 * when it is known to have changed since. Absent when that cannot be told.
+	 */
+	readonly fresh?: boolean
+}
+
+export interface TurnOutcome {
+	readonly verdict: TurnOutcomeVerdict
+	/**
+	 * How the workspace was observed. `calls`: only the kernel's own write tools
+	 * were seen, so a change made by a shell command or another tool is invisible
+	 * and `unchanged` means only that no write tool ran. `workspace`: the host
+	 * supplied a change detector and the start, each check and the end were
+	 * compared with it.
+	 */
+	readonly basis: 'calls' | 'workspace'
+	readonly changes: {
+		/** Distinct paths the turn's write tools changed, or the number of write calls when some had no path. */
+		readonly total: number
+		/** The first of them, bounded. */
+		readonly paths: readonly string[]
+		/** The workspace moved and no write tool call explains it. */
+		readonly outsideKnownTools: boolean
+	}
+	/** In order of first run; the latest run of each distinct command; bounded. */
+	readonly checks: readonly TurnOutcomeCheck[]
+	/** How many distinct checks ran, when `checks` was cut. */
+	readonly checksTotal?: number
+}
+
+/** Host hooks for the turn's outcome record. */
+export interface TurnOutcomeConfig {
+	/**
+	 * A fingerprint of the workspace, or `null` when it cannot be told.
+	 * `fingerprintWorkspace` is the kernel's own. `null` is never a match.
+	 * Called before the first call of the turn that could change the workspace,
+	 * after each check, and once when the turn ends; never in a turn whose calls
+	 * are all provably read-only.
+	 */
+	readonly detectChanges?: () => Promise<string | null>
+	/** Names a command that checks work, beyond the ones the kernel recognises. */
+	readonly isCheck?: (command: string) => boolean
+	/** Deadline per detector call. A detector that is late is `null`. Default 3000. */
+	readonly detectTimeoutMs?: number
+}
+
+/** Bounds on a recorded outcome. */
+export const OUTCOME_MAX_PATHS = 50
+export const OUTCOME_MAX_CHECKS = 20
+export const OUTCOME_MAX_COMMAND_CHARS = 300
+export const OUTCOME_MAX_PATH_CHARS = 300
+export const OUTCOME_DEFAULT_DETECT_TIMEOUT_MS = 3000
+
+const verdict = z.enum([
+	'unchanged',
+	'checked',
+	'stale',
+	'failing',
+	'inconclusive',
+	'unchecked',
+	'unknown',
+])
+const count = z.number().int().nonnegative().safe()
+
+/** The shape a recorded outcome must have to be written to, or read back from, the session log. */
+export const TurnOutcomeSchema: z.ZodType<TurnOutcome, unknown> = z
+	.object({
+		verdict,
+		basis: z.enum(['calls', 'workspace']),
+		changes: z
+			.object({
+				total: count,
+				// One more than the bound: a clipped path ends in an ellipsis.
+				paths: z.array(z.string().max(OUTCOME_MAX_PATH_CHARS + 1)).max(OUTCOME_MAX_PATHS),
+				outsideKnownTools: z.boolean(),
+			})
+			.strict(),
+		checks: z
+			.array(
+				z
+					.object({
+						command: z.string().max(OUTCOME_MAX_COMMAND_CHARS + 1),
+						step: count,
+						result: z.enum(['passed', 'failed', 'masked', 'unsettled']),
+						exitCode: z.number().int().safe().optional(),
+						fresh: z.boolean().optional(),
+					})
+					.strict(),
+			)
+			.max(OUTCOME_MAX_CHECKS),
+		checksTotal: count.optional(),
+	})
+	.strict()

package/src/types/session/prepare-step.ts

@@ -285,6 +285,8 @@ export interface RecalledMemory {
 	 * Absent when no selector ran; the words of the request chose it.
 	 */
 	readonly reason?: string
+	/** Set when the host's check found the record may no longer hold, e.g. `may be out of date: a file it names is gone`. */
+	readonly caution?: string
 }
 
 /**

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
 }
 
 /**

package/src/types/tool/presentation.ts

@@ -220,6 +220,12 @@ export type ToolFacts =
 			readonly reason: ToolFailureReason
 			/** What it was about: a path, or the tool's name for `unknown_tool`. */
 			readonly subject?: string
+			/**
+			 * Why a refused call did not run, as one plain line the kernel wrote
+			 * (a policy rule, the command guard). Absent when no reason was
+			 * recorded; a host shows nothing for it rather than a guess.
+			 */
+			readonly note?: string
 	  }
 
 /** The same shapes, for what a call produced. */