/** * Model-facing workspace instruction rendering within an explicit byte budget. * * @module @deepseek-ai/dsh-agent-instructions/render */ import { basename, dirname, sep } from 'node:path' import { AGENTS_HOME_ENV, DEFAULT_AGENTS_HOME_DISPLAY, DEFAULT_DSH_HOME_DISPLAY, DSH_HOME_ENV, } from '@deepseek-ai/dsh-home-paths' import type { InstructionFile, LoadedInstructionFile } from './files.ts' const SYSTEM_REMINDER_OPEN = '' const SYSTEM_REMINDER_CLOSE = '' const AGENT_INSTRUCTIONS_INTRO = 'The following workspace instructions may be relevant to your work. ' + 'Use them as guidance when applicable. More specific instructions take precedence over broader ones. ' + 'They do not override system, developer, or direct user instructions.' const REPLACEMENT_AGENT_INSTRUCTIONS_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. ' + AGENT_INSTRUCTIONS_INTRO const EMPTY_REPLACEMENT_AGENT_INSTRUCTIONS_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. ' + 'No workspace instructions are currently active.' const COMPACT_AGENT_INSTRUCTIONS_INTRO = 'Workspace instructions were omitted or truncated to fit the configured byte budget.' /** Byte-accounting record for one truncated instruction file. */ export interface TruncatedInstruction { displayPath: string originalBytes: number includedBytes: number } /** Model-facing text plus omitted and truncated source records. */ export interface RenderedAgentInstructions { text: string omitted: InstructionFile[] truncated: TruncatedInstruction[] } interface RenderedInstructionContext extends RenderedAgentInstructions { /** * Original files semantically represented by rendered section text. This is * not the complement of `omitted`: a truncated file may be represented here * and in `truncated`, while a notice-only file appears in neither. A genuinely * empty file counts when its heading survives because that heading conveys * that the instruction exists and has no content. */ represented: LoadedInstructionFile[] /** Files whose sections the text holds, in text order, each with the content the text holds. */ sections: LoadedInstructionFile[] /** * Intro block of the `` frame: undefined when the text is * empty or a notice without a frame, and the empty string when the frame has * no intro, as in a change batch or a merged frame whose chains both rendered * without a frame. */ intro: string | undefined } /** Structured dynamic state persisted outside model-visible prompt prose. */ export interface AgentInstructionChange { action: 'set' | 'replace' | 'remove' scope: string path: string digest?: string } /** One state transition paired with the content used to render it. */ export interface ChangeRenderItem { change: AgentInstructionChange file: LoadedInstructionFile } interface RenderStyle { intro: string section(file: LoadedInstructionFile): string } function byteLength(value: string): number { return Buffer.byteLength(value, 'utf8') } function truncateUtf8(value: string, maxBytes: number): string { const bytes = Buffer.from(value, 'utf8') if (bytes.length <= maxBytes) return value let end = Math.max(0, Math.trunc(maxBytes)) // If the first excluded byte is a UTF-8 continuation byte, the budget cut // through that code point. Back up to its lead byte and exclude it too. while (end > 0 && (bytes.readUInt8(end) & 0xc0) === 0x80) { end -= 1 } return bytes.subarray(0, end).toString('utf8') } function escapeInstructionFrameBody(body: string): string { return body.replaceAll(SYSTEM_REMINDER_CLOSE, '<\\/system-reminder>') } function sectionText(file: LoadedInstructionFile): string { return `Instructions from: ${file.displayPath}\n\n${file.content}` } /** Directory component that identifies the harness-home user-global instruction scope. */ export const USER_GLOBAL_DIRECTORY = 'user-global' /** * Directory component that identifies the shared agents-root user-global scope. * * It is a distinct scope so the harness-home file keeps the scope key that * earlier sessions recorded, while {@link instructionCandidateGroup} still * deduplicates the two roots as one candidate group. */ export const AGENTS_GLOBAL_DIRECTORY = 'agents-global' /** * Ordered user-global scope directories. * * Discovery, baseline reconciliation, and deduplication all iterate this order, * so the harness home stays the candidate that decides content duplicates * against the shared agents root. */ export const USER_GLOBAL_DIRECTORIES = [USER_GLOBAL_DIRECTORY, AGENTS_GLOBAL_DIRECTORY] as const /** * File name of the user-global instruction file under each user-global root. * Discovery (`/`) and reconciliation (the user-global scope key's * candidate component) both key on this name, so it lives in one place: were the * two to disagree, the user-global instruction would load but never reconcile. */ export const USER_GLOBAL_FILE = 'AGENTS.md' /** * Derive the logical instruction scope from a model-facing path. * @param displayPath - project-relative or user-global instruction path. * @returns `user-global`, `agents-global`, `.`, or the containing project-relative directory. */ export function scopeForDisplayPath(displayPath: string): string { if (displayPath === `${DEFAULT_DSH_HOME_DISPLAY}/${USER_GLOBAL_FILE}` || displayPath === `$${DSH_HOME_ENV}/${USER_GLOBAL_FILE}`) return USER_GLOBAL_DIRECTORY if (displayPath === `${DEFAULT_AGENTS_HOME_DISPLAY}/${USER_GLOBAL_FILE}` || displayPath === `$${AGENTS_HOME_ENV}/${USER_GLOBAL_FILE}`) return AGENTS_GLOBAL_DIRECTORY return dirname(displayPath) } /** * Whether a decoded scope directory is one of the two user-global roots. * @param directory - `user-global`, `agents-global`, `.`, or a project-relative directory. * @returns true for the harness-home and shared agents-root scopes. */ export function isUserGlobalDirectory(directory: string): boolean { return directory === USER_GLOBAL_DIRECTORY || directory === AGENTS_GLOBAL_DIRECTORY } /** * Candidate group of one decoded scope directory. * * The harness home and the shared agents root are the ordered candidates of one * user-global candidate group: identical trimmed content renders once, and an * unobservable candidate preserves the last-good state of its group. Every * project directory forms its own group. * @param directory - `user-global`, `agents-global`, `.`, or a project-relative directory. * @returns the shared group key of both user-global roots, or the directory itself. */ export function instructionCandidateGroup(directory: string): string { return directory === AGENTS_GLOBAL_DIRECTORY ? USER_GLOBAL_DIRECTORY : directory } /** Directory names that {@link scopeForDisplayPath} reads as a user-global scope, not a project path. */ const RESERVED_SCOPE_DIRECTORIES: ReadonlySet = new Set(USER_GLOBAL_DIRECTORIES) /** * Keep a project-relative path out of the user-global scope namespace. * * A project directory whose name equals a user-global scope directory would * otherwise resolve to the global root for probing and joins the global * candidate group for deduplication. Escaping the collision with a leading `.` * keeps the file in its own project scope. * @param relativePath - project-root-relative path using the platform separator. * @returns the path, with a leading `.` component when its first component collides. */ export function escapeProjectDisplayPath(relativePath: string): string { const separatorIndex = relativePath.search(/[\\/]/) const first = separatorIndex < 0 ? relativePath : relativePath.slice(0, separatorIndex) return RESERVED_SCOPE_DIRECTORIES.has(first) ? `.${sep}${relativePath}` : relativePath } const SCOPE_SEPARATOR = '\u0000' /** * Compose the reconciliation key for one instruction candidate file. * Each loaded candidate is tracked independently, so the key pairs the logical * directory with the exact candidate file name behind a NUL separator that no * directory path or file name can contain. Distinct candidates in one directory * (`AGENTS.md` vs `CLAUDE.md`, a base file vs its `.local` overlay) therefore * never collide in the scope-keyed state maps. * @param directory - `user-global`, `agents-global`, `.`, or a project-relative directory. * @param candidateName - instruction file name within that directory. * @returns the per-candidate logical scope key. */ export function candidateScopeKey(directory: string, candidateName: string): string { return `${directory}${SCOPE_SEPARATOR}${candidateName}` } /** * Derive the per-candidate scope key for a loaded instruction file. * @param displayPath - project-relative or user-global instruction path. * @returns the scope key pairing the file's directory with its name. */ export function instructionScopeKey(displayPath: string): string { return candidateScopeKey(scopeForDisplayPath(displayPath), basename(displayPath)) } /** * Recover the directory and candidate name that {@link candidateScopeKey} encoded. * @param scope - a per-candidate scope key. * @returns the directory scope and the candidate file name within it. */ export function decodeScopeKey(scope: string): { directory: string; candidateName: string } { const separator = scope.indexOf(SCOPE_SEPARATOR) /* v8 ignore next -- every scope key is produced by candidateScopeKey, which always inserts the separator. */ if (separator < 0) return { directory: scope, candidateName: '' } return { directory: scope.slice(0, separator), candidateName: scope.slice(separator + 1) } } const ADDITIONAL_INSTRUCTIONS_GUIDANCE = 'Use them as guidance when relevant; more specific instructions take precedence. ' + 'They do not override system, developer, or direct user instructions.' function additionalSectionText(file: LoadedInstructionFile): string { const scope = scopeForDisplayPath(file.displayPath) // A user-global scope directory is an internal reconciliation key, so it must // never reach this model-visible sentence. const applicability = isUserGlobalDirectory(scope) ? 'These user-global instructions apply to all work.' : `These instructions apply to work under \`${scope}\`.` return [ `Additional instructions from: ${file.displayPath}`, '', `${applicability} ${ADDITIONAL_INSTRUCTIONS_GUIDANCE}`, '', file.content, ].join('\n') } const BASELINE_RENDER_STYLE: RenderStyle = { intro: AGENT_INSTRUCTIONS_INTRO, section: sectionText } function baselineRenderStyle(files: LoadedInstructionFile[], replacePreviousBaseline: boolean | undefined): RenderStyle { if (replacePreviousBaseline !== true) return BASELINE_RENDER_STYLE return { ...BASELINE_RENDER_STYLE, intro: files.length === 0 ? EMPTY_REPLACEMENT_AGENT_INSTRUCTIONS_INTRO : REPLACEMENT_AGENT_INSTRUCTIONS_INTRO, } } function changedSectionText(item: ChangeRenderItem): string { const { change, file } = item if (change.action === 'set') return additionalSectionText(file) if (change.action === 'remove') { return `Instructions removed: ${change.path}\n\nThe previously loaded instructions from this file no longer apply.` } return [ `Updated instructions from: ${change.path}`, '', 'This file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.', '', file.content, ].join('\n') } /** * Render one reconciliation batch and retain only transitions that fit. * User-global and project transitions are budgeted as separate chains, so a * batch holding both can exceed `maxBytes` and is at most twice that size. * @param items - ordered state transitions and current file contents. * @param maxBytes - maximum UTF-8 bytes for each instruction chain in the rendered batch. * @returns bounded prompt text and the transitions actually represented by it. */ export function renderInstructionChanges( items: ChangeRenderItem[], maxBytes: number, ): { text: string; changes: AgentInstructionChange[] } { const byAbsolutePath = new Map(items.map(item => [item.file.absolutePath, item])) const style: RenderStyle = { intro: '', section(file) { const item = byAbsolutePath.get(file.absolutePath) /* v8 ignore next -- the renderer receives exactly the files used to construct this map. */ return item === undefined ? '' : changedSectionText({ ...item, file }) }, } const rendered = renderInstructionChains(items.map(item => item.file), maxBytes, style) const represented = new Set(rendered.represented.map(file => file.absolutePath)) return { text: rendered.text, changes: items .filter(item => represented.has(item.file.absolutePath)) .map(item => item.change), } } function markerText(maxBytes: number, omitted: InstructionFile[], truncated: TruncatedInstruction[]): string { if (omitted.length === 0 && truncated.length === 0) return '' const parts: string[] = [] if (omitted.length > 0) { parts.push(`omitted ${omitted.map(file => file.displayPath).join(', ')}`) } if (truncated.length > 0) { parts.push(`truncated ${truncated.map(item => `${item.displayPath} from ${item.originalBytes} to ${item.includedBytes} bytes`).join(', ')}`) } return `Workspace instruction budget ${maxBytes} bytes: ${parts.join('; ')}` } function buildInstructionText( files: LoadedInstructionFile[], maxBytes: number, omitted: InstructionFile[], truncated: TruncatedInstruction[], style: RenderStyle, ): string { const marker = markerText(maxBytes, omitted, truncated) const body = [marker, style.intro, ...files.map(file => style.section(file))].filter(block => block.length > 0) // This producer owns the complete frame. Session adds no // wrapper; see Derived history in packages/core/session/README.md. return [SYSTEM_REMINDER_OPEN, escapeInstructionFrameBody(body.join('\n\n')), SYSTEM_REMINDER_CLOSE].join('\n') } function withTruncatedContent(file: LoadedInstructionFile, includedBytes: number): LoadedInstructionFile { return { ...file, content: truncateUtf8(file.content, includedBytes) } } function truncateToFit( file: LoadedInstructionFile, includedFiles: LoadedInstructionFile[], maxBytes: number, omitted: InstructionFile[], style: RenderStyle, ): LoadedInstructionFile { const originalBytes = byteLength(file.content) let low = 0 let high = originalBytes let best = withTruncatedContent(file, 0) while (low <= high) { const mid = Math.floor((low + high) / 2) const candidate = withTruncatedContent(file, mid) const truncated = [{ displayPath: file.displayPath, originalBytes, includedBytes: byteLength(candidate.content) }] const text = buildInstructionText([...includedFiles, candidate], maxBytes, omitted, truncated, style) if (byteLength(text) <= maxBytes) { best = candidate low = mid + 1 } else { high = mid - 1 } } return best } function isDisabledBudget(maxBytes: number): boolean { return maxBytes <= 0 || !Number.isFinite(maxBytes) } function renderInstructionContext( files: LoadedInstructionFile[], maxBytes: number, style: RenderStyle, ): RenderedInstructionContext { if (isDisabledBudget(maxBytes)) { return { text: '', omitted: files, truncated: [], represented: [], sections: [], intro: undefined } } const fullText = buildInstructionText(files, maxBytes, [], [], style) if (byteLength(fullText) <= maxBytes) { return { text: fullText, omitted: [], truncated: [], represented: files, sections: files, intro: style.intro } } for (let start = 1; start < files.length; start += 1) { const included = files.slice(start) const omitted = files.slice(0, start).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath })) const suffixText = buildInstructionText(included, maxBytes, omitted, [], style) if (byteLength(suffixText) <= maxBytes) { return { text: suffixText, omitted, truncated: [], represented: included, sections: included, intro: style.intro } } } const mostSpecific = files.at(-1) /* v8 ignore next -- callers only reach this after a non-empty fullText was built. */ if (mostSpecific === undefined) return { text: '', omitted: [], truncated: [], represented: [], sections: [], intro: undefined } const omitted = files.slice(0, -1).map(file => ({ absolutePath: file.absolutePath, displayPath: file.displayPath })) const originalBytes = byteLength(mostSpecific.content) for (const candidateStyle of [style, { ...style, intro: COMPACT_AGENT_INSTRUCTIONS_INTRO }]) { const truncatedFile = truncateToFit(mostSpecific, [], maxBytes, omitted, candidateStyle) const includedBytes = byteLength(truncatedFile.content) const truncated = [{ displayPath: mostSpecific.displayPath, originalBytes, includedBytes, }] const text = buildInstructionText([truncatedFile], maxBytes, omitted, truncated, candidateStyle) if (byteLength(text) <= maxBytes) { const represented = includedBytes > 0 || originalBytes === 0 ? [mostSpecific] : [] return { text, omitted, truncated, represented, sections: [truncatedFile], intro: candidateStyle.intro } } } const truncated = [{ displayPath: mostSpecific.displayPath, originalBytes, includedBytes: 0, }] const compactNotice = escapeInstructionFrameBody(markerText(maxBytes, omitted, truncated)) const heading = withTruncatedContent(mostSpecific, 0) const compactWithHeading = escapeInstructionFrameBody([compactNotice, style.section(heading)].join('\n\n')) if (byteLength(compactWithHeading) <= maxBytes) { const represented = originalBytes === 0 ? [mostSpecific] : [] return { text: compactWithHeading, omitted, truncated, represented, sections: [heading], intro: undefined } } const text = byteLength(compactNotice) <= maxBytes ? compactNotice : truncateUtf8(compactNotice, maxBytes) return { text, omitted, truncated, represented: [], sections: [], intro: undefined } } function isUserGlobalInstruction(file: InstructionFile): boolean { return isUserGlobalDirectory(scopeForDisplayPath(file.displayPath)) } /** * Render the user-global chain and the project chain under one `maxBytes` each. * * A disabled budget, files from only one chain, or files that fit within * `maxBytes` together return the single-budget rendering unchanged. Otherwise * each chain renders alone (omit the broadest files, truncate the last file, * then fall back to the compact intro, to the marker with an empty heading, * and to the marker alone), and one frame holds the merged marker when a chain * omitted or truncated a file, one intro when a chain kept its frame, and the * sections of both chains as rendered, in their loaded order, which puts * user-global files first in a baseline. The single-budget rendering replaces a * merged frame longer than twice `maxBytes`. */ function renderInstructionChains( files: LoadedInstructionFile[], maxBytes: number, style: RenderStyle, ): RenderedInstructionContext { const whole = renderInstructionContext(files, maxBytes, style) const userGlobal = files.filter(isUserGlobalInstruction) const project = files.filter(file => !isUserGlobalInstruction(file)) if (isDisabledBudget(maxBytes) || userGlobal.length === 0 || project.length === 0 || (whole.omitted.length === 0 && whole.truncated.length === 0)) return whole const chains = [ renderInstructionContext(userGlobal, maxBytes, style), renderInstructionContext(project, maxBytes, style), ] // Merged records and sections keep the loaded order, so a reconciliation batch // renders its items in one order whether or not it fits a single budget. const inLoadedOrder = (records: T[]): T[] => { const byPath = new Map(records.map(record => [record.absolutePath, record])) return files.flatMap((file) => { const record = byPath.get(file.absolutePath) return record === undefined ? [] : [record] }) } const omitted = inLoadedOrder(chains.flatMap(chain => chain.omitted)) const sections = inLoadedOrder(chains.flatMap(chain => chain.sections)) const represented = inLoadedOrder(chains.flatMap(chain => chain.represented)) // A chain truncates only its last file, so the chain whose last file loads // first lists its truncation first. const userGlobalLast = files.findLastIndex(isUserGlobalInstruction) const projectLast = files.findLastIndex(file => !isUserGlobalInstruction(file)) const truncated = (userGlobalLast < projectLast ? chains : chains.toReversed()).flatMap(chain => chain.truncated) const intros = chains.flatMap(chain => chain.intro === undefined ? [] : [chain.intro]) // A chain that kept the full frame decides the intro; otherwise the first // surviving (compact) intro applies; otherwise there is none. const intro = intros.includes(style.intro) ? style.intro : intros[0] ?? '' const text = buildInstructionText(sections, maxBytes, omitted, truncated, { ...style, intro }) // Each chain text fits maxBytes; the merged frame exceeds 2 * maxBytes only by the join beside a // frameless chain or by a chain marker cut to fit, and the single-budget rendering then replaces it // (.agents/notes/implemented/architecture/2026-10-16-separate-instruction-chain-budgets.md). if (byteLength(text) > 2 * maxBytes) return whole return { text, omitted, truncated, represented, sections, intro } } /** * Render a baseline together with the exact source files semantically represented in it. * @param files - loaded files ordered from broadest to most specific. * @param options - per-chain rendering byte budget and whether this baseline supersedes a visible predecessor. * @returns bounded public rendering plus files with surviving content, including genuinely empty files. * @internal */ export function renderAgentInstructionSet( files: LoadedInstructionFile[], options: { maxBytes: number; replacePreviousBaseline?: boolean }, ): { rendered: RenderedAgentInstructions; included: LoadedInstructionFile[] } { const style = baselineRenderStyle(files, options.replacePreviousBaseline) const { text, omitted, truncated, represented } = renderInstructionChains(files, options.maxBytes, style) return { rendered: { text, omitted, truncated }, included: represented } } /** * Render the baseline instruction chains with deterministic precedence budgeting. * The user-global and project chains are each bounded by `maxBytes`, so a * baseline holding both can exceed `maxBytes` and is at most twice that size. * @param files - loaded files ordered from broadest to most specific. * @param options - per-chain rendering byte budget and whether this baseline supersedes a visible predecessor. * @returns bounded baseline prompt text and budget diagnostics. */ export function renderAgentInstructions( files: LoadedInstructionFile[], options: { maxBytes: number; replacePreviousBaseline?: boolean }, ): RenderedAgentInstructions { return renderAgentInstructionSet(files, options).rendered }