@namzu/sdk 54.0.0 → 55.0.0

package/src/types/message/index.ts

@@ -1,5 +1,6 @@
 import type { GoalId, MessageId } from '../ids/index.js'
 import { type InboundDeliveryRef, isInboundDeliveryRef } from './inbound-delivery.js'
+import { escapeNoticeFrame } from './notice-frame.js'
 
 export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
 
@@ -335,6 +336,12 @@ export interface GoalRoundMessageSource {
 export interface ProjectInstructionMessageSource {
 	readonly type: 'project-instructions'
 	readonly files: readonly string[]
+	/**
+	 * Set on a changed copy sent after the conversation's first one. It carries
+	 * the complete new policy under a header that says it replaces the earlier
+	 * copy, so the earlier copy keeps its place in the request.
+	 */
+	readonly update?: true
 }
 
 /**
@@ -647,7 +654,7 @@ export function createProjectInstructionMessage(
 			'Project instruction paths must be unique, canonical project-relative paths.',
 		)
 	}
-	return { ...createUserMessage(content, undefined, source), retain: true }
+	return { ...createUserMessage(escapeNoticeFrame(content), undefined, source), retain: true }
 }
 
 export function createAssistantMessage(
@@ -670,6 +677,15 @@ export function createAssistantMessage(
 	}
 }
 
+/** A tool's output can print anything; it cannot print the kernel's notice tag. */
+function escapeToolResult(content: ToolResultContent): ToolResultContent {
+	if (typeof content === 'string') return escapeNoticeFrame(content)
+	if (!content.some((block) => block.type === 'text' && block.text.includes('<'))) return content
+	return content.map((block) =>
+		block.type === 'text' ? { ...block, text: escapeNoticeFrame(block.text) } : block,
+	)
+}
+
 export function createToolMessage(
 	content: ToolResultContent,
 	toolCallId: string,
@@ -678,7 +694,7 @@ export function createToolMessage(
 ): ToolMessage {
 	return {
 		role: 'tool',
-		content,
+		content: escapeToolResult(content),
 		toolCallId,
 		...(isError !== undefined ? { isError } : {}),
 		...(revealedTools && revealedTools.length > 0 ? { revealedTools } : {}),
@@ -686,6 +702,8 @@ export function createToolMessage(
 	}
 }
 
+export { escapeNoticeFrame, frameNotice, NOTICE_TAG } from './notice-frame.js'
+export type { NoticeKind } from './notice-frame.js'
 export {
 	hasNonTextBlocks,
 	toToolResultBlocks,

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]
+}