@toolgrain/mcp 0.2.0 → 0.3.0-alpha.0

package/dist/tools/progress.d.ts

@@ -0,0 +1,17 @@
+import type { ProgressNotification } from "@toolgrain/protocol";
+/** One progress update; values are finite numbers and progress must strictly increase. */
+export interface ToolProgress {
+    /** Work completed so far, in application-defined units; the first value may be zero. */
+    readonly progress: number;
+    /** Optional total work, in the same units; omit when unknown. */
+    readonly total?: number;
+    /** Optional public status message sent to the client. */
+    readonly message?: string;
+}
+/** One invocation owns its reporter, ordering, and completion boundary. */
+export declare function createProgressReporter(signal: AbortSignal, token: unknown, send?: (message: ProgressNotification) => void | Promise<void>): {
+    report: (value: ToolProgress) => Promise<void>;
+    finish(): Promise<void>;
+    close(): void;
+};
+//# sourceMappingURL=progress.d.ts.map

package/dist/tools/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/tools/progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,qBAAqB,CAAC;AAI/E,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAQD,2EAA2E;AAC3E,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;oBAUvC,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC;;;EA8CpD"}

package/dist/tools/progress.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { abortable } from "../abort.js";
+const update = z.object({
+    progress: z.number().finite(),
+    total: z.number().finite().optional(),
+    message: z.string().optional(),
+});
+/** One invocation owns its reporter, ordering, and completion boundary. */
+export function createProgressReporter(signal, token, send) {
+    const validToken = typeof token === "string" ||
+        (typeof token === "number" &&
+            Number.isFinite(token) &&
+            Number.isInteger(token));
+    let open = true;
+    let previous = Number.NEGATIVE_INFINITY;
+    let writes = Promise.resolve();
+    const report = (value) => {
+        if (!open || signal.aborted || !validToken || !send)
+            return Promise.resolve();
+        const parsed = update.safeParse(value);
+        if (!parsed.success)
+            return Promise.reject(new TypeError("Invalid progress update"));
+        if (parsed.data.progress <= previous)
+            return Promise.reject(new TypeError("Progress must strictly increase"));
+        previous = parsed.data.progress;
+        const message = {
+            jsonrpc: "2.0",
+            method: "notifications/progress",
+            params: {
+                progress: parsed.data.progress,
+                ...(parsed.data.total === undefined
+                    ? {}
+                    : { total: parsed.data.total }),
+                ...(parsed.data.message === undefined
+                    ? {}
+                    : { message: parsed.data.message }),
+                progressToken: token,
+            },
+        };
+        const write = writes.then(async () => {
+            if (!signal.aborted)
+                await abortable(Promise.resolve().then(() => {
+                    if (!signal.aborted)
+                        return send(message);
+                }), signal);
+        });
+        // The awaiting handler observes failures; keep the queue usable for cleanup.
+        writes = write.catch(() => { });
+        return write;
+    };
+    return {
+        report,
+        async finish() {
+            open = false;
+            await writes;
+        },
+        close() {
+            open = false;
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/tools/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/tools/progress.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import type { ProtocolResponse } from "@toolgrain/protocol";
+import type { ProgressNotification, ProtocolResponse } from "@toolgrain/protocol";
 import type { Server } from "./server.js";
 /** Callbacks are synchronous; message processing runs independently. */
 export interface TransportCallbacks {
@@ -21,10 +21,10 @@ export interface Transport {
      */
     start(callbacks: TransportCallbacks): Promise<void>;
     /**
-     * Send one protocol response, resolving after the adapter's write/backpressure handling.
-     * @param message - Response envelope already converted for the client's protocol revision.
+     * Send one response or progress notification, resolving after write/backpressure handling.
+     * @param message - Envelope already converted for the client's protocol revision.
      */
-    send(message: ProtocolResponse): Promise<void>;
+    send(message: ProtocolResponse | ProgressNotification): Promise<void>;
     /** Release adapter-owned resources; closing is terminal and must tolerate repeated calls. */
     close(): Promise<void>;
 }

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,oFAAoF;IACpF,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,yFAAyF;IACzF,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,6FAA6F;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,KAAK,CACH,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,SAAS,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GACtC,SAAS,IAAI,gBAAgB,CAE/B"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,oFAAoF;IACpF,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,yFAAyF;IACzF,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,4FAA4F;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,6FAA6F;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;OAIG;IACH,KAAK,CACH,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,SAAS,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GACtC,SAAS,IAAI,gBAAgB,CAE/B"}

package/dist/transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAkDA,MAAM,UAAU,kBAAkB,CAChC,SAAuC;IAEvC,OAAO,MAAM,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAqDA,MAAM,UAAU,kBAAkB,CAChC,SAAuC;IAEvC,OAAO,MAAM,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0-alpha.0",
   "description": "Define reusable, typed MCP tools and servers with Zod validation.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "latest"
+    "tag": "alpha"
   },
   "type": "module",
   "exports": {
@@ -59,7 +59,7 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/protocol": "0.2.0"
+    "@toolgrain/protocol": "0.3.0-alpha.0"
   },
   "engines": {
     "node": "^24.20.0",

package/src/auth/authorization.ts

@@ -1,4 +1,4 @@
-import { abortable } from "./abort.js";
+import { abortable } from "../abort.js";
 import { identitySnapshot } from "./context.js";
 import { AuthError } from "./errors.js";
 import { validateAuthScopes } from "./scopes.js";

package/src/connection.ts

@@ -1,6 +1,7 @@
 import {
   INVALID_REQUEST,
   PARSE_ERROR,
+  type ProgressNotification,
   type ProtocolResponse,
 } from "@toolgrain/protocol";
 import { type ErrorHandler, reportError } from "./diagnostics.js";
@@ -134,7 +135,7 @@ class Connection implements ConnectionLifecycle {
   }
 
   private send(
-    message: ProtocolResponse,
+    message: ProtocolResponse | ProgressNotification,
     isActive: () => boolean = () => this.isOpen(),
   ): Promise<void> {
     const write = this.writes.then(async () => {
@@ -193,7 +194,11 @@ class Connection implements ConnectionLifecycle {
       const response = await executeRequest(
         this.dispatch,
         request,
-        { signal: pending.signal, client: this.legacy.client() },
+        {
+          signal: pending.signal,
+          client: this.legacy.client(),
+          notify: (message) => this.send(message, pending.isActive),
+        },
         (error) => this.report(error),
         prepared.protocolVersion,
       );

package/src/dispatcher.ts

@@ -2,6 +2,7 @@ import {
   type Implementation,
   type JSONRPCErrorResponse,
   LEGACY_PROTOCOL_VERSION,
+  type ProgressNotification,
   type ProtocolResponse,
   type SupportedProtocolVersion,
 } from "@toolgrain/protocol";
@@ -16,7 +17,7 @@ import { createModernDispatcher } from "./modern/dispatcher.js";
 import type { Request } from "./protocol/messages.js";
 import { validateVersionContext } from "./protocol/version-metadata.js";
 import type { ToolAdapter } from "./tools/adapter.js";
-import type { ToolClient } from "./tools/context.js";
+import type { ToolClient, ToolContext } from "./tools/context.js";
 
 /** Per-request execution state supplied by the connection or independent caller. */
 export interface RequestScope {
@@ -24,6 +25,8 @@ export interface RequestScope {
   /** Client details negotiated by legacy initialization, when the connection has them. */
   client?: ToolClient | undefined;
   auth?: AuthIdentity;
+  notify?: (message: ProgressNotification) => void | Promise<void>;
+  reportProgress?: ToolContext["reportProgress"];
 }
 
 export type Dispatcher = (

package/src/execute-request.ts

@@ -7,6 +7,7 @@ import { type ErrorHandler, reportError } from "./diagnostics.js";
 import type { Dispatcher, RequestScope } from "./dispatcher.js";
 import type { Request } from "./protocol/messages.js";
 import { ProtocolError, protocolError } from "./protocol/responses.js";
+import { createProgressReporter } from "./tools/progress.js";
 
 /** Shared dispatch boundary for connection-scoped and independent requests. */
 export async function executeRequest(
@@ -17,8 +18,20 @@ export async function executeRequest(
   protocolVersion?: SupportedProtocolVersion,
 ): Promise<ProtocolResponse | undefined> {
   const isActive = () => !scope.signal.aborted;
+  let progress: ReturnType<typeof createProgressReporter> | undefined;
   try {
-    const response = await dispatch(request, scope, protocolVersion);
+    progress = createProgressReporter(
+      scope.signal,
+      (request.params?._meta as Record<string, unknown> | undefined)
+        ?.progressToken,
+      scope.notify,
+    );
+    const response = await dispatch(
+      request,
+      { ...scope, reportProgress: progress.report },
+      protocolVersion,
+    );
+    await progress.finish();
     return isActive() ? response : undefined;
   } catch (error) {
     if (!isActive()) return;
@@ -31,5 +44,7 @@ export async function executeRequest(
       request.id,
       undefined,
     );
+  } finally {
+    progress?.close();
   }
 }

package/src/index.ts

@@ -26,6 +26,7 @@ export { toolContext } from "./tools/context.js";
 export type { Tool, ToolDefinition, ToolMetadata } from "./tools/definition.js";
 export { tool } from "./tools/definition.js";
 export { ToolNameError } from "./tools/name.js";
+export type { ToolProgress } from "./tools/progress.js";
 export type { ToolMap } from "./tools/registry.js";
 export type {
   McpErrorResult,

package/src/legacy/dispatcher.ts

@@ -61,6 +61,7 @@ export function createLegacyDispatcher(
             },
             scope.auth,
             providers,
+            scope.reportProgress,
           ),
         );
         break;

package/src/legacy/messages.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { object } from "../protocol/messages.js";
+import { object, requestId } from "../protocol/messages.js";
 
 export const commonParams = z.looseObject({
-  _meta: object.optional(),
+  _meta: z.looseObject({ progressToken: requestId.optional() }).optional(),
 });
 export const initializeParams = commonParams.extend({
   protocolVersion: z.string(),

package/src/modern/dispatcher.ts

@@ -66,6 +66,7 @@ export function createModernDispatcher(
             },
             scope.auth,
             providers,
+            scope.reportProgress,
           ),
         );
         break;

package/src/modern/metadata.ts

@@ -1,9 +1,8 @@
 import { z } from "zod";
 import { icon } from "../protocol/icon.js";
-import { object } from "../protocol/messages.js";
+import { object, requestId } from "../protocol/messages.js";
 
 const capabilityObject = z.record(z.string(), z.json());
-const requestId = z.union([z.string(), z.number().finite()]);
 const capabilities = z.looseObject({
   experimental: z.record(z.string(), capabilityObject).optional(),
   roots: object.optional(),

package/src/server.ts

@@ -1,8 +1,10 @@
 import type {
+  ProgressNotification,
   ProtocolResponse,
   Tool as ProtocolTool,
   SupportedProtocolVersion,
 } from "@toolgrain/protocol";
+import { abortable } from "./abort.js";
 import { createAuthorization } from "./auth/authorization.js";
 import { AuthError, isAuthError } from "./auth/errors.js";
 import type { AuthMetadata, AuthProvider, AuthScope } from "./auth/types.js";
@@ -21,6 +23,13 @@ import {
   type Transport,
 } from "./transport.js";
 
+// Internal adapter contract: final delivery remains part of the active request.
+// A global symbol preserves the hook across compatible package copies.
+const responseDelivery = Symbol.for("@toolgrain/mcp/response-delivery/v1");
+interface ResponseDeliveryOptions {
+  [responseDelivery]?: (response: ProtocolResponse) => void | Promise<void>;
+}
+
 /** Tool registrations, identity, and shared configuration for an MCP server. */
 export interface ServerOptions<Tools extends ToolMap = ToolMap> {
   /** Server implementation name advertised to clients. */
@@ -54,6 +63,13 @@ export interface HandleOptions {
   protocolVersion?: SupportedProtocolVersion;
   /** Single-use scope issued by this server's `authorize()`; dispose it in `finally`. */
   auth?: AuthScope;
+  /**
+   * Deliver progress notifications for this request, honoring asynchronous
+   * backpressure. Omit for a one-response caller; progress then becomes a no-op.
+   * The caller owns framing and must abort `signal` when its response channel closes.
+   * Callback failure cancels this invocation and reaches `onError(error)` without tool details.
+   */
+  onNotification?: (message: ProgressNotification) => void | Promise<void>;
 }
 
 /** An MCP dispatcher with one optional transport attachment and terminal shutdown. */
@@ -147,6 +163,9 @@ export function createServer<const Tools extends ToolMap>(
     running.add(controller);
     return {
       signal: controller.signal,
+      abort(reason: unknown) {
+        controller.abort(reason);
+      },
       finish() {
         signal?.removeEventListener("abort", abort);
         running.delete(controller);
@@ -185,10 +204,8 @@ export function createServer<const Tools extends ToolMap>(
         throw error;
       }
     },
-    async handle(
-      message,
-      { signal, protocolVersion, auth }: HandleOptions = {},
-    ) {
+    async handle(message, handleOptions: HandleOptions = {}) {
+      const { signal, protocolVersion, auth, onNotification } = handleOptions;
       if (closed) throw new Error("Server is closed");
       const identity = authorization.consume(auth);
       if (auth?.signal.aborted) return;
@@ -204,13 +221,62 @@ export function createServer<const Tools extends ToolMap>(
         ? AbortSignal.any([pending.signal, auth.signal])
         : pending.signal;
       try {
-        return await executeRequest(
-          dispatch,
-          incoming.request,
-          { signal: combined, ...(identity ? { auth: identity } : {}) },
-          options.onError,
-          protocolVersion,
+        const response = await abortable(
+          executeRequest(
+            dispatch,
+            incoming.request,
+            {
+              signal: combined,
+              ...(identity ? { auth: identity } : {}),
+              ...(onNotification
+                ? {
+                    notify: async (message: ProgressNotification) => {
+                      try {
+                        await onNotification(message);
+                      } catch (error) {
+                        if (combined.aborted) return;
+                        reportError(options.onError, error);
+                        pending.abort(
+                          new DOMException(
+                            "Progress delivery failed",
+                            "AbortError",
+                          ),
+                        );
+                      }
+                    },
+                  }
+                : {}),
+            },
+            options.onError,
+            protocolVersion,
+          ),
+          combined,
         );
+        const deliver = (handleOptions as ResponseDeliveryOptions)[
+          responseDelivery
+        ];
+        if (response && deliver) {
+          try {
+            await abortable(
+              Promise.resolve().then(() => {
+                combined.throwIfAborted();
+                return deliver(response);
+              }),
+              combined,
+            );
+          } catch (error) {
+            if (!combined.aborted) {
+              reportError(options.onError, error);
+              pending.abort(
+                new DOMException("Response delivery failed", "AbortError"),
+              );
+            }
+            return;
+          }
+        }
+        return response;
+      } catch (error) {
+        if (!combined.aborted) throw error;
       } finally {
         pending.finish();
       }

package/src/tools/context.ts

@@ -18,6 +18,7 @@ import {
 } from "../context/registry.js";
 import { createContextScope } from "../context/scope.js";
 import type { DeepReadonly } from "./json-value.js";
+import type { ToolProgress } from "./progress.js";
 
 /** What the client reported about itself; unverified, so not a basis for security decisions. */
 export interface ToolClient {
@@ -47,6 +48,14 @@ export interface ToolContext {
   readonly signal: AbortSignal;
   /** Frozen request metadata; contains no verified authorization identity. */
   readonly request: ToolRequest;
+  /**
+   * Report request-scoped progress; safe to pass to helpers without binding.
+   * Await delivery/backpressure. Resolves without sending when no progress token
+   * or delivery channel exists, or after cancellation/completion. Active updates
+   * require finite values and strictly increasing progress; invalid updates reject.
+   * Delivery failure cancels the request and reaches transport diagnostics.
+   */
+  readonly reportProgress: (update: ToolProgress) => Promise<void>;
 }
 
 /** Optional metadata, cancellation, and provider bindings for a direct-call context. */
@@ -94,10 +103,12 @@ export function createToolContext(
   { client, ...request }: ToolRequest,
   auth?: AuthIdentity,
   providers: ContextRegistry = createContextRegistry(),
+  reportProgress: ToolContext["reportProgress"] = () => Promise.resolve(),
 ): ToolContext {
   const ctx = attachAuth(
     {
       signal,
+      reportProgress,
       request: Object.freeze({
         ...request,
         ...(client === undefined

package/src/tools/progress.ts

@@ -0,0 +1,81 @@
+import type { ProgressNotification, ProgressToken } from "@toolgrain/protocol";
+import { z } from "zod";
+import { abortable } from "../abort.js";
+
+/** One progress update; values are finite numbers and progress must strictly increase. */
+export interface ToolProgress {
+  /** Work completed so far, in application-defined units; the first value may be zero. */
+  readonly progress: number;
+  /** Optional total work, in the same units; omit when unknown. */
+  readonly total?: number;
+  /** Optional public status message sent to the client. */
+  readonly message?: string;
+}
+
+const update = z.object({
+  progress: z.number().finite(),
+  total: z.number().finite().optional(),
+  message: z.string().optional(),
+});
+
+/** One invocation owns its reporter, ordering, and completion boundary. */
+export function createProgressReporter(
+  signal: AbortSignal,
+  token: unknown,
+  send?: (message: ProgressNotification) => void | Promise<void>,
+) {
+  const validToken =
+    typeof token === "string" ||
+    (typeof token === "number" &&
+      Number.isFinite(token) &&
+      Number.isInteger(token));
+  let open = true;
+  let previous = Number.NEGATIVE_INFINITY;
+  let writes = Promise.resolve();
+  const report = (value: ToolProgress): Promise<void> => {
+    if (!open || signal.aborted || !validToken || !send)
+      return Promise.resolve();
+    const parsed = update.safeParse(value);
+    if (!parsed.success)
+      return Promise.reject(new TypeError("Invalid progress update"));
+    if (parsed.data.progress <= previous)
+      return Promise.reject(new TypeError("Progress must strictly increase"));
+    previous = parsed.data.progress;
+    const message: ProgressNotification = {
+      jsonrpc: "2.0",
+      method: "notifications/progress",
+      params: {
+        progress: parsed.data.progress,
+        ...(parsed.data.total === undefined
+          ? {}
+          : { total: parsed.data.total }),
+        ...(parsed.data.message === undefined
+          ? {}
+          : { message: parsed.data.message }),
+        progressToken: token as ProgressToken,
+      },
+    };
+    const write = writes.then(async () => {
+      if (!signal.aborted)
+        await abortable(
+          Promise.resolve().then(() => {
+            if (!signal.aborted) return send(message);
+          }),
+          signal,
+        );
+    });
+    // The awaiting handler observes failures; keep the queue usable for cleanup.
+    writes = write.catch(() => {});
+    return write;
+  };
+  return {
+    report,
+    async finish() {
+      open = false;
+      await writes;
+    },
+    close() {
+      open = false;
+    },
+  };
+}

package/src/transport.ts

@@ -1,4 +1,7 @@
-import type { ProtocolResponse } from "@toolgrain/protocol";
+import type {
+  ProgressNotification,
+  ProtocolResponse,
+} from "@toolgrain/protocol";
 import type { Server } from "./server.js";
 
 /** Callbacks are synchronous; message processing runs independently. */
@@ -23,10 +26,10 @@ export interface Transport {
    */
   start(callbacks: TransportCallbacks): Promise<void>;
   /**
-   * Send one protocol response, resolving after the adapter's write/backpressure handling.
-   * @param message - Response envelope already converted for the client's protocol revision.
+   * Send one response or progress notification, resolving after write/backpressure handling.
+   * @param message - Envelope already converted for the client's protocol revision.
    */
-  send(message: ProtocolResponse): Promise<void>;
+  send(message: ProtocolResponse | ProgressNotification): Promise<void>;
   /** Release adapter-owned resources; closing is terminal and must tolerate repeated calls. */
   close(): Promise<void>;
 }

package/dist/auth/abort.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/auth/abort.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/auth/abort.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/auth/abort.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,UAAU,SAAS,CACvB,IAAgB,EAChB,MAAmB;IAEnB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,EAAE,CAAC;;YACvB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,IAAI;aACD,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC;aACrB,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC"}