fix: derive runtime ports from cli port

[mturac]

Summary

• derive streams, viewer, and engine ports from a non-default --port value
• keep explicit port environment overrides intact for manually separated local instances
• render a runtime iii config so bundled defaults stay unchanged while the launched engine uses the selected ports

Tests

• git diff --check
• npm test -- test/runtime-ports.test.ts
• npm run build

Closes #750

Summary by CodeRabbit

• New Features

  • Improved port configuration: the CLI’s --port flag and env vars now consistently derive REST, stream, viewer and engine ports; a new environment variable is honored for engine port.
  • Runtime config rendering: selected runtime config is rendered and persisted for startup when values change.

• Tests

  • Added tests covering runtime port derivation and config rendering behavior.

[vercel]

@mturac is attempting to deploy a commit to the rohitg00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 11715031-44de-4c8c-8b1d-b55ddf111e47

📥 Commits

Reviewing files that changed from the base of the PR and between 59cce04 and c45426a.

📒 Files selected for processing (2)

• src/cli/runtime-ports.ts
• test/runtime-ports.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/runtime-ports.test.ts
• src/cli/runtime-ports.ts

---

📝 Walkthrough

Walkthrough

Adds runtime port utilities and integrates them into CLI startup: a centralized applyPortFlag, computed rest/stream/engine/viewer ports from env/flags, runtime rendering of iii-config.yaml, and updated engine/viewer port resolution and startup to use rendered configs.

Changes

Runtime Port Configuration for Multi-Agent Deployment

Layer / File(s)	Summary
Port configuration utilities src/cli/runtime-ports.ts	Parses and validates numeric ports, implements configuredRuntimePorts(), applyPortFlag() to derive/populate sibling env vars and III_ENGINE_URL, and renderRuntimeIiiConfig() to substitute runtime ports into an iii-config YAML string.
CLI integration and startup wiring src/cli.ts, src/config.ts, src/index.ts	Imports and applies applyPortFlag(args) during CLI startup, updates viewer port resolution to prefer AGENTMEMORY_VIEWER_PORT/III_VIEWER_PORT, extends engine port resolution to check III_PORT before other fallbacks, adds prepareRuntimeIiiConfig() to render and write a runtime config copy, and uses the rendered config when starting the engine.
Runtime port derivation tests test/runtime-ports.test.ts	Adds tests verifying applyPortFlag derives sibling ports, respects explicit overrides and overflow rules, and that renderRuntimeIiiConfig emits updated YAML without mutating the original input.

Sequence Diagram

sequenceDiagram
  participant CLI as CLI Startup
  participant applyPortFlag
  participant configuredRuntimePorts
  participant prepareRuntimeIiiConfig
  participant renderRuntimeIiiConfig
  participant startEngine as Start Engine
  CLI->>applyPortFlag: Apply --port flag if provided
  applyPortFlag->>configuredRuntimePorts: Derive ports from env
  configuredRuntimePorts-->>applyPortFlag: restPort, streamPort, enginePort
  applyPortFlag->>applyPortFlag: Write III_REST_PORT and sibling vars
  CLI->>prepareRuntimeIiiConfig: Prepare config for startup
  prepareRuntimeIiiConfig->>renderRuntimeIiiConfig: Render config with runtime ports
  renderRuntimeIiiConfig-->>prepareRuntimeIiiConfig: Updated YAML
  prepareRuntimeIiiConfig->>prepareRuntimeIiiConfig: Write to ~/.agentmemory/iii-runtime-config.yaml if changed
  prepareRuntimeIiiConfig-->>CLI: Rendered config path
  CLI->>startEngine: Boot with rendered config

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰
I hopped through ports both near and far,
Flags and envs now line up like a star,
YAML dressed in ports anew,
Engines boot where once they flew,
Hooray — no collisions on my local jar!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the primary change: deriving runtime ports from a CLI port flag, which directly addresses issue #750's core requirement.
Linked Issues check	✅ Passed	The PR implementation fully addresses issue #750 by enabling distinct port assignment for multiple local instances through CLI port derivation, environment variable overrides, and runtime config rendering.
Out of Scope Changes check	✅ Passed	All changes are directly related to runtime port configuration and derivation, with no out-of-scope modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/cli/runtime-ports.ts`:
- Around line 41-55: applyPortFlag currently sets III_REST_PORT before
computing/validating sibling ports, causing a partial configuration if
enginePort overflows; change applyPortFlag to first compute restPort, streamPort
(restPort+1), viewerPort (restPort+2) and enginePort (restPort+3), validate that
all are within 1..65535 (or <=65535) before mutating env, and if validation
fails either log a clear warning or return an error without setting any env
variables (do not leave III_REST_PORT set alone); keep parsePort and
DEFAULT_REST_PORT usage but move env["III_REST_PORT"] assignment to after the
full-range check.

In `@test/runtime-ports.test.ts`:
- Around line 5-50: Add a unit test for the port overflow edge case: call
applyPortFlag(["--port","65533"], env) and assert that III_REST_PORT is set to
"65533" while all derived sibling ports and derived values (III_STREAMS_PORT,
III_STREAM_PORT, AGENTMEMORY_VIEWER_PORT, III_VIEWER_PORT, III_PORT,
III_ENGINE_PORT, III_ENGINE_URL) remain undefined, verifying the early-return
behavior in runtime-ports.ts (around the enginePort overflow check) to prevent
regressions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 10edccf5-4ed8-4bd9-9549-f45df39fa1cc

📥 Commits

Reviewing files that changed from the base of the PR and between d442fee and 59cce04.

📒 Files selected for processing (5)

• src/cli.ts
• src/cli/runtime-ports.ts
• src/config.ts
• src/index.ts
• test/runtime-ports.test.ts