Skip to content

Add durable per-thread environment variables to thread spawn - #3314

Open
aivanov93 wants to merge 1 commit into
get-bb:mainfrom
aivanov93:bb/add-per-thread-env-vars-to-bb-thr_h8mvrp7zf7
Open

Add durable per-thread environment variables to thread spawn#3314
aivanov93 wants to merge 1 commit into
get-bb:mainfrom
aivanov93:bb/add-per-thread-env-vars-to-bb-thr_h8mvrp7zf7

Conversation

@aivanov93

@aivanov93 aivanov93 commented Sep 9, 2026

Copy link
Copy Markdown

Human comments

The use of env vars at agent launch is a common flow used by most harnesses but bb currently does not allow passing custom env vars to thread spawn. This PR addresses that. Lots of files touched but mostly a pass through from different surfaces.

What was wrong

Thread creation had no way to carry caller-supplied process configuration from the CLI or SDK to the provider running on a host daemon. This is a common need, e.g. #2927.

What changed

  • Add optional envVars to threads.spawn() (including bb.sdk.threads.spawn()) and repeatable bb thread spawn --env KEY=VALUE. Empty values and additional = characters are preserved; duplicate names are rejected.
  • Validate portable variable names (128 characters maximum), reserve BB_*, reject null bytes, and limit maps to 32 entries, 16 KiB per value, and 64 KiB serialized.
  • Persist the map on the thread and carry it through queued starts, remote hosts, later turns, provider-session resumes, bridge restarts, and rewinds. Explicit thread values override matching host-shell and plugin-contributed values.
  • Omit values from public thread responses and plugin thread events. Provider-environment diagnostic events show masked values with thread provenance.
  • Generate migration 0115_familiar_thunderbird against current upstream migrations and bump HOST_DAEMON_PROTOCOL_VERSION from 195 to 196 for the new required internal field.
  • Update CLI help, the threads guide, built-in CLI/plugin-authoring references, and configuration/SDK usage documentation.

Scope: values are supplied at spawn time and retained for that thread. This does not add mutation through thread tell --env, --env-file, provider-wide defaults, or inheritance through the separate fork API. Values are stored as plaintext JSON in the server database, not in an encrypted secrets store; the documentation calls out data-directory and shell-history sensitivity.

Rebased onto upstream main at 682f0d2c5, including the bundled-guide move and later-turn Pi/ACP environment fixes. Unrelated formatting changes and unused test instrumentation were removed. Most added lines are the generated Drizzle snapshot.

How you verified

Added coverage for validation limits, CLI parsing and HTTP serialization, SDK serialization, migration backfill and persistence, queued dispatch, remote command contracts, runtime precedence/resume/rewind, reserved variables, and masked/public payloads.

Broad validation before the latest rebase:

  • Full workspace typecheck: pnpm exec turbo run typecheck --concurrency=4 --continue — passed, 93 tasks.
  • Builds: pnpm exec turbo run build --filter=@bb/cli --filter=@bb/server --filter=@bb/host-daemon --concurrency=3 — passed.
  • Repository lint: pnpm exec turbo run lint — passed with existing warnings.
  • Complete test suites for @bb/domain, @bb/sdk, @bb/thread-view, @bb/server-contract, @bb/host-daemon-contract, @bb/cli, @bb/agent-runtime, @bb/templates, @bb/db, @bb/host-daemon, and @bb/server5,152 tests passed; one server test file skipped by the suite.
  • The final DB/host/server run used pnpm exec turbo run test --filter=@bb/db --filter=@bb/host-daemon --filter=@bb/server --concurrency=1 -- --maxWorkers=3. Earlier Git-heavy tests timed out with the local Git wrapper; the rerun used plain Git and Node 24.18.0.
  • oxfmt --check passed on 41 changed source/documentation files; excluded generated migration files and five files whose unrelated upstream formatting was deliberately preserved. git diff origin/main --check passed.

Latest rebase verification (0911a87d4 on 682f0d2c5):

  • Targeted typechecks for server, CLI, host daemon, agent runtime, ACP bridge, Pi provider, and BB guide passed (12 Turbo tasks).
  • Server environment-provider/queued-start/runtime-config/plugin-event regressions: 103 tests passed.
  • Complete ACP bridge suite: 312 tests passed; BB guide suite: 5 tests passed.
  • Pi provider later-turn options: 7 tests passed.
  • The moved guide files retain the CLI/SDK environment documentation. GitHub reports the updated branch as mergeable with no conflicts.

No live provider/remote-machine manual test was performed; remote forwarding and provider lifecycle behavior are covered by automated tests.

Fixes #2927

AGENT GENERATED

@aivanov93
aivanov93 force-pushed the bb/add-per-thread-env-vars-to-bb-thr_h8mvrp7zf7 branch from a8bda81 to 0911a87 Compare September 9, 2026 04:45
@aivanov93
aivanov93 marked this pull request as ready for review September 9, 2026 16:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: per-thread environment passthrough on thread spawn/tell (--env KEY=VALUE)

1 participant