feat(agents): embedder docker-sandbox options + modelCatalog on AgentHandlerResult

[balegas]

What

• BuiltinAgentHandlerOptions.dockerSandbox?: { image, allowFloatingTag, env, extraMounts } — threads into the built-in docker sandbox profile's dockerSandbox() call (which already supports all of these). Custom mounts append after the working-directory mount.
• AgentHandlerResult.modelCatalog — exposes the catalog createBuiltinAgentHandler already builds.
• Exports: resolveBuiltinModelConfig, resolveDockerSandboxOpts, and types BuiltinModelCatalog, BuiltinAgentModelConfig, BuiltinDockerSandboxOptions, BuiltinDockerSandboxMount.

Why

OpenFactory registers a custom Discord-facing agent entity alongside horton/worker. It needs (a) a sandbox image with git + gh + a GitHub-App token helper baked in, plus the GH_APP env/key mount inside the container, and (b) the same model-arg resolution the built-in agents use, without re-implementing the catalog.

Tests

packages/agents/test/docker-sandbox-options.test.ts covers the option merge (cwd-mount only, full passthrough, mount append, empty).

🤖 Generated with Claude Code

Notes for reviewers

• BuiltinDockerSandboxMount intentionally duplicates the runtime's mount item shape instead of importing DockerSandboxOpts — that type only exists on the @electric-ax/agents-runtime/sandbox/docker subpath, which this package deliberately keeps out of its top-level import graph (docker code is reached via dynamic import only).
• env / extraMounts extend the existing embedder/operator trust boundary: same trust level as the embedder process itself, and extraMounts stays behind the runtime's docker-socket guard.

[github-actions]

Electric Agents Desktop Builds

Build artifacts for commit 60de4e9.

Platform	Status	Artifact
macOS Apple Silicon	Building	DMG
macOS Intel	Building	DMG
Windows x64	Passed	Installer
Linux x64	Passed	AppImage / deb

Workflow run

[codecov]

Codecov Report

❌ Patch coverage is 76.92308% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 70.98%. Comparing base (73c6f89) to head (60de4e9).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/agents/src/bootstrap.ts	76.92%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4569       +/-   ##
===========================================
+ Coverage   56.67%   70.98%   +14.31%     
===========================================
  Files         327       83      -244     
  Lines       37935     9879    -28056     
  Branches    10938     3139     -7799     
===========================================
- Hits        21498     7013    -14485     
+ Misses      16401     2848    -13553     
+ Partials       36       18       -18     

Flag	Coverage Δ
packages/agents	71.56% <76.92%> (+0.18%)	⬆️
packages/agents-mobile	?
packages/agents-runtime	?
packages/agents-server	74.83% <ø> (-0.03%)	⬇️
packages/agents-server-ui	?
packages/electric-ax	46.42% <ø> (ø)
typescript	70.98% <76.92%> (+14.31%)	⬆️
unit-tests	70.98% <76.92%> (+14.31%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.