Skip to content

types: export every public declaration from the package entry point - #378

Merged
roblourens merged 2 commits into
mainfrom
roblou/agents/export-all-public-types
Jul 31, 2026
Merged

types: export every public declaration from the package entry point#378
roblourens merged 2 commits into
mainfrom
roblou/agents/export-all-public-types

Conversation

@roblourens

Copy link
Copy Markdown
Member

Problem

types/index.ts is a hand-maintained allowlist, and it had silently fallen 60 declarations behind the sources. That file is copied verbatim into the published TypeScript client and is its root export, so those declarations weren't merely undocumented — they were unreachable for anyone consuming @microsoft/agent-host-protocol.

Verified against main:

import type { Customization, McpServerState, Icon, SessionMetadata } from './types/index.js';
import { CustomizationType } from './types/index.js';
error TS2305: Module './types/index.js' has no exported member 'Customization'.
error TS2305: Module './types/index.js' has no exported member 'McpServerState'.
error TS2305: Module './types/index.js' has no exported member 'Icon'.
error TS2305: Module './types/index.js' has no exported member 'SessionMetadata'.
error TS2305: Module './types/index.js' has no exported member 'CustomizationType'.

The gaps weren't obscure corners:

  • The entire customization subsystemCustomization, CustomizationType, ChildCustomization, and every variant (PluginCustomization, DirectoryCustomization, AgentCustomization, SkillCustomization, PromptCustomization, RuleCustomization, HookCustomization, McpServerCustomization), plus CustomizationLoadState and its four states
  • The entire MCP-server state machineMcpServerState, McpServerStatus, McpAuthRequiredReason, and the five state variants
  • 13 action types — all four working-directory actions, all four customization actions, all three MCP-server actions, and others
  • Icon, ChatInteractivity, InputRequestResponsePart, ToolCallContributor, SessionMetadata, JsonPrimitive, Implementation

Fix

Replace the allowlist with export * from the per-channel shims, so the entry point is complete by construction rather than by maintenance.

Two deliberate exceptions:

  • The reducer block stays explicit. The reducers.ts shim also re-exports softAssertNever, an internal exhaustiveness helper that shouldn't be public.
  • ChatAction is named explicitly. It's declared twice — by hand in channels-chat/actions.ts and in action-origin.generated.ts — with identical member sets, so export * from both is ambiguous. Naming it preserves the generated declaration the previous list exported. The duplicate declaration itself is left alone; collapsing it is a source change unrelated to this packaging fix, and worth its own look.

Guard

scripts/public-api.test.ts walks the canonical channel modules and asserts every declaration is reachable from the entry point, against a small justified withhold-list. It also asserts the reverse — that nothing on the withhold-list has become reachable — so the list can't quietly go stale.

Verified it actually fails: removing a single export * line makes it fail with the list of newly-unreachable declarations.

Also included

Four stale workingDirectory (singular) references in docs/specification/{chat,session}-channel.md, left over from the 0.7.0 rename to workingDirectories. One of them still described the old "session-level default that chats override" model rather than the current "session-level set that chats restrict to a subset of".

Compatibility

Purely additive — this only adds exports. No wire change, no change to any type, and no other client is affected (the Rust/Kotlin/Swift/Go generators read the channel modules directly and never consulted this barrel).

Verification

  • npm test — 381 pass (378 + 3 new), reducer branch coverage at 100%
  • npm run generate — no drift
  • Built the TypeScript client and type-checked a simulated consumer importing the previously-missing types from the package root: resolves cleanly here, fails on main

(Written by Copilot)

roblourens and others added 2 commits July 31, 2026 16:20
`types/index.ts` was a hand-maintained allowlist and had silently fallen 60
declarations behind the sources. It is copied verbatim into the published
TypeScript client and is its root export, so those declarations were
unreachable for consumers of `@microsoft/agent-host-protocol` -- not merely
undocumented. Verified against `origin/main`: importing `Customization`,
`McpServerState`, `Icon`, `SessionMetadata` or `CustomizationType` from the
entry point fails with `TS2305: has no exported member`.

The gaps were not obscure corners:

  - the entire customization subsystem -- `Customization`, `CustomizationType`,
    `ChildCustomization`, and every variant (`PluginCustomization`,
    `DirectoryCustomization`, `AgentCustomization`, `SkillCustomization`,
    `PromptCustomization`, `RuleCustomization`, `HookCustomization`,
    `McpServerCustomization`), plus `CustomizationLoadState` and its variants
  - the entire MCP-server state machine -- `McpServerState`, `McpServerStatus`,
    `McpAuthRequiredReason`, and the five state variants
  - 13 action types, including all four working-directory actions, all four
    customization actions and all three MCP-server actions
  - `Icon`, `ChatInteractivity`, `InputRequestResponsePart`,
    `ToolCallContributor`, `SessionMetadata`, `JsonPrimitive`, `Implementation`

Replace the allowlist with `export *` from the per-channel shims, so the entry
point is complete by construction rather than by maintenance. The reducer block
stays explicit because the `reducers.ts` shim also re-exports
`softAssertNever`, an internal helper that should not be public.

`ChatAction` is declared twice with identical member sets -- once by hand in
`channels-chat/actions.ts`, once in `action-origin.generated.ts` -- so it is
named explicitly to resolve the `export *` ambiguity, preserving the generated
declaration the previous list exported. The duplicate declaration itself is
left alone; collapsing it is a source change unrelated to this packaging fix.

Add `scripts/public-api.test.ts`, which walks the canonical channel modules and
asserts every declaration is reachable from the entry point, with a small
justified withhold-list. It also asserts the reverse -- that nothing on the
withhold-list has become reachable -- so the list cannot go stale. Verified it
fails when a re-export is removed.

Also refresh four stale `workingDirectory` (singular) references in the
specification left over from the 0.7.0 rename to `workingDirectories`.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@roblourens
roblourens marked this pull request as ready for review July 31, 2026 23:31
@roblourens
roblourens enabled auto-merge (squash) July 31, 2026 23:31
@roblourens
roblourens merged commit bd27d35 into main Jul 31, 2026
9 checks passed
@roblourens
roblourens deleted the roblou/agents/export-all-public-types branch July 31, 2026 23:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants