@namzu/sdk 34.2.0 → 36.0.0

package/src/compaction/salience/working-set.ts

@@ -0,0 +1,187 @@
+/**
+ * The working set: which messages stay whole for the next call.
+ *
+ * Given every message's salience, choose the cheapest actions that bring
+ * the estimated context under a target, lowest salience first, then the
+ * larger result among equally salient candidates:
+ *
+ *   clear   replace a tool result with the same excerpt the stale pass
+ *           uses, retaining a saved-artifact pointer when one exists;
+ *   stub    cut an assistant narration to its first sentence — the
+ *           decision survives, the paragraph around it does not.
+ *
+ * Nothing protected is touched, and a message is never removed: the
+ * shape of the conversation — every `tool_use` beside its `tool_result`,
+ * every turn boundary — is exactly what it was, which is what makes this
+ * safe to run on every iteration. Folding a span into the structured
+ * state and summarising stay with the existing plan, which runs after
+ * this when the target could not be reached. Pure, like the rest of the
+ * compaction arithmetic.
+ */
+
+import { CHARS_PER_TOKEN } from '../../constants/limits.js'
+import type { AssistantMessage, Message, ToolMessage } from '../../types/message/index.js'
+import { estimateMessageTokens } from '../token-estimate.js'
+import { clearToolResult, isClearedToolResult } from '../tool-result-editing.js'
+import type { ScoredMessage } from './score.js'
+
+export interface WorkingSetAction {
+	readonly kind: 'clear' | 'stub'
+	readonly index: number
+	readonly charsReclaimed: number
+}
+
+export interface WorkingSetPlan {
+	readonly messages: Message[]
+	readonly actions: readonly WorkingSetAction[]
+	readonly clearedCount: number
+	readonly stubbedCount: number
+	readonly charsReclaimed: number
+	readonly reclaimedTokens: number
+	/** Whether the actions brought the estimate under the target. */
+	readonly reachedTarget: boolean
+}
+
+export interface WorkingSetOptions {
+	readonly estimatedTokens: number
+	readonly targetTokens: number
+	/** Tool results smaller than this are not worth a placeholder. */
+	readonly minToolResultChars?: number
+	/** Assistant narrations shorter than this keep their whole text. */
+	readonly minNarrationChars?: number
+	/** Tools whose results are never cleared. */
+	readonly preserveTools?: readonly string[]
+	/**
+	 * A message the goal names or a later turn cited is not evicted to
+	 * reach the target while it scores above this fraction of the most
+	 * salient evictable message. A strict target evicted the one result
+	 * the goal named to shave the last few tokens — an eval watched it
+	 * happen — and a pass that stops short and says so is the better
+	 * answer: the trigger threshold still guards the hard limit.
+	 */
+	readonly keepAboveFraction?: number
+}
+
+const STUB_MARK = '… (elided'
+
+function firstSentence(text: string): string {
+	const match = /^[\s\S]*?[.!?](?=\s|$)/u.exec(text.trim())
+	return (match ? match[0] : (text.trim().split('\n')[0] ?? '')).slice(0, 240)
+}
+
+export function isStubbedNarration(content: unknown): boolean {
+	return typeof content === 'string' && content.includes(STUB_MARK)
+}
+
+export function planWorkingSet(
+	messages: readonly Message[],
+	scored: readonly ScoredMessage[],
+	options: WorkingSetOptions,
+): WorkingSetPlan {
+	const minTool = options.minToolResultChars ?? 1_000
+	const minNarration = options.minNarrationChars ?? 240
+	const preserve = new Set(options.preserveTools ?? [])
+	const toolNameByCallId = new Map<string, string>()
+	for (const m of messages) {
+		if (m.role !== 'assistant') continue
+		for (const call of (m as AssistantMessage).toolCalls ?? []) {
+			toolNameByCallId.set(call.id, call.function.name)
+		}
+	}
+
+	// Ordered by salience, not salience per token. Per token was the plan's
+	// first answer and it evicts the wrong thing: a large result the goal
+	// names loses to a small one it does not, because size divides the
+	// score. Among equals the larger goes first, which is where the tokens
+	// are.
+	type Candidate = {
+		readonly index: number
+		readonly kind: 'clear' | 'stub'
+		readonly salience: number
+		readonly tokens: number
+		/** Named by the goal or cited by a later turn: what the floor protects. */
+		readonly goalBound: boolean
+	}
+	const candidates: Candidate[] = []
+	for (const s of scored) {
+		if (s.protected !== null || s.tokens === 0) continue
+		const m = messages[s.index] as Message
+		if (m.role === 'tool') {
+			const tool = m as ToolMessage
+			if (tool.isError || isClearedToolResult(tool.content)) continue
+			if (preserve.has(toolNameByCallId.get(tool.toolCallId) ?? '')) continue
+			if (s.tokens * CHARS_PER_TOKEN < minTool) continue
+			candidates.push({
+				index: s.index,
+				kind: 'clear',
+				salience: s.salience,
+				tokens: s.tokens,
+				goalBound: s.relevance >= 0.5 || s.utility >= 1,
+			})
+		} else if (m.role === 'assistant' && !Array.isArray((m as AssistantMessage).toolCalls)) {
+			const text = typeof m.content === 'string' ? m.content : ''
+			if (text.length < minNarration || isStubbedNarration(text)) continue
+			candidates.push({
+				index: s.index,
+				kind: 'stub',
+				salience: s.salience,
+				tokens: s.tokens,
+				goalBound: s.relevance >= 0.5 || s.utility >= 1,
+			})
+		}
+	}
+	candidates.sort((a, b) => a.salience - b.salience || b.tokens - a.tokens || a.index - b.index)
+	const maxSalience = candidates.reduce((m, c) => Math.max(m, c.salience), Number.NEGATIVE_INFINITY)
+	const floor = maxSalience * (options.keepAboveFraction ?? 0.5)
+
+	const next = [...messages]
+	const actions: WorkingSetAction[] = []
+	let charsReclaimed = 0
+	let reclaimedTokens = 0
+	let clearedCount = 0
+	let stubbedCount = 0
+	const excess = () => options.estimatedTokens - reclaimedTokens - options.targetTokens
+	for (const candidate of candidates) {
+		if (excess() <= 0) break
+		// The floor guards what the goal names or a later turn used, not
+		// every above-average message: a run of look-alike dumps must still
+		// be evicted from the bottom when the target asks for it.
+		if (candidate.goalBound && candidate.salience > floor && candidate.salience > 0) continue
+		const m = next[candidate.index] as Message
+		if (candidate.kind === 'clear') {
+			const tool = m as ToolMessage
+			const cleared = clearToolResult(tool, toolNameByCallId.get(tool.toolCallId) ?? 'unknown')
+			const tokenSaving = estimateMessageTokens(tool) - estimateMessageTokens(cleared.message)
+			if (tokenSaving <= 0) continue
+			next[candidate.index] = cleared.message
+			charsReclaimed += cleared.charsReclaimed
+			reclaimedTokens += tokenSaving
+			clearedCount += 1
+			actions.push({
+				kind: 'clear',
+				index: candidate.index,
+				charsReclaimed: cleared.charsReclaimed,
+			})
+		} else {
+			const text = m.content as string
+			const stub = `${firstSentence(text)} ${STUB_MARK}; ${(text.length - firstSentence(text).length).toLocaleString('en-US')} characters of narration)`
+			const reclaimed = text.length - stub.length
+			if (reclaimed <= 0) continue
+			const stubbed = { ...(m as AssistantMessage), content: stub }
+			next[candidate.index] = stubbed
+			charsReclaimed += reclaimed
+			reclaimedTokens += estimateMessageTokens(m) - estimateMessageTokens(stubbed)
+			stubbedCount += 1
+			actions.push({ kind: 'stub', index: candidate.index, charsReclaimed: reclaimed })
+		}
+	}
+	return {
+		messages: next,
+		actions,
+		clearedCount,
+		stubbedCount,
+		charsReclaimed,
+		reclaimedTokens,
+		reachedTarget: excess() <= 0,
+	}
+}

package/src/compaction/serializer.ts

@@ -58,6 +58,20 @@ function renderToolResults(results: { tool: string; summary: string }[], evicted
 	return lines.join('\n')
 }
 
+/** The pinned-facts section alone, or null when nothing is pinned. */
+export function renderPins(state: WorkingState): string | null {
+	const pins = state.pins ? [...state.pins.values()] : []
+	if (pins.length === 0) return null
+	const lines = pins.map((p) => `- **${p.key}**: ${p.text} _(${p.source})_`)
+	const dropped = state.evicted.pins ?? 0
+	if (dropped > 0) {
+		lines.push(
+			`- _(${dropped} older ${dropped === 1 ? 'pin' : 'pins'} dropped to stay within the pin budget)_`,
+		)
+	}
+	return `${SECTION_HEADERS.pins}\n\n${lines.join('\n')}`
+}
+
 export function serializeState(state: WorkingState): string {
 	const sections: string[] = []
 
@@ -74,6 +88,8 @@ export function serializeState(state: WorkingState): string {
 	if (state.plan.length > 0) {
 		sections.push(`${SECTION_HEADERS.plan}\n\n${renderPlan(state.plan)}`)
 	}
+	const pinned = renderPins(state)
+	if (pinned) sections.push(pinned)
 
 	if (state.environment.length > 0) {
 		sections.push(

package/src/compaction/token-estimate.ts

@@ -0,0 +1,57 @@
+import { CHARS_PER_TOKEN } from '../constants/limits.js'
+import type { Message, MessageAttachment, ToolResultBlock } from '../types/message/index.js'
+
+// Heuristic allowances, not provider billing formulas or upper bounds. Encoded
+// byte length depends on compression, not the number of visual tokens. The
+// provider's measured prompt usage replaces these guesses after the next call.
+const IMAGE_TOKENS = 1_024
+const DOCUMENT_TOKENS = 4_096
+const OMITTED_IMAGE_TOKENS = 64
+
+function richTokens(block: Exclude<ToolResultBlock, { type: 'text' }> | MessageAttachment): number {
+	if (block.type === 'stored') return block.kind === 'image' ? IMAGE_TOKENS : DOCUMENT_TOKENS
+	if (block.type === 'document') return DOCUMENT_TOKENS
+	return block.modelOmission ? OMITTED_IMAGE_TOKENS : IMAGE_TOKENS
+}
+
+/**
+ * Provider-neutral prompt estimate shared by triggers, retention and eviction.
+ *
+ * Text and tool inputs use the existing characters-per-token approximation.
+ * Images and documents have an explicit allowance independent of compression
+ * and of whether the bytes are inline or stored externally. Without dimensions,
+ * page counts and a provider tokenizer their exact cost is unknown. In
+ * particular, serialized base64 is never treated as model-visible prose.
+ */
+export function estimateMessageTokens(message: Message): number {
+	let chars = 0
+	let rich = 0
+	if (typeof message.content === 'string') chars += message.content.length
+	else if (message.content) {
+		for (const block of message.content) {
+			if (block.type === 'text') chars += block.text.length
+			else {
+				rich += richTokens(block)
+				if (block.type === 'document') chars += block.name?.length ?? 0
+			}
+		}
+	}
+	if (message.role === 'assistant') {
+		for (const call of message.toolCalls ?? []) {
+			chars += call.function.name.length + call.function.arguments.length
+		}
+	}
+	if (message.role === 'user') {
+		for (const attachment of message.attachments ?? []) {
+			rich += richTokens(attachment)
+			if (attachment.type === 'document' || attachment.type === 'stored') {
+				chars += attachment.name?.length ?? 0
+			}
+		}
+	}
+	return Math.ceil(chars / CHARS_PER_TOKEN) + rich
+}
+
+export function estimateMessagesTokens(messages: readonly Message[]): number {
+	return messages.reduce((total, message) => total + estimateMessageTokens(message), 0)
+}

package/src/compaction/tool-result-editing.ts

@@ -1,7 +1,9 @@
+import { CHARS_PER_TOKEN } from '../constants/limits.js'
 import { SPILL_MARKER } from '../runtime/query/tool-output-budget.js'
 import { toolResultToText } from '../types/message/content.js'
 import type { Message, ToolMessage, ToolResultBlock } from '../types/message/index.js'
 import { findRetainedIndices } from './retention.js'
+import { estimateMessageTokens } from './token-estimate.js'
 
 /**
  * Clear stale tool OUTPUT in place, without touching the conversation's
@@ -91,7 +93,9 @@ function clearedPlaceholder(
 			'Read a window of it with `read` (offset/limit) or search it with `grep`.',
 		)
 	} else {
-		parts.push('Call the tool again if you still need the rest.')
+		parts.push(
+			'Full result unavailable here. Recover from a saved artifact or a read-only observation; do not repeat a state-changing action to recover its output.',
+		)
 	}
 
 	if (text.length > KEEP_HEAD_CHARS + KEEP_TAIL_CHARS) {
@@ -116,10 +120,23 @@ function clearedPlaceholder(
 export interface ToolResultEditOutcome {
 	readonly messages: Message[]
 	readonly clearedCount: number
-	/** Characters removed from the model-visible history. */
+	/** Payload characters removed, including encoded data; not a token estimate. */
 	readonly charsReclaimed: number
 }
 
+/**
+ * One result cleared on its own, for a caller that chose it by some
+ * other rule than staleness. The same placeholder, the same accounting.
+ */
+export function clearToolResult(
+	tool: ToolMessage,
+	toolName: string,
+): { readonly message: ToolMessage; readonly charsReclaimed: number } {
+	const size = measureContent(tool.content)
+	const content = clearedPlaceholder(tool.content, toolName, size)
+	return { message: { ...tool, content }, charsReclaimed: Math.max(0, size - content.length) }
+}
+
 export function isClearedToolResult(content: unknown): boolean {
 	return typeof content === 'string' && content.startsWith(CLEARED_PREFIX)
 }
@@ -183,39 +200,24 @@ export function clearStaleToolResults(
 		if (preserve.has(toolName)) return msg
 
 		const size = measureContent(tool.content)
-		if (size < minChars) return msg
+		if (estimateMessageTokens(tool) * CHARS_PER_TOKEN < minChars) return msg
 
+		const content = clearedPlaceholder(tool.content, toolName, size)
+		if (estimateMessageTokens({ ...tool, content }) >= estimateMessageTokens(tool)) return msg
 		clearedCount++
-		charsReclaimed += size - 0
+		charsReclaimed += size - content.length
 		return {
 			...tool,
-			content: clearedPlaceholder(tool.content, toolName, size),
+			content,
 		} satisfies ToolMessage
 	})
 
-	// Subtract what the placeholders themselves cost, so the number a
-	// caller uses to decide "was that enough?" is the real saving and not
-	// an overstatement.
-	if (clearedCount > 0) {
-		let placeholderChars = 0
-		for (const msg of edited) {
-			if (msg.role === 'tool' && isClearedToolResult(msg.content)) {
-				placeholderChars += measureContent(msg.content)
-			}
-		}
-		charsReclaimed = Math.max(0, charsReclaimed - placeholderChars)
-	}
-
-	return { messages: edited, clearedCount, charsReclaimed }
+	return { messages: edited, clearedCount, charsReclaimed: Math.max(0, charsReclaimed) }
 }
 
 /**
- * Size of a tool result as the model sees it.
- *
- * An image block is measured by its base64 payload, which is the whole
- * point: a screenshot is the single largest thing a tool result can carry,
- * and it is exactly the kind of output an agent reads once and never
- * needs again.
+ * Payload character count for storage telemetry. Encoded image length is
+ * independent of visual token cost; context decisions use the shared estimate.
  */
 function measureContent(content: ToolMessage['content']): number {
 	if (typeof content === 'string') return content.length
@@ -223,7 +225,7 @@ function measureContent(content: ToolMessage['content']): number {
 	let total = 0
 	for (const block of content as readonly ToolResultBlock[]) {
 		if (block.type === 'text') total += block.text.length
-		else if (block.type === 'image') total += block.data.length
+		else if (block.type === 'image' || block.type === 'document') total += block.data.length
 	}
 	return total
 }

package/src/compaction/types.ts

@@ -1,6 +1,15 @@
 export interface WorkingState {
 	task: string
 	plan: PlanSlot[]
+	/**
+	 * Facts pinned by tools, by key. A tool that knows something the model
+	 * must not lose — what its controls do, where the piece is, what has
+	 * already failed — pins it with a key, and a later pin under the same
+	 * key replaces it. Pins live in the working-memory slot, so they are in
+	 * front of the model every iteration and survive compaction; the
+	 * rule-based extractor below only guesses, a pin is stated.
+	 */
+	pins: Map<string, PinSlot>
 	files: Map<string, FileSlot>
 	decisions: string[]
 	failures: string[]
@@ -21,6 +30,20 @@ export interface WorkingState {
 	evicted: Record<string, number>
 }
 
+export interface PinSlot {
+	key: string
+	text: string
+	/** The tool that pinned it. */
+	source: string
+	updatedAt: number
+}
+
+/** What a tool result carries to pin a fact; see `ToolResult.workingState`. */
+export interface WorkingStatePin {
+	readonly key: string
+	readonly text: string
+}
+
 export interface PlanSlot {
 	id: string
 	label: string
@@ -44,4 +67,4 @@ export interface ToolResultSlot {
 	timestamp: number
 }
 
-export type CompactionStrategy = 'structured' | 'sliding-window' | 'disabled'
+export type CompactionStrategy = 'structured' | 'salience' | 'sliding-window' | 'disabled'

package/src/compaction/wire.ts

@@ -1,6 +1,6 @@
 import type { CompactionConfig } from '../config/runtime.js'
 import { WorkingStateManager } from './manager.js'
-import type { FileSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.js'
+import type { FileSlot, PinSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.js'
 
 /**
  * The working state in a form that survives a process boundary.
@@ -26,6 +26,8 @@ import type { FileSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.j
 export interface WorkingStateSnapshot {
 	readonly task: string
 	readonly plan: readonly PlanSlot[]
+	/** Absent in snapshots written before pins existed; restored as none. */
+	readonly pins?: readonly PinSlot[]
 	readonly files: readonly FileSlot[]
 	readonly decisions: readonly string[]
 	readonly failures: readonly string[]
@@ -47,6 +49,7 @@ export function snapshotWorkingState(manager: WorkingStateManager): WorkingState
 	return {
 		task: state.task,
 		plan: [...state.plan],
+		pins: [...(state.pins?.values() ?? [])],
 		files: [...state.files.values()],
 		decisions: [...state.decisions],
 		failures: [...state.failures],
@@ -76,6 +79,7 @@ export function restoreWorkingState(
 	const state: WorkingState = {
 		task: snapshot.task,
 		plan: [...snapshot.plan],
+		pins: new Map((snapshot.pins ?? []).map((p) => [p.key, p])),
 		files: new Map(snapshot.files.map((f) => [f.path, f])),
 		decisions: [...snapshot.decisions],
 		failures: [...snapshot.failures],

package/src/config/runtime.ts

@@ -17,7 +17,19 @@ export const TaskRouterConfigSchema = z
 	.optional()
 
 export const CompactionConfigSchema = z.object({
-	strategy: z.enum(['structured', 'sliding-window', 'disabled']).default('structured'),
+	/**
+	 * `salience` is the default: every message scored without a model, the
+	 * context held from half the window. `structured` is the previous
+	 * default — positional retention, a pass only at the trigger — and one
+	 * word away for a host that wants it back.
+	 */
+	strategy: z.enum(['structured', 'salience', 'sliding-window', 'disabled']).default('salience'),
+	/**
+	 * `salience` only: the fraction of the window at which the working-set
+	 * pass starts evicting low-salience messages, well before
+	 * `triggerThreshold` summarises. The context is held around here.
+	 */
+	softTarget: z.number().min(0).max(1).optional(),
 	/**
 	 * Optional model context-window size (tokens) the compaction trigger
 	 * measures the CURRENT window against. NO default: when omitted the

package/src/connector/builtins/http.ts

@@ -71,14 +71,8 @@ function stripTrailingSlashes(value: string): string {
 	return value.slice(0, end)
 }
 
-/**
- * Checked once at module load, not per instance.
- *
- * `'conn_http' as const` typed this as its own literal, which satisfied
- * `ConnectorId` only because the id types are still structural. The
- * constructor is what makes the prefix a fact rather than a spelling.
- */
-const HTTP_CONNECTOR_ID = asConnectorId('conn_http')
+/** Stable UUID for this built-in definition, checked once at module load. */
+const HTTP_CONNECTOR_ID = asConnectorId('dafa33b2-7035-47d2-986c-8a6d2ef338f3')
 
 export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 	readonly id = HTTP_CONNECTOR_ID

package/src/connector/builtins/webhook.ts

@@ -56,8 +56,8 @@ const WebhookSendInputSchema = z.object({
 	url: z.string().url().optional(),
 })
 
-/** Checked once at module load — see `HttpConnector`'s own constant. */
-const WEBHOOK_CONNECTOR_ID = asConnectorId('conn_webhook')
+/** Stable UUID for this built-in definition, checked once at module load. */
+const WEBHOOK_CONNECTOR_ID = asConnectorId('5d1e831d-d079-47c8-bdb6-ddf4489bb000')
 
 export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
 	readonly id = WEBHOOK_CONNECTOR_ID

package/src/connector/mcp/adapter.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { zodToJsonSchema } from 'zod-to-json-schema'
+import type { WorkingStatePin } from '../../compaction/types.js'
 import { type UntrustedEnvelope, wrapUntrusted } from '../../tools/untrusted-envelope.js'
 import type {
 	MCPJsonSchema,
@@ -11,6 +12,28 @@ import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/i
 import type { MCPClient } from './client.js'
 import { MCPHttpRedirectError } from './http-redirect.js'
 import { admitMcpImageBatch } from './image-admission.js'
+
+/** The resource type an MCP server returns to pin facts into working memory. */
+export const WORKING_STATE_MIME = 'application/vnd.namzu.working-state+json'
+
+function parsePins(text: string | undefined): WorkingStatePin[] {
+	if (!text) return []
+	try {
+		const raw: unknown = JSON.parse(text)
+		if (!Array.isArray(raw)) return []
+		return raw
+			.filter(
+				(p): p is { key: string; text: string } =>
+					typeof p === 'object' &&
+					p !== null &&
+					typeof (p as { key?: unknown }).key === 'string' &&
+					typeof (p as { text?: unknown }).text === 'string',
+			)
+			.map((p) => ({ key: p.key, text: p.text }))
+	} catch {
+		return []
+	}
+}
 import { inlineSchemaRefs } from './schema-refs.js'
 
 /**
@@ -579,7 +602,15 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 	// modelled `image` and `resource` blocks all along. Pass them through
 	// as model-visible content when any are present.
 	const blocks: ToolResultBlock[] = []
+	const pins: WorkingStatePin[] = []
 	for (const block of result.content) {
+		if (block.type === 'resource' && block.resource?.mimeType === WORKING_STATE_MIME) {
+			// A server pins facts by returning them as a resource of this type:
+			// a JSON array of { key, text }. Not text for the model; the kernel
+			// keeps them in the working-memory slot.
+			for (const pin of parsePins(block.resource.text)) pins.push(pin)
+			continue
+		}
 		if (block.type === 'text') {
 			blocks.push({ type: 'text', text: block.text })
 		} else if (block.type === 'image') {
@@ -620,6 +651,7 @@ export function mcpToolResultToToolResult(result: MCPToolResult): ToolResult {
 	const output = [visibleText, invalidImageNotice].filter((part) => part.length > 0).join('\n')
 
 	return {
+		...(pins.length > 0 ? { workingState: pins } : {}),
 		success: !result.isError,
 		output,
 		...(hasRichContent ? { content: blocks } : {}),

package/src/connector/tools/adapter.ts

@@ -4,7 +4,7 @@ import { renderToolSchema } from '../../registry/tool/schema.js'
 import type { ConnectorMethod } from '../../types/connector/index.js'
 import type { ConnectorId, ConnectorInstanceId } from '../../types/ids/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
-import { parseConnectorInstanceId } from '../../utils/id.js'
+import { asConnectorInstanceId } from '../../utils/id.js'
 import { connectorToolError } from './result.js'
 
 export function connectorMethodToTool(
@@ -96,7 +96,7 @@ export function createConnectorRouterTool(
 		isConcurrencySafe: () => true,
 
 		async execute(input: ConnectorRouterInput, context: ToolContext): Promise<ToolResult> {
-			const instanceId = parseConnectorInstanceId(String(input.instanceId))
+			const instanceId = asConnectorInstanceId(String(input.instanceId))
 			const instance = manager.getInstance(instanceId)
 			if (!instance) {
 				return {

package/src/connector/tools/definitions.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import type { ConnectorManager } from '../../manager/connector/lifecycle.js'
 import { defineTool } from '../../tools/defineTool.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
-import { parseConnectorInstanceId } from '../../utils/id.js'
+import { asConnectorInstanceId } from '../../utils/id.js'
 import { connectorToolError } from './result.js'
 
 export interface ConnectorToolConfig {
@@ -30,7 +30,7 @@ export function createConnectorExecuteTool(config: ConnectorToolConfig): ToolDef
 		concurrencySafe: true,
 
 		async execute(input, context) {
-			const instanceId = parseConnectorInstanceId(String(input.instance_id))
+			const instanceId = asConnectorInstanceId(String(input.instance_id))
 			const instance = config.manager.getInstance(instanceId)
 
 			if (!instance) {

package/src/constants/compaction/index.ts

@@ -12,6 +12,7 @@ export const SHELL_TOOLS = new Set(['bash'])
 export const SEARCH_TOOLS = new Set(['glob', 'grep'])
 
 export const SECTION_HEADERS = {
+	pins: '## Pinned by tools',
 	task: '## Task',
 	userRequirements: '## User Requirements',
 	plan: '## Plan',

package/src/constants/telemetry/index.ts

@@ -146,7 +146,6 @@ export const BOOT_EVENT_NAMES = {
 	CAPABILITY_DETECTED: 'namzu.capability.detected',
 	CAPABILITY_BROKEN: 'namzu.capability.broken',
 	TELEMETRY_STATUS: 'namzu.telemetry.status',
-	MIGRATION_COMPLETED: 'namzu.migration.completed',
 	DISCOVERY_COMPLETED: 'namzu.discovery.completed',
 	BOOT_REFUSED: 'namzu.boot.refused',
 	BOOT_READY: 'namzu.boot.ready',

package/src/contracts/api.ts

@@ -1,6 +1,7 @@
 import type { AgentCapabilities, AgentType } from '../types/agent/base.js'
 import type { ProjectId, RunId, SessionId } from '../types/ids/index.js'
 import type { MessageRole } from '../types/message/index.js'
+import type { PermissionMode } from '../types/permission/index.js'
 import type { StopReason } from '../types/run/events.js'
 
 export type { MessageRole, StopReason, AgentType, AgentCapabilities }
@@ -106,7 +107,8 @@ export interface RunHierarchyNode {
 	children: RunHierarchyNode[]
 }
 
-export type ApiPermissionMode = 'plan' | 'auto'
+/** The wire name for the kernel's `PermissionMode`; one union, not a second copy of it. */
+export type ApiPermissionMode = PermissionMode
 
 export interface RunConfig {
 	model?: string
@@ -168,6 +170,8 @@ export type StreamEventType =
 	| 'compaction.completed'
 	/** Oversized tool results were emptied instead of the history summarized. */
 	| 'compaction.tool_results_cleared'
+	| 'memory.consolidated'
+	| 'background_job.exited'
 	| 'compaction.failed'
 	/** A guardrail refused or corrected the run. */
 	| 'guardrail.triggered'