refactor: split 309-line generateDockerCompose into focused phases

[Copilot]

generateDockerCompose in src/compose-generator.ts mixed five distinct concerns into a single 309-line function body: filesystem side effects, environment pre-mutation, sysroot volume post-processing, optional sidecar orchestration, and dual network topology assembly.

Extracted modules

• src/services/optional-services.ts — new assembleOptionalServices() handles all optional sidecar concerns in one place: pre-setting AWF_API_PROXY_IP/AWF_CLI_PROXY_IP (ordering constraint preserved and documented), sysroot volume filtering, sysroot-stage/iptables-init/api-proxy/doh-proxy/cli-proxy service insertion, and depends_on wiring.

• src/compose-network.ts — new buildComposeNetworks() encapsulates the two network topology code paths (network-isolation internal network vs. standard external awf-net).

• src/workdir-setup.ts — added ensureInitSignalDir(workDir), called from prepareWorkDirectories (Phase 2 of writeConfigs). The directory is now created during setup rather than inside compose generation, making generateDockerCompose free of filesystem side effects.

Result

src/compose-generator.ts is reduced to a ~60-line orchestrating facade:

export function generateDockerCompose(config, networkConfig, sslConfig, squidConfigContent) {
  // resolve image config, log paths, dns servers
  const squidService = buildSquidService(...);
  const environment = buildAgentEnvironment(...);
  const agentVolumes = buildAgentVolumes(...);
  const agentService = buildAgentService(...);
  const services = { 'squid-proxy': squidService, agent: agentService };

  const { namedVolumes } = assembleOptionalServices({ services, agentService, agentVolumes, environment, ... });

  return buildComposeNetworks({ services, squidService, agentService, networkIsolation, networkConfig, namedVolumes });
}

Public API of generateDockerCompose is unchanged. All 3387 existing tests pass.

[Copilot]

Pull request overview

This PR refactors Docker Compose generation by splitting the previously large generateDockerCompose implementation into smaller, focused modules while keeping the public generateDockerCompose API unchanged. The intent is to separate concerns (workdir setup, optional sidecars, and network topology assembly) to make future changes safer and easier to reason about.

Changes:

• Moved optional sidecar/service insertion (sysroot-stage, iptables-init, api-proxy, doh-proxy, cli-proxy) into assembleOptionalServices().
• Extracted network topology assembly (network-isolation vs standard external network) into buildComposeNetworks().
• Moved init-signal directory creation into workdir setup (prepareWorkDirectories) to remove filesystem side effects from compose generation.

Show a summary per file

File	Description
src/workdir-setup.ts	Adds ensureInitSignalDir() and ensures the init-signal directory is created during workdir preparation.
src/services/optional-services.ts	New module that centralizes optional sidecar/service wiring, env pre-mutation ordering, and sysroot volume filtering.
src/compose-network.ts	New module that builds the final compose networks (and DNS override) for topology vs standard mode.
src/compose-generator.ts	Reduced to an orchestration facade that delegates optional services and network assembly to extracted modules.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Low

[lpcox]

@copilot address review feedback

[Copilot]

@copilot address review feedback

Addressed in bba7731 by updating the stale inline comment in src/compose-generator.ts to reflect that the init-signal path is forwarded through optional service assembly. Validation: npm run build and npm test -- --runInBand src/compose-generator.test.ts.

[github-actions]

✅ Copilot review passed with no inline comments.

@copilot Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

[github-actions]

Chroot tests passed! Smoke Chroot - All security and functionality tests succeeded.

[github-actions]

✅ Build Test Suite completed successfully!

[github-actions]

✨ The prophecy is fulfilled... Smoke Codex has completed its mystical journey. The stars align. 🌟

[github-actions]

✅ Smoke Claude passed

[github-actions]

🚀 Security Guard has started processing this pull request

[github-actions]

✅ Smoke Copilot BYOK completed. Copilot BYOK mode operational. 🔓

[github-actions]

✅ Smoke Copilot BYOK AOAI (api-key) completed. Copilot AOAI BYOK (api-key) mode operational. 🔓

[github-actions]

✅ Contribution Check completed successfully!

Contribution guidelines review complete for PR #5763: all applicable CONTRIBUTING.md items are satisfied; no comment needed.

[github-actions]

🔑 Smoke Copilot PAT PAT auth validated. All systems operational. ✅

[github-actions]

🔌 Smoke Services — All services reachable! ✅

[github-actions]

✅ Smoke Gemini completed. All facets verified. 💎

Smoke test completed with partial success (fallback used for GitHub MCP). PR #5763 updated.

[github-actions]

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	98.65%	98.69%	📈 +0.04%
Statements	98.53%	98.57%	📈 +0.04%
Functions	99.55%	99.55%	➡️ +0.00%
Branches	94.46%	94.49%	📈 +0.03%

📁 Per-file Coverage Changes (2 files)

File	Lines (Before → After)	Statements (Before → After)
src/compose-generator.ts	99.1% → 97.6% (-1.46%)	97.3% → 97.6% (+0.29%)
src/workdir-setup.ts	92.7% → 94.8% (+2.06%)	92.7% → 94.8% (+2.06%)

✨ New Files (2 files)

• src/compose-network.ts: 100.0% lines
• src/services/optional-services.ts: 100.0% lines

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[github-actions]

Smoke Test: Claude Engine Validation

Check	Result
API status	✅ PASS
gh check	✅ PASS
File status	✅ PASS

Overall result: PASS ✅

Generated by Smoke Claude for #5763 · 52.3 AIC · ⊞ 3.3K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

🧪 Smoke Test Results — PASS

Test	Result
GitHub MCP connectivity	✅
GitHub.com HTTP (200)	✅
File write/read	✅

PR: refactor: split 309-line generateDockerCompose into focused phases
Author: @Copilot | Assignees: @lpcox @Copilot

Overall: ✅ PASS

📰 BREAKING: Report filed by Smoke Copilot
_{Add label ready-for-aw to run again}

[github-actions]

🔥 Smoke Test — Auth mode: PAT (COPILOT_GITHUB_TOKEN)

Test	Result
GitHub MCP connectivity	✅
GitHub.com HTTP (200)	✅
File write/read	⚠️ (pre-step template vars not substituted)

Overall: PASS ✅

cc @lpcox (assignee)

🔑 PAT report filed by Smoke Copilot PAT
_{Add label ready-for-aw to run again}

[github-actions]

Smoke test results:

• fix: ensure chmod runs even when chown fails in rootless permission repair ✅
• Refactor startContainers into focused startup and failure helpers ✅
• Playwright GitHub title check ✅
• Smoke file check ✅
• npm ci && npm run build ✅
  Overall: PASS

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• registry.npmjs.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "registry.npmjs.org"

See Network Configuration for more information.

🔮 The oracle has spoken through Smoke Codex
_{Add label ready-for-aw to run again}

[github-actions]

@Copilot @lpcox
refactor: split 309-line generateDockerCompose into focused phases — ✅
docs: update runner doctor — A13 fixed in v0.27.15, B7 rootless repair incomplete — ✅
GitHub.com connectivity — ✅
File I/O — ✅
BYOK inference — ✅
Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY + COPILOT_PROVIDER_BASE_URL) via api-proxy → Azure OpenAI (Foundry, o4-mini-aw)
Status: PASS

🔑 BYOK (AOAI api-key) report filed by Smoke Copilot BYOK AOAI (api-key)
_{Add label ready-for-aw to run again}

[github-actions]

🔍 Smoke Test: API Proxy OpenTelemetry Tracing

Scenario	Status	Details
1. Module Loading	✅	otel.js loads and exports: startRequestSpan, setTokenAttributes, setBudgetAttributes, endSpan, endSpanError, shutdown, isEnabled + test helpers (_provider, _parseEndpoints, _parseOtlpHeaders, _buildResourceSpans). isEnabled() returns true after _init() on module load.
2. Test Suite	✅	otel.test.js present with suites covering: module init, header parsing, span creation/attributes, token usage attributes, parent context propagation, graceful degradation. Uses InMemorySpanExporter for isolation.
3. Env Var Forwarding	✅	src/services/api-proxy-env-config.ts forwards all 5 OTEL vars to the api-proxy container: GH_AW_OTLP_ENDPOINTS, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, GITHUB_AW_OTEL_TRACE_ID, GITHUB_AW_OTEL_PARENT_SPAN_ID, plus OTEL_SERVICE_NAME (defaults to awf-api-proxy).
4. Token Tracker Integration	✅	token-tracker-http.js exposes onUsage callback (invoked after normalized usage is extracted) — this is the OTEL hook point where setTokenAttributes and setBudgetAttributes attach span attributes.
5. OTEL Diagnostics	✅	Graceful degradation confirmed: when no endpoint is configured, FileSpanExporter writes span NDJSON to /var/log/api-proxy/otel.jsonl. Live span export requires a configured OTLP endpoint at runtime.

All scenarios pass or are correctly implemented. No unexpected failures found.

📡 OTel tracing validated by Smoke OTel Tracing
_{Add label ready-for-aw to run again}

[github-actions]

Chroot Smoke Test Results

Runtime	Host Version	Chroot Version	Match?
Python	3.12.13	3.12.3	❌ NO
Node.js	v24.17.0	v22.23.0	❌ NO
Go	go1.22.12	go1.22.12	✅ YES

Overall: ❌ FAILED — Python and Node.js versions differ between host and chroot environments.

Tested by Smoke Chroot
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test: Copilot BYOK (Direct) Mode ✅ PASS

Direct BYOK mode via api-proxy sidecar operational:

• ✅ GitHub MCP: Listed recent merged PRs successfully
• ✅ GitHub.com: HTTP 200 connectivity confirmed
• ✅ File I/O: Read/write test passed
• ✅ Inference: BYOK path (agent → sidecar → api.githubcopilot.com) working

Running in direct BYOK mode (COPILOT_PROVIDER_API_KEY) with credential injection via api-proxy sidecar.

🔑 BYOK report filed by Smoke Copilot BYOK
_{Add label ready-for-aw to run again}

[github-actions]

@Copilot @lpcox

GitHub MCP Testing: refactor: split 309-line generateDockerCompose into focused phases; docs: update runner doctor — A13 fixed in v0.27.15, B7 rootless repair incomplete ✅
GitHub.com Connectivity ✅
File Write/Read Test ✅
BYOK Inference Test ✅

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

🪪 BYOK (AOAI Entra) report filed by Smoke Copilot BYOK AOAI (Entra)
_{Add label ready-for-aw to run again}

[github-actions]

Gemini Smoke Test: MCP: ❌ (fallback used), Connectivity: ✅, File: ✅, Bash: ✅. Overall: FAIL. PRs: #5766, #5758

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• localhost

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "localhost"

See Network Configuration for more information.

💎 Faceted by Smoke Gemini
_{Add label ready-for-aw to run again}

[github-actions]

🏗️ Build Test Suite Results

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	✅	1/1 passed	✅ PASS
Bun	hono	✅	1/1 passed	✅ PASS
C++	fmt	✅	N/A	✅ PASS
C++	json	✅	N/A	✅ PASS
Deno	oak	N/A	1/1 passed	✅ PASS
Deno	std	N/A	1/1 passed	✅ PASS
.NET	hello-world	✅	N/A	✅ PASS
.NET	json-parse	✅	N/A	✅ PASS
Go	color	✅	passed	✅ PASS
Go	env	✅	passed	✅ PASS
Go	uuid	✅	passed	✅ PASS
Java	gson	✅	1/1 passed	✅ PASS
Java	caffeine	✅	1/1 passed	✅ PASS
Node.js	clsx	✅	passed	✅ PASS
Node.js	execa	✅	passed	✅ PASS
Node.js	p-limit	✅	passed	✅ PASS
Rust	fd	✅	1/1 passed	✅ PASS
Rust	zoxide	✅	1/1 passed	✅ PASS

Overall: 8/8 ecosystems passed — ✅ PASS

Notes

• Java: Maven's local repository directory (~/.m2) was owned by root; tests succeeded using -Dmaven.repo.local=/tmp/gh-aw/agent/m2-repo to redirect to a writable path.
• All other ecosystems ran without issues.

Generated by Build Test Suite for #5763 · 55.8 AIC · ⊞ 7.8K · ◷
_{Add label ready-for-aw to run again}

[github-actions]

Smoke Test Results — Services Connectivity

Check	Result
Redis PING	❌ Connection refused/filtered
PostgreSQL pg_isready	❌ No response
PostgreSQL SELECT 1	❌ No response

Overall: FAIL

host.docker.internal resolves to 172.17.0.1 but ports 6379 and 5432 are closed/filtered from this runner. The GitHub Actions service containers are not reachable — likely because Docker-in-Docker is not supported in this environment, so the AWF sandbox cannot start and the service containers are inaccessible.

🔌 Service connectivity validated by Smoke Services
_{Add label ready-for-aw to run again}