feat(workspace): add tiered bootstrap loading with configurable bootstrapTier#22439
feat(workspace): add tiered bootstrap loading with configurable bootstrapTier#22439882soft wants to merge 10 commits intoopenclaw:mainfrom
Conversation
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
ff1de5f to
8009d57
Compare
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
8009d57 to
b138be0
Compare
Additional Comments (1)
the hook calls Prompt To Fix With AIThis is a comment left during a code review.
Path: src/hooks/bundled/bootstrap-extra-files/handler.ts
Line: 50-53
Comment:
missing `tierOverride` parameter when filtering extra bootstrap files
the hook calls `filterBootstrapFilesForSession` without passing the tier from config (`context.cfg?.agents?.defaults?.bootstrapTier`), so extra files won't be filtered correctly for sessions with a configured tier
```suggestion
const tierOverride = context.cfg?.agents?.defaults?.bootstrapTier as import("../../../agents/workspace.js").BootstrapTier | undefined;
context.bootstrapFiles = filterBootstrapFilesForSession(
[...context.bootstrapFiles, ...extras],
context.sessionKey,
tierOverride,
);
```
How can I resolve this? If you propose a fix, please make it concise. |
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
b138be0 to
e8916da
Compare
Usage ExamplesHere are a few concrete scenarios where tiered bootstrap loading helps: 1. Lightweight sub-agents for quick tasksWithout this change, spawning a sub-agent to do a simple file search loads all 8 bootstrap files (~500+ tokens of context). With tiered loading, sub-agents stay on # No config needed — sub-agents already default to minimal
# Only AGENTS.md + TOOLS.md are loadedToken savings: ~300-400 tokens per sub-agent spawn, which adds up fast if you spawn 10+ sub-agents in a session. 2. Persona-consistent cron notificationsA daily summary cron job should sound like your configured persona, not a generic bot. Currently cron jobs only get AGENTS.md + TOOLS.md — no personality context: agents:
defaults:
bootstrapTier: "standard" # Now cron jobs load SOUL.md + IDENTITY.md tooBefore: "Here is your daily summary. 3 tasks completed." 3. Token-conscious main sessionsUsers with large MEMORY.md files (10K+ tokens) might want main sessions to skip heavy files on simple queries: agents:
defaults:
bootstrapTier: "minimal" # Main sessions load lean contextThis is an advanced use case for power users who manage context budgets carefully. 4. Full context for long-running projectsagents:
defaults:
bootstrapTier: "full" # Load standard files + any extraBootstrapFiles patternsUseful when you have custom bootstrap files (e.g., Happy to add any of these as documentation or adjust the implementation based on feedback! |
|
CI failure is in tui-formatters.test.ts — unrelated to this PR. Same test fails on main. |
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
d4f2f5e to
9441998
Compare
Greptile SummaryThis PR successfully introduces a three-tier bootstrap loading system ( Key Changes:
Minor Issues:
The core functionality is solid and addresses the stated goal of reducing unnecessary token usage by allowing users to control context window budget per session type. Confidence Score: 4/5
Last reviewed commit: 9441998 |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| * - `"full"` — Standard set plus any extra bootstrap file patterns | ||
| * configured via `agents.defaults.extraBootstrapFiles`. | ||
| */ |
There was a problem hiding this comment.
The comment mentions agents.defaults.extraBootstrapFiles but this config path doesn't exist. Extra files are configured via the bootstrap-extra-files hook config, not via agents.defaults. Update the comment to reference the correct configuration path.
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/agents/workspace.ts
Line: 506-508
Comment:
The comment mentions `agents.defaults.extraBootstrapFiles` but this config path doesn't exist. Extra files are configured via the `bootstrap-extra-files` hook config, not via `agents.defaults`. Update the comment to reference the correct configuration path.
How can I resolve this? If you propose a fix, please make it concise.| export function filterBootstrapFilesForSession( | ||
| files: WorkspaceBootstrapFile[], | ||
| sessionKey?: string, | ||
| tierOverride?: BootstrapTier, | ||
| ): WorkspaceBootstrapFile[] { | ||
| if (!sessionKey || (!isSubagentSessionKey(sessionKey) && !isCronSessionKey(sessionKey))) { | ||
| return files; | ||
| const tier = resolveBootstrapTier(sessionKey, tierOverride); | ||
| if (tier === "minimal") { | ||
| return files.filter((file) => MINIMAL_BOOTSTRAP_ALLOWLIST.has(file.name)); | ||
| } | ||
| return files.filter((file) => MINIMAL_BOOTSTRAP_ALLOWLIST.has(file.name)); | ||
| // "standard" and "full" both include all loaded files. | ||
| // "full" additionally loads extra bootstrap patterns — handled by the caller. | ||
| return files; | ||
| } |
There was a problem hiding this comment.
Currently "standard" and "full" tiers behave identically - both include all loaded files (including extra bootstrap files from the hook). Consider adding logic to distinguish them, e.g., only include extra bootstrap files when tier is "full". This would make the tier names more intuitive and match the help text description that says full is "standard + extra patterns".
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Prompt To Fix With AI
This is a comment left during a code review.
Path: src/agents/workspace.ts
Line: 533-545
Comment:
Currently `"standard"` and `"full"` tiers behave identically - both include all loaded files (including extra bootstrap files from the hook). Consider adding logic to distinguish them, e.g., only include extra bootstrap files when tier is `"full"`. This would make the tier names more intuitive and match the help text description that says full is "standard + extra patterns".
<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>
How can I resolve this? If you propose a fix, please make it concise.
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
403a49f to
469287a
Compare
|
Still active. Waiting for CI to pass on the latest push (38d9e0ab9). Will update once confirmed green. |
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
38d9e0a to
2838a32
Compare
|
CI failures are unrelated to this PR (channel package build errors) |
|
This pull request has been automatically marked as stale due to inactivity. |
openclaw-barnacle
Bot
added
stale
Still active. Waiting for CI to pass on the latest push (38d9e0a). Will update once confirmed green. |
|
This pull request has been automatically marked as stale due to inactivity. |
|
CI failures are from main, not this PR |
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
c652a20 to
728d908
Compare
|
This pull request has been automatically marked as stale due to inactivity. |
openclaw-barnacle
Bot
added
stale
|
Codex review: needs maintainer review before merge. What this changes: The PR branch adds a schema-backed Maintainer follow-up before merge: This is an open implementation PR for prompt-context and public config semantics, paired with an open proposal and prior maintainer-side keep-open guidance; the next action is human product/API review and normal PR review, not an autonomous repair job. Best possible solution: Keep the PR open with #22438 for maintainer product/API review. If accepted, refresh it against current main and land the tier contract across source, hook, schema/types, generated metadata/help/docs, and focused tests; if maintainers prefer an existing or alternate context-control model, close it manually after that decision. Acceptance criteria:
What I checked:
Likely related people:
Remaining risk / open question:
Codex review notes: model gpt-5.5, reasoning high; reviewed against 2d53b49b20e1. |
…trapTier Introduces a three-tier bootstrap file loading system: - 'minimal': AGENTS.md + TOOLS.md only (default for subagent/cron sessions) - 'standard': All recognized bootstrap files (default for main sessions) - 'full': Standard set plus extra bootstrap file patterns The tier can be configured via agents.defaults.bootstrapTier, allowing users to override the default session-type heuristic. For example, subagent sessions can be promoted to 'standard' to receive SOUL.md, IDENTITY.md, and other persona files. Changes: - Add BootstrapTier type and resolveBootstrapTier() to workspace.ts - Extend filterBootstrapFilesForSession() with optional tierOverride - Add bootstrapTier to config schema, types, labels, and help text - Wire tier resolution through bootstrap-files.ts - Add comprehensive test suite (11 tests)
…-extra-files hook
- standard tier now filters to recognized bootstrap files only, excluding extra patterns loaded by the bootstrap-extra-files hook - full tier includes all files (standard + extras) - fix comment: agents.defaults.extraBootstrapFiles → bootstrap-extra-files hook - add tests verifying standard vs full tier behavior
…ENTITY+USER) Upstream expanded the minimal bootstrap allowlist to include SOUL.md, IDENTITY.md, and USER.md alongside AGENTS.md and TOOLS.md. Align the tiered bootstrap implementation with this change to fix CI failures in workspace.test.ts and handler.test.ts.
882soft
force-pushed
the
feature/tiered-bootstrap-loading
branch
from
7f7fcc2 to
cf99538
Compare
|
@steipete Codex review acknowledged — keeping the PR alive. Quick status update:
Ready for human review whenever bandwidth allows. Happy to split into a smaller PR or address any specific concerns flagged in the Codex bot's notes. |
Upstream main consolidated DEFAULT_MEMORY_FILENAME = CANONICAL_ROOT_MEMORY_FILENAME and removed the separate _ALT_ constant. Our STANDARD bootstrap allowlist still referenced the old name, breaking type-check after the rebase. The single DEFAULT_MEMORY_FILENAME entry already covers the canonical case, so the _ALT_ entry was redundant — drop it.
|
After today's rebase + fix push (
Reasons we believe this is the same mock-LLM flake we noted on 2026-04-16, not a regression introduced by this PR:
Fork can't |
|
Codex review: found issues before merge. Summary Reproducibility: yes. for the blocking PR finding by source inspection: current main appends hook extras for a main session with no tier, while PR head resolves an undefined tier to Next step before merge Security Review findings
Review detailsBest possible solution: Keep this PR and #22438 open for maintainer product/API review; if accepted, preserve legacy no-tier extra-file behavior, document the public config, add the changelog entry, and validate the bootstrap/config test slice together. Do we have a high-confidence way to reproduce the issue? Yes for the blocking PR finding by source inspection: current main appends hook extras for a main session with no tier, while PR head resolves an undefined tier to Is this the best way to solve the issue? No, not as-is. The tiered direction may be useful, but the branch should preserve backward compatibility, add required release/docs coverage, and get maintainer sign-off on the public API before merge. Full review comments:
Overall correctness: patch is incorrect What I checked:
Likely related people:
Remaining risk / open question:
Codex review notes: model gpt-5.5, reasoning high; reviewed against 978bc53e80cc. |
…ndard tier
The standard tier filter previously matched only on basename, so a
hook-loaded extra like packages/core/AGENTS.md would pass through
the root allowlist and inject extra prompt context — making
standard indistinguishable from full on the real hook path.
Tag each WorkspaceBootstrapFile with provenance ("root" | "hook")
at load time. The standard tier filter now excludes source="hook"
explicitly. Root-loaded files keep their existing semantics; the
field is optional and absent values default to root for back-compat.
- src/agents/workspace.ts: add WorkspaceBootstrapFileSource and
source field; tag root files in loadWorkspaceBootstrapFiles and
hook extras in loadExtraBootstrapFilesWithDiagnostics; update
STANDARD filter to require source !== "hook".
- src/agents/workspace.tiered-bootstrap.test.ts: add regression
unit test asserting hook-sourced files with allowlist-matching
basenames are excluded under standard.
- src/hooks/bundled/bootstrap-extra-files/handler.test.ts: add
hook-level tests with a real packages/core/AGENTS.md fixture
covering both standard (excluded) and full (included) tiers;
scope existing append test to full tier.
Addresses Codex review feedback (P2).
The public type comment claimed minimal is "AGENTS.md + TOOLS.md only" but the actual implementation includes SOUL.md, IDENTITY.md, and USER.md. Updated the jsdoc to match the resolved allowlist and clarify that "full" extras are loaded via the bootstrap-extra-files hook. The generated help text in schema.help.ts and schema.base.generated.ts is already consistent with this list. Addresses Codex review feedback (P3).
CI status update — 2 fails were flaky, 1 fail appears upstream-relatedAfter the retry commit (
I verified locally:
This looks like an opengrep configuration / stale-path issue on |
Locally pnpm test test/scripts/test-projects.test.ts -t "narrows default-lane" passes both at baseline 08c5a69 and at HEAD 4098f81 — diff between commits on **/test-projects* is empty. The previous run's 'narrows default-lane changed source files to include globs' failure appears to be flaky / build-cache state on the core-support-boundary shard, unrelated to the four files this PR touches (workspace.ts, types.agent-defaults.ts, workspace.tiered-bootstrap.test.ts, bootstrap-extra-files/handler.test.ts). Retriggering the workflow.
2 participants
Closes #22438
Motivation
Bootstrap files consume LLM tokens on every session. For users with large workspaces, loading all files into every session — including sub-agents and cron jobs — wastes context window budget on files the agent never references. This PR introduces tiered loading so users can control how much context each session type receives, reducing unnecessary token usage while preserving persona consistency where needed.
What
Introduces a three-tier bootstrap file loading system (
minimal|standard|full) with a newagents.defaults.bootstrapTierconfiguration option.Why
The current binary split (main=all, subagent/cron=minimal) doesn't support use cases where subagents need persona context or where main sessions should be lightweight. This adds a clean, backward-compatible middle ground that lets users optimize their token budget per session type.
How
resolveBootstrapTier(sessionKey, tierOverride)— Resolves effective tier from session type + optional config overridefilterBootstrapFilesForSession(files, sessionKey, tierOverride)— Extended with optional tier parameter (backward compatible — no tierOverride = existing behavior)agents.defaults.bootstrapTierin zod schema, TypeScript types, labels, and help textTesting
11 unit tests covering:
All tests pass.
Changes
src/agents/workspace.tsBootstrapTiertype,resolveBootstrapTier(), extended filtersrc/agents/bootstrap-files.tssrc/config/zod-schema.agent-defaults.tssrc/config/types.agent-defaults.tssrc/config/schema.labels.tssrc/config/schema.help.tssrc/agents/workspace.tiered-bootstrap.test.ts7 files changed, 145 insertions(+), 3 deletions(-)