@hile/message-modem 2.1.1 → 4.0.0

package/AI.md

@@ -0,0 +1,295 @@
+# AI Guide For @hile/message-modem
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Implement request/response, push, abort, and stream protocol behavior independent of transport.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+Use `@hile/message-modem` for: Implement request/response, push, abort, and stream protocol behavior independent of transport.
+
+
+
+# Messaging And Microservices
+
+Packages: `@hile/message-modem`, `@hile/message-ws`, `@hile/message-ipc`, `@hile/message-worker-thread`, `@hile/message-loader`, `@hile/micro`, `@hile/micro-dynamic-configs`.
+
+## Copy-Paste Example
+
+Message handler file:
+
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
+  }
+})
+```
+
+Microservice boot file:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
+    },
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
+```
+
+Caller:
+
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
+```
+
+## More Examples
+
+Streaming handler:
+
+```ts
+// src/messages/events.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async function* () {
+  for (let i = 0; i < 3; i++) {
+    yield { seq: i }
+  }
+})
+```
+
+Streaming caller:
+
+```ts
+const stream = await app.stream('example.service', '/events', {})
+for await (const chunk of stream) {
+  console.log(chunk)
+}
+```
+
+Custom WebSocket modem:
+
+```ts
+import { MessageWs } from '@hile/message-ws'
+import type WebSocket from 'ws'
+
+class RpcWs extends MessageWs {
+  constructor(ws: WebSocket, private readonly dispatch: (url: string, data: unknown) => Promise<unknown>) {
+    super(ws)
+  }
+
+  protected exec(data: { url: string; data: unknown }) {
+    return this.dispatch(data.url, data.data)
+  }
+
+  request<T>(url: string, data: unknown, timeout = 30_000) {
+    return this._send<T>({ url, data }, { timeout })
+  }
+}
+```
+
+Notice that `request()` returns a `Promise<T>`. Await it directly.
+
+## Use When
+
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
+
+## Do Not Use When
+
+- Do not use `stream()` for normal single-result calls.
+- Do not rely on message IDs for business idempotency. They are transport IDs.
+- Do not bypass `defineMessage()` for file-loaded handlers.
+
+## Install
+
+```bash
+pnpm add @hile/micro @hile/message-loader @hile/message-ws
+```
+
+Use transport-specific packages only when you need to build custom IPC or worker-thread bridges.
+
+## Imports
+
+```ts
+import { defineMessage, MessageLoader } from '@hile/message-loader'
+import { Application, Registry, Server } from '@hile/micro'
+import { MessageWs } from '@hile/message-ws'
+import { MessageIpc } from '@hile/message-ipc'
+import { MessageWorkerThread } from '@hile/message-worker-thread'
+```
+
+## Compose With
+
+- `@hile/context` propagates context in micro message metadata.
+- `@hile/redis-idempotency` protects retryable side effects in message handlers.
+- `@hile/redis-stream-queue` is better for durable background jobs.
+
+## Runtime And Lifecycle Notes
+
+- `MessageLoader` maps `*.msg.*` files to routes using `@hile/loader`.
+- `MessageLoader.dispatch(path, data, extras?)` invokes the matched handler.
+- `MessageModem._send()` returns a `Promise`.
+- `MessageModem._stream()` returns a Node `Readable` in object mode.
+- A stream request requires `exec()` to return an async iterable.
+- `Application.call(namespace, url, data, options?)` returns a promise.
+- `Application.stream(namespace, url, data, options?)` returns a readable stream.
+- `Application.publish(topic, payload)` returns an object with `update()` and `unpublish()`.
+- `Application.subscribe(topic, callback)` returns an unsubscribe function.
+- `Registry` stores service addresses and retained config/topic state under `~/.registry`.
+
+## Anti-Patterns
+
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
+
+## Verification Checklist
+
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
+
+
+
+# Related Recipes
+
+
+
+# Micro RPC With Message Loader
+
+## Complete Example
+
+Provider handler:
+
+```ts
+// src/messages/charge.msg.ts
+import { defineMessage } from '@hile/message-loader'
+
+export default defineMessage(async ({ data }) => {
+  return { charged: true, input: data }
+})
+```
+
+Provider boot:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('billing.micro', async (shutdown) => {
+  const app = new Application({
+    namespace: 'billing',
+    registry: { host: '127.0.0.1', port: 9876 },
+    advertiseHost: '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(9101)
+  shutdown(stop)
+  return app
+})
+```
+
+Consumer:
+
+```ts
+const result = await app.call('billing', '/charge', {
+  tenantId: 't1',
+  amount: 100,
+})
+```
+
+## File Layout
+
+```text
+provider/
+  src/messages/charge.msg.ts
+  src/services/app.boot.ts
+consumer/
+  src/models/payments/pay.model.ts
+```
+
+## User Intent
+
+Use this recipe when services communicate over Hile registry-backed RPC.
+
+## Packages To Use
+
+- `@hile/micro`
+- `@hile/message-loader`
+- `@hile/context` when context must cross service boundaries
+- `@hile/redis-idempotency` for retryable side effects
+
+## Implementation Steps
+
+1. Start a Registry with `hile registry`.
+2. Start providers with stable namespaces.
+3. Load `*.msg.ts` handlers through `app.load()`.
+4. Call providers with `await app.call(namespace, url, data)`.
+5. Use `app.stream()` only for async-generator handlers.
+
+## Failure And Cleanup Behavior
+
+- `Application.call()` may retry; side-effecting handlers need idempotency.
+- Registry disconnect triggers reconnect; apps re-declare topics and subscriptions.
+- Circuit breaker excludes failing nodes for cooldown.
+
+## Verification Checklist
+
+- Registry is reachable.
+- Provider namespace matches consumer call.
+- Handlers default-export `defineMessage()`.
+- Consumer code awaits `app.call(...)` directly.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -1,215 +1,90 @@
 # @hile/message-modem
 
-传输无关的请求/响应消息通信抽象层。将底层传输机制（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 _send/receive 语义。
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
 
-## 安装
+Implement request/response, push, abort, and stream protocol behavior independent of transport.
 
-```bash
-pnpm add @hile/message-modem
-```
-
-## 核心特性
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
 
-- **传输无关** — 子类只需实现 `post`（如何发送）和 `exec`（如何处理），即可运行于任何通信通道
-- **双向请求/响应** — `_send` 发送请求并等待对端响应（`twoway: true`）
-- **单向推送** — `_push` 发送消息无需对端响应（`twoway: false`）
-- **流式传输** — `_stream` 发送流式请求，对端返回 async generator 时分块回传，发送方获得 `Readable` stream
-- **请求/响应配对** — 自增 ID + Promise 栈，自动配对请求与响应
-- **超时控制** — 默认 30 秒，可按请求自定义
-- **主动中止** — 发送方可 abort 等待，接收方可取消正在执行的任务
-- **错误传播** — `Exception` 携带 status 码透传；普通 Error 映射为 500
+## When To Use
 
-## 快速开始
-
-### 第一步：继承并实现抽象方法
-
-```typescript
-import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
-
-class WebSocketModem extends MessageModem {
-  constructor(private ws: WebSocket) {
-    super();
-    ws.addEventListener('message', (e) => {
-      this.receive(JSON.parse(e.data));
-    });
-  }
-
-  protected post<T>(data: MessageTransferFormat<T>): void {
-    this.ws.send(JSON.stringify(data));
-  }
-
-  protected async exec(data: any): Promise<any> {
-    // 处理远端请求
-    return handleRequest(data);
-  }
-
-  // 暴露发送方法
-  public request<T>(data: T, timeout?: number) {
-    return this._send(data, timeout);
-  }
-}
-```
+Use the message packages for request/response messaging over WebSocket, process IPC, worker threads, file-system message handlers, service discovery, streaming RPC, and registry-backed pub/sub.
 
-### 第二步：发送请求
+## Install
 
-```typescript
-const modem = new WebSocketModem(ws);
-
-const { abort, response } = modem.request({ action: 'getUser', id: 1 });
-
-// 等待响应
-const user = await response();
-console.log(user);
-
-// 或中止请求
-abort();
+```bash
+pnpm add @hile/message-modem
 ```
 
-### 第三步：处理超时与异常
+## Copy-Paste Example
 
-所有异常类均从主入口导出，无需单独引入：
+Message handler file:
 
-```typescript
-import { AbortException, Exception } from '@hile/message-modem';
+```ts
+// src/messages/ping.msg.ts
+import { defineMessage } from '@hile/message-loader'
 
-try {
-  // 5 秒超时
-  const result = await modem.request(data, 5000).response();
-} catch (e) {
-  if (e instanceof AbortException) {
-    console.log('请求超时或被中止');
-  } else if (e instanceof Exception) {
-    console.log(`远端错误 [${e.status}]: ${e.message}`);
+export default defineMessage(async ({ data, params }) => {
+  return {
+    type: 'pong',
+    data,
+    params,
+    timestamp: Date.now(),
   }
-}
-```
-
-## API
-
-### `MessageModem`（抽象类）
-
-| 方法 | 可见性 | 说明 |
-|------|--------|------|
-| `post(data)` | `protected abstract` | 子类实现：如何将消息发送到远端 |
-| `exec(data)` | `protected abstract` | 子类实现：如何处理收到的请求，返回 Promise |
-| `_send(data, opts?)` | `protected` | 发送双向请求（`twoway: true`），返回 `{ abort, response }` |
-| `_push(data, opts?)` | `protected` | 发送单向推送（`twoway: false`），无返回值，接收方不回复 RESPONSE |
-| `_stream(data, opts?)` | `protected` | 发送流式请求，返回 `Readable` stream。对端 `exec()` 须返回 async generator |
-| `receive(msg)` | `public` | 接收消息入口，根据 mode 分发处理 |
-
-### `_send` 返回值
-
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `abort` | `() => void` | 中止本次请求 |
-| `response` | `<U>() => Promise<U>` | 等待远端响应 |
-
-### 消息类型
-
-| 枚举值 | 说明 |
-|--------|------|
-| `MESSAGE_MODEM_TYPE.REQUEST` | 请求消息 |
-| `MESSAGE_MODEM_TYPE.RESPONSE` | 响应消息 |
-| `MESSAGE_MODEM_TYPE.ABORT` | 中止消息 |
-
-### 异常类
-
-| 类 | status | 默认 message | 说明 |
-|------|--------|------|------|
-| `Exception` | 自定义 | 自定义 | 基础异常，携带 status |
-| `TimeoutException` | `ETIMEDOUT` | `Timeout` | 超时异常 |
-| `AbortException` | `ECONNABORTED` | `Abort` | 中止异常 |
-
-### 消息格式
-
-```typescript
-// 传输格式
-interface MessageTransferFormat<T = any> {
-  id: number;
-  mode: MESSAGE_MODEM_TYPE;
-  twoway: boolean;
-  stream?: boolean;      // true → 流式模式
-  data?: T;
-}
-
-// 响应数据格式
-interface MessageReturnFormat<T = any> {
-  status: string | number;
-  data: T;
-  message: string;
-}
-
-// 流式分块格式（stream=true 时 RESPONSE 携带）
-interface MessageStreamChunk<T = any> {
-  status: string | number;
-  seq: number;           // 块序号，从 0 递增
-  payload: T;            // 块数据
-  final: boolean;        // true → 最后一块
-}
+})
 ```
 
-## 消息流转
-
-### 双向模式（`_send`）
-
-```
-发送方                        接收方
-  │                             │
-  │  _send(data)                │
-  │──── REQUEST (twoway) ──────►│
-  │                             │ exec(data)
-  │                             │
-  │◄──── RESPONSE ──────────────│
-  │  resolve(data)              │
-  │                             │
-  │  abort()                    │
-  │──── ABORT ─────────────────►│
-  │                             │ 取消 exec
+Microservice boot file:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('micro.app', async (shutdown) => {
+  const app = new Application({
+    namespace: process.env.MICRO_NAMESPACE ?? 'example.service',
+    registry: {
+      host: process.env.REGISTRY_HOST ?? '127.0.0.1',
+      port: Number(process.env.REGISTRY_PORT ?? 9876),
+    },
+    advertiseHost: process.env.HILE_ADVERTISE_HOST ?? '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(Number(process.env.MICRO_PORT ?? 0))
+  shutdown(stop)
+  return app
+})
 ```
 
-### 单向模式（`_push`）
+Caller:
 
-```
-发送方                        接收方
-  │                             │
-  │  _push(data)                │
-  │──── REQUEST (!twoway) ─────►│
-  │                             │ exec(data)
-  │                             │ （不回复 RESPONSE）
+```ts
+const result = await app.call('example.service', '/ping', { hello: 'world' })
 ```
 
-### 流式模式（`_stream`）
-
-```
-发送方                        接收方
-  │                             │
-  │  _stream(data)              │
-  │──── REQUEST (stream) ──────►│
-  │                             │ exec(data) → async generator
-  │                             │
-  │◄─── RESPONSE (seq:0) ───────│ for await (chunk of gen)
-  │◄─── RESPONSE (seq:1) ───────│
-  │◄─── RESPONSE (seq:2) ───────│
-  │  ...                        │
-  │◄─── RESPONSE (final) ───────│ 迭代结束
-  │                             │
-  │  abort()                    │
-  │──── ABORT ─────────────────►│ 取消迭代
-```
+## Boundaries
 
-对端 `exec()` 返回 `AsyncIterable` 时，`MessageModem` 自动检测并进入分块传输模式。发送方通过 `for await` 消费 `Readable` stream。
+- Do not use `stream()` for normal single-result calls.
+- Do not rely on message IDs for business idempotency. They are transport IDs.
+- Do not bypass `defineMessage()` for file-loaded handlers.
 
-**何时用**：大数据集、实时事件流、LLM token 输出、进度上报等需要持续推送的场景。
-**何时不用**：单次请求/响应 —— 用 `_send()` 即可，无需 `_stream()`。
+- Appending a secondary response getter to `client.request('/x', data)`
+- Returning a plain object from a handler called through `stream()`.
+- Using pub/sub as a durable queue.
+- Forgetting to register `shutdown(await app.listen(...))`.
 
-## 适用场景
+## Verify
 
-- **iframe 通信** — 父子页面 postMessage
-- **WebSocket** — 客户端与服务端双向通信
-- **Web Worker** — 主线程与 Worker 通信
-- **Electron IPC** — 主进程与渲染进程通信
-- **Node.js child_process** — 父子进程通信
+- Message files default-export `defineMessage(...)`.
+- RPC callers use `await app.call(...)`.
+- Streaming handlers are async generators.
+- Registry is started before application nodes need discovery.
+- Micro apps use stable namespaces and advertise reachable hosts.
 
-## License
+## More Context
 
-MIT
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/dist/index.d.ts

@@ -3,13 +3,15 @@ export * from './exception.js';
 export declare enum MESSAGE_MODEM_TYPE {
     REQUEST = 0,
     RESPONSE = 1,
-    ABORT = 2
+    ABORT = 2,
+    STREAM_CREDIT = 3
 }
 export interface MessageTransferFormat<T = any> {
     id: number;
     mode: MESSAGE_MODEM_TYPE;
     twoway: boolean;
     stream?: boolean;
+    streamVersion?: 1;
     data?: T;
 }
 export interface MessageReturnFormat<T = any> {
@@ -28,6 +30,7 @@ export declare abstract class MessageModem {
     private readonly aborts;
     private readonly stacks;
     private readonly streams;
+    private readonly streamProducers;
     protected _dispose(): void;
     /**
      * 创建自增 ID

package/dist/index.js

@@ -6,12 +6,30 @@ export var MESSAGE_MODEM_TYPE;
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["REQUEST"] = 0] = "REQUEST";
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["RESPONSE"] = 1] = "RESPONSE";
     MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["ABORT"] = 2] = "ABORT";
+    MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["STREAM_CREDIT"] = 3] = "STREAM_CREDIT";
 })(MESSAGE_MODEM_TYPE || (MESSAGE_MODEM_TYPE = {}));
+class CreditReadable extends Readable {
+    onConsumed;
+    constructor(onConsumed) {
+        super({ objectMode: true });
+        this.onConsumed = onConsumed;
+    }
+    _read() {
+        // Credits are tied to actual read() results, not Node's eager buffer filling.
+    }
+    read(size) {
+        const chunk = super.read(size);
+        if (chunk !== null)
+            this.onConsumed();
+        return chunk;
+    }
+}
 export class MessageModem {
     id = 0;
     aborts = new Map();
     stacks = new Map();
     streams = new Map();
+    streamProducers = new Map();
     _dispose() {
         for (const { reject } of this.stacks.values()) {
             reject(new AbortException());
@@ -19,12 +37,16 @@ export class MessageModem {
         for (const controller of this.aborts.values()) {
             controller.abort();
         }
-        for (const stream of this.streams.values()) {
+        for (const { stream } of this.streams.values()) {
             stream.destroy(new AbortException());
         }
+        for (const producer of this.streamProducers.values()) {
+            producer.wake?.();
+        }
         this.aborts.clear();
         this.stacks.clear();
         this.streams.clear();
+        this.streamProducers.clear();
     }
     /**
      * 创建自增 ID
@@ -85,23 +107,64 @@ export class MessageModem {
     }
     _stream(data, options) {
         const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, true, true);
-        const stream = new Readable({ objectMode: true, read() { } });
-        this.streams.set(state.id, stream);
-        this.post(state);
+        state.streamVersion = 1;
+        let consumer;
+        const stream = new CreditReadable(() => {
+            if (!consumer.creditOwed || consumer.completed || consumer.cancelled)
+                return;
+            consumer.creditOwed = false;
+            try {
+                this.post(this.createPostData(MESSAGE_MODEM_TYPE.STREAM_CREDIT, { id: state.id, seq: consumer.nextSeq - 1 }, false));
+            }
+            catch (error) {
+                consumer.cancelled = true;
+                stream.destroy(error);
+            }
+        });
+        consumer = {
+            stream,
+            completed: false,
+            cancelled: false,
+            creditOwed: false,
+            nextSeq: 0,
+        };
+        const sendAbort = () => {
+            if (consumer.completed || consumer.cancelled)
+                return;
+            consumer.cancelled = true;
+            try {
+                this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+            }
+            catch {
+                // The transport may already be closed.
+            }
+        };
         const onAbort = () => {
-            this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+            sendAbort();
             stream.destroy(new AbortException());
-            this.streams.delete(state.id);
         };
-        if (options?.signal) {
-            options.signal.addEventListener('abort', onAbort);
+        if (options?.signal?.aborted) {
+            consumer.cancelled = true;
+            queueMicrotask(() => stream.destroy(new AbortException()));
+            return stream;
         }
+        this.streams.set(state.id, consumer);
+        options?.signal?.addEventListener('abort', onAbort, { once: true });
         stream.on('close', () => {
+            sendAbort();
             if (this.streams.has(state.id)) {
                 this.streams.delete(state.id);
             }
             options?.signal?.removeEventListener('abort', onAbort);
         });
+        try {
+            this.post(state);
+        }
+        catch (error) {
+            consumer.cancelled = true;
+            this.streams.delete(state.id);
+            queueMicrotask(() => stream.destroy(error));
+        }
         return stream;
     }
     /**
@@ -116,26 +179,32 @@ export class MessageModem {
         const signal = options?.signal;
         // 创建请求消息数据
         const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, twoway);
-        // 发送消息
-        this.post(state);
         // 如果消息是单向的，则直接返回
-        if (!twoway)
+        if (!twoway) {
+            if (!signal?.aborted)
+                this.post(state);
             return;
+        }
         return new Promise((resolve, reject) => {
+            let timer;
+            let posted = false;
             const clear = () => {
                 if (this.stacks.has(state.id)) {
                     this.stacks.delete(state.id);
                 }
             };
             const clean = () => {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 signal?.removeEventListener('abort', onAbort);
                 clear();
             };
             const onAbort = () => {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
                 try {
-                    this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+                    if (posted)
+                        this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
                 }
                 catch {
                     /* 例如 WebSocket 已关闭时 send 可能抛错 */
@@ -156,12 +225,23 @@ export class MessageModem {
                 clean();
                 reject(e);
             };
-            const timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
-            signal?.addEventListener('abort', onAbort);
             this.stacks.set(state.id, {
                 resolve: _resolve,
                 reject: _reject,
             });
+            timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            try {
+                posted = true;
+                this.post(state);
+            }
+            catch (error) {
+                _reject(error);
+            }
         });
     }
     /**
@@ -238,30 +318,76 @@ export class MessageModem {
         }
     }
     onStreamRequest(msg) {
+        if (msg.streamVersion !== 1) {
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                streamVersion: 1,
+                data: { status: 400, seq: 0, payload: 'Unsupported stream protocol', final: true },
+                twoway: false,
+            });
+            return;
+        }
+        if (this.streamProducers.has(msg.id) || this.streamProducers.size >= 128) {
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                streamVersion: 1,
+                data: { status: 429, seq: 0, payload: 'Stream capacity exceeded', final: true },
+                twoway: false,
+            });
+            return;
+        }
         const controller = new AbortController();
+        const producer = {
+            credits: 1,
+            nextCreditSeq: 0,
+        };
+        let sequence = 0;
         this.aborts.set(msg.id, controller);
+        this.streamProducers.set(msg.id, producer);
         controller.signal.addEventListener('abort', () => {
+            producer.wake?.();
             if (this.aborts.has(msg.id)) {
                 this.aborts.delete(msg.id);
             }
         });
+        const takeCredit = async () => {
+            while (producer.credits === 0 && !controller.signal.aborted) {
+                await new Promise((resolve) => {
+                    producer.wake = resolve;
+                });
+                producer.wake = undefined;
+            }
+            if (controller.signal.aborted)
+                throw new AbortException();
+            producer.credits--;
+        };
         this.exec(msg.data, controller.signal)
             .then(async (value) => {
             if (!isAsyncIterable(value)) {
                 throw new Exception(500, 'Invalid async iterable');
             }
-            let i = 0;
-            for await (const chunk of value) {
+            const iterator = value[Symbol.asyncIterator]();
+            producer.iterator = iterator;
+            while (!controller.signal.aborted) {
+                await takeCredit();
+                const next = await iterator.next();
                 if (controller.signal.aborted)
                     return;
+                if (next.done)
+                    break;
                 this.post({
                     id: msg.id,
                     mode: MESSAGE_MODEM_TYPE.RESPONSE,
                     stream: true,
+                    streamVersion: msg.streamVersion,
                     data: {
                         status: 200,
-                        seq: i++,
-                        payload: chunk,
+                        seq: sequence++,
+                        payload: next.value,
                         final: false,
                     },
                     twoway: false,
@@ -273,9 +399,10 @@ export class MessageModem {
                 id: msg.id,
                 mode: MESSAGE_MODEM_TYPE.RESPONSE,
                 stream: true,
+                streamVersion: msg.streamVersion,
                 data: {
                     status: 200,
-                    seq: i++,
+                    seq: sequence++,
                     payload: undefined,
                     final: true,
                 },
@@ -289,16 +416,22 @@ export class MessageModem {
                 id: msg.id,
                 mode: MESSAGE_MODEM_TYPE.RESPONSE,
                 stream: true,
+                streamVersion: msg.streamVersion,
                 data: {
                     status: e instanceof Exception ? e.status : 500,
-                    seq: 0,
-                    payload: e instanceof Exception ? e.message : 'Unknown error',
+                    seq: sequence,
+                    payload: e instanceof Error ? e.message : 'Unknown error',
                     final: true,
                 },
                 twoway: false,
             });
         })
             .finally(() => {
+            if (controller.signal.aborted && producer.iterator?.return) {
+                void Promise.resolve(producer.iterator.return()).catch(() => { });
+            }
+            producer.wake?.();
+            this.streamProducers.delete(msg.id);
             if (this.aborts.has(msg.id)) {
                 this.aborts.delete(msg.id);
             }
@@ -309,22 +442,32 @@ export class MessageModem {
         const res = msg.data;
         // 如果栈中存在该消息，则处理响应消息
         if (this.streams.has(id)) {
-            const stream = this.streams.get(id);
+            const consumer = this.streams.get(id);
+            const stream = consumer.stream;
             if (res) {
+                if (!Number.isSafeInteger(res.seq) || res.seq !== consumer.nextSeq) {
+                    stream.destroy(new Exception(409, `Invalid stream sequence: expected ${consumer.nextSeq}, received ${String(res.seq)}`));
+                    return;
+                }
+                consumer.nextSeq++;
                 if (res.status === 200) {
                     if (res.final) {
+                        consumer.completed = true;
                         stream.push(null);
                     }
                     else {
+                        consumer.creditOwed = true;
                         stream.push(res.payload);
                     }
                 }
                 else {
+                    consumer.completed = true;
                     const err = new Exception(res.status, res.payload);
                     setImmediate(() => stream.destroy(err));
                 }
             }
             else {
+                consumer.completed = true;
                 const err = new Exception(404, 'Empty chunk data');
                 setImmediate(() => stream.destroy(err));
             }
@@ -365,6 +508,22 @@ export class MessageModem {
                     }
                 }
                 break;
+            case MESSAGE_MODEM_TYPE.STREAM_CREDIT: {
+                const credit = msg.data;
+                if (!credit
+                    || !Number.isSafeInteger(credit.id)
+                    || credit.id < 0
+                    || !Number.isSafeInteger(credit.seq)
+                    || credit.seq < 0)
+                    break;
+                const producer = this.streamProducers.get(credit.id);
+                if (producer && producer.credits === 0 && credit.seq === producer.nextCreditSeq) {
+                    producer.credits = 1;
+                    producer.nextCreditSeq++;
+                    producer.wake?.();
+                }
+                break;
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "2.1.1",
+  "version": "4.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -11,15 +11,16 @@
   "files": [
     "dist",
     "README.md",
-    "SKILL.md"
+    "AI.md"
   ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.2.0",
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "7903ae989bd001d1ed1437cb90c9e828a1909061"
+  "gitHead": "b46cb7f3705a226f58e4d65a2ff985ea54b9a159"
 }