{"_id":"@alvin0/ai-agent-sdk-instructions-node","_rev":"4-baaed8b3921730819725ac64dd1a9a0c","name":"@alvin0/ai-agent-sdk-instructions-node","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@alvin0/ai-agent-sdk-instructions-node","version":"0.1.0","author":{"name":"alvin0 - chaulamdinhai","email":"chaulamdinhai@gmail.com"},"license":"MIT","_id":"@alvin0/ai-agent-sdk-instructions-node@0.1.0","maintainers":[{"name":"alvin0","email":"chaulamdinhai@gmail.com"}],"homepage":"https://github.com/alvin0/ai-agent-sdk/tree/main/packages/instructions-node#readme","bugs":{"url":"https://github.com/alvin0/ai-agent-sdk/issues"},"dist":{"shasum":"20d840c9d0815488213e50002d56447fb7e0b08f","tarball":"https://registry.npmjs.org/@alvin0/ai-agent-sdk-instructions-node/-/ai-agent-sdk-instructions-node-0.1.0.tgz","fileCount":7,"integrity":"sha512-B3ICXRTajM/+JeLtrxC8AUitRw125ZwUehNwP+uH20PArPLWAmaKQpJuFxJPZdOAWwmNlZi9wFJWRBlSwsR4kg==","signatures":[{"sig":"MEYCIQC5N4bYA4l73F8/ZSo6kKE9n0HBUrQXomKVgvv4s6OyRgIhAIr4tCmHLSXgOPSwoyln3nkZI/G1+kOq+SDUTVEl04VG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alvin0%2fai-agent-sdk-instructions-node@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":67969},"main":"./dist/index.mjs","type":"module","_from":"file:artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.0.tgz","types":"./dist/index.d.mts","engines":{"node":">=22.12"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs","default":"./dist/index.mjs"},"./package.json":"./package.json"},"scripts":{"pack":"pnpm pack --pack-destination artifacts","test":"vitest run --config vitest.config.ts","build":"tsdown","clean":"node -e \"for(const p of ['dist','artifacts'])require('node:fs').rmSync(p,{recursive:true,force:true})\"","test:pack":"node ../../scripts/test-packed-node-capability.mts instructions-node","typecheck":"tsc --noEmit","check:types":"attw --profile esm-only --pack .","check:publint":"publint"},"_npmUser":{"name":"alvin0","email":"chaulamdinhai@gmail.com"},"_resolved":"/home/runner/work/ai-agent-sdk/ai-agent-sdk/artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.0.tgz","_integrity":"sha512-B3ICXRTajM/+JeLtrxC8AUitRw125ZwUehNwP+uH20PArPLWAmaKQpJuFxJPZdOAWwmNlZi9wFJWRBlSwsR4kg==","aiAgentSdk":{"roles":["context-section"],"coreApi":1,"runtime":"node"},"repository":{"url":"git+https://github.com/alvin0/ai-agent-sdk.git","type":"git","directory":"packages/instructions-node"},"_npmVersion":"10.9.3","description":"Node filesystem-backed AGENTS.md context section for ai-agent-sdk","directories":{},"sideEffects":false,"_nodeVersion":"22.18.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.14","vitest":"4.1.11","publint":"0.3.24","typescript":"7.0.2","@types/node":"26.4.0","@arethetypeswrong/cli":"0.18.5","@alvin0/ai-agent-sdk-core":"^0.1.0"},"peerDependencies":{"@alvin0/ai-agent-sdk-core":"^0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/ai-agent-sdk-instructions-node_0.1.0_1788971781102_0.6099822690342329","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alvin0/ai-agent-sdk-instructions-node","version":"0.1.1","author":{"name":"alvin0 - chaulamdinhai","email":"chaulamdinhai@gmail.com"},"license":"MIT","_id":"@alvin0/ai-agent-sdk-instructions-node@0.1.1","maintainers":[{"name":"alvin0","email":"chaulamdinhai@gmail.com"}],"homepage":"https://github.com/alvin0/ai-agent-sdk/tree/main/packages/instructions-node#readme","bugs":{"url":"https://github.com/alvin0/ai-agent-sdk/issues"},"dist":{"shasum":"d7bc224778d97b0719ac79ce2dc67e4299221330","tarball":"https://registry.npmjs.org/@alvin0/ai-agent-sdk-instructions-node/-/ai-agent-sdk-instructions-node-0.1.1.tgz","fileCount":7,"integrity":"sha512-urTB1b6hIFWAvlOn3OBoT8BokuFItwf/fS/7D2g/s9KJoWz5VBcHr1ZW5eXW5GHG7nhMKKzvw9w4XRU3dm+MGA==","signatures":[{"sig":"MEUCIQDWAwnJAZ0EsKG6yHjmJ+zg2JRxYE9nuvgPCfQiWRvmQQIgQ4Ad62IoIa0wTGMkf9LD6w6iP0Eh5qQajBpBDpaZEgc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alvin0%2fai-agent-sdk-instructions-node@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":67969},"main":"./dist/index.mjs","type":"module","_from":"file:artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.1.tgz","types":"./dist/index.d.mts","engines":{"node":">=22.12"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs","default":"./dist/index.mjs"},"./package.json":"./package.json"},"scripts":{"pack":"pnpm pack --pack-destination artifacts","test":"vitest run --config vitest.config.ts","build":"tsdown","clean":"node -e \"for(const p of ['dist','artifacts'])require('node:fs').rmSync(p,{recursive:true,force:true})\"","test:pack":"node ../../scripts/test-packed-node-capability.mts instructions-node","typecheck":"tsc --noEmit","check:types":"attw --profile esm-only --pack .","check:publint":"publint"},"_npmUser":{"name":"alvin0","email":"chaulamdinhai@gmail.com"},"_resolved":"/home/runner/work/ai-agent-sdk/ai-agent-sdk/artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.1.tgz","_integrity":"sha512-urTB1b6hIFWAvlOn3OBoT8BokuFItwf/fS/7D2g/s9KJoWz5VBcHr1ZW5eXW5GHG7nhMKKzvw9w4XRU3dm+MGA==","aiAgentSdk":{"roles":["context-section"],"coreApi":1,"runtime":"node"},"repository":{"url":"git+https://github.com/alvin0/ai-agent-sdk.git","type":"git","directory":"packages/instructions-node"},"_npmVersion":"10.9.3","description":"Node filesystem-backed AGENTS.md context section for ai-agent-sdk","directories":{},"sideEffects":false,"_nodeVersion":"22.18.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.14","vitest":"4.1.11","publint":"0.3.24","typescript":"7.0.2","@types/node":"26.4.0","@arethetypeswrong/cli":"0.18.5","@alvin0/ai-agent-sdk-core":"^0.1.1"},"peerDependencies":{"@alvin0/ai-agent-sdk-core":"^0.1.1"},"_npmOperationalInternal":{"tmp":"tmp/ai-agent-sdk-instructions-node_0.1.1_1789238127935_0.6704255933776602","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@alvin0/ai-agent-sdk-instructions-node","version":"0.1.2","author":{"name":"alvin0 - chaulamdinhai","email":"chaulamdinhai@gmail.com"},"license":"MIT","_id":"@alvin0/ai-agent-sdk-instructions-node@0.1.2","maintainers":[{"name":"alvin0","email":"chaulamdinhai@gmail.com"}],"homepage":"https://github.com/alvin0/ai-agent-sdk/tree/main/packages/instructions-node#readme","bugs":{"url":"https://github.com/alvin0/ai-agent-sdk/issues"},"dist":{"shasum":"46825c13c7c793145522a57cb8bb8bdcb109de45","tarball":"https://registry.npmjs.org/@alvin0/ai-agent-sdk-instructions-node/-/ai-agent-sdk-instructions-node-0.1.2.tgz","fileCount":7,"integrity":"sha512-ZK2fkVlT/oAx+kDSKg4aWeMbnHHuTJFMP2+vk41LNPeJFYE42BoQq+vYwZEgk4EKC8eeHXRzcZavnNcEUzWVlQ==","signatures":[{"sig":"MEYCIQD78y7+MMNAAjFdCBKfZWfjWdhg100fjOrrhoprJw/7UQIhAIqeyExtR3ityh9LWWbgOyTP/NqYmHKc5DqtdjjcvlBQ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alvin0%2fai-agent-sdk-instructions-node@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":67969},"main":"./dist/index.mjs","type":"module","_from":"file:artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.2.tgz","types":"./dist/index.d.mts","engines":{"node":">=22.12"},"exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs","default":"./dist/index.mjs"},"./package.json":"./package.json"},"scripts":{"pack":"pnpm pack --pack-destination artifacts","test":"vitest run --config vitest.config.ts","build":"tsdown","clean":"node -e \"for(const p of ['dist','artifacts'])require('node:fs').rmSync(p,{recursive:true,force:true})\"","test:pack":"node ../../scripts/test-packed-node-capability.mts instructions-node","typecheck":"tsc --noEmit","check:types":"attw --profile esm-only --pack .","check:publint":"publint"},"_npmUser":{"name":"alvin0","email":"chaulamdinhai@gmail.com"},"_resolved":"/home/runner/work/ai-agent-sdk/ai-agent-sdk/artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.2.tgz","_integrity":"sha512-ZK2fkVlT/oAx+kDSKg4aWeMbnHHuTJFMP2+vk41LNPeJFYE42BoQq+vYwZEgk4EKC8eeHXRzcZavnNcEUzWVlQ==","aiAgentSdk":{"roles":["context-section"],"coreApi":1,"runtime":"node"},"repository":{"url":"git+https://github.com/alvin0/ai-agent-sdk.git","type":"git","directory":"packages/instructions-node"},"_npmVersion":"10.9.3","description":"Node filesystem-backed AGENTS.md context section for ai-agent-sdk","directories":{},"sideEffects":false,"_nodeVersion":"22.18.0","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"0.22.14","vitest":"4.1.11","publint":"0.3.24","typescript":"7.0.2","@types/node":"26.4.0","@arethetypeswrong/cli":"0.18.5","@alvin0/ai-agent-sdk-core":"^0.1.2"},"peerDependencies":{"@alvin0/ai-agent-sdk-core":"^0.1.2"},"_npmOperationalInternal":{"tmp":"tmp/ai-agent-sdk-instructions-node_0.1.2_1789281425061_0.8790434690739455","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@alvin0/ai-agent-sdk-instructions-node","author":{"name":"alvin0 - chaulamdinhai","email":"chaulamdinhai@gmail.com"},"version":"0.1.3","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,"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.3"},"devDependencies":{"@alvin0/ai-agent-sdk-core":"^0.1.3","@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 ."},"_id":"@alvin0/ai-agent-sdk-instructions-node@0.1.3","_integrity":"sha512-Ttiq3wxYpzi4PN2MEaCtDFs/0SLA7dagzmERqdIhUNkz6soKAdstL2dDurIqp/vhoj0KmzE0Y2keDvxHKfo79A==","_resolved":"/home/runner/work/ai-agent-sdk/ai-agent-sdk/artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.3.tgz","_from":"file:artifacts/alvin0-ai-agent-sdk-instructions-node-0.1.3.tgz","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-Ttiq3wxYpzi4PN2MEaCtDFs/0SLA7dagzmERqdIhUNkz6soKAdstL2dDurIqp/vhoj0KmzE0Y2keDvxHKfo79A==","shasum":"400869a3869743ebe55572363d5ed2ba4ce2cdec","tarball":"https://registry.npmjs.org/@alvin0/ai-agent-sdk-instructions-node/-/ai-agent-sdk-instructions-node-0.1.3.tgz","fileCount":7,"unpackedSize":67969,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@alvin0%2fai-agent-sdk-instructions-node@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG3dQUdCuK25SovCw5vjk0b5pjkWwWC/zwrOsJZJqURTAiEAssQHwbLSDaSNYoomhLtQsVhhZFtKmg5DGgtka4JKCQw="}]},"_npmUser":{"name":"alvin0","email":"chaulamdinhai@gmail.com"},"directories":{},"maintainers":[{"name":"alvin0","email":"chaulamdinhai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-agent-sdk-instructions-node_0.1.3_1789484943227_0.5733903620277914"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-09T16:36:20.647Z","modified":"2026-09-15T15:09:03.702Z","0.1.0":"2026-09-09T16:36:21.255Z","0.1.1":"2026-09-12T18:35:28.063Z","0.1.2":"2026-09-13T06:37:05.193Z","0.1.3":"2026-09-15T15:09:03.375Z"},"bugs":{"url":"https://github.com/alvin0/ai-agent-sdk/issues"},"author":{"name":"alvin0 - chaulamdinhai","email":"chaulamdinhai@gmail.com"},"license":"MIT","homepage":"https://github.com/alvin0/ai-agent-sdk/tree/main/packages/instructions-node#readme","repository":{"type":"git","url":"git+https://github.com/alvin0/ai-agent-sdk.git","directory":"packages/instructions-node"},"description":"Node filesystem-backed AGENTS.md context section for ai-agent-sdk","maintainers":[{"name":"alvin0","email":"chaulamdinhai@gmail.com"}],"readme":"# @alvin0/ai-agent-sdk-instructions-node\n\nNode filesystem discovery for `AGENTS.md`-style project instructions, delivered\nas a core **context section**.\n\nRuntime: **Node 22.12+**.\n\n```bash\npnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-instructions-node\n```\n\nThe core SDK never reads a file. It exposes `ContextSection`: a callback the\nturn loop re-runs before every model round, owning exactly one node on the model\nsurface and rewriting it only when its revision changes. This package is the\nNode implementation of that callback for project instruction files.\n\n## Usage\n\n```ts\nimport { defineAgent } from '@alvin0/ai-agent-sdk-core'\nimport { createProjectInstructionsSection } from '@alvin0/ai-agent-sdk-instructions-node'\n\nconst agent = defineAgent({\n  id: 'coder',\n  instructions: 'You are a coding agent.',\n  contextSections: [createProjectInstructionsSection({ cwd: process.cwd() })],\n})\n```\n\nMount it per session instead when the working directory belongs to the session\nrather than the definition:\n\n```ts\nconst session = runtime.agent(agent).createSession({\n  contextSections: [createProjectInstructionsSection({ cwd: workspaceDir })],\n})\n```\n\n## Discovery\n\n1. The configured `globalFile`, when one is supplied. There is no default —\n   a library does not guess where a host keeps a user's standing instructions.\n2. Walk up from `cwd` until a `projectRootMarkers` entry is found (`.git` by\n   default), then read the candidates from that root **down to `cwd`**,\n   inclusive. The walk never passes the root.\n3. Once a tool call touches a file below `cwd`, that subtree's directories join\n   the scan and stay in scope for the rest of the session.\n\nWithin one directory, `perDirectory: 'first'` (the default) takes the first\npresent candidate — `AGENTS.override.md`, then `AGENTS.md` — and `'all'` takes\nevery present candidate. Files with identical trimmed content collapse to the\nfirst occurrence, so a symlinked or copied twin is not rendered twice.\n\nRendering is broad-to-specific, each file introduced by\n`Instructions from: <path relative to the project root>`. Content is admitted\nwhole under `maxBytes` (64 KiB by default); anything that does not fit is named\nin a closing line rather than silently cut.\n\n## Sharing one instance across agents\n\nOne section object is normally mounted on a definition that many sessions\ninstantiate — every member of a team, every worker cloned from a lead — and\nthose sessions run concurrently. Everything this section accumulates is keyed by\nthe conversation scope the loop passes to `resolve`, so a team member that reads\ninto `packages/api` does not put that directory's instructions in front of its\npeers. Buckets are bounded by `maxTrackedScopes` and the least recently used one\nis dropped first. A bare `runTurn` with no trace identity shares one unscoped\nbucket.\n\nMounting the section on the session instead of the definition is still the right\ncall when the working directory belongs to the session — the scope keying makes\nsharing *safe*, not preferable.\n\nA skill-relative path never counts as a workspace path: arguments carrying a\n`skillId` (as `read_skill_resource({ skillId, path })` does) are ignored, so a\nskill resource named `references/patterns.md` cannot pull `references/AGENTS.md`\ninto context.\n\n## Why a section and not a skill\n\nProject instructions are always-on: a model that never loads them has violated\nthe project's conventions without knowing they existed. Skills are the opposite\ncontract — advertised by description and loaded only when the model picks them.\n\nWhy a section and not `additionalInstructions`: the system prompt is the cache\nprefix, and these files change during a session (the cwd moves, a tool reaches\ninto a new subtree, someone edits the file). Rewriting the prefix each time\nwould discard the prompt cache, and appending has no way to retract text that no\nlonger applies. A section writes into the conversation surface, replaces its own\nnode in place, and costs nothing on the steps where nothing changed.\n\n## Options\n\n| Option | Default | Meaning |\n|---|---|---|\n| `id` | `project-instructions` | Section id on the model surface |\n| `cwd` | `process.cwd()` | Session working directory |\n| `globalFile` | — | Absolute path read before any project file |\n| `projectRootMarkers` | `['.git']` | Entries that stop the upward walk |\n| `fileNames` | `['AGENTS.override.md', 'AGENTS.md']` | Same-directory candidates, in precedence order |\n| `perDirectory` | `'first'` | `first` or `all` present candidates per directory |\n| `maxBytes` | `65536` | Total UTF-8 ceiling for the rendered section |\n| `maxFileBytes` | `maxBytes` | Per-file UTF-8 ceiling |\n| `nested` | `true` | Scan subtrees a tool call reaches into |\n| `maxNestedDirs` | `256` | Most subtree directories kept in scope at once |\n| `onNestedLimit` | — | Called once per conversation when that cap is reached |\n| `maxTrackedScopes` | `64` | Conversations whose subtrees this instance remembers |\n| `filePathFromTouch` | reads `file_path`/`path`/`filePath` | Which committed call touched which path |\n| `intro` | see `DEFAULT_INTRO` | Paragraph placed above the files |\n| `retractionText` | see `DEFAULT_RETRACTION` | Written when every file leaves scope |\n\nA failed tool call never contributes a path: a read that errored did not enter\nthat directory.\n\nEvery retained directory is re-probed before every model round, so `maxNestedDirs`\nbounds the per-step filesystem cost of an agent that walks a large tree. Once the\ncap is reached the directories already in scope win, and `onNestedLimit` fires\nonce so a host can log it. `maxFileBytes` is bounded by `maxBytes`: a file larger\nthan the whole section is skipped without being read.\n","readmeFilename":"README.md"}