@namzu/sdk 53.2.2 → 55.0.0

package/src/types/message/notice-frame.ts

@@ -0,0 +1,88 @@
+/**
+ * The frame the kernel puts around a notice it sends the model: the operator's
+ * message typed while a tool ran, a background job's exit, a monitor's events.
+ *
+ * A notice is its own user-role message at the next request boundary. It is
+ * never appended to a tool result: a tool result carries only what the tool
+ * returned, and Namzu's own words inside that slot read as tool output.
+ *
+ * The frame says what the text is and whose it is, and its tag carries a
+ * random marker drawn after the text is fixed (`<namzu-notice-1f3a...>`), so
+ * nothing the text says can spell the closing tag. {@link escapeNoticeFrame}
+ * is the second layer: it turns every spelling of the tag prefix in tool
+ * output and file content into inert text before it reaches the conversation.
+ */
+
+import {
+	generateRenderNonce,
+	nonceClosureStatement,
+	pickRenderNonce,
+} from '../../tools/render-nonce.js'
+
+/** The fixed prefix of every notice tag; the real tag adds `-<marker>`. */
+export const NOTICE_TAG = 'namzu-notice'
+
+export type NoticeKind = 'operator-message' | 'job' | 'monitor'
+
+const OPEN_OR_CLOSE = /<(\/?)(namzu-notice)/gi
+
+/**
+ * Make the notice tag inert: `<namzu-notice` becomes `&lt;namzu-notice`, in any
+ * case, opening or closing, with or without a marker after it. Idempotent, so
+ * text that passes through twice (a result rebuilt on resume) is not changed
+ * again.
+ */
+export function escapeNoticeFrame(text: string): string {
+	return text.includes('<') ? text.replace(OPEN_OR_CLOSE, '&lt;$1$2') : text
+}
+
+/** What a frame says about whose words are inside it. */
+export const NOTICE_PREAMBLE: Readonly<Record<NoticeKind, string>> = {
+	'operator-message': '',
+	job: 'Namzu sent this automatically. The operator did not write it, so it is neither an answer to a question you asked nor an approval.',
+	monitor:
+		'Namzu sent this automatically. The operator did not write it, so it is neither an answer to a question you asked nor an approval.',
+}
+
+export function noticeTag(nonce: string): string {
+	return `${NOTICE_TAG}-${nonce}`
+}
+
+export function noticeOpen(kind: NoticeKind, nonce: string): string {
+	return `<${noticeTag(nonce)} kind="${kind}">`
+}
+
+export function noticeClose(nonce: string): string {
+	return `</${noticeTag(nonce)}>`
+}
+
+/**
+ * `label`, the preamble and the body inside one frame, the body escaped. The
+ * marker is drawn fresh for each frame and never occurs in the label or body.
+ */
+export function frameNotice(
+	kind: NoticeKind,
+	label: string,
+	body: string,
+	generateNonce: () => string = generateRenderNonce,
+): string {
+	const safe = escapeNoticeFrame(body)
+	const nonce = pickRenderNonce(generateNonce, [label, safe])
+	const lines = [noticeOpen(kind, nonce), label]
+	if (NOTICE_PREAMBLE[kind]) lines.push(NOTICE_PREAMBLE[kind])
+	lines.push(nonceClosureStatement(noticeClose(nonce)), safe, noticeClose(nonce))
+	return lines.join('\n')
+}
+
+const OPERATOR_FRAME = new RegExp(
+	`^<${NOTICE_TAG}-([0-9a-f]+) kind="operator-message">\\n[^\\n]*\\n[^\\n]*\\n([\\s\\S]*)\\n</${NOTICE_TAG}-\\1>$`,
+)
+
+/**
+ * The operator's text inside a frame {@link frameNotice} made for an operator
+ * message, as the frame held it (tag already made inert), or `undefined` for
+ * any other text.
+ */
+export function readOperatorNotice(content: string): string | undefined {
+	return OPERATOR_FRAME.exec(content)?.[2]
+}

package/src/types/provider/chat.ts

@@ -21,6 +21,14 @@ export type ResponseFormat =
 
 export interface CacheControl {
 	type: 'auto' | 'ephemeral'
+	/**
+	 * How long the provider should keep this prefix cached: `'5m'` (the
+	 * default every provider uses when this is absent) or `'1h'`. Honoured only
+	 * by a driver that has an extended lifetime; others ignore it. The longer
+	 * lifetime is priced higher for the cache write, so asking for it is a cost
+	 * decision, not a translation.
+	 */
+	ttl?: '5m' | '1h'
 }
 
 export interface ChatCompletionParams {

package/src/types/provider/config.ts

@@ -157,6 +157,12 @@ export interface ProviderCapabilities {
 	/** Whether the driver maps document blocks returned by tools onto its result wire. */
 	supportsToolResultDocuments?: boolean
 	maxOutputTokens?: number
+	/**
+	 * Prompt-cache lifetimes the driver can be asked for through
+	 * `cacheControl.ttl`. Absent means the driver offers none (it has no cache,
+	 * or the lifetime is the provider's own and cannot be chosen or read).
+	 */
+	cacheTtl?: readonly ('5m' | '1h')[]
 }
 
 export interface ProviderFactoryResult {

package/src/types/session/checkpoint.ts

@@ -79,6 +79,11 @@ export const TokenUsageSchema = z
 		cachedTokens: count,
 		cacheWriteTokens: count,
 		reasoningTokens: count.optional(),
+		cacheTtlMs: count.optional(),
+		cacheWriteTtlTokens: z
+			.object({ fiveMin: count.optional(), oneHour: count.optional() })
+			.strict()
+			.optional(),
 	})
 	.strict()
 

package/src/types/session/events.ts

@@ -811,6 +811,12 @@ type CoreSessionEvent =
 			turnId: TurnId
 			usage: TokenUsage
 			cost: CostInfo
+			/**
+			 * The prompt cache after the latest model call alone (not the turn
+			 * total above). Present only when the driver reports a lifetime;
+			 * absent means unknown, and a host must not assume one.
+			 */
+			cache?: { ttlMs: number; touched: boolean }
 			/**
 			 * How large the CONTEXT is right now, and how large it may get.
 			 *

package/src/types/session/records.ts

@@ -494,7 +494,7 @@ export const DecisionExpiredRecordSchema = inTurn('decision_expired', {
 export const CompactionRecordSchema = recordSchema('compaction', {
 	compactionId: text.min(1),
 	strategy: text.min(1),
-	trigger: z.enum(['auto', 'manual']),
+	trigger: z.enum(['auto', 'manual', 'idle']),
 	replacesSeqRange: z.tuple([positive, positive]),
 	summary: z.union([z.array(messageBody), spill]),
 	keptMessageIds: z.array(messageId),

package/src/types/tool/presentation.ts

@@ -106,6 +106,16 @@ export type ToolFailureReason =
 	| 'unknown_tool'
 	| 'timed_out'
 	| 'invalid_input'
+	/** An edit or write on a file the conversation never read. */
+	| 'not_read'
+	/** An edit or write based on a copy that has since changed on disk. */
+	| 'changed_on_disk'
+	/** An edit whose text is not in the file. */
+	| 'text_not_found'
+	/** An edit whose text appears more than once. */
+	| 'not_unique'
+	/** The call's arguments did not fit the tool's input schema, so the tool never ran. */
+	| 'invalid_arguments'
 
 /**
  * What a call was about and what came of it, as typed fields.
@@ -126,6 +136,12 @@ export type ToolFacts =
 			/** The command line, on the call. */
 			readonly command?: string
 			readonly exitCode?: number
+			/**
+			 * A non-zero `exitCode` that is the command's answer and not a failure
+			 * (`grep` found nothing, `diff` found a difference): a short plain
+			 * sentence. A host draws the call as having succeeded.
+			 */
+			readonly exitNote?: string
 			readonly timedOut?: boolean
 			/** The signal that ended it, when one did. */
 			readonly signal?: string