@aalis/api-hooks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @aalis/api-hooks
+
+钩子契约：`hooks` 服务描述符、中间件签名 `MiddlewareFn` / `MiddlewareNext`、提供者契约 `HookRegistry` 与扩展点 `HookContextMap`。不含实现，默认提供者是 `@aalis/plugin-hooks`。
+
+## 角色
+
+- `hooks`：服务描述符。插件在 `uses` 里声明后得到绑定门面：`middleware(hook, fn)` 登记中间件，随本次激活撤回；`run(hook, data, defaultAction?, opts?)` 驱动一条链，返回 `false` 表示被截停。
+- `HookContextMap`：空接口，由各领域 `-api` 包经 declaration merging 注入「钩子名 → 中间件上下文」。
+- 没有提供者时 `run` 返回被拒的 Promise，不执行默认动作。
+
+## 顺序
+
+链内按登记顺序执行。登记序是每条登记自带的序号，提供者按它排链：以更高优先级换上另一个提供者时，各插件的登记整批重挂，链序不变。提供者重启时，依赖它的插件随之重启并重新登记，链序即重新激活的次序，与冷启动相同。相位内的 handler 应与顺序无关。
+
+自己实现提供者时，`register` 须按 `order` 升序插入。
+
+## 运行中换提供者的已知现状
+
+以更高优先级上线第二个钩子提供者，或在服务页切换 hooks 偏好时，有两种情形会让截停者暂时缺席：
+
+- 换人那一刻正在执行的链会跳过已移到新提供者的中间件。被跳过的若是截停者，默认动作照样执行。
+- 胜者在容器里同步换人，各插件的登记要逐个重挂到新提供者上。重挂完成前新发起的链，只能看到已经搬过来的中间件。
+
+两种情形都只发生在运行中换提供者的那一刻。第一方部署只有 `@aalis/plugin-hooks` 一个提供者，不会遇到。
+
+## 安装
+
+```bash
+pnpm add @aalis/api-hooks
+```
+
+## 使用
+
+```ts
+import { hooks } from '@aalis/api-hooks';
+
+// uses: { hooks }
+hooks.middleware('agent:llm:before', async (data, next) => {
+  // 改 data 后交棒；不调 next 即截停
+  await next();
+});
+```
+
+扩展钩子键：
+
+```ts
+declare module '@aalis/api-hooks' {
+  interface HookContextMap {
+    'schedule:before': { jobId: string };
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/** 钩子扩展点（空接口；由各 -api 包经 declaration merging 注入「钩子名 → 中间件上下文」） */
+export interface HookContextMap {
+}
+/** 中间件 next：把控制交给下一个中间件或默认动作 */
+export type MiddlewareNext = () => Promise<void>;
+/** 中间件：可改 data（引用传递），调 next() 继续，不调即截停（含默认动作） */
+export type MiddlewareFn<T> = (data: T, next: MiddlewareNext) => Promise<void>;
+/** `run` 的选项 */
+export interface RunOptions {
+    /** 广播型相位：某 handler 返回却没调 next() 时点名告警（其后的注入会被静默丢弃） */
+    warnOnStall?: boolean;
+}
+/**
+ * 提供者契约（钩子登记表本体）。插件不直接调用：登记经 {@link hooks} 的绑定门面，
+ * 它盖上本激活 id、随激活撤回。
+ */
+export interface HookRegistry {
+    /**
+     * 按 order 升序插入该钩子链。order 是门面在登记时分配的登记序（进程内全部 api-hooks 副本共用一个计数器，单调递增），换提供者重挂时原样带过来，
+     * 提供者据它还原原来的交错次序。contextId 供卡链告警点名。返回退订（幂等，只撤这一条）
+     */
+    register(hook: string, fn: MiddlewareFn<unknown>, contextId: string, order: number): () => void;
+    /** 驱动一条钩子链；true = 走到底（含执行了默认动作或本就没有 handler），false = 被截停 */
+    run(hook: string, data: unknown, defaultAction?: () => Promise<void>, opts?: RunOptions): Promise<boolean>;
+}
+/** `hooks` 的绑定接口 */
+export interface Hooks {
+    /** 注册中间件（洋葱模型，按登记顺序）；返回退订，随这次激活撤回 */
+    middleware<K extends string & keyof HookContextMap>(hook: K, fn: MiddlewareFn<HookContextMap[K]>): () => void;
+    /** 驱动一条钩子链；返回 false 表示被某个中间件截停 */
+    run<K extends string & keyof HookContextMap>(hook: K, data: HookContextMap[K], defaultAction?: () => Promise<void>, opts?: RunOptions): Promise<boolean>;
+}
+export declare const hooks: import("@aalis/core").ServiceDescriptor<HookRegistry, Hooks>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,iEAAiE;AACjE,MAAM,WAAW,cAAc;CAAG;AAElC,gCAAgC;AAChC,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjD,iDAAiD;AACjD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,gBAAgB;AAChB,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAChG,4DAA4D;IAC5D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5G;AAED,oBAAoB;AACpB,MAAM,WAAW,KAAK;IACpB,qCAAqC;IACrC,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC9G,kCAAkC;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EACzC,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAWD,eAAO,MAAM,KAAK,8DAYhB,CAAC"}

package/dist/index.js

@@ -0,0 +1,38 @@
+// ============================================================
+// @aalis/api-hooks — 钩子契约
+//
+// 每个钩子键代表一个语义清晰的生命周期事件（如 inbound:command / agent:llm:before），
+// handler 在事件内部按**登记顺序**串行执行洋葱模型（next 交棒）。不用数字 priority：
+// 相位之间的次序由调度方显式表达；相位内部的 handler 应顺序无关，或由相位拥有方约定。
+// 登记序是每条登记自带的序号，提供者按它排链：换提供者时各账本整批重挂，链序不变；
+// 提供者重启时依赖方随之重启、重新登记，链序即重新激活的次序（与冷启动相同）。
+// 默认提供者：@aalis/plugin-hooks。没有提供者时 run 返回被拒的 Promise（不执行默认动作）。
+//
+// 钩子键由各 -api 包经 declaration merging 注入 HookContextMap：
+//   declare module '@aalis/api-hooks' {
+//     interface HookContextMap { 'schedule:before': { jobId: string } }
+//   }
+// ============================================================
+import { defineService } from '@aalis/core';
+/**
+ * 登记序计数器：进程内全部 api-hooks 副本共用一个（经全局符号表取同一个对象），登记即取号。
+ * 契约包可能装了两份，各自从 0 计数的话序号不可比，提供者按序排链就会把后登记的排到前面。
+ */
+const ORDER = Symbol.for('@aalis/api-hooks.order');
+const shared = globalThis;
+shared[ORDER] ??= { n: 0 };
+const orderCounter = shared[ORDER];
+export const hooks = defineService('hooks', port => {
+    // 每次登记一个独立账目：同一激活可在同一钩子上挂多个 handler，没有「同键替换」。登记序全局唯一，
+    // 用作账本键不会撞；键带钩子名，关闭后登记的告警能点名
+    const ledger = port.registrar({
+        key: ({ hook, order }) => `${hook}#${order}`,
+        register: (registry, { hook, fn, order }) => registry.register(hook, fn, port.id, order),
+    });
+    return {
+        middleware: (hook, fn) => ledger.add({ hook, fn: fn, order: ++orderCounter.n }),
+        // async：没有提供者时以被拒的 Promise 传出，不在调用点同步抛（与提供者 run 的异步口径一致）
+        run: async (hook, data, defaultAction, opts) => port.require().run(hook, data, defaultAction, opts),
+    };
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,0BAA0B;AAC1B,EAAE;AACF,8DAA8D;AAC9D,yDAAyD;AACzD,iDAAiD;AACjD,2CAA2C;AAC3C,yCAAyC;AACzC,+DAA+D;AAC/D,EAAE;AACF,uDAAuD;AACvD,wCAAwC;AACxC,wEAAwE;AACxE,MAAM;AACN,+DAA+D;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA4C5C;;;GAGG;AACH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AACnD,MAAM,MAAM,GAAG,UAAuD,CAAC;AACvE,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC3B,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAEnC,MAAM,CAAC,MAAM,KAAK,GAAG,aAAa,CAAsB,OAAO,EAAE,IAAI,CAAC,EAAE;IACtE,sDAAsD;IACtD,6BAA6B;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAA6D;QACxF,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE;QAC5C,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC;KACzF,CAAC,CAAC;IACH,OAAO;QACL,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAA2B,EAAE,KAAK,EAAE,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QACxG,yDAAyD;QACzD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC;KACpG,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aalis/api-hooks",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AalisLabs/Aalis.git",
+    "directory": "packages/api-hooks"
+  },
+  "author": "Ace Nyan <ace@acenyan.com>",
+  "bugs": {
+    "url": "https://github.com/AalisLabs/Aalis/issues"
+  },
+  "homepage": "https://github.com/AalisLabs/Aalis#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "@aalis/core": "0.18.0"
+  },
+  "peerDependencies": {
+    "@aalis/core": ">=0.18.0 <1.0.0"
+  },
+  "keywords": [
+    "aalis",
+    "aalis-api"
+  ],
+  "description": "钩子契约：hooks 服务描述符、中间件签名与 HookContextMap 扩展点（默认提供者 @aalis/plugin-hooks）",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}