@namzu/sdk 62.10.0 → 62.11.0

package/src/execution/workflow/phases.ts

@@ -12,25 +12,51 @@ export interface PhaseRecord {
 	readonly declared: boolean
 }
 
+/**
+ * The entry of `entries` a title belongs to: one with exactly that title
+ * first; only when there is none, the first one whose title matches ignoring
+ * case. Two entries that differ only by case therefore stay two, because each
+ * matches itself exactly.
+ */
+function matchTitle<T extends { readonly title: string }>(
+	entries: Iterable<T>,
+	title: string,
+): T | undefined {
+	const lower = title.toLowerCase()
+	let loose: T | undefined
+	for (const entry of entries) {
+		if (entry.title === title) return entry
+		if (loose === undefined && entry.title.toLowerCase() === lower) loose = entry
+	}
+	return loose
+}
+
 /**
  * Phase titles of one run. A title is the only grouping key: the same title
- * is the same group. Indexes are 1-based first-seen order, declared titles
+ * is the same group. A title matches a registered one exactly first; only when
+ * none matches exactly does it match one ignoring case (the first registered
+ * wins, and its spelling is kept). Two declared titles that differ only by
+ * case stay two phases. Indexes are 1-based first-seen order, declared titles
  * first. `register` reports whether the title was announced just now.
  */
 export class PhaseRegistry {
-	private readonly byTitle = new Map<string, PhaseRecord>()
+	private readonly records: PhaseRecord[] = []
 
 	register(rawTitle: string, declared = false): { phase: PhaseRecord; isNew: boolean } {
 		const title = normalizePhaseTitle(rawTitle)
-		const existing = this.byTitle.get(title)
+		// A declared title is matched exactly only, so two declared titles that
+		// differ only by case each get their own phase.
+		const existing = declared
+			? this.records.find((record) => record.title === title)
+			: matchTitle(this.records, title)
 		if (existing) return { phase: existing, isNew: false }
-		const phase = { index: this.byTitle.size + 1, title, declared }
-		this.byTitle.set(title, phase)
+		const phase = { index: this.records.length + 1, title, declared }
+		this.records.push(phase)
 		return { phase, isNew: true }
 	}
 
 	all(): PhaseRecord[] {
-		return [...this.byTitle.values()]
+		return [...this.records]
 	}
 }
 
@@ -57,7 +83,7 @@ export function summarizeWorkflowPhases(
 	phases: readonly PhaseRecord[],
 	agents: readonly PhaseAgentView[],
 ): WorkflowPhaseSummary[] {
-	const detail = new Map(declared.map((p) => [normalizePhaseTitle(p.title), p.detail]))
+	const named = declared.map((p) => ({ title: normalizePhaseTitle(p.title), detail: p.detail }))
 	const summarize = (
 		index: number,
 		title: string,
@@ -82,7 +108,7 @@ export function summarizeWorkflowPhases(
 			p.index,
 			p.title,
 			agents.filter((a) => a.phaseIndex === p.index),
-			detail.get(p.title),
+			matchTitle(named, p.title)?.detail,
 		),
 	)
 	const ungrouped = agents.filter((a) => a.phaseIndex === undefined)

package/src/runtime/query/iteration/phases/compaction.ts

@@ -3,6 +3,13 @@ import {
 	resolveTriggerThreshold,
 } from '../../../../compaction/context-window.js'
 import { findDanglingMessages } from '../../../../compaction/dangling.js'
+import {
+	LOADED_SKILLS_ENTRY_KEY,
+	type RenderedSkills,
+	adoptableSkills,
+	handledSkillNames,
+	renderLoadedSkills,
+} from '../../../../compaction/loaded-skills.js'
 import { replaceableSummaries, summarizeWithModel } from '../../../../compaction/model-summary.js'
 import {
 	type CompactionPlan,
@@ -29,7 +36,11 @@ import { CHARS_PER_TOKEN } from '../../../../constants/limits.js'
 import { NAMZU } from '../../../../constants/telemetry/index.js'
 import { invariants } from '../../../../invariants/index.js'
 import { resolveTaskModel } from '../../../../model-router/task-router.js'
-import type { Message } from '../../../../types/message/index.js'
+import {
+	type Message,
+	createTurnContextEntry,
+	turnContextEntries,
+} from '../../../../types/message/index.js'
 import { applyLifecycleHookResults } from '../../plugin-hooks.js'
 import {
 	COMPACTION_REFILL_MESSAGE,
@@ -168,6 +179,65 @@ async function emitToolResultClear(
 	})
 }
 
+/**
+ * Keep the skills this conversation loaded where the pass cannot cut them.
+ * Called before a pass edits the history: whatever the messages show of a
+ * skill now goes into the working state, which outlives the messages.
+ */
+function adoptLoadedSkills(ctx: IterationContext): void {
+	ctx.workingStateManager?.adoptSkillBodies(adoptableSkills(ctx.recorder.messages))
+}
+
+/**
+ * After a pass that cut or cleared history: if a loaded skill's instructions
+ * are no longer in it, say them again, as reference.
+ *
+ * The entry goes at the END of the history, after everything the pass left.
+ * A clear already rewrites the request from the first result it cut, so the
+ * cached start of the request ends no earlier than it did; putting the skills
+ * anywhere before that point would move it further forward. At the end it
+ * also reads as the latest guidance, and the entry is never edited after, so
+ * later requests start with it unchanged.
+ */
+async function carryLoadedSkills(
+	ctx: IterationContext,
+	contextWindowTokens: number,
+): Promise<void> {
+	const manager = ctx.workingStateManager
+	const loaded = manager?.getState().restorable?.skills
+	if (!loaded || loaded.length === 0) return
+	const handled = handledSkillNames(ctx.recorder.messages)
+	const missing = loaded.filter((skill) => !handled.has(skill.name))
+	if (missing.length === 0) return
+	const rendered = renderLoadedSkills(missing, { contextWindowTokens })
+	if (!rendered.text) return
+	const earlier = turnContextEntries(ctx.recorder.messages, LOADED_SKILLS_ENTRY_KEY)
+	ctx.recorder.pushMessage(
+		createTurnContextEntry(LOADED_SKILLS_ENTRY_KEY, rendered.text, new Date(), {
+			later: earlier.length > 0,
+		}),
+	)
+	await emitSkillsCarried(ctx, rendered)
+}
+
+async function emitSkillsCarried(
+	ctx: IterationContext,
+	rendered: {
+		carried: readonly string[]
+		cut: readonly string[]
+		left: readonly string[]
+	},
+): Promise<void> {
+	await ctx.emitEvent?.({
+		type: 'compaction_skills_carried',
+		turnId: ctx.recorder.turnId,
+		iteration: ctx.recorder.currentIteration,
+		skills: [...rendered.carried],
+		cut: [...rendered.cut],
+		leftOut: [...rendered.left],
+	})
+}
+
 /** Install a clear-only pass and publish the state it established. */
 async function commitToolResultClear(
 	ctx: IterationContext,
@@ -180,11 +250,13 @@ async function commitToolResultClear(
 	// content in the same archive used by whole-message compaction before
 	// changing the live history or publishing the clear.
 	await recordShed(ctx, [...ctx.recorder.messages], plan.messages, reason)
+	adoptLoadedSkills(ctx)
 	installMessages(ctx.recorder.messages, plan.messages)
 	// The provider counted the pre-edit prompt. Leaving that measurement live
 	// makes the next trigger compare the old prompt against the new history.
 	ctx.recorder.clearLastPromptTokens?.()
 	await emitToolResultClear(ctx, plan)
+	await carryLoadedSkills(ctx, contextWindowTokens)
 	await emitContextUsageSnapshot(ctx, estimateTokens(ctx), contextWindowTokens, windowSource)
 	// A host-requested pass is not the kernel's own relief of a full context,
 	// so it must not reset the breaker's failure streak.
@@ -1136,6 +1208,9 @@ async function runCompactionCheckInner(
 
 	// Skills the model loaded and files it read go back verbatim after the
 	// summary, with whatever the host wants carried across (its plan file).
+	// The skills come from the conversation as it stands, so a skill loaded in
+	// an earlier turn, or before a resume, is put back too.
+	adoptLoadedSkills(ctx)
 	let hostNote: string | undefined
 	try {
 		hostNote = await ctx.postCompactionContext?.()
@@ -1146,21 +1221,6 @@ async function runCompactionCheckInner(
 			'exception.message': error instanceof Error ? error.message : String(error),
 		})
 	}
-	const restored = renderRestoredContext(manager.getState(), {
-		contextWindowTokens: budget,
-		...(hostNote ? { hostNote } : {}),
-	})
-	if (restored) compactedContent = `${compactedContent}\n\n${restored}`
-
-	// The pointer is only worth a line when both tools it names are mounted.
-	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
-	const compactionMessage = buildCompactionMessage(
-		compactedContent,
-		mounted.has('search_conversation') && mounted.has('read_conversation')
-			? COMPACTION_RECOVERY_NOTE
-			: undefined,
-	)
-
 	// Drop a replaceable PRIOR `[COMPACTED CONTEXT]` summary from this turn's
 	// leading floor — `serializeState` is cumulative, so the new summary
 	// supersedes it. A retained summary came from outside this manager's state
@@ -1183,6 +1243,29 @@ async function runCompactionCheckInner(
 					.slice(systemMessages.length, keepStart)
 					.filter((_, offset) => retained.has(systemMessages.length + offset))
 
+	// A skill whose instructions are in what the pass keeps as it is, whole or
+	// shown by an earlier pass, is not put back a second time.
+	const wholeSkills = handledSkillNames([...preservedSystem, ...retainedOlder, ...recentMessages])
+	const putBack: { rendered?: RenderedSkills } = {}
+	const restored = renderRestoredContext(manager.getState(), {
+		contextWindowTokens: budget,
+		wholeSkills,
+		onSkills: (rendered) => {
+			putBack.rendered = rendered
+		},
+		...(hostNote ? { hostNote } : {}),
+	})
+	if (restored) compactedContent = `${compactedContent}\n\n${restored}`
+
+	// The pointer is only worth a line when both tools it names are mounted.
+	const mounted = new Set(ctx.tools?.listNames?.() ?? [])
+	const compactionMessage = buildCompactionMessage(
+		compactedContent,
+		mounted.has('search_conversation') && mounted.has('read_conversation')
+			? COMPACTION_RECOVERY_NOTE
+			: undefined,
+	)
+
 	const newMessages = [...preservedSystem, compactionMessage, ...retainedOlder, ...recentMessages]
 
 	// OPAQUE survival guard: the pinned working-memory slot is a
@@ -1282,6 +1365,9 @@ async function runCompactionCheckInner(
 		reachedResetThreshold: reachedReset,
 	})
 	await emitContextUsageSnapshot(ctx, newEstimate, budget, window.source)
+	if (putBack.rendered && putBack.rendered.carried.length > 0) {
+		await emitSkillsCarried(ctx, putBack.rendered)
+	}
 	compactionBreaker(ctx)?.recordCompaction(
 		ctx.recorder.currentIteration,
 		beforeTokens,

package/src/tools/builtins/skill.ts

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto'
 import { z } from 'zod'
 
 import { parseAllowedTools } from '../../authorization/skill-grant.js'
+import { forkedSkillReportNote } from '../../compaction/loaded-skills.js'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import { isInvocableBy, skillInvocation } from '../../types/skills/index.js'
 import type { ToolContext } from '../../types/tool/index.js'
@@ -701,6 +702,10 @@ async function runForkedSkill(input: {
 	})
 	return {
 		...result,
+		// Says what the text is, so a later pass never carries a report as the skill's steps.
+		output: result.success
+			? `${forkedSkillReportNote(input.name)}\n\n${result.output}`
+			: result.output,
 		data: {
 			...(typeof result.data === 'object' && result.data !== null ? result.data : {}),
 			skill: input.name,

package/src/turn/reporter.ts

@@ -350,6 +350,16 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 				})
 				break
 
+			case 'compaction_skills_carried':
+				log.info('Put loaded skills back after a pass cut them', {
+					[NAMZU.TURN_ID]: event.turnId,
+					[NAMZU.ITERATION]: event.iteration,
+					'namzu.compaction.skills': event.skills.join(','),
+					'namzu.compaction.skills_cut': event.cut.join(','),
+					'namzu.compaction.skills_left_out': event.leftOut.join(','),
+				})
+				break
+
 			case 'compaction_failed':
 				// warn rather than info: the turn is now continuing at a context
 				// size it had already decided was too large.

package/src/types/session/events.ts

@@ -304,6 +304,27 @@ type CoreSessionEvent =
 			 */
 			reliefWasEnough: boolean
 	  }
+	/**
+	 * A pass cut or summarised history and the instructions of skills the
+	 * conversation had loaded were put back in front of the model, as reference.
+	 *
+	 * Emitted only when something was put back: a skill whose instructions are
+	 * still whole in the context is never repeated, so most passes say nothing.
+	 * Live only (ephemeral): it is not written to the session log, because the
+	 * put-back text is a message of its own and is in the log as one.
+	 */
+	| {
+			type: 'compaction_skills_carried'
+			sessionId: SessionId
+			turnId?: TurnId
+			iteration: number
+			/** Skills put back, oldest load first. */
+			skills: string[]
+			/** The ones among them cut to their per-skill cap, each with a line saying how to load it in full. */
+			cut: string[]
+			/** Skills left out for room, newest first; each is named in the text the model reads. */
+			leftOut: string[]
+	  }
 	/**
 	 * A compaction pass ran and shed nothing, so the history is unchanged.
 	 *
@@ -1443,7 +1464,9 @@ export type SessionEventListener = (event: SessionEvent) => void | Promise<void>
  * log is what cannot be written while they matter.
  * `compaction_started` is ephemeral too: it only says a pass is about to run,
  * and the `compaction` record or `compaction_failed` that ends it is the
- * durable fact.
+ * durable fact. `compaction_skills_carried` is ephemeral for the same kind of
+ * reason: the text it announces is a message of its own and is in the log as
+ * one, so a log carries no record an older reader would have to skip.
  */
 export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEventType>([
 	'text_delta',
@@ -1452,6 +1475,7 @@ export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<Sess
 	'tool_progress',
 	'monitor_event',
 	'compaction_started',
+	'compaction_skills_carried',
 	'session_log_degraded',
 	'session_log_recovered',
 ])
@@ -1460,7 +1484,7 @@ export function isEphemeralEvent(event: { readonly type: string }): boolean {
 	return EPHEMERAL_EVENT_TYPES.has(event.type as SessionEventType)
 }
 
-/** The event types a session log records: every literal except the ephemeral eight. */
+/** The event types a session log records: every literal except the ephemeral nine. */
 export type PersistedSessionEventType = Exclude<
 	SessionEventType,
 	| 'text_delta'
@@ -1469,6 +1493,7 @@ export type PersistedSessionEventType = Exclude<
 	| 'tool_progress'
 	| 'monitor_event'
 	| 'compaction_started'
+	| 'compaction_skills_carried'
 	| 'session_log_degraded'
 	| 'session_log_recovered'
 >

package/src/types/session/records.ts

@@ -724,6 +724,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	compaction_shed: true,
 	compaction_completed: true,
 	compaction_tool_results_cleared: true,
+	compaction_skills_carried: true,
 	compaction_failed: true,
 	tool_executing: true,
 	tool_progress: true,