Port Registrar: onboarding scaffolder to emit port-registrar-compliant templates

[TalZaccai]

Summary

Updates the onboarding scaffolder so newly-generated websocket-bridge and view-ui agents follow the modern port-allocation pattern introduced by the port-registrar work: OS-assigned port + context.registerPort(role, port), discoverable by external clients via discoverPort(name, role).

Templates emitted by pnpm onboarding scaffold were stuck on hardcoded ports (8081 / 9092) and a module-level singleton server, which collides with the dynamic-port contract every other agent has migrated to.

What changed

ts/packages/onboarding/src/scaffolder/scaffolderHandler.ts:

• buildWebSocketBridgeTemplate (scaffoldPlugin): emits a class with a static start(port = 0) factory, close(), connected getter, and sendCommand helper. Wraps AgentWebSocketServer from websocket-utils so callers never bind a literal port.
• buildWebSocketBridgeHandler (scaffoldAgent): full AppAgent with initializeAgentContext / updateAgentContext lifecycle, refcounted shared server, context.registerPort("bridge", port), and a backstop close().
• buildViewUiHandler: full AppAgent with view server, context.registerPort("view", port), setLocalHostPort for shell integration, and an ActivityContext-driven openLocalView in executeAction.
• Both templates honor <NAME>_BRIDGE_PORT / <NAME>_VIEW_PORT env-var overrides for debugging.
• PLUGIN_TEMPLATES.nextSteps updated to show the new await <PascalName>Bridge.start() usage.

ts/docs/architecture/agent-patterns.md:

• Sections 5 and 8 document the new port contract (registerPort / discoverPort, role name "default", env-var overrides).

Validation

• pnpm --filter onboarding build ✓
• prettier --check ✓
• repo-policy-check ✓
• Manual scaffold smoke test: scaffolded a fresh websocket-bridge agent and a view-ui agent in a temp dir; both build clean, register their ports with the dispatcher on init, and are discoverable via discoverPort. Generated code matches the patterns established in already-migrated agents (e.g. code, localView).

Related

• Follows the port-registrar foundation (Workflow engine: structured output, validation passes, onError recovery, and dependency-aware branching #2333) and the per-agent migrations that landed on top of it.
• No runtime behavior change to existing agents — only the scaffolder output changes.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the onboarding scaffolder templates (websocket-bridge + view-ui) to follow the port-registrar contract: bind on OS-assigned ports by default and publish them via context.registerPort(...), with docs updated to describe the new contract.

Changes:

• WebSocket bridge template now uses an async start(port=0) factory, tracks connections, and exposes .port for registrar publication.
• WebSocket bridge agent template now manages a refcounted shared server, registers the bound port per session, and supports env-var port overrides.
• View UI agent template now binds an HTTP server on port=0, registers/discloses ports, and surfaces the view via ActivityContext.openLocalView.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
ts/packages/agents/onboarding/src/scaffolder/scaffolderHandler.ts	Updates scaffolded templates and next-steps text to use dynamic port binding + port registration patterns.
ts/docs/architecture/agent-patterns.md	Documents the new register/discover port contract and env-var overrides for bridge + view patterns.

Comments suppressed due to low confidence (1)

ts/packages/agents/onboarding/src/scaffolder/scaffolderHandler.ts:1

• isFirstForSession is computed before the await ensureSharedBridge(). If two updateAgentContext(true, ...) calls interleave for the same session (e.g. two schemas enabled concurrently), the second call can observe enabledSchemas.size > 0 and skip registration/refcounting, and then the first call can fail and roll back—leaving the session enabled with no portRegistration and no refcount increment. To make this robust, determine “first for session” at the time of registration (after the await) or gate registration on ctx.portRegistration (e.g., register iff ctx.portRegistration is undefined and ctx.enabledSchemas.size > 0), ideally under a per-session async mutex to prevent interleaving.

// Copyright (c) Microsoft Corporation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.