@omni-api/core 0.0.1

package/dist/registry-ZWfxJhSP.d.ts

@@ -0,0 +1,263 @@
+import { ZodTypeAny, z } from 'zod';
+
+/**
+ * 用户主体（Principal）
+ *
+ * 由各 Adapter 的鉴权中间件填充到 Context.user。
+ * 业务层只需要相信这个字段为 true，无需关心鉴权方式。
+ */
+interface UserPrincipal {
+    /** 全局唯一用户 ID */
+    id: string;
+    /** 角色，自由字符串数组（如 ['admin','op']） */
+    roles?: string[];
+    /** 其他自定义字段 */
+    [key: string]: unknown;
+}
+/** 极简 Logger 接口，避免强绑定具体库；插件可注入 pino/winston 适配 */
+interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * 调用来源标识
+ *
+ * - http: 来自 HTTP Adapter
+ * - mcp:  来自 MCP Adapter
+ * - test: 单元测试中的直接调用
+ */
+type ContextSource = 'http' | 'mcp' | 'test' | (string & {});
+/**
+ * 请求级上下文。
+ *
+ * 中间件链 / handler 都拿到同一个 Context 实例。
+ * raw 字段是 Adapter 的私有数据（如 Fastify request/reply），业务原则上不应直接使用。
+ */
+interface Context {
+    /** 调用来源 */
+    source: ContextSource;
+    /** 请求级唯一 ID */
+    requestId: string;
+    /** 用户身份（鉴权后填充） */
+    user?: UserPrincipal;
+    /** 请求级 logger */
+    logger: Logger;
+    /** 中间件之间传值的临时槽位 */
+    state: Record<string, unknown>;
+    /** 取消信号 */
+    signal: AbortSignal;
+    /** Adapter 私有上下文，类型由各 Adapter 自行声明合并 */
+    raw?: unknown;
+    /**
+     * 当前正在执行的 procedure 引用（由 runProcedure 在执行前注入）。
+     * 中间件可据此区分场景，例如限流按 procedure name 隔离。
+     * 调用方一般不需要主动传，runProcedure 会负责设置。
+     */
+    procedure?: {
+        readonly name: string;
+    };
+}
+/** 控制台 Logger，作为默认 / 测试用 fallback */
+declare const consoleLogger: Logger;
+/**
+ * 创建一个测试 / Adapter 默认用的 Context。
+ *
+ * 各 Adapter 一般会基于此函数再补充自己的 raw 字段。
+ */
+declare function createContext(partial: Partial<Context> & {
+    source: ContextSource;
+}): Context;
+
+/**
+ * 中间件函数签名（类 Koa onion 模型）
+ *
+ * - 必须 await next() 才能让后续中间件 / handler 执行
+ * - 可在 next() 前后做任何事（鉴权、计时、错误转换…）
+ * - 抛出的错误会被 runProcedure 捕获并规范化
+ */
+type Middleware<C extends Context = Context> = (ctx: C, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * 把多个中间件合并为单个执行函数。
+ *
+ * 调用 `compose(mws)(ctx, finalHandler)` 会按 mws 顺序进入、反向退出，
+ * 最终调用 finalHandler 并返回其结果。
+ *
+ * 实现要点：
+ *   1. 每个中间件 next 只能调用一次（防止重复 await）
+ *   2. finalHandler 的返回值会原样向上传递
+ */
+declare function compose<C extends Context>(middlewares: ReadonlyArray<Middleware<C>>): (ctx: C, finalHandler: () => Promise<unknown>) => Promise<unknown>;
+
+/**
+ * Procedure 元信息 —— 仅声明真实出口（HTTP / MCP）。
+ *
+ * 各 Adapter 只读自己关心的那块；插件可通过自定义 key 扩展。
+ */
+interface ProcedureMeta {
+    /** HTTP 出口配置；不写则用默认约定（按 name 派生路径，按动词推断 method） */
+    http?: {
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        /** 默认 /<namespace>/<action>，如 order.create → /order/create */
+        path?: string;
+        /** 成功状态码，默认 200 */
+        status?: number;
+        /** 是否暴露到 HTTP，默认 true */
+        expose?: boolean;
+    };
+    /** MCP 出口配置 */
+    mcp?: {
+        /** 是否暴露到 MCP，默认 true */
+        expose?: boolean;
+        /** 在 MCP Client 中的分组（如 commerce / admin） */
+        category?: string;
+        /** 是否在执行前要求 MCP Host 用户确认（destructive 操作建议 true） */
+        requireConfirmation?: boolean;
+        /** 危险等级：拼接进 description 头部，帮助 LLM 谨慎使用 */
+        dangerLevel?: 'read' | 'write' | 'destructive';
+        /** 给 LLM 的额外示例，会拼接进 description */
+        examples?: ReadonlyArray<{
+            input: unknown;
+            when: string;
+            output?: unknown;
+        }>;
+        /** 别名：拼接进 description，提升 LLM 召回 */
+        aliases?: ReadonlyArray<string>;
+    };
+    /** 插件自由扩展用的自定义元信息 */
+    [key: string]: unknown;
+}
+/** Procedure 定义（用户传给 defineProcedure 的形态） */
+interface ProcedureDef<Input extends ZodTypeAny, Output extends ZodTypeAny, C extends Context = Context> {
+    /** 全局唯一名，建议 namespace.action 格式：order.create */
+    name: string;
+    /** 单行简述（用于列表 / table） */
+    summary?: string;
+    /** 详细描述：作为 OpenAPI / MCP description 的主体 */
+    description: string;
+    /** 输入 schema */
+    input: Input;
+    /** 输出 schema */
+    output: Output;
+    /** 多端元信息 */
+    meta?: ProcedureMeta;
+    /** 中间件链（按声明顺序进入、反向退出） */
+    middleware?: ReadonlyArray<Middleware<C>>;
+    /** 业务逻辑 */
+    handler: (params: {
+        input: z.infer<Input>;
+        ctx: C;
+    }) => Promise<z.infer<Output>> | z.infer<Output>;
+    /** 标签，用于分组、按需暴露 */
+    tags?: ReadonlyArray<string>;
+}
+/** 冻结后的 Procedure 实例 */
+interface Procedure<Input extends ZodTypeAny = ZodTypeAny, Output extends ZodTypeAny = ZodTypeAny, C extends Context = Context> extends Required<Pick<ProcedureDef<Input, Output, C>, 'name' | 'description' | 'input' | 'output' | 'handler'>> {
+    readonly summary?: string;
+    readonly meta: Readonly<ProcedureMeta>;
+    readonly middleware: ReadonlyArray<Middleware<C>>;
+    readonly tags: ReadonlyArray<string>;
+}
+/**
+ * 定义一个 Procedure。
+ *
+ * 工厂的价值：
+ *   1. 类型推导起点：I/O 由 input/output 自动推出，业务无需手写泛型
+ *   2. 声明期校验：name 合法性、必要字段
+ *   3. 不可变保证：返回 frozen 对象，防止运行时被改写
+ */
+declare function defineProcedure<Input extends ZodTypeAny, Output extends ZodTypeAny, C extends Context = Context>(def: ProcedureDef<Input, Output, C>): Procedure<Input, Output, C>;
+/** 取 Procedure 的 namespace（"order.create" → "order"；无点则返回整个 name） */
+declare function getNamespace(p: Pick<Procedure, 'name'>): string;
+
+/**
+ * 任意 Procedure（输入输出类型不限）。
+ *
+ * 用 `Procedure<any, any>` 而非 `Procedure<ZodTypeAny, ZodTypeAny>` 来获得协变行为，
+ * 让具体 procedure（带窄 schema 类型）能被赋值到 router.procedures 数组里。
+ */
+type AnyProcedure = Procedure<any, any>;
+/**
+ * Router：Procedure 的批量组合 + 共享 middleware 的语法糖。
+ *
+ * 不引入新的运行时概念 —— Registry 注册时会把 Router 拍平为 Procedure 列表，
+ * 并把 router.middleware 前置到每个 procedure.middleware 之前。
+ */
+interface Router<C extends Context = Context> {
+    /** 命名空间（可选） */
+    readonly namespace?: string;
+    /** 该组下所有 procedure 共享的中间件 */
+    readonly middleware: ReadonlyArray<Middleware<C>>;
+    /** 组内的 procedure 列表 */
+    readonly procedures: ReadonlyArray<AnyProcedure>;
+}
+interface RouterDef<C extends Context = Context> {
+    namespace?: string;
+    middleware?: ReadonlyArray<Middleware<C>>;
+    procedures: ReadonlyArray<AnyProcedure>;
+}
+declare function createRouter<C extends Context = Context>(def: RouterDef<C>): Router<C>;
+
+/** Adapter 名称的常量集合（也允许字符串扩展） */
+type AdapterName = 'http' | 'mcp' | (string & {});
+interface ListFilter {
+    /** 按 namespace 精确过滤 */
+    namespace?: string;
+    /** 必须包含所有给定 tag */
+    tags?: ReadonlyArray<string>;
+}
+interface RegistryOptions {
+    /**
+     * 全局前置中间件 —— 在每个 procedure 的 router.middleware + procedure.middleware 之前。
+     *
+     * 典型用途：attachDataSource / observability.middleware / 全局 audit。
+     *
+     * 顺序：全局 → router → procedure
+     */
+    globalMiddleware?: ReadonlyArray<Middleware<Context>>;
+}
+/**
+ * 全局注册中心：所有 Adapter 共享的单一事实源。
+ *
+ * 职责：
+ *   - 收集 Procedure / Router
+ *   - 校验 name 唯一性
+ *   - 按 Adapter 维度（meta.<adapter>.expose）过滤可暴露集合
+ *   - 提供基于 namespace / tag 的查询
+ *   - 维护"全局 → router → procedure"的中间件叠加
+ */
+declare class Registry {
+    private readonly entries;
+    private readonly globalMiddleware;
+    constructor(options?: RegistryOptions);
+    /** 注册单个 Procedure */
+    register(procedure: AnyProcedure): void;
+    /** 注册一个 Router，会把 router.middleware 前置合并到每个 procedure */
+    registerRouter(router: Router): void;
+    /** 按 name 查找 */
+    get(name: string): AnyProcedure | undefined;
+    /** 取某个 procedure 的最终中间件链（router 共享 + procedure 自有） */
+    getMiddleware(name: string): ReadonlyArray<Middleware<Context>>;
+    /** 是否存在 */
+    has(name: string): boolean;
+    /** 总数 */
+    get size(): number;
+    /** 列出全部（可选过滤） */
+    list(filter?: ListFilter): AnyProcedure[];
+    /**
+     * 列出某个 Adapter 应该暴露的 Procedure。
+     *
+     * 规则：
+     *   - meta[adapter].expose === false → 排除
+     *   - 否则 → 包含（默认暴露）
+     *
+     * 注：CLI 等"白名单式"出口可由该 adapter 自己再过滤一遍。
+     */
+    listFor(adapter: AdapterName): AnyProcedure[];
+    /** 清空（测试用） */
+    clear(): void;
+}
+
+export { type AdapterName as A, type Context as C, type ListFilter as L, type Middleware as M, type Procedure as P, Registry as R, type UserPrincipal as U, type AnyProcedure as a, type ContextSource as b, type Logger as c, type ProcedureDef as d, type ProcedureMeta as e, type RegistryOptions as f, type Router as g, type RouterDef as h, compose as i, consoleLogger as j, createContext as k, createRouter as l, defineProcedure as m, getNamespace as n };

package/dist/utils/index.d.ts

@@ -0,0 +1,171 @@
+import { ZodTypeAny, ZodType } from 'zod';
+import { P as Procedure, R as Registry, C as Context } from '../registry-ZWfxJhSP.js';
+
+/**
+ * 把 Zod schema 转 JSON Schema（draft-07 风格，OpenAPI/MCP/LLM 通用）。
+ *
+ * 这里做一层薄封装，统一选项，并去掉 zod-to-json-schema 默认加上的 `$schema` 字段
+ * （MCP / OpenAI tool 格式都不需要也不允许该字段）。
+ */
+declare function zodToJsonSchema(schema: ZodTypeAny): Record<string, unknown>;
+
+/** OpenAI Function Calling 工具格式 */
+interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** Anthropic（Claude）Tool Use 格式 */
+interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+/** 通用格式（直接是 input schema + 名称描述） */
+interface GenericTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+type ToolFormat = 'openai' | 'anthropic' | 'generic';
+interface ExportToolsOptions {
+    /** 输出格式，默认 'openai' */
+    format?: ToolFormat;
+    /**
+     * 名字转换函数。
+     *
+     * - openai: 默认把 "." 替换为 "_"（OpenAI tool name 不允许 "."）
+     * - anthropic / generic: 默认保留原名
+     */
+    renameTool?: (name: string) => string;
+    /** 自定义过滤；默认导出所有 procedure */
+    filter?: (p: Procedure) => boolean;
+}
+/**
+ * 把 Registry 中的 Procedure 导出为给 LLM 的工具数组。
+ *
+ * 这是为了"老平台兼容 / 调试"而存在的逃生出口；推荐场景仍是直接走 MCP。
+ */
+declare function exportToolsJSON(registry: Registry, options: ExportToolsOptions & {
+    format: 'openai';
+}): OpenAITool[];
+declare function exportToolsJSON(registry: Registry, options: ExportToolsOptions & {
+    format: 'anthropic';
+}): AnthropicTool[];
+declare function exportToolsJSON(registry: Registry, options?: ExportToolsOptions & {
+    format?: 'generic';
+}): GenericTool[];
+
+/**
+ * Graceful shutdown helper —— 跨 adapter / plugin 的优雅停机协调器。
+ *
+ * 设计原则：
+ *   1. 顺序停机：先停接收（adapters），再停依赖（dataSource / cache / observability）
+ *   2. 超时强杀：每个 hook 有独立超时，整体也有超时；防止挂死
+ *   3. 幂等：重复信号只触发一次（防止 double-shutdown 撞死）
+ *   4. 信号统一：SIGTERM / SIGINT / 可选 uncaughtException
+ *
+ * 用法：
+ *   ```ts
+ *   const g = createGracefulShutdown({ logger });
+ *   g.add('http', () => httpAdapter.close(), 10_000);
+ *   g.add('db',   () => dataSource.disconnect(), 5_000);
+ *   g.add('logs', () => logger.flush?.(), 2_000);
+ *   g.listen();   // 注册 SIGTERM/SIGINT
+ *   ```
+ */
+interface ShutdownHook {
+    /** 名字，仅用于日志 */
+    name: string;
+    /** 关闭函数 */
+    fn: () => Promise<void> | void;
+    /** 该 hook 的超时（毫秒），默认 5000 */
+    timeoutMs?: number;
+}
+interface GracefulShutdownOptions {
+    /** 整体超时（毫秒），超过则强制 process.exit。默认 30s */
+    totalTimeoutMs?: number;
+    /** 日志记录器（任意 console-like 接口） */
+    logger?: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+        warn?(msg: string, meta?: Record<string, unknown>): void;
+    };
+    /** 是否处理 uncaughtException / unhandledRejection（默认 true） */
+    handleFatalErrors?: boolean;
+    /** 退出函数（默认 process.exit）；测试时可注入 */
+    exit?: (code: number) => void;
+    /** 信号注入点（默认监听 process）；测试时可传自定义 emitter */
+    on?: (signal: 'SIGTERM' | 'SIGINT', handler: () => void) => void;
+}
+interface GracefulShutdown {
+    /** 注册 shutdown hook，按注册顺序倒序执行（后注册的先关） */
+    add(name: string, fn: () => Promise<void> | void, timeoutMs?: number): void;
+    /** 开始监听信号 */
+    listen(): void;
+    /** 主动触发 shutdown（用于测试 / 业务自管） */
+    trigger(reason: string): Promise<void>;
+    /** 是否已经在 shutdown 中 */
+    readonly isShuttingDown: boolean;
+}
+declare function createGracefulShutdown(options?: GracefulShutdownOptions): GracefulShutdown;
+
+/**
+ * 启动期环境变量校验。
+ *
+ * 设计原则：
+ *   - 缺关键变量直接挂（fail-fast），比启动后第一个请求才报错好
+ *   - 错误信息友好（指出具体哪个变量错了）
+ *   - 类型化输出，业务用 `env.JWT_SECRET` 直接拿到 string
+ *
+ * 用法：
+ *   ```ts
+ *   import { z } from 'zod';
+ *   import { loadEnv } from '@omni-api/core/utils';
+ *
+ *   const Env = z.object({
+ *     PORT: z.coerce.number().default(3000),
+ *     JWT_SECRET: z.string().min(32, 'must be ≥ 32 chars'),
+ *     DATABASE_URL: z.string().url(),
+ *   });
+ *   export const env = loadEnv(Env);
+ *   ```
+ */
+declare function loadEnv<T>(schema: ZodType<T>, source?: Record<string, string | undefined>): T;
+
+/**
+ * createTracedFetch —— 带请求上下文的 fetch 包装。
+ *
+ * 自动注入：
+ *   - x-request-id：当前请求 ID（贯穿调用链）
+ *   - traceparent：W3C Trace Context（如果当前 ctx 有 / 或装了 OTel 能取到 active span）
+ *   - signal：当前请求的 AbortSignal（客户端断开 → 下游也取消）
+ *
+ * 业务用法：
+ *   const fetchx = createTracedFetch(ctx);
+ *   const res = await fetchx('https://internal-api/users/1');
+ *
+ * 设计：返回 fetch-compatible 函数，业务无需改动调用语义。
+ */
+
+interface TracedFetchOptions {
+    /** 自定义 fetch 实现（默认 globalThis.fetch） */
+    fetch?: typeof fetch;
+    /**
+     * 额外要透传的请求头键名，从 ctx.state 中按 key 取（小写）。
+     * 例如 ['x-tenant-id'] 会让租户 ID 自动透传到下游。
+     */
+    forwardStateKeys?: string[];
+}
+/**
+ * 创建一个绑定到当前 ctx 的 fetch。
+ *
+ * 注意：返回值是普通 fetch 函数，可以直接传给任何接受 fetch 的 SDK
+ * （比如 OpenAI SDK 的 `fetch` 选项）。
+ */
+declare function createTracedFetch(ctx: Context, options?: TracedFetchOptions): typeof fetch;
+
+export { type AnthropicTool, type ExportToolsOptions, type GenericTool, type GracefulShutdown, type GracefulShutdownOptions, type OpenAITool, type ShutdownHook, type ToolFormat, type TracedFetchOptions, createGracefulShutdown, createTracedFetch, exportToolsJSON, loadEnv, zodToJsonSchema };

package/dist/utils/index.js

@@ -0,0 +1,221 @@
+import { zodToJsonSchema as zodToJsonSchema$1 } from 'zod-to-json-schema';
+
+// src/utils/zod-to-json-schema.ts
+function zodToJsonSchema(schema) {
+  const raw = zodToJsonSchema$1(schema, {
+    target: "jsonSchema7",
+    $refStrategy: "none"
+    // 内联，避免下游处理 $ref
+  });
+  const { $schema, ...rest } = raw;
+  return rest;
+}
+
+// src/utils/export-tools.ts
+function buildAgentDescription(p) {
+  const mcpMeta = p.meta.mcp;
+  const lines = [];
+  if (mcpMeta?.dangerLevel === "destructive") {
+    lines.push("[DESTRUCTIVE] \u6B64\u64CD\u4F5C\u4F1A\u9020\u6210\u4E0D\u53EF\u9006\u540E\u679C\uFF0C\u8C03\u7528\u524D\u52A1\u5FC5\u4E0E\u7528\u6237\u786E\u8BA4\u3002");
+  } else if (mcpMeta?.dangerLevel === "write") {
+    lines.push("[WRITE] \u6B64\u64CD\u4F5C\u4F1A\u4FEE\u6539\u6570\u636E\u3002");
+  }
+  lines.push(p.description.trim());
+  if (mcpMeta?.aliases && mcpMeta.aliases.length > 0) {
+    lines.push(`\u522B\u540D: ${mcpMeta.aliases.join(", ")}`);
+  }
+  if (mcpMeta?.examples && mcpMeta.examples.length > 0) {
+    lines.push("\u793A\u4F8B:");
+    for (const ex of mcpMeta.examples) {
+      const inputStr = JSON.stringify(ex.input);
+      lines.push(`  - \u5F53 ${ex.when}: ${inputStr}`);
+    }
+  }
+  return lines.join("\n");
+}
+function exportToolsJSON(registry, options = {}) {
+  const format = options.format ?? "generic";
+  const procedures = registry.list().filter((p) => options.filter ? options.filter(p) : true);
+  const defaultRename = (name) => format === "openai" ? name.replace(/\./g, "_") : name;
+  const rename = options.renameTool ?? defaultRename;
+  return procedures.map((p) => {
+    const description = buildAgentDescription(p);
+    const parameters = zodToJsonSchema(p.input);
+    const name = rename(p.name);
+    if (format === "openai") {
+      const tool2 = {
+        type: "function",
+        function: { name, description, parameters }
+      };
+      return tool2;
+    }
+    if (format === "anthropic") {
+      const tool2 = { name, description, input_schema: parameters };
+      return tool2;
+    }
+    const tool = { name, description, parameters };
+    return tool;
+  });
+}
+
+// src/utils/graceful-shutdown.ts
+function withTimeout(p, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`Shutdown hook "${label}" timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    Promise.resolve(p).then(
+      (v) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function createGracefulShutdown(options = {}) {
+  const totalTimeoutMs = options.totalTimeoutMs ?? 3e4;
+  const logger = options.logger ?? console;
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const on = options.on ?? ((signal, handler) => {
+    process.on(signal, handler);
+  });
+  const hooks = [];
+  let shuttingDown = false;
+  let shutdownPromise;
+  async function runShutdown(reason, exitCode = 0) {
+    if (shutdownPromise) return shutdownPromise;
+    shuttingDown = true;
+    logger.info("shutdown.start", { reason, hooks: hooks.length });
+    shutdownPromise = (async () => {
+      const startedAt = Date.now();
+      const killTimer = setTimeout(() => {
+        logger.error("shutdown.timeout_force_exit", { totalTimeoutMs });
+        exit(exitCode || 1);
+      }, totalTimeoutMs);
+      const ordered = [...hooks].reverse();
+      for (const h of ordered) {
+        const t = h.timeoutMs ?? 5e3;
+        try {
+          await withTimeout(h.fn(), t, h.name);
+          logger.info("shutdown.hook.ok", { name: h.name });
+        } catch (err) {
+          logger.error("shutdown.hook.fail", {
+            name: h.name,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
+      clearTimeout(killTimer);
+      logger.info("shutdown.complete", { durationMs: Date.now() - startedAt });
+      exit(exitCode);
+    })();
+    return shutdownPromise;
+  }
+  if (options.handleFatalErrors !== false) {
+    process.on("uncaughtException", (err) => {
+      logger.error("uncaughtException", { error: err.message, stack: err.stack });
+      void runShutdown("uncaughtException", 1);
+    });
+    process.on("unhandledRejection", (reason) => {
+      logger.error("unhandledRejection", {
+        reason: reason instanceof Error ? reason.message : String(reason)
+      });
+      void runShutdown("unhandledRejection", 1);
+    });
+  }
+  return {
+    add(name, fn, timeoutMs) {
+      if (shuttingDown) {
+        logger.warn?.("shutdown.add_after_start_ignored", { name });
+        return;
+      }
+      hooks.push({ name, fn, timeoutMs });
+    },
+    listen() {
+      on("SIGTERM", () => void runShutdown("SIGTERM"));
+      on("SIGINT", () => void runShutdown("SIGINT"));
+    },
+    trigger(reason) {
+      return runShutdown(reason);
+    },
+    get isShuttingDown() {
+      return shuttingDown;
+    }
+  };
+}
+
+// src/utils/load-env.ts
+function loadEnv(schema, source = process.env) {
+  const parsed = schema.safeParse(source);
+  if (parsed.success) return parsed.data;
+  const issues = parsed.error?.issues ?? [];
+  const lines = issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`);
+  const msg = `Invalid environment variables:
+${lines.join("\n")}`;
+  console.error(msg);
+  throw new Error(msg);
+}
+
+// src/utils/traced-fetch.ts
+function createTracedFetch(ctx, options = {}) {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  if (typeof baseFetch !== "function") {
+    throw new Error("createTracedFetch: globalThis.fetch is not available; provide options.fetch");
+  }
+  const forwardStateKeys = options.forwardStateKeys ?? [];
+  const tracedFetch = async (input, init) => {
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+    if (!headers.has("x-request-id")) {
+      headers.set("x-request-id", ctx.requestId);
+    }
+    const tp = pickTraceparent(ctx);
+    if (tp && !headers.has("traceparent")) {
+      headers.set("traceparent", tp);
+    }
+    for (const key of forwardStateKeys) {
+      const v = ctx.state[key];
+      if (typeof v === "string" && !headers.has(key)) {
+        headers.set(key, v);
+      }
+    }
+    const signal = init?.signal ?? ctx.signal;
+    return baseFetch(input, {
+      ...init,
+      headers,
+      signal
+    });
+  };
+  return tracedFetch;
+}
+function pickTraceparent(ctx) {
+  const fromState = ctx.state["traceparent"];
+  if (typeof fromState === "string") return fromState;
+  const otel = globalThis.__OMNI_OTEL_API__;
+  if (otel?.trace?.getActiveSpan) {
+    try {
+      const span = otel.trace.getActiveSpan();
+      const sc = span?.spanContext?.();
+      if (sc?.traceId && sc?.spanId) {
+        const flags = (sc.traceFlags ?? 0).toString(16).padStart(2, "0");
+        return `00-${sc.traceId}-${sc.spanId}-${flags}`;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+
+export { createGracefulShutdown, createTracedFetch, exportToolsJSON, loadEnv, zodToJsonSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map