@agen-ai/acp-transport 0.4.1 → 0.4.2

package/README.md

@@ -5,12 +5,17 @@ This optional AgenAI Agent SDK package connects a host to streams supplied by th
 host. It validates messages against packaged, hash-pinned ACP schemas and owns
 framing, correlation, reverse requests, deadlines and connection cleanup.
 
-The coordinated SDK source version is `0.4.1` and remains unpublished; the published
-release is `0.4.0`. The package is ESM, MIT
+The coordinated source candidate is unpublished `0.4.2`; published `0.4.1` keeps its original
+archives and qualification. The package is ESM, MIT
 licensed and side-effect-free on import, with exact Ajv `8.17.1` as its sole runtime
 dependency. It is independent of the provider-neutral `@agen-ai/agent-protocol`
 and `@agen-ai/agent-runtime` packages.
 
+Keep installed SDK packages at one coordinated version. Exact reverse-request cancellation and
+actual response-write settlement are transport facts; the provider maps them to V12 request
+availability and independent delivery receipts. Controlled transport FIFO proof does not qualify
+simultaneous vendor callbacks. See the [0.4.2 migration guide](../../MIGRATING-TO-0.4.2.md).
+
 ## Connect existing streams
 
 The host supplies the agent's stdin, stdout and optional stderr streams. Process
@@ -57,7 +62,7 @@ bounded protocol limits, typed errors and explicit extension registration.
 No internal file path is a supported import.
 
 Transport errors and validated remote JSON-RPC errors retain their ACP meanings. Provider adapters
-own translation into Agent Protocol V11 failures and any provider-owned retry observation; the
+own translation into Agent Protocol V12 failures and any provider-owned retry observation; the
 transport has no dependency on that protocol and grants no turn replay or quota authority.
 
 An adapter migrating from a private transport import should use these public
@@ -88,6 +93,14 @@ A reverse-request handler fulfills before its validated JSON-RPC response is ser
 Successful local writing does not establish peer receipt: the transport tracks no acknowledgment
 of a reverse response. A provider's canonical answer receipt must state its own acceptance boundary.
 
+Each reverse handler receives `context.settled`, a nonrejecting promise that fulfills after that
+handler and its actual response-write obligation settle. Register reservation release against it
+when callback material must remain charged through writing. Do not await it inside the handler:
+the transport must first receive the handler's result before it can write the response. The promise
+also remains pending when disposal rejects an entered write early; an actual write callback or
+stream termination must settle the underlying obligation. Fulfillment observes completion, not
+successful delivery or peer acceptance, and does not authorize answer replay.
+
 Requests can set `onResponseReceived` to admit a validated result or remote error
 synchronously before the request promise settles and before the next frame is
 delivered. This lets a session order its terminal marker behind preceding updates.

package/dist/client.js

@@ -101,18 +101,18 @@ function createAcpClient(options) {
     if (state !== "open") return;
     void close({ kind: "fatal", error }).catch(() => void 0);
   };
-  const writeOrFail = async (message) => {
+  const writeOrFail = async (message, observeSettlement) => {
     try {
-      await writer.write(message);
+      await writer.write(message, observeSettlement);
     } catch (error) {
       const normalized = error instanceof Error ? error : new AcpClientError("acp_stdin_write_failed", "The ACP input stream write failed.");
       fatal(normalized);
       throw normalized;
     }
   };
-  const sendErrorResponse = async (id, error) => {
+  const sendErrorResponse = async (id, error, observeSettlement) => {
     if (state !== "open") return;
-    await writeOrFail({ jsonrpc: "2.0", id, error });
+    await writeOrFail({ jsonrpc: "2.0", id, error }, observeSettlement);
   };
   const sendReservedErrorResponse = (key, id, error) => {
     reservedInboundRequestIds.add(key);
@@ -267,18 +267,23 @@ function createAcpClient(options) {
       }
     })();
   };
-  const runReverseRequest = (message, extension, handler, controller) => (async () => {
+  const runReverseRequest = (message, extension, handler, controller, settled) => (async () => {
+    let actualWrite;
+    const observeWrite = (settlement) => {
+      actualWrite = settlement;
+    };
     try {
       const result = await handler({
         id: message.id,
         method: message.method,
         params: message.params,
-        signal: controller.signal
+        signal: controller.signal,
+        settled
       });
       assertBoundedAcpJson(result, limits);
       if (extension) extensions.validateResult("inbound_request", message.method, result);
       else schema.validate("client", message.method, "response", result);
-      if (state === "open") await writeOrFail({ jsonrpc: "2.0", id: message.id, result });
+      if (state === "open") await writeOrFail({ jsonrpc: "2.0", id: message.id, result }, observeWrite);
     } catch (error) {
       if (state !== "open") return;
       const rpcError = error instanceof AcpRpcHandlerError ? error : controller.signal.aborted ? new AcpRpcHandlerError(-32800, "Request cancelled") : new AcpRpcHandlerError(-32603, "Internal error");
@@ -287,7 +292,9 @@ function createAcpClient(options) {
         code: rpcError.code,
         message: rpcError.message,
         ...rpcError.data !== void 0 ? { data: rpcError.data } : {}
-      });
+      }, observeWrite);
+    } finally {
+      await actualWrite;
     }
   })();
   const handleRequest = (message) => {
@@ -339,7 +346,7 @@ function createAcpClient(options) {
     reservedInboundRequestIds.add(key);
     const settlement = deferred();
     activeReverse.set(key, { controller, settlement: settlement.promise });
-    void runReverseRequest(message, extension, handler, controller).catch((error) => fatal(error instanceof Error ? error : new AcpProtocolError(
+    void runReverseRequest(message, extension, handler, controller, settlement.promise).catch((error) => fatal(error instanceof Error ? error : new AcpProtocolError(
       "acp_reverse_request_failed"
     ))).finally(() => {
       activeReverse.delete(key);

package/dist/clientContracts.d.ts

@@ -10,6 +10,8 @@ export interface AcpReverseRequestContext {
     readonly method: string;
     readonly params: AcpJsonValue | undefined;
     readonly signal: AbortSignal;
+    /** Fulfills after this handler and its actual response write settle. Observe without awaiting inside the handler. */
+    readonly settled: Promise<void>;
 }
 export type AcpReverseRequestHandler = (context: AcpReverseRequestContext) => AcpJsonValue | Promise<AcpJsonValue>;
 export interface AcpNotificationContext {

package/dist/messageWriter.d.ts

@@ -1,7 +1,7 @@
 import type { Writable } from 'node:stream';
 import type { AcpMessage } from './protocol.js';
 export interface AcpMessageWriter {
-    readonly write: (message: AcpMessage) => Promise<void>;
+    readonly write: (message: AcpMessage, observeSettlement?: (settled: Promise<void>) => void) => Promise<void>;
     readonly dispose: (drainMs: number) => Promise<void>;
 }
 export declare function createAcpMessageWriter(input: {

package/dist/messageWriter.js

@@ -4,8 +4,9 @@ function createAcpMessageWriter(input) {
   let queuedBytes = 0;
   let queue = Promise.resolve();
   const activeRejectors = /* @__PURE__ */ new Set();
-  const writeNow = (frame) => new Promise((resolve, reject) => {
+  const writeNow = (frame, settled) => new Promise((resolve, reject) => {
     if (disposed) {
+      settled?.();
       reject(new AcpClientError("acp_client_disposed", "The ACP client is disposed."));
       return;
     }
@@ -14,7 +15,7 @@ function createAcpMessageWriter(input) {
     let writeCompleted = false;
     let drainRequired = false;
     let drainObserved = false;
-    let settled = false;
+    let observed = false;
     const cleanupListeners = () => {
       if (!listenersAttached) return;
       listenersAttached = false;
@@ -23,8 +24,8 @@ function createAcpMessageWriter(input) {
       input.writable.off("close", onClose);
     };
     const settle = (error) => {
-      if (settled) return;
-      settled = true;
+      if (observed) return;
+      observed = true;
       activeRejectors.delete(rejectActive);
       if (error) reject(error);
       else resolve();
@@ -32,6 +33,7 @@ function createAcpMessageWriter(input) {
     const complete = (error) => {
       cleanupListeners();
       settle(error);
+      settled?.();
     };
     const completeSuccessfulWrite = () => {
       if (!returnObserved || !writeCompleted || drainRequired && !drainObserved) return;
@@ -40,7 +42,10 @@ function createAcpMessageWriter(input) {
     const rejectActive = (error) => {
       settle(error);
       input.writable.off("drain", onDrain);
-      if (writeCompleted) cleanupListeners();
+      if (writeCompleted) {
+        cleanupListeners();
+        settled?.();
+      }
     };
     const onDrain = () => {
       drainObserved = true;
@@ -62,8 +67,10 @@ function createAcpMessageWriter(input) {
       const admitted = input.writable.write(frame, (error) => {
         if (error) return;
         writeCompleted = true;
-        if (disposed) cleanupListeners();
-        else completeSuccessfulWrite();
+        if (disposed) {
+          cleanupListeners();
+          settled?.();
+        } else completeSuccessfulWrite();
       });
       drainRequired = !admitted;
       drainObserved = admitted;
@@ -77,7 +84,7 @@ function createAcpMessageWriter(input) {
     }
   });
   const writer = {
-    write: (message) => {
+    write: (message, observeSettlement) => {
       if (disposed) {
         return Promise.reject(new AcpClientError(
           "acp_client_disposed",
@@ -99,7 +106,9 @@ function createAcpMessageWriter(input) {
         );
       }
       queuedBytes += frame.byteLength;
-      const operation = queue.then(() => writeNow(frame));
+      const actual = observeSettlement ? Promise.withResolvers() : void 0;
+      if (actual) observeSettlement?.(actual.promise);
+      const operation = queue.then(() => writeNow(frame, actual?.resolve));
       queue = operation.then(
         () => {
           queuedBytes -= frame.byteLength;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agen-ai/acp-transport",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "private": false,
   "type": "module",
   "sideEffects": false,