Add Agent Factories Authoring Surface

[MRayermannMSFT]

What

Adds the SDK authoring surface for Agent Factories. Extensions can define a factory with defineFactory({ meta, run }), register it by passing factory handles to joinSession({ factories }), and run it from a session through session.factory.run(name, options), with getRun and cancel for run management. RunOptions accepts per-invocation ad-hoc limits and a resumeFromRunId so a caller can retry the same run under a raised, user-approved budget after a limit failure. The factory body receives a context that exposes the durable factory primitives (agent, step, parallel, pipeline, phase, log) alongside the caller-supplied args and the full session. The entire hand-authored surface is annotated @experimental so consumers know it may change.

Why

The runtime exposes Agent Factories over a JSON-RPC contract, but extension authors need an ergonomic, typed TypeScript surface to define and run factories rather than hand-writing wire calls. This adds that friendly layer and the factory context primitives that let a multi-agent factory read as ordinary async code. Marking the surface experimental sets clear expectations while the feature stabilizes alongside the runtime.

Companion PR: github/copilot-agent-runtime#12953

[Copilot]

Pull request overview

Adds the experimental TypeScript authoring surface for defining, registering, executing, and managing Agent Orchestrations.

Changes:

• Adds orchestration definitions, handles, context primitives, metadata, and run APIs.
• Integrates orchestration registration and reverse-RPC execution into extension sessions.
• Adds generated RPC contracts and comprehensive unit tests.

Show a summary per file

File	Description
nodejs/src/orchestration.ts	Defines the public orchestration API.
nodejs/src/session.ts	Implements execution, primitives, progress, and cancellation.
nodejs/src/client.ts	Registers orchestrations during extension resume.
nodejs/src/extension.ts	Exposes orchestration registration through joinSession.
nodejs/src/index.ts	Exports the new public surface.
nodejs/src/types.ts	Adds orchestration metadata and limits.
nodejs/src/generated/rpc.ts	Adds orchestration RPC contracts and handlers.
nodejs/test/orchestration.test.ts	Tests orchestration behavior and integration.

Review details

• Files reviewed: 7/8 changed files
• Comments generated: 7
• Review effort level: Medium

[github-actions]

Cross-SDK Consistency Review

Summary: This PR adds the Agent Factories authoring surface exclusively to the Node.js/TypeScript SDK. No equivalent feature exists in Python, Go, .NET, Java, or Rust.

Finding: New experimental feature, Node.js only ⚠️

The PR introduces a significant new API surface:

• defineFactory({ meta, run }) — define a factory
• joinSession({ factories }) — register factories at session join
• session.factory.run(...), .getRun(runId), .cancel(runId) — invoke and manage factory runs
• FactoryContext primitives: agent, step, parallel, pipeline, phase, log

None of these exist in the other five SDK implementations (Python, Go, .NET, Java, Rust).

Assessment: Expected gap — no action required right now

This is an intentional inconsistency for the following reasons:

1. Marked @experimental throughout — every exported type and function carries an @experimental JSDoc tag noting it may change or be removed. This signals the API is not yet stable for cross-language rollout.
2. Companion runtime PR — the PR description references a companion runtime PR (github/copilot-agent-runtime#12953), indicating this is a staged rollout where the Node.js SDK serves as the initial authoring surface.
3. TypeScript-first pattern — the SDK already has TypeScript-only experimental APIs. This follows that established pattern.

Suggested follow-up (non-blocking)

When the Agent Factories feature graduates from @experimental status, the following should be considered for cross-SDK parity:

SDK	Equivalent surface needed
Python	define_factory(), join_session(factories=[...]), session.factory.run()
Go	DefineFactory(), JoinSession with Factories option, session.Factory.Run()
.NET	DefineFactory(), JoinSession with Factories property, session.Factory.RunAsync()
Java	defineFactory(), joinSession with factories list, session.factory().run()
Rust	define_factory(), session factory API

No changes are required at this time. The PR is internally consistent with the Node.js SDK's established patterns for experimental features.

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

Generated by SDK Consistency Review Agent for #2009 · 40.3 AIC · ⌖ 7.69 AIC · ⊞ 5K · ◷