Introduce extension SDK for TS - #21
Draft
LucaButBoring wants to merge 26 commits into
Draft
Conversation
- add provenance-checked V1 and V2 schema artifacts - implement generation-specific declarations and strict codecs - cover protocol invariants with property-based tests
- implement the connected session port and immediate executions - manage tool declarations with abortable ordered refreshes - add input routing, lifecycle guards, and V2 tool codecs
- add package-level format and format-check scripts - enforce formatting in the package check workflow - preserve immutable schema artifacts through ignore rules
- Add V1 and V2 task drivers with polling, notifications, and retries - Implement conflated updates, cancellation, and lifecycle cleanup - Cover protocol envelopes and adversarial races with property tests
- Add type-aware ESLint configuration for the ext-tasks package - Integrate linting into package checks and prepack verification - Fix type-safety, lifecycle, and test diagnostics without suppressions
- Correlate V1 task input with related-task metadata - Handle keyed V2 input through validated partial updates - Add fail-closed and lifecycle race coverage
- Bind serialized references to durable endpoint identities - Resume V1 and V2 tasks with generation-specific lifecycles - Adapt Client 2.0 through public request and handler seams
- Split client and core monoliths into cohesive internal modules - Consolidate generation-specific task drivers and remove pre-release aliases - Strengthen codec, export, packed-consumer, and CI contracts
- Share generation-neutral codec validation and path helpers - Preserve generation-specific request and wire decoding - Require and add JSDoc for exported functions
- Replace handwritten V1/V2 codecs and wire types with inferred Zod schemas - Accept caller result schemas directly and remove custom codec compatibility APIs - Harden schema exports, protocol defaults, and packed dependency contracts
- Enable the strict type-checked typescript-eslint preset - Resolve all unsafe, redundant, and confusing typed lint findings - Strengthen runtime boundary checks and race/property tests
- Extract input projection, correlation, and context utilities - Decompose V2 input resolution and schema construction - Clarify task update queues and close a notification startup race
Centralize snapshot arbitration and observation sequencing behind named driver contexts. Decompose V2 task and input processing, with regression coverage for terminal authority and one-shot input keys.
Replace forward-declared branch results with focused helpers and explicit outcomes. Keep timing-sensitive session locals and iterative cursor state unchanged.
- Finalize generation-tagged declarations and codec-neutral results - Correct task input routing, recovery ownership, and lifecycle cleanup - Add packed exports and SDK peer-range contract validation - Document the initial client integration API without naming consumers Signed-off-by: Luca Chang <lucalc@amazon.com>
- Add semantic task sessions, controllers, settlement, and input routing - Add SDK raw-dispatch integration and receiver task bindings - Add runtime boundary adapters and generation-neutral projections - Remove obsolete task-result bridging and session history APIs - Expand protocol, lifecycle, packaging, and consumer validation Signed-off-by: Luca Chang <lucalc@amazon.com>
- Add per-request timeout options to tool calls and task controllers - Preserve timeout context across initiating and follow-up requests - Forward timeout values through the SDK client adapter - Cover managed and detached task request propagation Signed-off-by: Luca Chang <lucalc@amazon.com>
There was a problem hiding this comment.
🟡 Changes recommended
Protocol routing, task preference enforcement, schema validation, timer handling, and lifecycle issues remain unresolved.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Introduces a publishable TypeScript SDK for MCP Tasks, supporting V1/V2 requester workflows and V1 receivers, with documentation, tests, packaging, and CI integration.
Changes:
- Adds generation-neutral task sessions, execution lifecycle, recovery, input routing, and receiver APIs.
- Adds runtime schemas, adapters, extensive tests, and package validation.
- Adds TypeScript guides and repository CI/documentation integration.
File summaries
| File | Description |
|---|---|
.github/workflows/ci.yml |
Expands package, documentation, and peer-range CI. |
.github/workflows/deploy.yml |
Validates the repository before documentation deployment. |
.gitignore |
Ignores package tarballs. |
.vitepress/config.mts |
Adds TypeScript SDK navigation. |
README.md |
Documents the TypeScript package and development commands. |
package-lock.json |
Locks workspace dependencies. |
package.json |
Configures workspaces and root scripts. |
packages/ext-tasks/.prettierignore |
Excludes generated/package artifacts. |
packages/ext-tasks/LICENSE |
Adds package licensing. |
packages/ext-tasks/README.md |
Documents package usage and entry points. |
packages/ext-tasks/eslint.config.mjs |
Configures package linting. |
packages/ext-tasks/package.json |
Defines package exports, dependencies, and scripts. |
packages/ext-tasks/schema/v1/schema.json |
Adds the pinned V1 JSON schema. |
packages/ext-tasks/schema/v1/schema.ts |
Adds pinned V1 TypeScript declarations. |
packages/ext-tasks/schema/v2/schema.json |
Adds the pinned V2 JSON schema. |
packages/ext-tasks/schema/v2/schema.ts |
Adds pinned V2 TypeScript declarations. |
packages/ext-tasks/scripts/check-exports.mjs |
Validates package and consumer contracts. |
packages/ext-tasks/scripts/check-peer-range.mjs |
Checks supported client peer versions. |
packages/ext-tasks/scripts/check-schema-provenance.mjs |
Verifies pinned schema provenance. |
packages/ext-tasks/src/client/api.ts |
Defines the public client API. |
packages/ext-tasks/src/client/client-adapter.test.ts |
Tests SDK client adaptation. |
packages/ext-tasks/src/client/declarations-capabilities.test.ts |
Tests declarations and negotiated capabilities. |
packages/ext-tasks/src/client/execution.ts |
Implements execution state, observation, and settlement. |
packages/ext-tasks/src/client/immediate-session-basics.test.ts |
Tests immediate execution and session basics. |
packages/ext-tasks/src/client/index.ts |
Exposes the client entry point. |
packages/ext-tasks/src/client/input-routing.ts |
Implements application-input routing. |
packages/ext-tasks/src/client/internal.ts |
Provides generation-neutral projections. |
packages/ext-tasks/src/client/port.ts |
Implements task RPC dispatch. |
packages/ext-tasks/src/client/protocol-matrix.test.ts |
Tests V1/V2 semantic parity. |
packages/ext-tasks/src/client/request-input-continuation.test.ts |
Tests request-scoped input continuation. |
packages/ext-tasks/src/client/sdk-client-adapter.ts |
Adapts SDK clients to task sessions. |
packages/ext-tasks/src/client/session-facade.test.ts |
Tests the public session facade. |
packages/ext-tasks/src/client/session.ts |
Implements task-enabled sessions. |
packages/ext-tasks/src/client/task-controller.test.ts |
Tests manual task controllers. |
packages/ext-tasks/src/client/task-controller.ts |
Implements manual task operations. |
packages/ext-tasks/src/client/task-lifecycle-races.test.ts |
Tests lifecycle and concurrency races. |
packages/ext-tasks/src/client/task-protocol-v1.ts |
Implements V1 task execution. |
packages/ext-tasks/src/client/task-protocol-v2.ts |
Implements V2 task execution and input. |
packages/ext-tasks/src/client/task-resumption.test.ts |
Tests task recovery and ownership. |
packages/ext-tasks/src/client/tool-declarations.ts |
Manages tool discovery and refreshes. |
packages/ext-tasks/src/client/v1-input-task.test.ts |
Tests V1 input routing. |
packages/ext-tasks/src/client/v2-input-task.test.ts |
Tests V2 task input handling. |
packages/ext-tasks/src/core/index.test.ts |
Tests core JSON and codec utilities. |
packages/ext-tasks/src/core/index.ts |
Adds common types, codecs, and errors. |
packages/ext-tasks/src/core/v1/index.test.ts |
Tests V1 schemas and negotiation. |
packages/ext-tasks/src/core/v1/index.ts |
Exposes V1 APIs. |
packages/ext-tasks/src/core/v1/negotiation.ts |
Implements V1 capability negotiation. |
packages/ext-tasks/src/core/v1/schemas.ts |
Defines V1 runtime schemas. |
packages/ext-tasks/src/core/v2/index.test.ts |
Tests V2 runtime contracts. |
packages/ext-tasks/src/core/v2/index.ts |
Exposes V2 APIs. |
packages/ext-tasks/src/core/v2/integration.ts |
Adds V2 capability and subscription helpers. |
packages/ext-tasks/src/core/v2/schemas.ts |
Defines V2 runtime schemas. |
packages/ext-tasks/src/receiver/index.ts |
Implements the V1 Tasks receiver. |
packages/ext-tasks/src/receiver/receiver.test.ts |
Tests receiver lifecycle behavior. |
packages/ext-tasks/test-support/client/fake-port.ts |
Adds a client test port. |
packages/ext-tasks/test-support/client/semantic.ts |
Adds semantic test adapters. |
packages/ext-tasks/tsconfig.eslint.json |
Configures lint type information. |
packages/ext-tasks/tsconfig.json |
Configures package compilation. |
packages/ext-tasks/tsconfig.test.json |
Configures test type-checking. |
packages/ext-tasks/vitest.config.ts |
Configures package tests. |
tsconfig.package.json |
Adds shared package compiler settings. |
typescript/adapters-and-schemas.md |
Documents advanced adapters and schemas. |
typescript/client/execution.md |
Documents execution control. |
typescript/client/input-and-recovery.md |
Documents input handling and recovery. |
typescript/getting-started.md |
Adds a requester quick start. |
typescript/index.md |
Adds the TypeScript SDK overview. |
typescript/migrating-from-the-sdk.md |
Documents SDK migration. |
typescript/receiver.md |
Documents V1 receiver usage. |
typescript/troubleshooting.md |
Documents common lifecycle failures. |
Review details
- Files reviewed: 65/69 changed files
- Comments generated: 9
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟡 Changes recommended
V2 validation, capability merging, and documented signal behavior contain interoperability issues.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (4)
Previously missed (2) — in code that hasn't changed since the last review.
packages/ext-tasks/src/core/v2/integration.ts:126
- This overwrites an existing
io.modelcontextprotocol/clientCapabilitiesobject. For custom ports, request metadata that already advertises sampling, elicitation, or another extension loses those capabilities whenever Tasks framing is added. Merge the existing capability object and itsextensionsmap, then add the Tasks key, matching the merge performed byframeV2TaskRequest().
typescript/client/execution.md:93 - This states that
signalbounds the whole operation, but aftercallTool()returns a task execution the implementation disposes the linked call signal and constructs the execution with only the session lifecycle signal. Aborting the supplied signal later therefore does not stop task polling or input handling. Either retain that signal in the task execution lifecycle or document that it only bounds task creation.
packages/ext-tasks/src/core/v2/schemas.ts:256
- The wire schema accepts any JSON value as a root, so values such as
{ roots: [null, "x"] }pass validation and are sent intasks/update. The 2026-07-28 schema requires each root to be an object with a stringuri(plus optionalnameand_meta). Validate the actual Root shape here.
packages/ext-tasks/src/core/v2/schemas.ts:259 - This schema only validates
action; becauseopenObjecttreatscontentand_metaas undeclared keys, it accepts any JSON value for either. The protocol requirescontentto be an object whose values are strings, integers, booleans, or string arrays, and_metato be an object. Invalid handler output currently passes and is sent to the server.
- Files reviewed: 65/69 changed files
- Comments generated: 1
- Review effort level: Balanced
| _meta: MetaSchema.optional(), | ||
| }); | ||
|
|
||
| const CompleteResultTypeSchema = z.literal("complete").default("complete"); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Introduces an extension SDK for Tasks support, layered on top of the general TS SDK. Supports both the
2025-11-25and2026-07-28specifications. Original implementation comes from the Inspector and has been reshaped to make a cleaner public API.Motivation and Context
Unblocks support for Tasks for TS SDK consumers.
How Has This Been Tested?
Integrated into the MCP Inspector in a branch (modelcontextprotocol/inspector#2308).
Breaking Changes
N/A; new package.
Types of changes
Checklist
Additional context
We'll need to set up CI/CD to actually publish this separately. Need to figure out how to do this.