@namzu/sdk 56.0.1 → 56.2.0

package/src/types/message/index.ts

@@ -371,6 +371,7 @@ export const RUNTIME_CONTEXT_MESSAGE_KINDS = [
 	'step-context',
 	'structured-output',
 	'task-completion',
+	'turn-context',
 ] as const
 
 export type RuntimeContextMessageKind = (typeof RUNTIME_CONTEXT_MESSAGE_KINDS)[number]
@@ -381,8 +382,18 @@ export interface RuntimeContextMessageSource {
 	readonly kind: RuntimeContextMessageKind
 	/** Optional durable host delivery identity; it never grants operator authority. */
 	readonly deliveryRef?: InboundDeliveryRef
+	/**
+	 * What a `turn-context` entry reports (for example `repository`). A later
+	 * entry with the same key adds to or replaces what an earlier one said.
+	 */
+	readonly key?: string
 }
 
+/** The longest key a recorded context entry may carry. */
+export const MAX_TURN_CONTEXT_KEY_LENGTH = 64
+
+const TURN_CONTEXT_KEY = /^[a-z][a-z0-9-]*$/
+
 export type UserMessageSource =
 	| GoalRoundMessageSource
 	| ProjectInstructionMessageSource
@@ -437,12 +448,14 @@ export function isRuntimeContextMessageSource(
 		readonly type?: unknown
 		readonly kind?: unknown
 		readonly deliveryRef?: unknown
+		readonly key?: unknown
 	}
 	return (
 		candidate.type === 'runtime-context' &&
 		typeof candidate.kind === 'string' &&
 		(RUNTIME_CONTEXT_MESSAGE_KINDS as readonly string[]).includes(candidate.kind) &&
-		(candidate.deliveryRef === undefined || isInboundDeliveryRef(candidate.deliveryRef))
+		(candidate.deliveryRef === undefined || isInboundDeliveryRef(candidate.deliveryRef)) &&
+		(candidate.key === undefined || isTurnContextKey(candidate.key))
 	)
 }
 
@@ -640,6 +653,100 @@ export function createRuntimeContextMessage(
 	})
 }
 
+/** Whether `value` is a name a recorded context entry may be filed under. */
+export function isTurnContextKey(value: unknown): value is string {
+	return (
+		typeof value === 'string' &&
+		value.length <= MAX_TURN_CONTEXT_KEY_LENGTH &&
+		TURN_CONTEXT_KEY.test(value)
+	)
+}
+
+function localTime(at: Date): string {
+	const pad = (n: number) => String(n).padStart(2, '0')
+	return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`
+}
+
+/**
+ * Build a recorded context entry: text a step learned for this turn that
+ * stays in the conversation, after whatever came before it, so later requests
+ * keep beginning with it. The header is written into the content once and the
+ * entry is never edited afterwards; a later entry under the same key says what
+ * changed. It is not an operator message and carries no authority.
+ *
+ * The first entry under a key says that a later one adds to or replaces it;
+ * with `later` set, for an entry that follows another under the same key, the
+ * header leaves that sentence out, since the conversation already holds it.
+ */
+export function createTurnContextEntry(
+	key: string,
+	text: string,
+	at: Date = new Date(),
+	options: { readonly later?: boolean } = {},
+): UserMessage {
+	if (!isTurnContextKey(key))
+		throw new TypeError('A recorded context key is lowercase words joined by hyphens.')
+	const label = `Recorded context (runtime-generated; not a new user request) - ${key}, as of ${localTime(at)}`
+	return createUserMessage(
+		`${label}${options.later ? ':' : '. A later entry with this key adds to or replaces what it says:'}\n${text}`,
+		undefined,
+		{ type: 'runtime-context', kind: 'turn-context', key },
+	)
+}
+
+/** The key a recorded context entry is filed under, or undefined for any other message. */
+export function turnContextKey(message: { readonly role: string; readonly source?: unknown }):
+	| string
+	| undefined {
+	if (message.role !== 'user') return undefined
+	const source = message.source as RuntimeContextMessageSource | undefined
+	return source?.type === 'runtime-context' && source.kind === 'turn-context'
+		? source.key
+		: undefined
+}
+
+/** Whether `message` is a recorded context entry. */
+export function isTurnContextEntry(message: {
+	readonly role: string
+	readonly source?: unknown
+}): boolean {
+	if (message.role !== 'user') return false
+	const source = message.source as RuntimeContextMessageSource | undefined
+	return source?.type === 'runtime-context' && source.kind === 'turn-context'
+}
+
+/**
+ * What a step recorded under `key`, oldest first, without each entry's header.
+ * A history that was compacted holds only the entries the compaction kept, so
+ * an empty list means the step may say everything again.
+ */
+export function turnContextEntries(messages: readonly Message[], key: string): readonly string[] {
+	const bodies: string[] = []
+	for (const message of messages) {
+		if (turnContextKey(message) !== key || typeof message.content !== 'string') continue
+		bodies.push(message.content.slice(message.content.indexOf('\n') + 1))
+	}
+	return bodies
+}
+
+/**
+ * The text of the newest user-role message with plain text, skipping recorded
+ * context entries: a history that ends in one (a resumed session) must not
+ * take the host's own recalled text for the question.
+ */
+export function lastPromptText(messages: readonly Message[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i]
+		if (
+			message?.role === 'user' &&
+			typeof message.content === 'string' &&
+			!isTurnContextEntry(message)
+		)
+			return message.content
+	}
+	return ''
+}
+
 /** Build the retained user-context message that carries live project policy. */
 export function createProjectInstructionMessage(
 	content: string,

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

@@ -227,10 +227,36 @@ export interface PrepareStepResult {
 	 */
 	readonly context?: string
 
+	/**
+	 * Text to keep in the conversation from this step on, filed under a key.
+	 *
+	 * Where `context` is gone after the request, an item here becomes a
+	 * recorded entry appended after whatever the history ends with, so every
+	 * later request (of this turn and of the next turns) begins with it and a
+	 * caching provider keeps reading the same prefix. Entries are never edited
+	 * or moved; a step that has something new says only that, under the same
+	 * key, and reads what it said before with `turnContextEntries`. An item
+	 * whose text is empty, or equal to the last entry under its key, adds
+	 * nothing. Entries are ordinary history to compaction, which drops them
+	 * with the messages around them, after which a step sees none and may say
+	 * everything again.
+	 *
+	 * The model reads an entry as recorded context the host generated, not as
+	 * something the operator said, and a person is never shown one.
+	 */
+	readonly recordedContext?: readonly RecordedContextItem[]
+
 	readonly temperature?: number
 	readonly maxResponseTokens?: number
 }
 
+/** One piece of text a step asks to have recorded, under what it reports. */
+export interface RecordedContextItem {
+	/** Lowercase words joined by hyphens (for example `repository`). */
+	readonly key: string
+	readonly text: string
+}
+
 /**
  * Called before each model call, with everything the turn has produced so
  * far.

package/src/types/tool/index.ts

@@ -1050,6 +1050,24 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * the safe direction to be wrong in.
 	 */
 	pathArgument?: string
+	/**
+	 * A refusal that needs no person's answer: the call cannot run as it stands,
+	 * and the tool can already tell.
+	 *
+	 * Asked once the arguments are valid and BEFORE the call is put to a
+	 * reviewer, so a person is never asked to approve a change that would be
+	 * refused the moment they said yes. A file tool answers here when the file
+	 * moved on disk after the session read it. Returning `undefined` means no
+	 * objection; the call goes on to review and `execute`, which keep their own
+	 * checks, since the state may move again in between. A hook that throws is
+	 * read as no objection too.
+	 */
+	refuseBeforeReview?(
+		input: TInput,
+		context: ToolContext,
+	): Promise<
+		{ readonly error: string; readonly facts?: import('./presentation.js').ToolFacts } | undefined
+	>
 	/**
 	 * The argument that holds an absolute URL the tool has already
 	 * canonicalised in its input schema — one spelling, no whitespace.