dev-tunnel

Domain Owner: deployment-governance Module Kind: external-resource Service: none Process: package-managed devtunnel host child Business Fact Owner: none Supported Platform: macOS only (x64 / arm64)

Owner

@tomflow/proflow-dev-tunnel is the single ProFlow owner for Microsoft Dev Tunnel public ingress.

Consumers

• agent-gateway
• agent-product / Custom GPT Actions through public-ingress

Purpose

The package owns acquisition of the pinned official Microsoft devtunnel CLI, stable workspace tunnel identity, exact Gateway port mapping, package-owned host lifecycle, HTTPS public URL discovery, and durable non-sensitive setup/process facts.

The production lifecycle intentionally stays close to the official CLI flow:

1. setup / reconcile confirms the official Dev Tunnel user session and performs GitHub browser authorization when needed;
2. the package reuses or creates the stable workspace Tunnel;
3. it reconciles the exact Gateway HTTP port;
4. it reuses or starts package-owned devtunnel host;
5. it discovers and verifies the HTTPS forwarding URL.

Module status and CLI verify are observation-only. Module status reads the same exact configured Tunnel as start: a verified local host is sufficient; otherwise it performs one official read-only Tunnel show. UNKNOWN remains UNKNOWN. CLI verify stays local-only. Neither performs user show, browser authorization, token issuance or runtime repair. No extra runtime ownership state is persisted. The package does not maintain a second workspace manageToken/hostToken credential protocol.

The package never resolves a system PATH devtunnel and does not carry Linux or Windows artifact support.

Does NOT own

• Agent Gateway business surface
• Gateway routing
• Gateway auth
• WebMCP / tunnel-client
• Browser Extension or Monitor transport
• Task/Agent facts
• a custom workspace Dev Tunnel access-token store

CLI contract

setup, reconcile, and read-only verify accept --workspace --json and emit one proflow.dev-tunnel-cli.v1 JSON receipt. READY requires configured ingress and a running package-owned host. No user credential, access token, or raw CLI stderr appears in receipts.

The legacy credential field remains in the receipt for compatibility. It is NOT_APPLICABLE during normal observation and becomes AUTH_REQUIRED only when a mutating setup/reconcile attempt returns an explicit authentication failure.

Maintenance delegates only to the workspace-installed package bin. verify performs observation only: no downloads, login, remote Tunnel calls, host changes, or process-fact cleanup.

Older workspaces may still contain a tunnel-access.json written by a previous package version. It is not a readiness or runtime authority and is not read or rotated by the current owner.