Runtime Terminal Port and Project-ID Hardening

Overview

This design documents two production issues that surfaced in first-run and npm-installed flows:

1. Direct terminal stuck on CONNECTING... when runtime ports differ from client bundle fallback.
2. /api/spawn receiving a session ID as projectId, leading to deep-core Unknown project failures.

The implementation introduces runtime configuration discovery for terminal WebSocket connection and stricter semantic validation for project identifiers at API and page-data boundaries.

Problem Statement

Problem A: Terminal WebSocket Port Drift

• ao start can auto-select terminal ports at runtime (for example 14802/14803) when defaults are occupied.
• Direct terminal server listens on DIRECT_TERMINAL_PORT at runtime.
• Browser client previously relied on build-time NEXT_PUBLIC_DIRECT_TERMINAL_PORT, with fallback 14801.
• In prebuilt Next.js client bundles, NEXT_PUBLIC_* values are embedded at build time.
• Result: client can attempt ws://...:14801 while server is on 14803, leaving UI in permanent CONNECTING.

Problem B: Project ID / Session ID Domain Confusion

• Session IDs and project IDs share syntax ([a-zA-Z0-9_-]+).
• Orchestrator session IDs are generated as ${project.sessionPrefix}-orchestrator, which can visually resemble project keys.
• /api/spawn previously validated only identifier shape, not membership in config.projects.
• Invalid but syntactically valid IDs reached core spawn logic and failed late with 500.

Root Cause Analysis

A. Build-Time vs Runtime Config Boundary Mismatch

• The server process controls actual runtime port assignment.
• The browser bundle cannot safely depend on build-time env values for runtime-selected ports.
• There was no first-party runtime endpoint for client port discovery.

B. Namespace Collision and Inconsistent Validation

• Project IDs and session IDs were treated as plain strings at API boundaries.
• Some routes sanitize project filters against config; others previously did not.
• Validation was format-only in /api/spawn instead of semantic (is configured project).

Goals

1. Make direct terminal connection deterministic across runtime-selected ports in prebuilt deployments.
2. Ensure /api/spawn rejects non-configured project IDs early and predictably.
3. Normalize dashboard project filter values so invalid query state cannot poison project context.
4. Preserve backwards compatibility for existing default-port setups.

Non-Goals

1. Redesign session ID format.
2. Introduce full typed ID wrappers across all packages in this change.
3. Remove existing reverse-proxy path-based WS support.

Proposed Design

1. Runtime Terminal Config Endpoint

Add GET /api/runtime/terminal (dynamic, no-store):

• terminalPort from TERMINAL_PORT (normalized, fallback 14800)
• directTerminalPort from DIRECT_TERMINAL_PORT (normalized, fallback 14801)
• proxyWsPath from TERMINAL_WS_PATH/NEXT_PUBLIC_TERMINAL_WS_PATH (normalized path or null)

2. Runtime-Aware DirectTerminal Connection

Update client connection flow:

1. Resolve build-time values if available.
2. Fetch /api/runtime/terminal before socket connect when needed.
3. Parse and normalize returned values.
4. Build WS URL from runtime values.
5. Reuse the same runtime-aware logic on reconnect attempts.

Default ports remain unchanged; runtime-shifted ports become deterministic.

3. Semantic Project Validation in /api/spawn

Before calling spawn, verify config.projects[projectId] exists. If missing:

• Return 404 with Unknown project: <id>
• Record structured observability failure reason
• Do not invoke core spawn path

4. Dashboard Project Filter Normalization

• keep "all"
• keep only configured project IDs
• otherwise fallback to first valid configured project (or primary fallback)

Flow Chart

Alternatives Considered

1. Keep fixed ports only (14800/14801) and disable auto-shift. Rejected: blocks multi-instance startup and fails on legitimate port conflicts.
2. Continue relying on NEXT_PUBLIC_* runtime injection. Rejected: production client bundles are build-time materialized.
3. Accept any projectId in /api/spawn and let core throw. Rejected: late 500 errors and poor API ergonomics.

Risks and Mitigations

1. Runtime endpoint unavailable. Mitigation: client retains safe fallback and reconnect logic.
2. Reverse-proxy deployments with custom WS path. Mitigation: preserve proxy-path precedence and include runtime proxy field.
3. Behavior change for invalid project query. Mitigation: normalization affects only unknown IDs; valid IDs and all remain unchanged.

Validation Plan

• GET /api/runtime/terminal returns runtime env ports.
• POST /api/spawn returns 404 for unknown project and does not call spawn.
• Project filter normalization keeps valid IDs, keeps all, and falls back on unknown IDs.
• Existing DirectTerminal URL construction tests remain green.

Rollout Plan

1. Merge patch to main.
2. Release new npm package version containing web/client and API updates.
3. Announce behavior note:
   • default-port users unaffected
   • runtime-shifted port users no longer hit CONNECTING deadlock

Release Checklist (Commands)

# 1) Push branch and open PR
git push origin fix-runtime-terminal-projectid-hardening

# 2) Ensure patch changeset exists (this PR includes one)
ls .changeset/five-lamps-heal.md

# 3) CI validation (already required by repo workflows)
pnpm --filter @composio/ao-web test -- \
  src/__tests__/api-routes.test.ts \
  src/lib/__tests__/dashboard-page-data.test.ts \
  src/components/__tests__/DirectTerminal.test.ts

# 4) After PR merge: version packages from changesets
pnpm changeset version

# 5) Commit version bumps and changelogs
git add .
git commit -m "chore(release): version packages for runtime terminal + spawn hardening"

# 6) Publish
pnpm release

# 7) Post-release smoke check
npm i -g @composio/ao@latest
ao start <project-path>
# verify terminal works when direct terminal port is non-default

Acceptance Criteria

1. Direct terminal connects in npm prebuilt flow even when runtime direct port is not 14801.
2. /api/spawn never returns 500 for unknown-but-valid-format project IDs.
3. Invalid project query values do not become active project state.
4. Existing default-port flows remain functional without configuration changes.