Port Registrar: onboarding scaffolder to emit port-registrar-compliant templates by TalZaccai · Pull Request #2368 · microsoft/TypeAgent

TalZaccai · 2026-05-19T20:29:44Z

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).

Updates the scaffolder so newly-generated websocket-bridge and view-ui agents follow the modern port-allocation pattern: OS-assigned port + context.registerPort(role, port), discoverable by external clients via discoverPort(name, role). - buildWebSocketBridgeTemplate (scaffoldPlugin): static start(port=0) factory, close(), connected getter, sendCommand helper. - buildWebSocketBridgeHandler (scaffoldAgent): full AppAgent lifecycle with refcounted shared server, registerPort, and backstop close. - buildViewUiHandler: full AppAgent with view server, registerPort, setLocalHostPort for shell integration, and ActivityContext-driven openLocalView in executeAction. - Both templates honor <NAME>_BRIDGE_PORT / <NAME>_VIEW_PORT env-var overrides for debugging. - Updated PLUGIN_TEMPLATES nextSteps for websocket-bridge to reflect the new await <PascalName>Bridge.start() usage. - agent-patterns.md sections 5 and 8 document the new port contract. The office-addin template is left unchanged in this PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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.

- websocket-bridge nextSteps: use <PascalName> placeholder instead of literal ${PascalName} interpolation - Both bridge templates: pending map now stores {resolve, reject}; close() rejects all pending so callers don't hang - Both bridge templates: post-listen errors are now console.error'd (was a TODO) - websocket-bridge template: add closeAgentContext backstop that releases the per-session port registration and decrements the shared refcount Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Per PR #2368 review feedback, 14 build* functions that emitted multi- hundred-line TypeScript blobs as template literals have been split into plain .template files loaded at runtime by a shared templateLoader. Reviewers can now read each emitted file as syntax-highlighted code in its own file instead of scrolling through escaped backticks inside scaffolderHandler.ts. The source file drops from ~2100 lines to ~970. Pattern matches the existing cliHandler.template precedent in the same directory: {{TOKEN}} placeholders (so they don't collide with the ${...} template literals that survive into the emitted code), loaded from src/ at runtime so no postbuild copy step is needed. The loader throws on unsubstituted placeholders to catch typos at scaffold time. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The previous sequential split/join loop would re-process a substituted value that happened to contain `{{KEY}}` text. Not exploitable today -- all callers pass values derived from toPascalCase(name) etc. -- but a future caller passing a var derived from user input could see surprising behavior. Switch to a single-pass regex replace that treats each substituted value as opaque. Bonus: an evil `{{KEY}}` value now correctly surfaces via the leftover-placeholder check rather than silently re-expanding. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@robgruen

…PORT placeholder Addresses the three remaining open comments on PR #2368 from @robgruen: 1. commandHandlerTemplate / externalApiHandler / other handler templates: "Should we make this file a .ts so it compiles and we can verify it has no compilation issues?" Renamed 11 of the 14 scaffolder templates from `.template` to `.ts` so `tsc` validates each one as standalone TypeScript at build time. Changes: - Renamed placeholder convention from `{{TOKEN}}` to sentinel identifiers `__token__` / `__Token__` / `__TOKEN__` so the templates remain valid TypeScript when read by the compiler (`class __AgentName__Bridge {}`, `process.env["__PORT_ENV__"]`, `import { __AgentName__Actions } from "./__agentName__Schema.js"`). - The substitution regex requires *paired* double-underscores, so Node's `__filename` / `__dirname` are left untouched. - Added `templates/__agentName__Schema.ts` — a stub schema module so the import paths in the templates resolve. - Added `templates/tsconfig.json` — composite sub-project that extends `tsconfig.base.json` and disables `noUnusedLocals` / `noUnusedParameters` (templates intentionally pre-import helpers for the user's TODOs). Wired in via project reference from `src/tsconfig.json`. - `templateLoader` regex updated to match the new `__TOKEN__` convention; reserved-name guard added so the stub schema / placeholders d.ts can never be `loadTemplate`'d at scaffold time. - Added `ws`, `@types/ws`, `@types/node` to devDependencies so the websocket-bridge templates type-check standalone. - `viewUiHandler.ts` switched from `agentContext.x = undefined` to `delete agentContext.x` to satisfy `exactOptionalPropertyTypes`, matching the convention already in `websocketBridgeHandler`. The three browser/markup templates (officeAddinHtml, officeManifestXml, officeAddinTs) stay as `.template` — they're not Node TypeScript and would need a separate DOM/Office.js lib configuration. They use the same `__TOKEN__` placeholder syntax for consistency. 2. officeAddinTs.template:8 (`const BRIDGE_PORT = 5678;`): "Should this be a replaceable template value?" Yes — the addin's bridge port must match whatever port the bridge agent is bound to. Made it a `__BRIDGE_PORT__` placeholder with a `5678` default (the same pinned-sideload default the bridge handler uses when `<NAME>_BRIDGE_PORT` is unset). The scaffolder substitutes the value at scaffold time via `buildOfficeAddinTs`. Verification: - `pnpm --filter onboarding-agent build` clean. - Migration smoke test (verifyTemplateMigration.mjs) renders each template with a canned (NAME, PASCAL_NAME, PORT_ENV) tuple and diffs against the pre-migration output. 13 of 14 templates are byte-identical; the one diff is `viewUiHandler.ts` switching to `delete` (intentional, as above). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

+            // TODO: serve static assets from ./site/, plus any
+            // JSON/IPC endpoints the view needs. For now, a placeholder.
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<h1>__AgentName__ view</h1><p>Path: ${req.url}</p>`);


TalZaccai had a problem deploying to development-fork May 19, 2026 20:29 — with GitHub Actions Error

Merge branch 'main' into talzacc/onboarding-scaffolder-migration

fdb5dd3

TalZaccai had a problem deploying to development-fork May 19, 2026 20:30 — with GitHub Actions Error

TalZaccai requested a review from Copilot May 19, 2026 20:33

Copilot AI reviewed May 19, 2026

View reviewed changes

Copilot started reviewing on behalf of TalZaccai May 19, 2026 20:58 View session

TalZaccai temporarily deployed to development-fork May 19, 2026 22:40 — with GitHub Actions Inactive

TalZaccai requested a review from robgruen May 21, 2026 19:23

TalZaccai marked this pull request as ready for review May 21, 2026 19:23

Merge branch 'main' into talzacc/onboarding-scaffolder-migration

8f68f03

TalZaccai temporarily deployed to development-fork May 21, 2026 19:45 — with GitHub Actions Inactive

TalZaccai had a problem deploying to development-fork May 21, 2026 19:45 — with GitHub Actions Failure

TalZaccai had a problem deploying to development-fork May 22, 2026 01:20 — with GitHub Actions Failure

TalZaccai temporarily deployed to development-fork May 22, 2026 01:48 — with GitHub Actions Inactive

robgruen requested changes May 27, 2026

View reviewed changes

Comment thread ts/packages/agents/onboarding/src/scaffolder/scaffolderHandler.ts

TalZaccai had a problem deploying to development-fork May 28, 2026 20:21 — with GitHub Actions Error

TalZaccai temporarily deployed to development-fork May 28, 2026 20:37 — with GitHub Actions Inactive

TalZaccai had a problem deploying to development-fork May 28, 2026 20:37 — with GitHub Actions Failure

TalZaccai requested a review from robgruen May 28, 2026 21:57

TalZaccai had a problem deploying to development-fork May 28, 2026 22:46 — with GitHub Actions Failure

robgruen approved these changes Jun 2, 2026

View reviewed changes

Comment thread ts/packages/agents/onboarding/src/scaffolder/templates/commandHandlerTemplate.ts

Comment thread ts/packages/agents/onboarding/src/scaffolder/templates/externalApiHandler.ts

Comment thread ts/packages/agents/onboarding/src/scaffolder/templates/officeAddinTs.template Outdated

TalZaccai requested a deployment to development-fork June 3, 2026 01:45 — with GitHub Actions Waiting

github-advanced-security AI found potential problems Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Port Registrar: onboarding scaffolder to emit port-registrar-compliant templates#2368
TalZaccai wants to merge 7 commits into
mainfrom
talzacc/onboarding-scaffolder-migration

TalZaccai commented May 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

TalZaccai commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Validation

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TalZaccai commented May 19, 2026 •

edited

Loading