Define Secure Host Interface contracts for Agent Machine terminal browser editor and agent tools

[mdheller]

Context

SourceOS Agent Machine needs secure interfaces between the host user surfaces and the internal Podman-backed agent workspace.

Target surfaces:

• local terminal
• local browser
• local code editor such as VS Code
• OpenCLAW/OpenClaw tool surface
• Hermes agent surface
• future agent tools routed through Agent Registry

This must align with the existing SourceOS / Agent OS principles: separate user and agent spaces, explicit capability grants, Nix/policy governed lifecycle, evidence/fingerprint output, and no ambient host authority.

Scope

Add v0 contracts for:

1. SecureHostInterfaceProfile

   • host OS adapter
   • interface kind: terminal | browser | editor | agent-tool
   • target AgentMachineProfile reference
   • transport mode
   • allowed operations
   • denial behavior
   • evidence requirements

2. HostInterfaceGrant

   • subject identity
   • workspace identity
   • allowed repo paths
   • operation set
   • expiration
   • policy hash
   • revocation reference

3. TerminalDoor

   • PTY attach policy
   • command execution policy
   • transcript capture
   • redaction policy

4. BrowserDoor

   • browser automation mode: isolated-browser | host-extension | remote-debug-target | no-browser
   • native messaging or broker reference
   • cookie/profile isolation policy
   • screenshot/download/upload policy

5. EditorDoor

   • editor integration mode: VS Code extension | devcontainer | remote SSH | local CLI bridge
   • repo mount scope
   • task/test/run commands
   • file edit authorization

6. AgentToolDoor

   • tool ids for OpenCLAW/OpenClaw, Hermes, Codex, Claude Code, local shell, GitHub bots, CI bots
   • Agent Registry grant references
   • AgentPlane evidence requirements

Security invariants

• No host $HOME wholesale mounts.
• No default access to SSH keys, browser profiles, keychains, API tokens, cloud credentials, or password stores.
• Browser profile sharing is denied by default; any exception requires an explicit BrowserDoor grant.
• Editor integration may edit only allowlisted repo paths.
• Terminal attach is operator-scoped, logged, and distinguishable from agent execution.
• Agent execution must remain AgentPlane-governed when side effects or automation occur.
• Every bridge launch emits a fingerprint and evidence record.

Acceptance criteria

• Schemas and examples added using existing SourceOS schema conventions.
• macOS, Windows, and Linux examples included.
• Examples validate.
• README/schema catalog updated.
• Contracts explicitly align with AgentMachineProfile and AgentMachineFingerprint.

Non-goals

• Do not implement VS Code extension code here.
• Do not implement browser extension/native messaging host here.
• Do not add real credentials, real local paths, device-specific secrets, or private keys.
• Do not claim production isolation guarantees beyond the v0 contract.