Add kit-declared serviceGateways for policy-controlled agent service access #472

Problem

Agent sandboxes intentionally run with a constrained network perimeter. That is the right default, but it means some useful agent capabilities are difficult or impossible to provide directly from inside the sandbox.

Examples:

• Web search / web fetch tools may need access to arbitrary public domains, while the sandbox itself should not receive broad internet egress.
• Agents may need to interact with external services such as Gmail, but should not receive the real service credentials or direct API access.
• Some operations must be technically impossible for the agent, not merely prohibited by prompt instruction. For example, a mail triage helper may be allowed to read and draft messages, but never send mail without a separate human-in-the-loop step.

A good pattern for these cases is to run a policy-controlled gateway outside the sandbox perimeter, then expose only that gateway endpoint back into the sandbox. The gateway can hold credentials, enforce allowed operations, sanitize output, log requests, and require HITL approval where appropriate.

Today, the neutral kit vocabulary can install client-side config/software in the sandbox, but it does not have a way for a kit to declare that acq should manage and expose an associated gateway service.

Proposed Shape

Add a neutral serviceGateways capability to the kit vocabulary.

A service gateway is a kit-declared, acq-managed service that runs outside the sandbox network perimeter and exposes a narrow, policy-controlled endpoint back into the sandbox.

Initial scope:

• Gateway runtime is declared with a Compose file local to the kit.
• Compose files must be part of the kit payload for v1.
• Local kit sources remain supported for development/private kits.
• Remote service-gateway kits must come from trusted kit sources.
• No privileged containers.
• Floating image tags warn.
• acq stop stops associated service gateways.
• acq rm removes associated service gateways and state.
• Guest exposure is env-var injection only.
• MCP/client config remains out of scope for this field; existing kit files/commands can install clients and write config.
• The kit declares a logical service interface, not a concrete host/guest route.
• acq and the selected backend decide how the gateway endpoint is made reachable from the sandbox.

Example sketch:

serviceGateways:
  - name: vetted-web
    description: "Vetted web search/fetch gateway returning inert markdown"

    runtime:
      compose:
        file: compose.yaml
        service: web-gateway

    interface:
      protocol: http
      port: 8080
      health:
        path: /healthz

    expose:
      env:
        WEB_GATEWAY_URL: url

interface.port should be optional when acq can infer the agent-facing port unambiguously from the Compose service. If the Compose service exposes zero or multiple candidate ports, validation should require the kit to specify the port.

The final URL injected into the sandbox is resolved by acq. The kit should not encode host IPs, guest IPs, DNS names, VSOCK details, Podman machine addresses, Kubernetes service names, or other backend-specific routing details.

Why This Is Neutral

The vocabulary should not assume that:

• the sandbox runs on the same host as acq
• the service gateway runs on the same host as acq
• the selected backend is sbx or msb
• Compose is the only possible future runtime
• the gateway is local forever

The stable abstraction is:

This kit requires a service gateway with this logical interface, and the sandbox should receive a resolved URL for that gateway.

The backend-specific implementation can evolve independently. A future backend might realize the same declaration with local Podman, a remote VM, Kubernetes, a managed gateway, or some other substrate without changing the kit's user-facing intent.

Acceptance Criteria

• A trusted or local kit can declare a serviceGateways entry.
• acq can start the kit-local Compose service for the gateway.
• acq can derive or validate the gateway interface port.
• acq injects the resolved gateway URL into the sandbox environment.
• acq stop stops gateway services associated with the sandbox.
• acq rm removes gateway services and associated state.
• Remote kits from untrusted sources cannot start service gateways.
• Privileged containers are rejected.
• Floating image tags produce a warning.
• Existing guest-side kit behavior remains unchanged.
• The implementation includes an ADR covering the security boundary, lifecycle model, backend-neutral vocabulary, and why Compose files are kit-local in v1.

Notes

This likely requires coordinated changes in both repositories:

• GSA-TTS/agentic-coding-patterns: add the neutral schema and validation support for serviceGateways.
• GSA-TTS/agentic-coding-quickstart: implement parsing, lifecycle management, backend endpoint resolution, env injection, docs, ADR, and tests.