feat: add bounded agent enclaves - #6872
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d78e26c7-9fe6-4d34-a8bb-4afa87fc5f84
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d503c75e-4dae-4e09-a3bc-99bba4728421
There was a problem hiding this comment.
Pull request overview
Adds bounded-agent enclaves that provide finite, schema-constrained repository analysis through isolated Docker/gVisor environments and a dedicated API proxy.
Changes:
- Adds configuration, staging, broker, enclave, networking, and lifecycle integration.
- Enforces disclosure budgets, fixed runtime arguments, canonical responses, and fail-closed validation.
- Adds container publishing, documentation, and extensive tests.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/release.yml |
Publishes enclave and broker images. |
.gitignore |
Ignores Python bytecode. |
CLAUDE.md |
Documents bounded-agent architecture. |
containers/agent/Dockerfile |
Installs the agent wrapper. |
containers/agent/bounded-agent-wrapper.sh |
Adds the narrow agent CLI. |
containers/agent/entrypoint.sh |
Activates CLI and skill artifacts. |
containers/bounded-agent/Dockerfile |
Builds enclave and broker images. |
containers/bounded-agent/enclave-entrypoint.py |
Implements the fixed model loop. |
containers/bounded-agent/bounded-execution/*.js |
Adds source-tree compatibility shims. |
containers/bounded-agent/broker/audit.js |
Configures protected auditing. |
containers/bounded-agent/broker/broker.js |
Implements budgeting and invocation flow. |
containers/bounded-agent/broker/config.js |
Loads trusted broker configuration. |
containers/bounded-agent/broker/docker-client.js |
Executes bounded Docker commands. |
containers/bounded-agent/broker/docker-enclave-runner.js |
Runs and cleans Docker enclaves. |
containers/bounded-agent/broker/enclave-runner-spec.js |
Defines fixed container arguments. |
containers/bounded-agent/broker/enclave-runner.js |
Selects the configured backend. |
containers/bounded-agent/broker/framing.js |
Validates request framing. |
containers/bounded-agent/broker/gvisor-enclave-runner.js |
Adds runsc execution. |
containers/bounded-agent/broker/healthcheck.js |
Checks broker readiness. |
containers/bounded-agent/broker/ledger.js |
Exposes the shared ledger. |
containers/bounded-agent/broker/protocol.js |
Exposes finite-disclosure primitives. |
containers/bounded-agent/broker/scheduler.js |
Exposes fixed timing. |
containers/bounded-agent/broker/sensitivity.js |
Exposes sensitivity policy. |
containers/bounded-agent/broker/server.js |
Serves the Unix-socket protocol. |
containers/bounded-agent/broker/workspace.js |
Manages invocation artifacts. |
containers/bounded-query/bounded-execution/finite-disclosure.js |
Caps cardinality calculations. |
containers/bounded-query/bounded-execution/protected-audit.js |
Supports custom audit filenames. |
docs/awf-config.schema.json |
Defines bounded-agent configuration. |
docs/awf-config-spec.md |
Documents the configuration contract. |
docs/bounded-agents.md |
Documents usage and threat model. |
docs/bounded-queries.md |
Cross-links bounded agents. |
scripts/build-bundle.mjs |
Embeds the agent wrapper. |
src/awf-config-schema.json |
Adds the runtime schema. |
src/bounded-agent/broker.test.ts |
Tests broker and runner behavior. |
src/bounded-agent/manager.ts |
Orchestrates staging and teardown. |
src/bounded-agent/manager.test.ts |
Tests lifecycle orchestration. |
src/bounded-agent/mount-policy.ts |
Enforces private-root isolation. |
src/bounded-agent/network.ts |
Defines dedicated networks. |
src/bounded-agent/paths.ts |
Defines private filesystem layout. |
src/bounded-agent/preflight.ts |
Performs fail-closed validation. |
src/bounded-agent/preflight.test.ts |
Tests preflight constraints. |
src/bounded-agent/protocol.ts |
Defines the narrow request protocol. |
src/bounded-agent/protocol.test.ts |
Tests protocol and broker parity. |
src/bounded-agent/skill.ts |
Generates agent guidance. |
src/bounded-agent/staging.ts |
Stages readable immutable seeds. |
src/bounded-agent/workflow-integration.test.ts |
Tests workflow ordering. |
src/bounded-agent/workspace-artifacts.test.ts |
Tests artifacts and workspaces. |
src/bounded-agent/wrapper-artifact.ts |
Materializes the wrapper. |
src/bounded-execution/finite-disclosure.ts |
Bounds cardinality computation. |
src/bounded-query/mount-policy.ts |
Generalizes root isolation. |
src/bounded-query/protocol.test.ts |
Tests capped cardinality charging. |
src/bounded-query/staging.ts |
Generalizes repository staging. |
src/cli-workflow.ts |
Runs bounded-agent preparation. |
src/commands/build-config.ts |
Normalizes bounded-agent config. |
src/commands/main-action.ts |
Wires lifecycle dependencies. |
src/compose-generator.ts |
Creates enclave networks. |
src/config-file.ts |
Adds raw config types. |
src/config-mapper.ts |
Passes config-only settings through. |
src/constants.ts |
Adds the broker container name. |
src/image-tag.ts |
Supports enclave image digests. |
src/parsers/bounded-agent-parser.ts |
Applies configuration defaults. |
src/parsers/bounded-agent-parser.test.ts |
Tests normalization and schema rules. |
src/services/bounded-agent-service.ts |
Builds broker, proxy, and mounts. |
src/services/bounded-agent-service.test.ts |
Tests Compose isolation. |
src/services/optional-services.ts |
Assembles optional services. |
src/types/bounded-agent-options.ts |
Defines configuration types/defaults. |
src/types/index.ts |
Exports bounded-agent types. |
src/types/wrapper-config.ts |
Extends the main configuration. |
tests/integration/bounded-agent-enclave.test.ts |
Exercises the real enclave loop. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 74/75 changed files
- Comments generated: 4
- Review effort level: Balanced
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d503c75e-4dae-4e09-a3bc-99bba4728421
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d503c75e-4dae-4e09-a3bc-99bba4728421
|
✅ Copilot review passed with no inline comments. @lpcox Add the |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
| Metric | Base | PR | Delta |
|---|---|---|---|
| Lines | 98.79% | 98.55% | 📉 -0.24% |
| Statements | 98.72% | 98.40% | 📉 -0.32% |
| Functions | 99.02% | 97.82% | 📉 -1.20% |
| Branches | 95.11% | 94.53% | 📉 -0.58% |
📁 Per-file Coverage Changes (5 files)
| File | Lines (Before → After) | Statements (Before → After) |
|---|---|---|
src/bounded-execution/finite-disclosure.ts |
100.0% → 100.0% (+0.00%) | 99.8% → 99.4% (-0.41%) |
src/services/optional-services.ts |
100.0% → 100.0% (+0.00%) | 99.1% → 98.4% (-0.70%) |
src/commands/main-action.ts |
98.2% → 98.2% (+0.02%) | 97.6% → 97.6% (+0.03%) |
src/commands/build-config.ts |
97.2% → 97.3% (+0.07%) | 97.2% → 97.3% (+0.07%) |
src/log-directory-setup.ts |
96.2% → 100.0% (+3.78%) | 96.3% → 100.0% (+3.71%) |
✨ New Files (12 files)
src/bounded-agent/manager.ts: 86.7% linessrc/bounded-agent/mount-policy.ts: 100.0% linessrc/bounded-agent/network.ts: 100.0% linessrc/bounded-agent/paths.ts: 97.3% linessrc/bounded-agent/preflight.ts: 90.4% linessrc/bounded-agent/protocol.ts: 98.1% linessrc/bounded-agent/skill.ts: 100.0% linessrc/bounded-agent/staging.ts: 100.0% linessrc/bounded-agent/wrapper-artifact.ts: 86.7% linessrc/parsers/bounded-agent-parser.ts: 100.0% linessrc/services/bounded-agent-service.ts: 100.0% linessrc/types/bounded-agent-options.ts: 100.0% lines
Coverage comparison generated by scripts/ci/compare-coverage.ts
|
@copilot fix the ci codeql failures |
Fixed in the latest commit. The TOCTOU race at |
|
| Metric | Base | PR | Delta |
|---|---|---|---|
| Lines | 98.79% | 98.55% | 📉 -0.24% |
| Statements | 98.72% | 98.40% | 📉 -0.32% |
| Functions | 99.02% | 97.82% | 📉 -1.20% |
| Branches | 95.11% | 94.53% | 📉 -0.58% |
📁 Per-file Coverage Changes (5 files)
| File | Lines (Before → After) | Statements (Before → After) |
|---|---|---|
src/bounded-execution/finite-disclosure.ts |
100.0% → 100.0% (+0.00%) | 99.8% → 99.4% (-0.41%) |
src/services/optional-services.ts |
100.0% → 100.0% (+0.00%) | 99.1% → 98.4% (-0.70%) |
src/commands/main-action.ts |
98.2% → 98.2% (+0.02%) | 97.6% → 97.6% (+0.03%) |
src/commands/build-config.ts |
97.2% → 97.3% (+0.07%) | 97.2% → 97.3% (+0.07%) |
src/log-directory-setup.ts |
96.2% → 100.0% (+3.78%) | 96.3% → 100.0% (+3.71%) |
✨ New Files (12 files)
src/bounded-agent/manager.ts: 86.7% linessrc/bounded-agent/mount-policy.ts: 100.0% linessrc/bounded-agent/network.ts: 100.0% linessrc/bounded-agent/paths.ts: 97.3% linessrc/bounded-agent/preflight.ts: 90.4% linessrc/bounded-agent/protocol.ts: 98.1% linessrc/bounded-agent/skill.ts: 100.0% linessrc/bounded-agent/staging.ts: 100.0% linessrc/bounded-agent/wrapper-artifact.ts: 86.7% linessrc/parsers/bounded-agent-parser.ts: 100.0% linessrc/services/bounded-agent-service.ts: 100.0% linessrc/types/bounded-agent-options.ts: 100.0% lines
Coverage comparison generated by scripts/ci/compare-coverage.ts
|
✅ Smoke Gemini completed. All facets verified. 💎 |
|
✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟 |
|
❌ Security Guard failed. Please review the logs for details. |
|
❌ Smoke Copilot BYOK AOAI (Entra) reports failed. AOAI BYOK (Entra) mode investigation needed... Smoke test for Copilot BYOK Azure OpenAI Entra: FAIL (GitHub MCP Testing ❌, GitHub.com Connectivity ✅, File Write/Read ✅, BYOK Inference ✅). |
|
📰 VERDICT: Smoke Docker Sbx has concluded. All systems operational. This is a developing story. 🎤 |
|
✅ Build Test Suite completed successfully! |
|
✅ Smoke Claude passed |
|
❌ Contribution Check failed. Please review the logs for details. |
|
🔌 Smoke Services — All services reachable! ✅ |
|
✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓 |
|
✅ Build Test Suite completed successfully! |
|
📰 VERDICT: Smoke Docker Sbx has concluded. All systems operational. This is a developing story. 🎤 |
|
✅ Smoke Claude passed |
|
✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟 |
|
📡 Smoke OTel Tracing completed. All tracing scenarios validated. ✅ |
|
✅ Smoke Copilot BYOK AOAI (Entra) completed. Copilot AOAI BYOK (Entra) mode operational. 🔓 |
|
🔌 Smoke Services — All services reachable! ✅ |
|
Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded. |
|
✅ Contribution Check completed successfully! PR #6872 appears to follow the contribution checklist in the provided context: it includes clear PR description, references the upstream stack/related PR, adds tests and docs updates, and places new files in the expected directories. No contribution-guideline comment needed. |
|
📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤 |
|
Smoke Test: Copilot BYOK (Direct) Mode ✅
Status: PASS — Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY)
|
Smoke Test: Claude Engine Validation
Overall result: PASS
|
|
feat(bounded-agent): finish enclave hardening Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "registry.npmjs.org"See Network Configuration for more information.
|
|
Smoke Test: Copilot Engine
Overall: PASS cc @lpcox
|
Chroot Version Comparison Results
Overall: FAILED — Node.js version differs between host and chroot environment. Since not all tests passed, the
|
Smoke Test: API Proxy OTel Tracing — Results
All 5 scenarios passed. No issues found.
|
Smoke Test: GitHub Actions Services Connectivity
Overall: FAIL —
|
|
Smoke test results for Copilot BYOK (Azure OpenAI Foundry):
Running in direct BYOK mode (AWF_AUTH_TYPE=github-oidc + AWF_AUTH_AZURE_* + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw) authenticated via Microsoft Entra Overall: PASS cc: @lpcox
|
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — ✅ PASS All clones, installs, builds, and tests succeeded across Bun, C++, Deno, .NET, Go, Java, Node.js, and Rust. Note: Java required setting Maven
|
|
❌ Smoke Copilot BYOK AOAI (api-key) reports failed. AOAI BYOK (api-key) mode investigation needed... Smoke Test BYOK Direct: MCP ❌, GitHub.com ✅, File I/O ✅, Inference ✅ → FAIL |
|
@lpcox Network isolation egress smoke test results: EGRESS_RESULT allow=pass deny=pass ✅ Allowed domain (api.github.com) reachable — allowed=200 Overall: PASS Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
To allow these domains, add them to the network:
allowed:
- defaults
- "example.com"See Network Configuration for more information.
|
|
Smoke Test: Docker Sbx Validation
Overall: PASS cc @lpcox (author)
|
Smoke Test: Gemini Engine Validation
Overall status: FAIL
|
Summary
boundedAgentswith Docker/runc and gVisor/runsc enclave backends, conservative resource/model budgets, generated schema, validation, and documentationStack
lpcox-bounded-execution-foundation)This PR targets
lpcox-bounded-execution-foundation, notmain.runtime: "sbx"is schema-recognized but fails closed with an explicit not-yet-implemented capability error.Security notes
gh, safe outputs, CLI proxy, MCP gateway, Docker socket, host home/tool state, or direct internet route enters the enclaveValidation
npm run generate:schemanpm run type-checknpm run buildnpm run build:bundlenpm run lint -- --quietnpx jest --runInBand— 295 suites passed; 5,195 passed, 1 skippednpx jest --config tests/setup/jest.integration.config.js --runInBand bounded-agent-enclave— 9 passednpx markdownlint-cli2 'docs/**/*.md' CLAUDE.md— 0 errors