@alvin0/ai-agent-sdk-instructions-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @alvin0/ai-agent-sdk-instructions-node
+
+Node filesystem discovery for `AGENTS.md`-style project instructions, delivered
+as a core **context section**.
+
+Runtime: **Node 22.12+**.
+
+```bash
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-instructions-node
+```
+
+The core SDK never reads a file. It exposes `ContextSection`: a callback the
+turn loop re-runs before every model round, owning exactly one node on the model
+surface and rewriting it only when its revision changes. This package is the
+Node implementation of that callback for project instruction files.
+
+## Usage
+
+```ts
+import { defineAgent } from '@alvin0/ai-agent-sdk-core'
+import { createProjectInstructionsSection } from '@alvin0/ai-agent-sdk-instructions-node'
+
+const agent = defineAgent({
+  id: 'coder',
+  instructions: 'You are a coding agent.',
+  contextSections: [createProjectInstructionsSection({ cwd: process.cwd() })],
+})
+```
+
+Mount it per session instead when the working directory belongs to the session
+rather than the definition:
+
+```ts
+const session = runtime.agent(agent).createSession({
+  contextSections: [createProjectInstructionsSection({ cwd: workspaceDir })],
+})
+```
+
+## Discovery
+
+1. The configured `globalFile`, when one is supplied. There is no default —
+   a library does not guess where a host keeps a user's standing instructions.
+2. Walk up from `cwd` until a `projectRootMarkers` entry is found (`.git` by
+   default), then read the candidates from that root **down to `cwd`**,
+   inclusive. The walk never passes the root.
+3. Once a tool call touches a file below `cwd`, that subtree's directories join
+   the scan and stay in scope for the rest of the session.
+
+Within one directory, `perDirectory: 'first'` (the default) takes the first
+present candidate — `AGENTS.override.md`, then `AGENTS.md` — and `'all'` takes
+every present candidate. Files with identical trimmed content collapse to the
+first occurrence, so a symlinked or copied twin is not rendered twice.
+
+Rendering is broad-to-specific, each file introduced by
+`Instructions from: <path relative to the project root>`. Content is admitted
+whole under `maxBytes` (64 KiB by default); anything that does not fit is named
+in a closing line rather than silently cut.
+
+## Sharing one instance across agents
+
+One section object is normally mounted on a definition that many sessions
+instantiate — every member of a team, every worker cloned from a lead — and
+those sessions run concurrently. Everything this section accumulates is keyed by
+the conversation scope the loop passes to `resolve`, so a team member that reads
+into `packages/api` does not put that directory's instructions in front of its
+peers. Buckets are bounded by `maxTrackedScopes` and the least recently used one
+is dropped first. A bare `runTurn` with no trace identity shares one unscoped
+bucket.
+
+Mounting the section on the session instead of the definition is still the right
+call when the working directory belongs to the session — the scope keying makes
+sharing *safe*, not preferable.
+
+A skill-relative path never counts as a workspace path: arguments carrying a
+`skillId` (as `read_skill_resource({ skillId, path })` does) are ignored, so a
+skill resource named `references/patterns.md` cannot pull `references/AGENTS.md`
+into context.
+
+## Why a section and not a skill
+
+Project instructions are always-on: a model that never loads them has violated
+the project's conventions without knowing they existed. Skills are the opposite
+contract — advertised by description and loaded only when the model picks them.
+
+Why a section and not `additionalInstructions`: the system prompt is the cache
+prefix, and these files change during a session (the cwd moves, a tool reaches
+into a new subtree, someone edits the file). Rewriting the prefix each time
+would discard the prompt cache, and appending has no way to retract text that no
+longer applies. A section writes into the conversation surface, replaces its own
+node in place, and costs nothing on the steps where nothing changed.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `id` | `project-instructions` | Section id on the model surface |
+| `cwd` | `process.cwd()` | Session working directory |
+| `globalFile` | — | Absolute path read before any project file |
+| `projectRootMarkers` | `['.git']` | Entries that stop the upward walk |
+| `fileNames` | `['AGENTS.override.md', 'AGENTS.md']` | Same-directory candidates, in precedence order |
+| `perDirectory` | `'first'` | `first` or `all` present candidates per directory |
+| `maxBytes` | `65536` | Total UTF-8 ceiling for the rendered section |
+| `maxFileBytes` | `maxBytes` | Per-file UTF-8 ceiling |
+| `nested` | `true` | Scan subtrees a tool call reaches into |
+| `maxNestedDirs` | `256` | Most subtree directories kept in scope at once |
+| `onNestedLimit` | — | Called once per conversation when that cap is reached |
+| `maxTrackedScopes` | `64` | Conversations whose subtrees this instance remembers |
+| `filePathFromTouch` | reads `file_path`/`path`/`filePath` | Which committed call touched which path |
+| `intro` | see `DEFAULT_INTRO` | Paragraph placed above the files |
+| `retractionText` | see `DEFAULT_RETRACTION` | Written when every file leaves scope |
+
+A failed tool call never contributes a path: a read that errored did not enter
+that directory.
+
+Every retained directory is re-probed before every model round, so `maxNestedDirs`
+bounds the per-step filesystem cost of an agent that walks a large tree. Once the
+cap is reached the directories already in scope win, and `onNestedLimit` fires
+once so a host can log it. `maxFileBytes` is bounded by `maxBytes`: a file larger
+than the whole section is skipped without being read.

package/dist/index.d.mts

@@ -0,0 +1,214 @@
+import { ContextSection, ContextSectionScope } from "@alvin0/ai-agent-sdk-core";
+//#region src/config.d.ts
+/**
+ * Normalized discovery configuration for filesystem instruction files.
+ *
+ * @module @alvin0/ai-agent-sdk-instructions-node/config
+ */
+declare const DEFAULT_FILE_NAMES: readonly string[];
+declare const DEFAULT_PROJECT_ROOT_MARKERS: readonly string[];
+declare const DEFAULT_MAX_BYTES = 65536;
+declare const DEFAULT_SECTION_ID = "project-instructions";
+/** Descendant directories retained for re-probing before every model round. */
+declare const DEFAULT_MAX_NESTED_DIRS = 256;
+/** Conversations whose nested scope one section instance remembers at once. */
+declare const DEFAULT_MAX_TRACKED_SCOPES = 64;
+/** One tool call the loop committed, as seen by the path extractor. */
+interface InstructionToolTouch {
+  readonly toolName: string;
+  readonly rawArguments: string;
+  readonly failed: boolean;
+}
+interface ProjectInstructionsOptions {
+  /** Section id on the model surface. Defaults to `project-instructions`. */
+  readonly id?: string;
+  /** Session working directory. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /**
+   * One absolute file read before any project file — the user's own standing
+   * instructions. No default: a package does not guess where a host keeps them.
+   */
+  readonly globalFile?: string;
+  /** Directory entries that stop the upward walk. Defaults to `['.git']`. */
+  readonly projectRootMarkers?: readonly string[];
+  /** Same-directory candidates in precedence order. Defaults to override-then-`AGENTS.md`. */
+  readonly fileNames?: readonly string[];
+  /**
+   * `first` loads the first candidate present in a directory (Codex semantics);
+   * `all` loads every present candidate (deepseek-harness semantics).
+   * Defaults to `first`.
+   */
+  readonly perDirectory?: 'first' | 'all';
+  /** Total UTF-8 ceiling for the rendered section. Defaults to 64 KiB. */
+  readonly maxBytes?: number;
+  /** Per-file UTF-8 ceiling. Defaults to {@link ProjectInstructionsOptions.maxBytes}. */
+  readonly maxFileBytes?: number;
+  /**
+   * Also scan directories below `cwd` once a tool touches a file inside them.
+   *
+   * A model that opens `packages/api/handler.ts` gets `packages/api/AGENTS.md`
+   * without the host having predicted the path. Defaults to true.
+   */
+  readonly nested?: boolean;
+  /**
+   * Which committed tool call touched which path.
+   *
+   * Defaults to reading a `file_path` or `path` string from JSON arguments of a
+   * call that succeeded. Replace it when your tools name the argument otherwise.
+   */
+  readonly filePathFromTouch?: (touch: InstructionToolTouch) => string | undefined;
+  /**
+   * Most descendant directories kept in scope at once. Defaults to 256.
+   *
+   * Each retained directory is re-probed before every model round, so this
+   * bounds the per-step filesystem cost of an agent that walks a large tree.
+   */
+  readonly maxNestedDirs?: number;
+  /** Called once per conversation when {@link ProjectInstructionsOptions.maxNestedDirs} is reached. */
+  readonly onNestedLimit?: (limit: number) => void;
+  /**
+   * Conversations whose accumulated subtrees this section instance remembers.
+   *
+   * One section object is normally mounted on a definition that many sessions
+   * instantiate, so its per-conversation state is kept in a bounded map and the
+   * least recently used conversation is dropped first. Defaults to 64.
+   */
+  readonly maxTrackedScopes?: number;
+  /** Leading paragraph placed above the files. A default is supplied. */
+  readonly intro?: string;
+  /** Replaces the live node when every instruction file disappears. */
+  readonly retractionText?: string;
+}
+interface ResolvedInstructionsConfig {
+  readonly id: string;
+  readonly cwd: string;
+  readonly globalFile: string | undefined;
+  readonly projectRootMarkers: readonly string[];
+  readonly fileNames: readonly string[];
+  readonly perDirectory: 'first' | 'all';
+  readonly maxBytes: number;
+  readonly maxFileBytes: number;
+  readonly nested: boolean;
+  readonly maxNestedDirs: number;
+  readonly onNestedLimit: ((limit: number) => void) | undefined;
+  readonly maxTrackedScopes: number;
+  readonly filePathFromTouch: (touch: InstructionToolTouch) => string | undefined;
+  readonly intro: string;
+  readonly retractionText: string;
+}
+declare const DEFAULT_INTRO: string;
+declare const DEFAULT_RETRACTION: string;
+/**
+ * Read a filesystem path out of one committed tool call.
+ *
+ * Only successful calls are considered: a failed read did not enter a
+ * directory, so it must not pull that directory's instructions into context.
+ * @param touch - the committed call.
+ * @returns the touched path, when the arguments carry a recognizable one.
+ */
+declare function defaultFilePathFromTouch(touch: InstructionToolTouch): string | undefined;
+//#endregion
+//#region src/section.d.ts
+interface ProjectInstructionsSection extends ContextSection {
+  /**
+   * Absolute paths rendered for one conversation, for host diagnostics.
+   * @param scope - the conversation to report on; defaults to the unscoped one.
+   * @returns the paths in the order they were rendered.
+   */
+  loadedPaths(scope?: ContextSectionScope): readonly string[];
+}
+/**
+ * Build the AGENTS.md-compatible context section.
+ *
+ * Discovery walks up from `cwd` to the project root, reads the configured
+ * candidates from the root down, and — once a tool touches a file below `cwd` —
+ * adds that subtree's instruction files too. Content is rendered into one
+ * surface node; the loop rewrites it only when the digest changes.
+ *
+ * One instance is safe to mount on a definition that many sessions instantiate.
+ * Everything it accumulates is keyed by the conversation scope the loop hands
+ * to `resolve`, so a team member that reads into `packages/api` does not put
+ * that directory's instructions in front of its peers. Sessions with no trace
+ * identity — a bare `runTurn` — share one unscoped bucket.
+ *
+ * ```ts
+ * const agent = defineAgent({
+ *   id: 'coder',
+ *   instructions: 'You are a coding agent.',
+ *   contextSections: [createProjectInstructionsSection({ cwd: process.cwd() })],
+ * })
+ * ```
+ * @param options - discovery, budget, and rendering controls.
+ * @returns a section ready to mount on an agent or a session.
+ */
+declare function createProjectInstructionsSection(options?: ProjectInstructionsOptions): ProjectInstructionsSection;
+//#endregion
+//#region src/discovery.d.ts
+/** One instruction file that exists and was read. */
+interface LoadedInstructionFile {
+  readonly absolutePath: string;
+  /** Project-root-relative path shown to the model. */
+  readonly displayPath: string;
+  readonly content: string;
+  readonly mtimeMs: number;
+  readonly size: number;
+}
+/**
+ * Walk upward until a root marker is found.
+ * @param cwd - absolute starting directory.
+ * @param markers - directory entries that identify a root.
+ * @returns the marked ancestor, or `cwd` when no marker exists above it.
+ */
+declare function findProjectRoot(cwd: string, markers: readonly string[], signal?: AbortSignal): Promise<string>;
+/**
+ * Directories from the project root down to `cwd`, inclusive.
+ * @param root - the project root.
+ * @param cwd - the session working directory.
+ * @returns root-first directory chain.
+ */
+declare function ancestorChain(root: string, cwd: string): string[];
+/**
+ * Directories crossed between `base` and a touched file, excluding `base`.
+ * @param base - the directory the chain already covers.
+ * @param touchedPath - absolute path, or one relative to `base`.
+ * @returns shallowest-first descendant directories, empty when the path escapes `base`.
+ */
+declare function descendantDirsBetween(base: string, touchedPath: string): string[];
+/**
+ * Order directories shallowest-first, so a deeper file still reads as the more
+ * specific one. Path length is not depth: `/a/bbbb` is shallower than `/a/b/c`.
+ * @param left - first directory.
+ * @param right - second directory.
+ * @returns a comparator result usable with `Array#sort`.
+ */
+declare function byDepthThenPath(left: string, right: string): number;
+//#endregion
+//#region src/render.d.ts
+interface RenderedInstructions {
+  readonly text: string;
+  readonly revision: string;
+  /** Files that made it into the rendered text, in surface order. */
+  readonly included: readonly LoadedInstructionFile[];
+  /** Files dropped because the section ran out of budget. */
+  readonly omitted: readonly LoadedInstructionFile[];
+}
+/**
+ * Drop files whose trimmed content already appeared earlier.
+ * @param files - discovered files in precedence order.
+ * @returns the first occurrence of each distinct content.
+ */
+declare function dedupeByContent(files: readonly LoadedInstructionFile[]): LoadedInstructionFile[];
+/**
+ * Compose the model-facing text under the total byte ceiling.
+ *
+ * Files are admitted whole, nearest-first is *not* used: precedence order is
+ * broad-to-specific, and a specific file dropped for budget is reported rather
+ * than silently cut in half.
+ * @param files - deduplicated files in precedence order.
+ * @param config - normalized configuration.
+ * @returns the rendered section, or undefined when nothing is in scope.
+ */
+declare function renderInstructions(files: readonly LoadedInstructionFile[], config: ResolvedInstructionsConfig): RenderedInstructions | undefined;
+//#endregion
+export { DEFAULT_FILE_NAMES, DEFAULT_INTRO, DEFAULT_MAX_BYTES, DEFAULT_MAX_NESTED_DIRS, DEFAULT_MAX_TRACKED_SCOPES, DEFAULT_PROJECT_ROOT_MARKERS, DEFAULT_RETRACTION, DEFAULT_SECTION_ID, type InstructionToolTouch, type LoadedInstructionFile, type ProjectInstructionsOptions, type ProjectInstructionsSection, type RenderedInstructions, ancestorChain, byDepthThenPath, createProjectInstructionsSection, dedupeByContent, defaultFilePathFromTouch, descendantDirsBetween, findProjectRoot, renderInstructions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/section.ts","../src/discovery.ts","../src/render.ts"],"mappings":";;;;;;;cAMa;cACA;cACA;cACA;;cAEA;;cAEA;;UAKI;WACN;WACA;WACA;;UAGM;;WAEN;;WAEA;;;;;WAKA;;WAEA;;WAEA;;;;;;WAMA;;WAEA;;WAEA;;;;;;;WAOA;;;;;;;WAOA,qBAAqB,OAAO;;;;;;;WAO5B;;WAEA,iBAAiB;;;;;;;;WAQjB;;WAEA;;WAEA;;UAGM;WACN;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA,iBAAiB;WACjB;WACA,oBAAoB,OAAO;WAC3B;WACA;;cAGE;cAIA;;;;;;;;;iBAWG,yBAAyB,OAAO;;;UCnE/B,mCAAmC;;;;;;EAMlD,YAAY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCN,iCACd,UAAS,6BACR;;;;UCrFc;WACN;;WAEA;WACA;WACA;WACA;;;;;;;;iBA8BW,gBACpB,aACA,4BACA,SAAS,cACR;;;;;;;iBAkBa,cAAc,cAAc;;;;;;;iBAoB5B,sBAAsB,cAAc;;;;;;;;iBAiGpC,gBAAgB,cAAc;;;UCjL7B;WACN;WACA;;WAEA,mBAAmB;;WAEnB,kBAAkB;;;;;;;iBAqBb,gBAAgB,gBAAgB,0BAA0B;;;;;;;;;;;iBAyB1D,mBACd,gBAAgB,yBAChB,QAAQ,6BACP"}

package/dist/index.mjs

@@ -0,0 +1,437 @@
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { defineContextSection } from "@alvin0/ai-agent-sdk-core";
+import { readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+
+//#region src/config.ts
+/**
+* Normalized discovery configuration for filesystem instruction files.
+*
+* @module @alvin0/ai-agent-sdk-instructions-node/config
+*/
+const DEFAULT_FILE_NAMES = Object.freeze(["AGENTS.override.md", "AGENTS.md"]);
+const DEFAULT_PROJECT_ROOT_MARKERS = Object.freeze([".git"]);
+const DEFAULT_MAX_BYTES = 65536;
+const DEFAULT_SECTION_ID = "project-instructions";
+/** Descendant directories retained for re-probing before every model round. */
+const DEFAULT_MAX_NESTED_DIRS = 256;
+/** Conversations whose nested scope one section instance remembers at once. */
+const DEFAULT_MAX_TRACKED_SCOPES = 64;
+const RESERVED_SEGMENTS = /* @__PURE__ */ new Set([
+	"",
+	".",
+	".."
+]);
+const DEFAULT_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 DEFAULT_RETRACTION = "The workspace instructions provided earlier no longer apply. No instruction files are currently in scope.";
+/**
+* Read a filesystem path out of one committed tool call.
+*
+* Only successful calls are considered: a failed read did not enter a
+* directory, so it must not pull that directory's instructions into context.
+* @param touch - the committed call.
+* @returns the touched path, when the arguments carry a recognizable one.
+*/
+function defaultFilePathFromTouch(touch) {
+	if (touch.failed) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(touch.rawArguments);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const record = parsed;
+	if (typeof record.skillId === "string") return void 0;
+	for (const key of [
+		"file_path",
+		"filePath",
+		"path"
+	]) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim().length > 0) return value.trim();
+	}
+}
+function positiveBytes(value, fallback, name) {
+	if (value === void 0) return fallback;
+	if (!Number.isFinite(value) || value <= 0) throw new TypeError(`${name} must be a positive finite number`);
+	return Math.floor(value);
+}
+/**
+* Apply defaults and drop candidates that are not plain file names.
+* @param options - user-facing options.
+* @param cwd - fallback working directory when none was supplied.
+* @returns the normalized configuration.
+*/
+function resolveInstructionsConfig(options, cwd) {
+	const maxBytes = positiveBytes(options.maxBytes, DEFAULT_MAX_BYTES, "maxBytes");
+	const fileNames = (options.fileNames ?? DEFAULT_FILE_NAMES).filter((name) => !RESERVED_SEGMENTS.has(name) && !/[\\/]/.test(name));
+	if (fileNames.length === 0) throw new TypeError("fileNames must contain at least one plain file name");
+	return Object.freeze({
+		id: options.id ?? "project-instructions",
+		cwd: options.cwd ?? cwd,
+		globalFile: options.globalFile,
+		projectRootMarkers: Object.freeze([...options.projectRootMarkers ?? DEFAULT_PROJECT_ROOT_MARKERS]),
+		fileNames: Object.freeze(fileNames),
+		perDirectory: options.perDirectory ?? "first",
+		maxBytes,
+		maxFileBytes: positiveBytes(options.maxFileBytes, maxBytes, "maxFileBytes"),
+		nested: options.nested ?? true,
+		maxNestedDirs: positiveBytes(options.maxNestedDirs, 256, "maxNestedDirs"),
+		onNestedLimit: options.onNestedLimit,
+		maxTrackedScopes: positiveBytes(options.maxTrackedScopes, 64, "maxTrackedScopes"),
+		filePathFromTouch: options.filePathFromTouch ?? defaultFilePathFromTouch,
+		intro: options.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.",
+		retractionText: options.retractionText ?? "The workspace instructions provided earlier no longer apply. No instruction files are currently in scope."
+	});
+}
+
+//#endregion
+//#region src/discovery.ts
+/**
+* Filesystem walk for instruction files: project root, ancestor chain, and the
+* descendant directories a tool call reached into.
+*
+* @module @alvin0/ai-agent-sdk-instructions-node/discovery
+*/
+async function isFile(path) {
+	try {
+		const info = await stat(path);
+		return info.isFile() ? {
+			mtimeMs: info.mtimeMs,
+			size: info.size
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+async function hasMarker(dir, markers) {
+	for (const marker of markers) try {
+		await stat(join(dir, marker));
+		return true;
+	} catch {}
+	return false;
+}
+/**
+* Walk upward until a root marker is found.
+* @param cwd - absolute starting directory.
+* @param markers - directory entries that identify a root.
+* @returns the marked ancestor, or `cwd` when no marker exists above it.
+*/
+async function findProjectRoot(cwd, markers, signal) {
+	if (markers.length === 0) return resolve(cwd);
+	let current = resolve(cwd);
+	while (true) {
+		signal?.throwIfAborted();
+		if (await hasMarker(current, markers)) return current;
+		const parent = dirname(current);
+		if (parent === current) return resolve(cwd);
+		current = parent;
+	}
+}
+/**
+* Directories from the project root down to `cwd`, inclusive.
+* @param root - the project root.
+* @param cwd - the session working directory.
+* @returns root-first directory chain.
+*/
+function ancestorChain(root, cwd) {
+	const resolvedRoot = resolve(root);
+	const chain = [];
+	let current = resolve(cwd);
+	while (current !== resolvedRoot) {
+		chain.push(current);
+		const parent = dirname(current);
+		if (parent === current) return [resolvedRoot];
+		current = parent;
+	}
+	chain.push(resolvedRoot);
+	return chain.reverse();
+}
+/**
+* Directories crossed between `base` and a touched file, excluding `base`.
+* @param base - the directory the chain already covers.
+* @param touchedPath - absolute path, or one relative to `base`.
+* @returns shallowest-first descendant directories, empty when the path escapes `base`.
+*/
+function descendantDirsBetween(base, touchedPath) {
+	const resolvedBase = resolve(base);
+	const target = isAbsolute(touchedPath) ? resolve(touchedPath) : resolve(resolvedBase, touchedPath);
+	const dir = dirname(target);
+	const rel = relative(resolvedBase, dir);
+	if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel)) return [];
+	const segments = rel.split(sep).filter((segment) => segment.length > 0);
+	return segments.map((_, index) => join(resolvedBase, ...segments.slice(0, index + 1)));
+}
+function utf8Bytes$1(value) {
+	return Buffer.byteLength(value, "utf8");
+}
+/**
+* Read the instruction candidates present in one directory.
+* @param dir - absolute directory to probe.
+* @param root - display base.
+* @param config - normalized configuration.
+* @returns the files that exist, in candidate precedence order.
+*/
+async function directoryInstructionFiles(dir, root, config, signal) {
+	const found = [];
+	for (const name of config.fileNames) {
+		signal?.throwIfAborted();
+		const absolutePath = join(dir, name);
+		const info = await isFile(absolutePath);
+		if (info === void 0) continue;
+		const loaded = await readInstructionFile(absolutePath, root, config, info);
+		if (loaded !== void 0) {
+			found.push(loaded);
+			if (config.perDirectory === "first") break;
+		}
+	}
+	return found;
+}
+/**
+* Read one instruction file, skipping it when it exceeds the per-file ceiling.
+* @param absolutePath - the file to read.
+* @param root - display base.
+* @param config - normalized configuration.
+* @param info - stat data already collected for the file.
+* @returns the loaded file, or undefined when it is empty, oversized, or unreadable.
+*/
+async function readInstructionFile(absolutePath, root, config, info) {
+	const ceiling = Math.min(config.maxFileBytes, config.maxBytes);
+	if (info.size > ceiling) return void 0;
+	let content;
+	try {
+		content = await readFile(absolutePath, "utf8");
+	} catch {
+		return;
+	}
+	if (content.trim().length === 0) return void 0;
+	if (utf8Bytes$1(content) > ceiling) return void 0;
+	return {
+		absolutePath,
+		displayPath: absolutePath.startsWith(resolve(root) + sep) ? relative(resolve(root), absolutePath) : absolutePath,
+		content,
+		mtimeMs: info.mtimeMs,
+		size: info.size
+	};
+}
+/**
+* Probe the configured global file, when one was supplied.
+* @param config - normalized configuration.
+* @returns the loaded global file, or undefined.
+*/
+async function globalInstructionFile(config) {
+	if (config.globalFile === void 0) return void 0;
+	const absolutePath = resolve(config.globalFile);
+	const info = await isFile(absolutePath);
+	if (info === void 0) return void 0;
+	return readInstructionFile(absolutePath, dirname(absolutePath), config, info);
+}
+/**
+* Order directories shallowest-first, so a deeper file still reads as the more
+* specific one. Path length is not depth: `/a/bbbb` is shallower than `/a/b/c`.
+* @param left - first directory.
+* @param right - second directory.
+* @returns a comparator result usable with `Array#sort`.
+*/
+function byDepthThenPath(left, right) {
+	const depth = left.split(sep).length - right.split(sep).length;
+	return depth !== 0 ? depth : left < right ? -1 : left > right ? 1 : 0;
+}
+
+//#endregion
+//#region src/render.ts
+/**
+* Rendering and byte accounting for the instruction section.
+*
+* @module @alvin0/ai-agent-sdk-instructions-node/render
+*/
+function utf8Bytes(value) {
+	return Buffer.byteLength(value, "utf8");
+}
+/** Whitespace-insensitive identity, so a symlinked or copied twin collapses. */
+function trimmedDigest(content) {
+	return createHash("sha256").update(content.trim()).digest("hex");
+}
+function sectionText(file) {
+	return `Instructions from: ${file.displayPath}\n\n${file.content.trim()}`;
+}
+/**
+* Drop files whose trimmed content already appeared earlier.
+* @param files - discovered files in precedence order.
+* @returns the first occurrence of each distinct content.
+*/
+function dedupeByContent(files) {
+	const seenPaths = /* @__PURE__ */ new Set();
+	const seenContent = /* @__PURE__ */ new Set();
+	const kept = [];
+	for (const file of files) {
+		if (seenPaths.has(file.absolutePath)) continue;
+		seenPaths.add(file.absolutePath);
+		const digest = trimmedDigest(file.content);
+		if (seenContent.has(digest)) continue;
+		seenContent.add(digest);
+		kept.push(file);
+	}
+	return kept;
+}
+/**
+* Compose the model-facing text under the total byte ceiling.
+*
+* Files are admitted whole, nearest-first is *not* used: precedence order is
+* broad-to-specific, and a specific file dropped for budget is reported rather
+* than silently cut in half.
+* @param files - deduplicated files in precedence order.
+* @param config - normalized configuration.
+* @returns the rendered section, or undefined when nothing is in scope.
+*/
+function renderInstructions(files, config) {
+	if (files.length === 0) return void 0;
+	const included = [];
+	const omitted = [];
+	let used = utf8Bytes(config.intro);
+	for (const file of files) {
+		const cost = utf8Bytes(sectionText(file)) + 2;
+		if (used + cost > config.maxBytes) {
+			omitted.push(file);
+			continue;
+		}
+		used += cost;
+		included.push(file);
+	}
+	if (included.length === 0) return void 0;
+	const notice = omitted.length === 0 ? "" : `\n\nOmitted for the ${config.maxBytes}-byte instruction budget: ${omitted.map((file) => file.displayPath).join(", ")}.`;
+	const text = `${config.intro}\n\n${included.map(sectionText).join("\n\n")}${notice}`;
+	return {
+		text,
+		revision: createHash("sha256").update(text).digest("hex"),
+		included: Object.freeze(included),
+		omitted: Object.freeze(omitted)
+	};
+}
+
+//#endregion
+//#region src/section.ts
+/**
+* The filesystem-backed {@link ContextSection} itself.
+*
+* @module @alvin0/ai-agent-sdk-instructions-node/section
+*/
+/**
+* Discover every instruction file currently in scope.
+* @param config - normalized configuration.
+* @param extraDirs - descendant directories a tool call reached into.
+* @returns files in broad-to-specific precedence order.
+*/
+async function discover(config, extraDirs, signal) {
+	const cwd = resolve(config.cwd);
+	const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, signal);
+	const files = [];
+	const global = await globalInstructionFile(config);
+	if (global !== void 0) files.push(global);
+	const seen = new Set(ancestorChain(projectRoot, cwd));
+	const dirs = [...seen];
+	for (const dir of [...extraDirs].sort(byDepthThenPath)) {
+		if (seen.has(dir)) continue;
+		seen.add(dir);
+		dirs.push(dir);
+	}
+	for (const dir of dirs) files.push(...await directoryInstructionFiles(dir, projectRoot, config, signal));
+	return {
+		files,
+		projectRoot
+	};
+}
+function scopeKey(scope) {
+	return `${scope?.agentId ?? ""}\u0000${scope?.conversationId ?? ""}`;
+}
+/**
+* Build the AGENTS.md-compatible context section.
+*
+* Discovery walks up from `cwd` to the project root, reads the configured
+* candidates from the root down, and — once a tool touches a file below `cwd` —
+* adds that subtree's instruction files too. Content is rendered into one
+* surface node; the loop rewrites it only when the digest changes.
+*
+* One instance is safe to mount on a definition that many sessions instantiate.
+* Everything it accumulates is keyed by the conversation scope the loop hands
+* to `resolve`, so a team member that reads into `packages/api` does not put
+* that directory's instructions in front of its peers. Sessions with no trace
+* identity — a bare `runTurn` — share one unscoped bucket.
+*
+* ```ts
+* const agent = defineAgent({
+*   id: 'coder',
+*   instructions: 'You are a coding agent.',
+*   contextSections: [createProjectInstructionsSection({ cwd: process.cwd() })],
+* })
+* ```
+* @param options - discovery, budget, and rendering controls.
+* @returns a section ready to mount on an agent or a session.
+*/
+function createProjectInstructionsSection(options = {}) {
+	const config = resolveInstructionsConfig(options, process.cwd());
+	const scopes = /* @__PURE__ */ new Map();
+	const stateFor = (scope) => {
+		const key = scopeKey(scope);
+		const existing = scopes.get(key);
+		if (existing !== void 0) {
+			scopes.delete(key);
+			scopes.set(key, existing);
+			return existing;
+		}
+		const created = {
+			nestedDirs: /* @__PURE__ */ new Set(),
+			nestedLimitReported: false,
+			loaded: Object.freeze([])
+		};
+		scopes.set(key, created);
+		while (scopes.size > config.maxTrackedScopes) {
+			const oldest = scopes.keys().next();
+			if (oldest.done === true) break;
+			scopes.delete(oldest.value);
+		}
+		return created;
+	};
+	const section = defineContextSection({
+		id: config.id,
+		retractionText: config.retractionText,
+		async resolve(input) {
+			const state = stateFor(input.scope);
+			if (config.nested) for (const touch of input.touches) {
+				const path = config.filePathFromTouch(touch);
+				if (path === void 0) continue;
+				for (const dir of descendantDirsBetween(config.cwd, path)) {
+					if (state.nestedDirs.size >= config.maxNestedDirs) {
+						if (!state.nestedLimitReported) {
+							state.nestedLimitReported = true;
+							config.onNestedLimit?.(config.maxNestedDirs);
+						}
+						break;
+					}
+					state.nestedDirs.add(dir);
+				}
+			}
+			input.signal.throwIfAborted();
+			const { files } = await discover(config, [...state.nestedDirs], input.signal);
+			const rendered = renderInstructions(dedupeByContent(files), config);
+			if (rendered === void 0) {
+				state.loaded = Object.freeze([]);
+				return;
+			}
+			state.loaded = Object.freeze(rendered.included.map((file) => file.absolutePath));
+			return {
+				revision: rendered.revision,
+				text: rendered.text
+			};
+		}
+	});
+	return Object.freeze({
+		...section,
+		loadedPaths: (scope) => scopes.get(scopeKey(scope))?.loaded ?? Object.freeze([])
+	});
+}
+
+//#endregion
+export { DEFAULT_FILE_NAMES, DEFAULT_INTRO, DEFAULT_MAX_BYTES, DEFAULT_MAX_NESTED_DIRS, DEFAULT_MAX_TRACKED_SCOPES, DEFAULT_PROJECT_ROOT_MARKERS, DEFAULT_RETRACTION, DEFAULT_SECTION_ID, ancestorChain, byDepthThenPath, createProjectInstructionsSection, dedupeByContent, defaultFilePathFromTouch, descendantDirsBetween, findProjectRoot, renderInstructions };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["utf8Bytes"],"sources":["../src/config.ts","../src/discovery.ts","../src/render.ts","../src/section.ts"],"sourcesContent":["/**\n * Normalized discovery configuration for filesystem instruction files.\n *\n * @module @alvin0/ai-agent-sdk-instructions-node/config\n */\n\nexport const DEFAULT_FILE_NAMES = Object.freeze(['AGENTS.override.md', 'AGENTS.md'])\nexport const DEFAULT_PROJECT_ROOT_MARKERS = Object.freeze(['.git'])\nexport const DEFAULT_MAX_BYTES = 65_536\nexport const DEFAULT_SECTION_ID = 'project-instructions'\n/** Descendant directories retained for re-probing before every model round. */\nexport const DEFAULT_MAX_NESTED_DIRS = 256\n/** Conversations whose nested scope one section instance remembers at once. */\nexport const DEFAULT_MAX_TRACKED_SCOPES = 64\n\nconst RESERVED_SEGMENTS = new Set(['', '.', '..'])\n\n/** One tool call the loop committed, as seen by the path extractor. */\nexport interface InstructionToolTouch {\n  readonly toolName: string\n  readonly rawArguments: string\n  readonly failed: boolean\n}\n\nexport interface ProjectInstructionsOptions {\n  /** Section id on the model surface. Defaults to `project-instructions`. */\n  readonly id?: string\n  /** Session working directory. Defaults to `process.cwd()`. */\n  readonly cwd?: string\n  /**\n   * One absolute file read before any project file — the user's own standing\n   * instructions. No default: a package does not guess where a host keeps them.\n   */\n  readonly globalFile?: string\n  /** Directory entries that stop the upward walk. Defaults to `['.git']`. */\n  readonly projectRootMarkers?: readonly string[]\n  /** Same-directory candidates in precedence order. Defaults to override-then-`AGENTS.md`. */\n  readonly fileNames?: readonly string[]\n  /**\n   * `first` loads the first candidate present in a directory (Codex semantics);\n   * `all` loads every present candidate (deepseek-harness semantics).\n   * Defaults to `first`.\n   */\n  readonly perDirectory?: 'first' | 'all'\n  /** Total UTF-8 ceiling for the rendered section. Defaults to 64 KiB. */\n  readonly maxBytes?: number\n  /** Per-file UTF-8 ceiling. Defaults to {@link ProjectInstructionsOptions.maxBytes}. */\n  readonly maxFileBytes?: number\n  /**\n   * Also scan directories below `cwd` once a tool touches a file inside them.\n   *\n   * A model that opens `packages/api/handler.ts` gets `packages/api/AGENTS.md`\n   * without the host having predicted the path. Defaults to true.\n   */\n  readonly nested?: boolean\n  /**\n   * Which committed tool call touched which path.\n   *\n   * Defaults to reading a `file_path` or `path` string from JSON arguments of a\n   * call that succeeded. Replace it when your tools name the argument otherwise.\n   */\n  readonly filePathFromTouch?: (touch: InstructionToolTouch) => string | undefined\n  /**\n   * Most descendant directories kept in scope at once. Defaults to 256.\n   *\n   * Each retained directory is re-probed before every model round, so this\n   * bounds the per-step filesystem cost of an agent that walks a large tree.\n   */\n  readonly maxNestedDirs?: number\n  /** Called once per conversation when {@link ProjectInstructionsOptions.maxNestedDirs} is reached. */\n  readonly onNestedLimit?: (limit: number) => void\n  /**\n   * Conversations whose accumulated subtrees this section instance remembers.\n   *\n   * One section object is normally mounted on a definition that many sessions\n   * instantiate, so its per-conversation state is kept in a bounded map and the\n   * least recently used conversation is dropped first. Defaults to 64.\n   */\n  readonly maxTrackedScopes?: number\n  /** Leading paragraph placed above the files. A default is supplied. */\n  readonly intro?: string\n  /** Replaces the live node when every instruction file disappears. */\n  readonly retractionText?: string\n}\n\nexport interface ResolvedInstructionsConfig {\n  readonly id: string\n  readonly cwd: string\n  readonly globalFile: string | undefined\n  readonly projectRootMarkers: readonly string[]\n  readonly fileNames: readonly string[]\n  readonly perDirectory: 'first' | 'all'\n  readonly maxBytes: number\n  readonly maxFileBytes: number\n  readonly nested: boolean\n  readonly maxNestedDirs: number\n  readonly onNestedLimit: ((limit: number) => void) | undefined\n  readonly maxTrackedScopes: number\n  readonly filePathFromTouch: (touch: InstructionToolTouch) => string | undefined\n  readonly intro: string\n  readonly retractionText: string\n}\n\nexport const DEFAULT_INTRO = 'The following workspace instructions may be relevant to your work. '\n  + 'Use them as guidance when applicable. More specific instructions take precedence over broader '\n  + 'ones. They do not override system, developer, or direct user instructions.'\n\nexport const DEFAULT_RETRACTION = 'The workspace instructions provided earlier no longer apply. '\n  + 'No instruction files are currently in scope.'\n\n/**\n * Read a filesystem path out of one committed tool call.\n *\n * Only successful calls are considered: a failed read did not enter a\n * directory, so it must not pull that directory's instructions into context.\n * @param touch - the committed call.\n * @returns the touched path, when the arguments carry a recognizable one.\n */\nexport function defaultFilePathFromTouch(touch: InstructionToolTouch): string | undefined {\n  if (touch.failed) return undefined\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(touch.rawArguments)\n  } catch {\n    return undefined\n  }\n  if (typeof parsed !== 'object' || parsed === null) return undefined\n  const record = parsed as Record<string, unknown>\n  // A `path` beside a `skillId` addresses a resource inside that skill's\n  // bundle, not a place in the workspace. `read_skill_resource({skillId, path})`\n  // would otherwise resolve `references/patterns.md` against the cwd and pull a\n  // wholly unrelated directory's instructions into context.\n  if (typeof record.skillId === 'string') return undefined\n  for (const key of ['file_path', 'filePath', 'path']) {\n    const value = record[key]\n    if (typeof value === 'string' && value.trim().length > 0) return value.trim()\n  }\n  return undefined\n}\n\nfunction positiveBytes(value: number | undefined, fallback: number, name: string): number {\n  if (value === undefined) return fallback\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new TypeError(`${name} must be a positive finite number`)\n  }\n  return Math.floor(value)\n}\n\n/**\n * Apply defaults and drop candidates that are not plain file names.\n * @param options - user-facing options.\n * @param cwd - fallback working directory when none was supplied.\n * @returns the normalized configuration.\n */\nexport function resolveInstructionsConfig(\n  options: ProjectInstructionsOptions,\n  cwd: string,\n): ResolvedInstructionsConfig {\n  const maxBytes = positiveBytes(options.maxBytes, DEFAULT_MAX_BYTES, 'maxBytes')\n  const fileNames = (options.fileNames ?? DEFAULT_FILE_NAMES).filter(name => (\n    !RESERVED_SEGMENTS.has(name) && !/[\\\\/]/.test(name)\n  ))\n  if (fileNames.length === 0) throw new TypeError('fileNames must contain at least one plain file name')\n  return Object.freeze({\n    id: options.id ?? DEFAULT_SECTION_ID,\n    cwd: options.cwd ?? cwd,\n    globalFile: options.globalFile,\n    projectRootMarkers: Object.freeze([...options.projectRootMarkers ?? DEFAULT_PROJECT_ROOT_MARKERS]),\n    fileNames: Object.freeze(fileNames),\n    perDirectory: options.perDirectory ?? 'first',\n    maxBytes,\n    maxFileBytes: positiveBytes(options.maxFileBytes, maxBytes, 'maxFileBytes'),\n    nested: options.nested ?? true,\n    maxNestedDirs: positiveBytes(options.maxNestedDirs, DEFAULT_MAX_NESTED_DIRS, 'maxNestedDirs'),\n    onNestedLimit: options.onNestedLimit,\n    maxTrackedScopes: positiveBytes(\n      options.maxTrackedScopes, DEFAULT_MAX_TRACKED_SCOPES, 'maxTrackedScopes',\n    ),\n    filePathFromTouch: options.filePathFromTouch ?? defaultFilePathFromTouch,\n    intro: options.intro ?? DEFAULT_INTRO,\n    retractionText: options.retractionText ?? DEFAULT_RETRACTION,\n  })\n}\n","/**\n * Filesystem walk for instruction files: project root, ancestor chain, and the\n * descendant directories a tool call reached into.\n *\n * @module @alvin0/ai-agent-sdk-instructions-node/discovery\n */\n\nimport { readFile, stat } from 'node:fs/promises'\nimport { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'\nimport type { ResolvedInstructionsConfig } from './config.ts'\n\n/** One instruction file that exists and was read. */\nexport interface LoadedInstructionFile {\n  readonly absolutePath: string\n  /** Project-root-relative path shown to the model. */\n  readonly displayPath: string\n  readonly content: string\n  readonly mtimeMs: number\n  readonly size: number\n}\n\nasync function isFile(path: string): Promise<{ mtimeMs: number; size: number } | undefined> {\n  try {\n    const info = await stat(path)\n    return info.isFile() ? { mtimeMs: info.mtimeMs, size: info.size } : undefined\n  } catch {\n    // A missing candidate is the normal case; an unreadable one is skipped for\n    // the same reason — assembled context must never fail a turn.\n    return undefined\n  }\n}\n\nasync function hasMarker(dir: string, markers: readonly string[]): Promise<boolean> {\n  for (const marker of markers) {\n    try {\n      await stat(join(dir, marker))\n      return true\n    } catch { /* keep looking */ }\n  }\n  return false\n}\n\n/**\n * Walk upward until a root marker is found.\n * @param cwd - absolute starting directory.\n * @param markers - directory entries that identify a root.\n * @returns the marked ancestor, or `cwd` when no marker exists above it.\n */\nexport async function findProjectRoot(\n  cwd: string,\n  markers: readonly string[],\n  signal?: AbortSignal,\n): Promise<string> {\n  if (markers.length === 0) return resolve(cwd)\n  let current = resolve(cwd)\n  while (true) {\n    signal?.throwIfAborted()\n    if (await hasMarker(current, markers)) return current\n    const parent = dirname(current)\n    if (parent === current) return resolve(cwd)\n    current = parent\n  }\n}\n\n/**\n * Directories from the project root down to `cwd`, inclusive.\n * @param root - the project root.\n * @param cwd - the session working directory.\n * @returns root-first directory chain.\n */\nexport function ancestorChain(root: string, cwd: string): string[] {\n  const resolvedRoot = resolve(root)\n  const chain: string[] = []\n  let current = resolve(cwd)\n  while (current !== resolvedRoot) {\n    chain.push(current)\n    const parent = dirname(current)\n    if (parent === current) return [resolvedRoot]\n    current = parent\n  }\n  chain.push(resolvedRoot)\n  return chain.reverse()\n}\n\n/**\n * Directories crossed between `base` and a touched file, excluding `base`.\n * @param base - the directory the chain already covers.\n * @param touchedPath - absolute path, or one relative to `base`.\n * @returns shallowest-first descendant directories, empty when the path escapes `base`.\n */\nexport function descendantDirsBetween(base: string, touchedPath: string): string[] {\n  const resolvedBase = resolve(base)\n  const target = isAbsolute(touchedPath) ? resolve(touchedPath) : resolve(resolvedBase, touchedPath)\n  const dir = dirname(target)\n  const rel = relative(resolvedBase, dir)\n  if (rel.length === 0 || rel.startsWith('..') || isAbsolute(rel)) return []\n  const segments = rel.split(sep).filter(segment => segment.length > 0)\n  return segments.map((_, index) => join(resolvedBase, ...segments.slice(0, index + 1)))\n}\n\nfunction utf8Bytes(value: string): number {\n  return Buffer.byteLength(value, 'utf8')\n}\n\n/**\n * Read the instruction candidates present in one directory.\n * @param dir - absolute directory to probe.\n * @param root - display base.\n * @param config - normalized configuration.\n * @returns the files that exist, in candidate precedence order.\n */\nexport async function directoryInstructionFiles(\n  dir: string,\n  root: string,\n  config: ResolvedInstructionsConfig,\n  signal?: AbortSignal,\n): Promise<LoadedInstructionFile[]> {\n  const found: LoadedInstructionFile[] = []\n  for (const name of config.fileNames) {\n    signal?.throwIfAborted()\n    const absolutePath = join(dir, name)\n    const info = await isFile(absolutePath)\n    if (info === undefined) continue\n    const loaded = await readInstructionFile(absolutePath, root, config, info)\n    if (loaded !== undefined) {\n      found.push(loaded)\n      if (config.perDirectory === 'first') break\n    }\n  }\n  return found\n}\n\n/**\n * Read one instruction file, skipping it when it exceeds the per-file ceiling.\n * @param absolutePath - the file to read.\n * @param root - display base.\n * @param config - normalized configuration.\n * @param info - stat data already collected for the file.\n * @returns the loaded file, or undefined when it is empty, oversized, or unreadable.\n */\nexport async function readInstructionFile(\n  absolutePath: string,\n  root: string,\n  config: ResolvedInstructionsConfig,\n  info: { mtimeMs: number; size: number },\n): Promise<LoadedInstructionFile | undefined> {\n  // A file larger than the whole section can never be rendered usefully, and\n  // reading it first would spend the memory to prove that. The section ceiling\n  // bounds the per-file ceiling for exactly that reason.\n  const ceiling = Math.min(config.maxFileBytes, config.maxBytes)\n  if (info.size > ceiling) return undefined\n  let content: string\n  try {\n    content = await readFile(absolutePath, 'utf8')\n  } catch {\n    return undefined\n  }\n  if (content.trim().length === 0) return undefined\n  if (utf8Bytes(content) > ceiling) return undefined\n  const displayPath = absolutePath.startsWith(resolve(root) + sep)\n    ? relative(resolve(root), absolutePath)\n    : absolutePath\n  return { absolutePath, displayPath, content, mtimeMs: info.mtimeMs, size: info.size }\n}\n\n/**\n * Probe the configured global file, when one was supplied.\n * @param config - normalized configuration.\n * @returns the loaded global file, or undefined.\n */\nexport async function globalInstructionFile(\n  config: ResolvedInstructionsConfig,\n): Promise<LoadedInstructionFile | undefined> {\n  if (config.globalFile === undefined) return undefined\n  const absolutePath = resolve(config.globalFile)\n  const info = await isFile(absolutePath)\n  if (info === undefined) return undefined\n  return readInstructionFile(absolutePath, dirname(absolutePath), config, info)\n}\n\n/**\n * Order directories shallowest-first, so a deeper file still reads as the more\n * specific one. Path length is not depth: `/a/bbbb` is shallower than `/a/b/c`.\n * @param left - first directory.\n * @param right - second directory.\n * @returns a comparator result usable with `Array#sort`.\n */\nexport function byDepthThenPath(left: string, right: string): number {\n  const depth = left.split(sep).length - right.split(sep).length\n  return depth !== 0 ? depth : (left < right ? -1 : left > right ? 1 : 0)\n}\n","/**\n * Rendering and byte accounting for the instruction section.\n *\n * @module @alvin0/ai-agent-sdk-instructions-node/render\n */\n\nimport { createHash } from 'node:crypto'\nimport type { ResolvedInstructionsConfig } from './config.ts'\nimport type { LoadedInstructionFile } from './discovery.ts'\n\nexport interface RenderedInstructions {\n  readonly text: string\n  readonly revision: string\n  /** Files that made it into the rendered text, in surface order. */\n  readonly included: readonly LoadedInstructionFile[]\n  /** Files dropped because the section ran out of budget. */\n  readonly omitted: readonly LoadedInstructionFile[]\n}\n\nfunction utf8Bytes(value: string): number {\n  return Buffer.byteLength(value, 'utf8')\n}\n\n/** Whitespace-insensitive identity, so a symlinked or copied twin collapses. */\nfunction trimmedDigest(content: string): string {\n  return createHash('sha256').update(content.trim()).digest('hex')\n}\n\nfunction sectionText(file: LoadedInstructionFile): string {\n  return `Instructions from: ${file.displayPath}\\n\\n${file.content.trim()}`\n}\n\n/**\n * Drop files whose trimmed content already appeared earlier.\n * @param files - discovered files in precedence order.\n * @returns the first occurrence of each distinct content.\n */\nexport function dedupeByContent(files: readonly LoadedInstructionFile[]): LoadedInstructionFile[] {\n  const seenPaths = new Set<string>()\n  const seenContent = new Set<string>()\n  const kept: LoadedInstructionFile[] = []\n  for (const file of files) {\n    if (seenPaths.has(file.absolutePath)) continue\n    seenPaths.add(file.absolutePath)\n    const digest = trimmedDigest(file.content)\n    if (seenContent.has(digest)) continue\n    seenContent.add(digest)\n    kept.push(file)\n  }\n  return kept\n}\n\n/**\n * Compose the model-facing text under the total byte ceiling.\n *\n * Files are admitted whole, nearest-first is *not* used: precedence order is\n * broad-to-specific, and a specific file dropped for budget is reported rather\n * than silently cut in half.\n * @param files - deduplicated files in precedence order.\n * @param config - normalized configuration.\n * @returns the rendered section, or undefined when nothing is in scope.\n */\nexport function renderInstructions(\n  files: readonly LoadedInstructionFile[],\n  config: ResolvedInstructionsConfig,\n): RenderedInstructions | undefined {\n  if (files.length === 0) return undefined\n  const included: LoadedInstructionFile[] = []\n  const omitted: LoadedInstructionFile[] = []\n  let used = utf8Bytes(config.intro)\n  for (const file of files) {\n    const block = sectionText(file)\n    const cost = utf8Bytes(block) + 2\n    if (used + cost > config.maxBytes) {\n      omitted.push(file)\n      continue\n    }\n    used += cost\n    included.push(file)\n  }\n  if (included.length === 0) return undefined\n  const notice = omitted.length === 0\n    ? ''\n    : `\\n\\nOmitted for the ${config.maxBytes}-byte instruction budget: `\n      + `${omitted.map(file => file.displayPath).join(', ')}.`\n  const text = `${config.intro}\\n\\n${included.map(sectionText).join('\\n\\n')}${notice}`\n  // The digest covers exactly what the model reads, so any change to content,\n  // ordering, or the omission notice produces a new revision and one rewrite.\n  return {\n    text,\n    revision: createHash('sha256').update(text).digest('hex'),\n    included: Object.freeze(included),\n    omitted: Object.freeze(omitted),\n  }\n}\n","/**\n * The filesystem-backed {@link ContextSection} itself.\n *\n * @module @alvin0/ai-agent-sdk-instructions-node/section\n */\n\nimport { resolve } from 'node:path'\nimport { defineContextSection } from '@alvin0/ai-agent-sdk-core'\nimport type { ContextSection, ContextSectionScope, ContextSectionState } from '@alvin0/ai-agent-sdk-core'\nimport {\n  resolveInstructionsConfig,\n  type ProjectInstructionsOptions,\n  type ResolvedInstructionsConfig,\n} from './config.ts'\nimport {\n  ancestorChain, byDepthThenPath, descendantDirsBetween, directoryInstructionFiles, findProjectRoot,\n  globalInstructionFile, type LoadedInstructionFile,\n} from './discovery.ts'\nimport { dedupeByContent, renderInstructions } from './render.ts'\n\n/**\n * Discover every instruction file currently in scope.\n * @param config - normalized configuration.\n * @param extraDirs - descendant directories a tool call reached into.\n * @returns files in broad-to-specific precedence order.\n */\nasync function discover(\n  config: ResolvedInstructionsConfig,\n  extraDirs: readonly string[],\n  signal: AbortSignal,\n): Promise<{ files: LoadedInstructionFile[]; projectRoot: string }> {\n  const cwd = resolve(config.cwd)\n  const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, signal)\n  const files: LoadedInstructionFile[] = []\n  const global = await globalInstructionFile(config)\n  if (global !== undefined) files.push(global)\n  const seen = new Set(ancestorChain(projectRoot, cwd))\n  const dirs = [...seen]\n  // Nested directories come after the chain and shallowest-first, so a deeper\n  // file still reads as the more specific one.\n  for (const dir of [...extraDirs].sort(byDepthThenPath)) {\n    if (seen.has(dir)) continue\n    seen.add(dir)\n    dirs.push(dir)\n  }\n  for (const dir of dirs) {\n    files.push(...await directoryInstructionFiles(dir, projectRoot, config, signal))\n  }\n  return { files, projectRoot }\n}\n\nexport interface ProjectInstructionsSection extends ContextSection {\n  /**\n   * Absolute paths rendered for one conversation, for host diagnostics.\n   * @param scope - the conversation to report on; defaults to the unscoped one.\n   * @returns the paths in the order they were rendered.\n   */\n  loadedPaths(scope?: ContextSectionScope): readonly string[]\n}\n\n/** Mutable state one conversation accumulates. */\ninterface ScopeState {\n  readonly nestedDirs: Set<string>\n  nestedLimitReported: boolean\n  loaded: readonly string[]\n}\n\nfunction scopeKey(scope: ContextSectionScope | undefined): string {\n  return `${scope?.agentId ?? ''}\\u0000${scope?.conversationId ?? ''}`\n}\n\n/**\n * Build the AGENTS.md-compatible context section.\n *\n * Discovery walks up from `cwd` to the project root, reads the configured\n * candidates from the root down, and — once a tool touches a file below `cwd` —\n * adds that subtree's instruction files too. Content is rendered into one\n * surface node; the loop rewrites it only when the digest changes.\n *\n * One instance is safe to mount on a definition that many sessions instantiate.\n * Everything it accumulates is keyed by the conversation scope the loop hands\n * to `resolve`, so a team member that reads into `packages/api` does not put\n * that directory's instructions in front of its peers. Sessions with no trace\n * identity — a bare `runTurn` — share one unscoped bucket.\n *\n * ```ts\n * const agent = defineAgent({\n *   id: 'coder',\n *   instructions: 'You are a coding agent.',\n *   contextSections: [createProjectInstructionsSection({ cwd: process.cwd() })],\n * })\n * ```\n * @param options - discovery, budget, and rendering controls.\n * @returns a section ready to mount on an agent or a session.\n */\nexport function createProjectInstructionsSection(\n  options: ProjectInstructionsOptions = {},\n): ProjectInstructionsSection {\n  const config = resolveInstructionsConfig(options, process.cwd())\n  // Insertion-ordered, so the first key is the least recently created bucket.\n  const scopes = new Map<string, ScopeState>()\n\n  const stateFor = (scope: ContextSectionScope | undefined): ScopeState => {\n    const key = scopeKey(scope)\n    const existing = scopes.get(key)\n    if (existing !== undefined) {\n      // Refresh recency so an active conversation is never the one evicted.\n      scopes.delete(key)\n      scopes.set(key, existing)\n      return existing\n    }\n    const created: ScopeState = {\n      nestedDirs: new Set<string>(), nestedLimitReported: false, loaded: Object.freeze([]),\n    }\n    scopes.set(key, created)\n    while (scopes.size > config.maxTrackedScopes) {\n      const oldest = scopes.keys().next()\n      if (oldest.done === true) break\n      scopes.delete(oldest.value)\n    }\n    return created\n  }\n\n  const section = defineContextSection({\n    id: config.id,\n    retractionText: config.retractionText,\n    async resolve(input): Promise<ContextSectionState | undefined> {\n      const state = stateFor(input.scope)\n      if (config.nested) {\n        for (const touch of input.touches) {\n          const path = config.filePathFromTouch(touch)\n          if (path === undefined) continue\n          for (const dir of descendantDirsBetween(config.cwd, path)) {\n            // Every retained directory is re-probed on every model round. An\n            // agent that walks a large tree would otherwise turn one section\n            // into thousands of stat calls per step, so the set is capped and\n            // the directories already in scope win.\n            if (state.nestedDirs.size >= config.maxNestedDirs) {\n              if (!state.nestedLimitReported) {\n                state.nestedLimitReported = true\n                config.onNestedLimit?.(config.maxNestedDirs)\n              }\n              break\n            }\n            state.nestedDirs.add(dir)\n          }\n        }\n      }\n      input.signal.throwIfAborted()\n      const { files } = await discover(config, [...state.nestedDirs], input.signal)\n      const rendered = renderInstructions(dedupeByContent(files), config)\n      if (rendered === undefined) {\n        state.loaded = Object.freeze([])\n        return undefined\n      }\n      state.loaded = Object.freeze(rendered.included.map(file => file.absolutePath))\n      return { revision: rendered.revision, text: rendered.text }\n    },\n  })\n\n  return Object.freeze({\n    ...section,\n    loadedPaths: (scope?: ContextSectionScope) => scopes.get(scopeKey(scope))?.loaded ?? Object.freeze([]),\n  })\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@alvin0/ai-agent-sdk-instructions-node",
+  "author": {
+    "name": "alvin0 - chaulamdinhai",
+    "email": "chaulamdinhai@gmail.com"
+  },
+  "version": "0.1.0",
+  "description": "Node filesystem-backed AGENTS.md context section for ai-agent-sdk",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alvin0/ai-agent-sdk.git",
+    "directory": "packages/instructions-node"
+  },
+  "homepage": "https://github.com/alvin0/ai-agent-sdk/tree/main/packages/instructions-node#readme",
+  "bugs": {
+    "url": "https://github.com/alvin0/ai-agent-sdk/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@alvin0/ai-agent-sdk-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@alvin0/ai-agent-sdk-core": "^0.1.0",
+    "@arethetypeswrong/cli": "0.18.5",
+    "@types/node": "26.4.0",
+    "publint": "0.3.24",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "aiAgentSdk": {
+    "runtime": "node",
+    "coreApi": 1,
+    "roles": [
+      "context-section"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "node -e \"for(const p of ['dist','artifacts'])require('node:fs').rmSync(p,{recursive:true,force:true})\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "pack": "pnpm pack --pack-destination artifacts",
+    "test:pack": "node ../../scripts/test-packed-node-capability.mts instructions-node",
+    "check:publint": "publint",
+    "check:types": "attw --profile esm-only --pack ."
+  }
+}