AGENTS.md

1# agents-md-core — AGENTS.md Discovery + Injection (Core)
2 
3**Generated:** 2026-06-17
4 
5## OVERVIEW
6 
7Harness-neutral logic for walking a file path UP its directory tree, discovering nearby `AGENTS.md` files, truncating their content, and formatting them as a `[Directory Context: ...]` block for injection into the session. Discovery itself is delegated to [`rules-engine`](../rules-engine/AGENTS.md) (`findAgentsMdUp`, `AgentsMdCache`); this package owns path resolution, formatting, and the per-session injected-paths cache. Package: `@oh-my-opencode/agents-md-core`.
8 
9## PUBLIC API (`src/index.ts`)
10 
11| Export | Source | Role |
12|--------|--------|------|
13| `AGENTS_FILENAME` | `constants.ts` | re-exported from `rules-engine` (value `"AGENTS.md"`) |
14| `resolveFilePath(rootDir, path)` | `finder.ts` | resolve + `realpathSync` validate path is inside `rootDir`; `null` if escapes |
15| `formatAgentsMdContextBlock({agentsPath, content, truncated})` | `formatter.ts` | wrap content in directory-context block + optional truncation notice |
16| `getSessionCache({sessionCaches, sessionID, storage})` | `injection-cache.ts` | per-session `Set<string>` of already-injected dirs, backed by storage |
17| `processFilePathForAgentsInjection(...)` | `injector.ts` | orchestrator: resolve → `findAgentsMdUp` → read → truncate → format → cache |
18| types | `types.ts` | `AgentsMdTruncator`, `AgentsMdContextOutput`, `AgentsMdInjectedPathsStorage`, `TruncationResult` |
19 
20## DEPENDENCIES & CONSUMERS
21 
22- **Depends on:** `@oh-my-opencode/rules-engine` only.
23- **Consumed by** (OpenCode edition only; no Codex consumer): `omo-opencode/src/hooks/directory-agents-injector/{finder,injector}.ts` (re-export) and `hooks/hephaestus-agents-md-injector/hook.ts` (`formatAgentsMdContextBlock`).
24 
25## NOTES
26 
27- **Path-traversal guard is a security invariant.** `resolveFilePath` canonicalizes via `realpathSync` and returns `null` when the resolved path is outside `rootDirectory`.
28- **Truncator + storage are injected** (`AgentsMdTruncator`, `AgentsMdInjectedPathsStorage`) — this package never implements truncation strategy or persistence itself.
29- Parent: [`packages/AGENTS.md`](../AGENTS.md).
30