🥽 feat: Configure Attached Defaults and Honor Skill Read Ranges

[lia-by-librechat]

Summary

Attached Bash always uses a 30-second foreground timeout when the model omits timeoutMs, even when the environment supports longer commands. Attached read_file similarly requests 200 lines when max_lines is omitted. Operators can now configure those defaults per environment through configSchema.limits.defaultCommandTimeoutMs and defaultReadFileLines.

Omission preserves the existing defaults. A foreground timeout never raises the administrator, worker, protocol, or verified HTTP-budget ceiling. Explicit timeouts still win, and detached background calls still default to the effective maximum. Programmatic tools retain the SDK's attached-workspace instructions, input-file/artifact locations, intent and tool-manifest fields, and validation bounds; only omission-time timeout defaults and guidance are customized. Timed-out command results retain stdout, stderr, termination markers, and truncation markers, then explain the actual timeout, effective retry ceiling, optional background execution, and possible partial side effects.

Workspace read windows can be configured up to the existing 500-line ceiling. Skill SKILL.md bodies, cached bundled text, streamed bundled text, and sandbox text now also honor explicit start_line and max_lines values instead of returning the whole file. A request for lines 100–159 returns only those 60 lines, numbered from 100, with a continuation pointing to 160. No range still returns the existing full skill/sandbox read, including unchanged size-limit and binary/image behavior. Full-content filtering happens before slicing, and streamed caches retain the complete text. Explicit sandbox ranges first retrieve the complete file within the existing 256 KiB budget through the already-windowed byte transport; truncated stdout is never treated as EOF. Oversized or incomplete retrieval fails without exposing a partial page. Workspace responses share the validator and formatter but are not sliced a second time. This PR does not change worker contracts, shell state, cd handling, search, or patch/edit tools.

How it works

Authorized environment config and worker ceiling
  → bounded defaults in agent and skill tool definitions
  → explicit call value or resolved default
  → existing workspace transport and validators

Full skill/sandbox text
  → full-content filtering
  → explicit local window or unchanged full read
  → shared numbering and continuation formatter

Example settings beneath an attached environment:

configSchema:
  limits:
    defaultCommandTimeoutMs: 60000
    maxCommandTimeoutMs: 80000
    defaultReadFileLines: 500

HTTP admission, settlement, and delivery reserves can lower the effective maximum. Update all LibreChat API replicas before enabling new strict configuration fields. No worker update or data migration is required.

Type of change

• Feature
• Bug fix
• Tests / tooling / CI

Testing

Focused coverage includes configured and omitted defaults, explicit and background overrides, administrator/worker/HTTP ceilings, invalid configuration, timeout diagnostics, wider reads, pagination, shared-schema isolation, code-to-skill upgrades, skill-first registration, production tool-loader wiring, all three skill-text sources, sandbox ranges, full-file filtering outside the requested window, EOF/blank lines, UTF-8 byte truncation, complete cache writes, images/binary metadata, and SDK schema-field preservation.

Local checks and GitHub CI results are recorded in the head handoff comment.

Screenshots / recordings

No UI component, layout, or control changes. Model-facing tool descriptions, line-window results, continuation text, and timeout results are covered by focused execution tests. No UI screenshots captured.

Risk / compatibility

• Existing deployments retain 30-second foreground commands and 200-line workspace reads when the new fields are absent.
• Explicit sandbox ranges require complete retrieval within the existing 256 KiB read budget. Files over that budget or the windowed transport round-trip allowance return an actionable error. No-range sandbox reads and images keep their existing behavior.
• Programmatic Bash applies the configured foreground default only when timeout is omitted. Explicit requests retain the independent negotiated ceiling. Without a configured foreground default, the legacy maxCommandTimeoutMs behavior is preserved. The SDK has a 1,000 ms minimum; with the new default configured, a ceiling below that minimum refuses programmatic execution rather than increasing its budget. Use bash_tool for shorter budgets.
• New strict configuration fields must not be enabled while older LibreChat API replicas are still running.
• Timeout guidance does not automatically retry commands and does not imply that background execution bypasses the same timeout ceiling.

Checklist

• I reviewed my own changes
• Relevant tests have been added or updated
• Required dependency changes: none
• Required documentation PR: N/A, configuration guidance is included in librechat.example.yaml; read-range guidance ships in the tool schemas

[lia-by-librechat]

Ready for review at exact remote head a00f362f393fd38df4787d6eb46acca619161273.

A1 adds optional attached-environment foreground command and read-window defaults, preserves explicit/background overrides and existing defaults, and bounds timeout guidance by the effective negotiated ceiling. No worker changes.

Local verification:

• Focused packages/api tests: 638 passed across six suites.
• Production ToolService loader tests: 143 passed.
• data-provider configuration tests: 289 passed.
• packages/api and packages/data-provider: tsc --noEmit passed.
• Real data-provider/API builds passed, along with the data-schemas dependency build.
• Scoped static checks passed: ESLint, Prettier, import sorting, package.json validation, and circular dependencies.
• Lighthouse is running. GitHub CI is independently running on this head.

Title verification: 🥽 has 2 indexed commits, both subject-leading, among 5,615 LibreChat commits through 2026-09-28 23:44:55 UTC. The sentinel passed; the checked open-PR snapshot had no matching title. Frame: a configurable but bounded view and execution budget. This PR title records the spend.

[lia-by-librechat]

Verification update for exact pushed head a00f362f393fd38df4787d6eb46acca619161273:

Local check	Result
Focused packages/api suites	638 passed
ToolService loader suite	143 passed
data-provider config suite	289 passed
tsc --noEmit: packages/api, packages/data-provider	Passed
Real data-provider and API builds	Passed
Dependency data-schemas and client-package builds	Passed during Lighthouse preparation
Scoped static checks and commit hooks	Passed
npm run lighthouse	Build and MongoDB startup succeeded; browser launch blocked by missing system libatk-1.0.so.0

No Lighthouse performance result was obtained locally. GitHub CI is running on this head; no failing check was reported in the latest snapshot. No inline review threads or submitted reviews have arrived yet.

Not run locally: whole workspace suites, config migration suites, unused-i18n-key sweep, and unused-npm-package sweep. Screenshots were not captured because local Chromium cannot start. No tracked harness changes were made.

[lia-by-librechat]

Ready for review at exact remote head d6f2afab5af6fe4ae04923b8fe7dbefb179b6e6f.

Finding ledger:

• R1-P2-1 (P2), "Separate the programmatic default from its timeout ceiling": fixed in d6f2afab5af6fe4ae04923b8fe7dbefb179b6e6f. A parent-run real-SDK regression reproduced the original truncation before the correction. Configured defaults now apply only to omitted programmatic timeout; explicit values retain the independently negotiated cap.
• The first independent review was incomplete because its Finding Verifier could not initialize. The parent audited and reproduced its finding. A fresh independent review of this head is being requested; no clean-review claim is made yet.

Current local verification:

• packages/api focused tests: 690 passed across seven suites, including real-SDK default/explicit timeout requests and classification coverage.
• ToolService loader tests: 143 passed.
• data-provider config tests: 289 passed.
• tsc --noEmit in packages/api and packages/data-provider passed.
• Real API build, scoped ESLint/Prettier/import checks, circular-dependency checks, diff whitespace checks, and commit hooks passed.

GitHub CI is running independently on this pushed head. Local Lighthouse will be retried; the previous local attempt could not launch Chromium because the sandbox lacks libatk-1.0.so.0. The previous head's green CI Lighthouse result does not cover this head.

[lia-by-librechat]

Ready for review at exact remote head ce407369611a25185971ffbc7cccbd58c30fb2eb.

Finding ledger:

• R1-P2-1 (P2), "Separate the programmatic default from its timeout ceiling": fixed in d6f2afab5af6fe4ae04923b8fe7dbefb179b6e6f.
• R2-P2-1 (P2), "Preserve attached-workspace instructions when overriding the timeout schema": fixed in ce407369611a25185971ffbc7cccbd58c30fb2eb. Parent real-SDK regressions failed before the correction, both with and without Git identity. The factory now clones the SDK instance's specialized schema and changes only the timeout default and guidance. Full non-timeout schema preservation and production definition/runtime agreement are covered.
• No rejected findings. Both prior independent rounds reported an unavailable Finding Verifier, so neither is represented as clean or complete.

After two actionable rounds, the parent swept the subsystem by authorization, identity, schema ownership, default/ceiling separation, state/replay, cancellation, reads, and mixed-version behavior. The full production diff and affected SDK boundaries/callers were inspected. A fresh independent review is being requested on this head.

Local checks:

• Focused packages/api: 770 passed across nine suites.
• Production ToolService loader: 143 passed.
• data-provider config: 289 passed.
• Both changed workspaces: tsc --noEmit passed.
• Real API build, diff-wide scoped static checks, diff whitespace, and staged commit hooks passed.

GitHub CI runs on this head. Local Lighthouse will be retried; earlier local attempts were blocked by missing system libatk-1.0.so.0. No prior-head CI result is claimed to cover this head. Whole suites, config migrations, unused-i18n and unused-package sweeps, and live-worker execution were not run locally.

[lia-by-librechat]

Independent PR Reviewer completed review of exact head ce407369611a25185971ffbc7cccbd58c30fb2eb against merge-base e9d1d330b1e1429b01f49b3a6c77764e2049f47d.

Result: Complete, no new findings. Both ledger findings were confirmed fixed:

ID	Severity	Finding	Disposition
R1-P2-1	P2	Separate the programmatic default from its timeout ceiling	Fixed in d6f2afab5af6fe4ae04923b8fe7dbefb179b6e6f
R2-P2-1	P2	Preserve attached-workspace instructions when overriding the timeout schema	Fixed in ce407369611a25185971ffbc7cccbd58c30fb2eb

No rejected or open findings. After two actionable rounds, the parent completed a subsystem invariant sweep. The final independent reviewer read the full frozen diff and affected paths and ran a dependency-free frozen-source harness. Repository Jest and real LangChain invocation were not rerun in the review environment; the parent's real-SDK regressions and focused repository tests passed before publication. No live-worker, actual proxy-budget, or mixed-replica rollout testing was performed.

Current-head CI is green, including Lighthouse, API/data-provider tests, type checks, static checks, and integrations. The latest authoritative check snapshot has no pending or failing checks. Workflow-gated e2e, MCP list_changed, Bombadil, and one Codegraph-select job were skipped. No inline GitHub review threads remain; no submitted GitHub review is claimed by this independent-review comment.

Parent local verification: 770 packages/api tests, 143 production loader tests, and 289 configuration tests passed (1,202 total). Both changed TypeScript workspaces passed tsc --noEmit. Real API build and committed-diff static checks passed. Local Lighthouse was attempted but blocked by missing libatk-1.0.so.0; CI Lighthouse passed on this exact head.

Not run locally: whole workspace suites, config migration tests, unused-i18n and unused-package sweeps, live-worker/proxy-budget/mixed-replica rollout tests, and browser screenshots.

[lia-by-librechat]

Ready for review at exact remote head c30de952bf8827ece7616e9524bfadbfa21e3f83.

This head adds the requested read-range correction to A1:

• Explicit start_line / max_lines now apply to SKILL.md, cached bundled text, streamed bundled text, and sandbox text.
• No-range skill/sandbox behavior is unchanged. Workspace defaults remain configurable and worker pages are not sliced twice.
• Shared validation, numbering, UTF-8 byte truncation, and continuation logic. Full skill/file filtering happens before slicing; streamed cache updates retain the complete source.
• SDK schemas are extended locally with both parameters while retaining path/intent fields. Images, binary metadata, and oversized-file paths are preserved. No agents or worker dependency changes.

The regression run on the earlier head confirmed explicit ranges returned the complete file. Current source-path tests pass; final focused tests/typechecks/build/static checks run in parallel with this head's CI. A fresh independent PR Reviewer is being requested for this head. Prior clean review covers ce407369611a25185971ffbc7cccbd58c30fb2eb, not this extension.

Acceptance measurement: a synthetic 660-line catalogue reproduction through the real handler returned exactly 60 and 85 lines. With o200k_base, the full output was 4,742 tokens; those windows were 463 and 638 tokens respectively. These are fixture measurements, not verification of the reported 19 historical reads or their aggregate savings. Historical traces were not supplied.

Existing ledger: R1-P2-1 fixed in d6f2afab5; R2-P2-1 fixed in ce4073696. No rejected findings.

Title refresh retains this PR's already-used 🥽, connecting to a bounded view. Verified: 2 prior subject-leading uses among 5,639 commits through 2026-09-30 09:10:10 UTC; sentinel 🧹=54 passed. The applied PR title is the spend record.

[lia-by-librechat]

Verification for exact pushed head c30de952bf8827ece7616e9524bfadbfa21e3f83:

Local check	Result
Focused packages/api suites, including read/skill/schema/background/shutdown paths	841 passed across 10 suites
Production ToolService loader	143 passed
data-provider configuration	289 passed
tsc --noEmit, packages/api and packages/data-provider	Passed
Real API build	Passed
npm run static-checks -- --against origin/dev, touched-file imports/lint, whitespace and commit hooks	Passed

Total focused repository tests: 1,273. The separate disposable output-measurement harness also passed.

The real read handler was exercised with a synthetic 660-line catalogue reproduction and start_line: 100:

Read	Returned numbered lines	Output bytes	o200k_base tokens
No range	660	16,451	4,742
max_lines: 60	60	1,680	463
max_lines: 85	85	2,305	638

The token reductions are 90.2% and 86.5% for this synthetic fixture. This is not a replay of the actual SQL catalogue or the 19 historical reads: the original traces were not supplied and the skill source repository was inaccessible to this environment. No historical aggregate token-savings claim is made.

A fresh independent review is running on this head. The earlier complete review of ce4073696 does not cover the extension. Both earlier P2 ledger findings remain fixed; no findings have been rejected.

Not run locally: whole workspace suites, config migration tests, unused-i18n and unused-package sweeps, live-worker/proxy-budget/mixed-replica testing, browser screenshots, or live deployed skill-library invocation.

Local Lighthouse: npm run lighthouse reached the harness but the enclosing check stream exhausted its tool budget; the separate npm run lighthouse:run attempt failed at Chromium startup because the sandbox lacks libatk-1.0.so.0. No local performance result was obtained.

Current-head CI snapshot: 11 pending; 0 failing. All claimed CI results are scoped to this head.

[lia-by-librechat]

Independent PR Reviewer completed review of exact pushed head c30de952bf8827ece7616e9524bfadbfa21e3f83 against merge-base e9d1d330b1e1429b01f49b3a6c77764e2049f47d.

Result: Complete, no findings. The review covered the full 17-file diff and the four-file skill/sandbox range extension. Both earlier P2 findings remain resolved:

ID	Severity	Finding	Disposition
R1-P2-1	P2	Separate the programmatic default from its timeout ceiling	Fixed in d6f2afab5af6fe4ae04923b8fe7dbefb179b6e6f
R2-P2-1	P2	Preserve attached-workspace instructions when overriding the timeout schema	Fixed in ce407369611a25185971ffbc7cccbd58c30fb2eb

No open or rejected findings. The reviewer traced consumers, full-content filters, storage/cache writes, schemas, byte truncation, continuation, and binary/image paths. Dependency-free frozen-source probes covered all four local text sources, validation, filtering before slicing, complete streamed cache writes, EOF/blank lines, UTF-8 truncation, and already-paged workspace output.

Review limitations: repository Jest, TypeScript, and real SDK integration were not rerun in the isolated reviewer environment because dependencies were unavailable. The parent ran the focused repository suites, real-SDK regressions, both changed workspace typechecks, builds, and static checks. No live-worker execution was performed.

Latest exact-head CI: no failures. Tests, typechecks, static checks, integrations, builds, and Lighthouse passed. API runtime smoke (production image boots) remains in progress. Workflow-gated e2e, MCP list_changed, Bombadil, and one Codegraph-select job were skipped. There are no GitHub inline review threads; this comment records the independent review, not a submitted GitHub approval.

Local verification: 841 packages/api tests, 143 loader tests, and 289 configuration tests passed (1,273 total). Both changed workspaces passed tsc --noEmit; real API build and committed-diff static checks passed. Local Lighthouse was attempted but blocked by missing system libatk-1.0.so.0; CI Lighthouse passed on this exact head.

The synthetic 660-line catalogue reproduction returned exactly 60/85 requested lines and measured 463/638 o200k_base tokens versus 4,742 for the full read. These are fixture measurements, not a replay of the actual codegraph catalogue or the 19 historical traces.

Not run locally: whole workspace suites, config migration tests, unused-i18n/package sweeps, live-worker/proxy-budget/mixed-replica testing, browser screenshots, or deployed skill-library invocation.

[lia-by-librechat]

Ready for review at exact rebased head aa5e48fd36639a1eaa68b6af1c7455d54a85fd58.

Rebased the four scoped commits onto 3b4e7b1e5e8146303006d03cdc6d6c85bfc33983 (current fetched dev). Only two import-block conflicts required resolution; both branches' imports were retained. Range-diff shows the other three commits unchanged, with no intentional behavior changes. Published using an exact old-head lease against c30de952bf8827ece7616e9524bfadbfa21e3f83.

A1 still carries configurable attached foreground command/read defaults and explicit skill/sandbox read ranges with full-file filtering, unchanged no-range reads, and shared continuation formatting. The two prior P2 ledger findings remain fixed in the rebased history. Previous reviews and CI cover earlier SHAs, not this head.

Dependencies are being refreshed for dev's agents SDK upgrade. Focused repository tests, both changed-workspace typechecks, builds, static checks, and a fresh independent review are running alongside GitHub CI. No current-head passing checks or clean review are claimed yet.

[lia-by-librechat]

Ready for review at exact rebased head 9e313d7a3969f11dfaa6a3e0f545b88eb35f74c0, based on dev 3b4e7b1e5e8146303006d03cdc6d6c85bfc33983.

The initial rebased head aa5e48fd3 contained duplicate timeout imports from my conflict resolution. That caused its build and downstream CI failures. The duplicate was removed in 9e313d7a3969f11dfaa6a3e0f545b88eb35f74c0; there are no intended functional changes from the previously reviewed implementation. Its independent review was cancelled when the build defect was identified.

The corrected code passed focused tests, package builds, and scoped static checks with SDK 4.0.1. The interrupted dependency refresh left missing declaration files locally, so a clean lockfile install was completed and both workspace typechecks and focused checks are being rerun on this exact head. Do not treat any earlier-head results as covering this head.

The rebased ledger is R1-P2-1 fixed in 9050ca270, R2-P2-1 fixed in 3772636c1; no rejected findings. A fresh independent PR Reviewer is being started on this corrected head alongside GitHub CI.

[lia-by-librechat]

Verification for exact rebased head 9e313d7a3969f11dfaa6a3e0f545b88eb35f74c0, based on dev 3b4e7b1e5e8146303006d03cdc6d6c85bfc33983:

Local check	Result
Focused packages/api suites	867 passed across 10 suites
Production ToolService loader	145 passed
data-provider configuration	346 passed
tsc --noEmit: packages/api, packages/data-provider	Passed
npm run build:packages: data-provider, data-schemas, API, client package	Passed
npm run static-checks -- --against origin/dev	Passed
Diff whitespace checks	Passed

Total focused tests: 1,358. Dependencies were refreshed from the rebased lockfile; agents SDK 4.0.1 is installed. The first dependency refresh was interrupted and left missing declaration files; those results were discarded and a clean lockfile install plus all checks were rerun.

Rebase conflict resolution was import-only. Initial rebased head aa5e48fd3 had duplicated timeout imports and was not working; 9e313d7a3 removes that duplication. No intended functional changes. The prior review of c30de952b is not reused as review coverage for this head. Fresh independent review and CI are running.

Ledger: R1-P2-1 remains fixed in rebased 9050ca270; R2-P2-1 remains fixed in rebased 3772636c1. RB-P1-1 (duplicate timeout imports after rebase) is fixed in 9e313d7a3. No open or rejected findings.

Not run locally: whole workspace suites, config migration tests, unused-i18n/package sweeps, live-worker/proxy-budget/mixed-replica rollout, historical trace replay, or screenshots.

Current-head CI snapshot: 11 passing checks, 29 pending, 0 failing.

Local npm run lighthouse attempted on this head; Chromium startup was blocked by the missing system library libatk-1.0.so.0. No local performance result was obtained.

[lia-by-librechat]

Ready for review at exact pushed head 57592e02030a801ccbc3fe201ad9b853fb94c943.

R4-P2-1 (P2), "Retrieve complete sandbox text before slicing line ranges": fixed in 57592e02030a801ccbc3fe201ad9b853fb94c943. The parent reproduced it through the production callback under a simulated 65,536-character stdout cap: the earlier head lost existing line 850 in a 900-line file.

Explicit sandbox ranges now use the existing windowed byte transport and require complete retrieval within the existing 256 KiB byte budget. Full text is validated, filtered, then sliced. Incomplete or oversized retrieval cannot produce a false EOF. Legacy no-range reads, images, and worker contracts are unchanged. A small TS adapter owns completeness; CJS changes are export wiring only.

Local checks: 909 packages/api tests, 378 callback/loader/transport tests, and 346 config tests passed (1,633 total). Both workspace typechecks, real API build, scoped static checks and whitespace checks passed. Tests include the production adapter and handler under capped responses, protected content beyond the stdout prefix, adaptive smaller-cap windows, complete UTF-8 assembly, route/session/auth preservation, and cancellation.

Prior findings R1-P2-1, R2-P2-1, and RB-P1-1 remain fixed. No rejected findings. A fresh independent review and GitHub CI run on this exact head; the previous review covers 9e313d7a3, not this fix. Local Lighthouse will be attempted separately.

Not run locally: whole suites, config migration tests, unused-i18n/package sweeps, live-worker/proxy-budget/mixed-replica tests, historical trace replay, or screenshots.

[lia-by-librechat]

Independent PR Reviewer completed review of exact pushed head 57592e02030a801ccbc3fe201ad9b853fb94c943 against merge-base 3b4e7b1e5e8146303006d03cdc6d6c85bfc33983.

Result: Complete, no findings. All four ledger dispositions were independently rechecked:

ID	Severity	Finding	Disposition
R1-P2-1	P2	Separate programmatic default from timeout ceiling	Fixed in rebased 9050ca270
R2-P2-1	P2	Preserve attached-workspace schema instructions	Fixed in rebased 3772636c1
RB-P1-1	P1	Duplicate imports after rebase break builds	Fixed in 9e313d7a3
R4-P2-1	P2	Retrieve complete sandbox text before slicing ranges	Fixed in 57592e020

No open or rejected findings. The reviewer inspected the full frozen diff, SDK 4.0.1 archive, and production callback harnesses under simulated 64 KiB/16 KiB stdout caps. Completeness, byte limits, malformed output, invalid UTF-8, cancellation, execution identity, full-text filtering order, pagination, and timeout contracts were checked. Harnesses mocked transport and external dependencies; repository Jest, TypeScript, full LangChain invocation, and live-worker checks were not rerun in that environment.

Parent local verification: 1,633 focused tests passed (909 packages/api, 378 callback/loader/transport, 346 config), both changed workspace typechecks passed, real API build and committed-diff static checks passed. Local Lighthouse was attempted but blocked by missing libatk-1.0.so.0.

Exact-head CI has no failures. Lighthouse, typechecks, backend/frontend tests, static checks, builds, integrations, production runtime smoke, MCP Apps/list_changed, and Redis-transport e2e passed. Six memory-e2e shards remain running. Bombadil and one workflow-gated Codegraph-select check were skipped. No GitHub inline review threads exist; this comment records the independent review, not a submitted GitHub approval.

Not run locally: full workspace suites, config migrations, unused-i18n/package sweeps, live-worker/proxy-budget/mixed-replica rollout tests, historical trace replay, or screenshots. PR remains open and unmerged.