Deliberationv4.6.1

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

json
"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:

text
AGENTS.md (else CLAUDE.md - never both), package.json, pyproject.toml,
Cargo.toml, go.mod, tsconfig.json, main.tf, README.md

AGENTS.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:

  1. Files that fit the remaining budget are added whole, in priority order, up to maxFiles.
  2. 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 maxFiles is not reached. It outranks every whole file after it, so when those files are what leaves too little room (or fill maxFiles), 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:

  1. The provider is file-blind (walksFilesystem === false).
  2. The caller passed no files of its own (the files array 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.

Rendered from TECHNICAL.md in the repository.

Type to search the site.