Orientation auto-attach
Orientation auto-attach
A mechanism, on by default, that automatically attaches a small repo orientation bundle to
advisory calls targeting file-blind providers (Grok and OpenRouter), so they
reach context parity with Codex and Gemini, which already walk cwd under their
read-only sandboxes. Default ON - set orientation.enabled to false when the repo
root holds files you do not want sent to those providers.
Configuration
"orientation": { "enabled": true, "maxFiles": 6, "maxBytes": 16000 }| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
boolean | true |
Attach the bundle to file-blind providers when they carry no files. |
maxFiles |
integer | 6 |
Cap on the number of files in the bundle. |
maxBytes |
integer | 16000 |
Content-byte budget for the whole bundle (about 4K tokens). 0 = no budget. |
How it works
core/orientation.js - resolveOrientationFiles(cwd, { maxFiles, maxBytes })
returns an array of FileRef objects (absolute paths of EXISTING, non-empty regular
files) in fixed priority order:
AGENTS.md (else CLAUDE.md - never both), package.json, pyproject.toml,
Cargo.toml, go.mod, tsconfig.json, main.tf, README.mdAGENTS.md is the guide written for non-Claude agents, which are exactly the providers that receive the bundle. The small manifests come before README so a large README cannot crowd them out.
Byte budget - maxBytes counts file content plus truncation markers; the
=== name === header each bridge adds per file (under 100 bytes) is not counted.
Selection runs two passes:
- Files that fit the remaining budget are added whole, in priority order, up to
maxFiles. - The highest-priority file skipped for size is added cut to the rest of the budget
(minus a 64-byte marker reserve), but only when at least 2048 bytes remain and
maxFilesis not reached. It outranks every whole file after it, so when those files are what leaves too little room (or fillmaxFiles), they are dropped, lowest priority first, until it fits. Nothing is dropped if even that would not leave 2048 bytes. At most one file is cut for the budget.
Every file is also capped at 256 KiB minus the marker reserve (both bridges' default
per-file inline cap); a file over that cap is charged its marker against the budget
too, and maxBytes: 0 turns the budget off (only maxFiles and the
per-file cap apply). Each entry is { path, headBytes, mode: "inline" }: the bridge
reads at most headBytes (so a file that grows after selection is still bounded) and
appends [truncated: first N of M bytes] when it cuts. Grok receives the bundle
inline rather than uploaded, so what is sent equals what was budgeted. If
GROK_INLINE_MAX_BYTES or OPENROUTER_INLINE_MAX_BYTES is set below 256 KiB, the
bridge's lower cap wins.
The function is stat-only (never reads file content), never throws, and silently
skips missing or empty files.
orientationFilesFor(config, cwd) is the public entry-point: it returns the bundle
array when orientation.enabled is true, else undefined.
Provider capability: walksFilesystem - declared in core/types.js
ProviderCapabilities. true for codex and gemini (they walk the cwd under their
sandbox); false for grok and every OpenRouter per-alias wrapper (set via
registry.js pinAlias). This flag, not fileUpload, is the file-blind
discriminator.
core/orchestrate.js withOrientation gate - shared helper called in
callProvider BEFORE the dedup cache key is computed. It attaches the bundle when
two conditions both hold:
- The provider is file-blind (
walksFilesystem === false). - The caller passed no files of its own (the
filesarray is absent or empty).
Injection before the cache-key computation matters: core/result-cache.js keyFor
excludes cwd, so injecting a bundle AFTER the cache check would risk a cross-repo
false cache hit (same prompt, different repo). Injecting BEFORE makes the now-file-bearing
request correctly skip the in-session result cache.
Scope - orientation is applied to the peer fan-out AND the arbiter blind pass. It is NOT applied to the adjudication and revision passes, which reason over peer-opinion text rather than repo files directly.
Zero cross-contamination - the bundle travels in the per-provider files[]
argument, never in the shared prompt. The prompt text is byte-identical across
every provider; only the file list differs for file-blind delegates.
Bridge caps apply - each bridge enforces its own size limits. OpenRouter inlines
files as text (256 KB/file, 1 MB aggregate); Grok delivers them as inline or uploaded
attachments per the usual mode rules. Bundle entries carry headBytes and
mode: "inline", so both bridges read only the budgeted head of each file.
Manual override
When orientation.enabled is false, or when you need more than
maxFiles files for a particular query, embed the context manually in the prompt
as described in the ask-all and consensus command files. The per-command
guidance still applies and takes precedence over the auto-attach when you pass your
own files.