weacpx 0.3.1 → 0.4.0-beta.0

package/dist/config/types.d.ts

@@ -0,0 +1,64 @@
+export type PermissionMode = "approve-all" | "approve-reads" | "deny-all";
+export type NonInteractivePermissions = "deny" | "fail";
+export type ReplyMode = "stream" | "final" | "verbose";
+/** @deprecated Use ReplyMode. */
+export type WechatReplyMode = ReplyMode;
+export interface ChannelConfig {
+    type: string;
+    replyMode: ReplyMode;
+    options?: Record<string, unknown>;
+}
+/** @deprecated Legacy input shape only. Use ChannelConfig. */
+export interface WechatConfig {
+    replyMode: ReplyMode;
+}
+export interface TransportConfig {
+    type: "acpx-cli" | "acpx-bridge";
+    command?: string;
+    sessionInitTimeoutMs?: number;
+    permissionMode: PermissionMode;
+    nonInteractivePermissions: NonInteractivePermissions;
+}
+export type LoggingLevel = "error" | "info" | "debug";
+export interface LoggingConfig {
+    level: LoggingLevel;
+    maxSizeBytes: number;
+    maxFiles: number;
+    retentionDays: number;
+}
+export interface AgentConfig {
+    driver: string;
+    command?: string;
+}
+export interface WorkspaceConfig {
+    cwd: string;
+    description?: string;
+}
+export interface OrchestrationConfig {
+    maxPendingAgentRequestsPerCoordinator: number;
+    allowWorkerChainedRequests: boolean;
+    allowedAgentRequestTargets: string[];
+    allowedAgentRequestRoles: string[];
+    progressHeartbeatSeconds: number;
+}
+export interface ChannelRuntimeConfig {
+    id: string;
+    type: string;
+    enabled: boolean;
+    options?: Record<string, unknown>;
+}
+export interface PluginConfig {
+    name: string;
+    version?: string;
+    enabled: boolean;
+}
+export interface AppConfig {
+    transport: TransportConfig;
+    logging: LoggingConfig;
+    channel: ChannelConfig;
+    channels: ChannelRuntimeConfig[];
+    plugins: PluginConfig[];
+    agents: Record<string, AgentConfig>;
+    workspaces: Record<string, WorkspaceConfig>;
+    orchestration: OrchestrationConfig;
+}

package/dist/logging/app-logger.d.ts

@@ -0,0 +1,23 @@
+import type { LoggingLevel } from "../config/types";
+type LogContextValue = string | number | boolean | null | undefined | Record<string, unknown> | unknown[];
+interface LogContext {
+    [key: string]: LogContextValue;
+}
+interface CreateAppLoggerOptions {
+    filePath: string;
+    level: LoggingLevel;
+    maxSizeBytes: number;
+    maxFiles: number;
+    retentionDays: number;
+    now?: () => Date;
+}
+export interface AppLogger {
+    debug: (event: string, message: string, context?: LogContext) => Promise<void>;
+    info: (event: string, message: string, context?: LogContext) => Promise<void>;
+    error: (event: string, message: string, context?: LogContext) => Promise<void>;
+    cleanup: () => Promise<void>;
+    flush: () => Promise<void>;
+}
+export declare function createNoopAppLogger(): AppLogger;
+export declare function createAppLogger(options: CreateAppLoggerOptions): AppLogger;
+export {};

package/dist/orchestration/orchestration-types.d.ts

@@ -0,0 +1,156 @@
+export type OrchestrationTaskStatus = "pending" | "needs_confirmation" | "running" | "blocked" | "waiting_for_human" | "completed" | "failed" | "cancelled";
+export type OrchestrationSourceKind = "human" | "coordinator" | "worker";
+export interface OrchestrationOpenQuestionRecord {
+    questionId: string;
+    question: string;
+    whyBlocked: string;
+    whatIsNeeded: string;
+    askedAt: string;
+    status: "open" | "answered" | "superseded";
+    answeredAt?: string;
+    answerSource?: "coordinator" | "human";
+    answerText?: string;
+    packageId?: string;
+    lastWakeError?: string;
+    lastResumeError?: string;
+}
+export interface OrchestrationReviewPendingRecord {
+    reviewId: string;
+    reason: "misrouted_answer";
+    createdAt: string;
+    resultId: string;
+    resultText: string;
+}
+export interface OrchestrationCorrectionPendingRecord {
+    requestedAt: string;
+    reason: "misrouted_answer";
+}
+export interface OrchestrationTaskRecord {
+    taskId: string;
+    sourceHandle: string;
+    sourceKind: OrchestrationSourceKind;
+    coordinatorSession: string;
+    workerSession?: string;
+    workspace: string;
+    cwd?: string;
+    targetAgent: string;
+    role?: string;
+    task: string;
+    status: OrchestrationTaskStatus;
+    summary: string;
+    resultText: string;
+    createdAt: string;
+    updatedAt: string;
+    chatKey?: string;
+    replyContextToken?: string;
+    accountId?: string;
+    deliveryAccountId?: string;
+    coordinatorInjectedAt?: string;
+    cancelRequestedAt?: string;
+    cancelCompletedAt?: string;
+    lastCancelError?: string;
+    noticePending?: boolean;
+    noticeSentAt?: string;
+    lastNoticeError?: string;
+    injectionPending?: boolean;
+    injectionAppliedAt?: string;
+    lastInjectionError?: string;
+    lastProgressAt?: string;
+    groupId?: string;
+    openQuestion?: OrchestrationOpenQuestionRecord;
+    reviewPending?: OrchestrationReviewPendingRecord;
+    correctionPending?: OrchestrationCorrectionPendingRecord;
+}
+export interface OrchestrationGroupRecord {
+    groupId: string;
+    coordinatorSession: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    coordinatorInjectedAt?: string;
+    injectionPending?: boolean;
+    injectionAppliedAt?: string;
+    lastInjectionError?: string;
+}
+export interface OrchestrationGroupSummary {
+    group: OrchestrationGroupRecord;
+    tasks: OrchestrationTaskRecord[];
+    totalTasks: number;
+    pendingApprovalTasks: number;
+    runningTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    cancelledTasks: number;
+    terminal: boolean;
+}
+export interface ExternalCoordinatorRecord {
+    coordinatorSession: string;
+    workspace?: string;
+    createdAt: string;
+    updatedAt: string;
+    defaultTargetAgent?: string;
+}
+export interface WorkerBindingRecord {
+    sourceHandle: string;
+    coordinatorSession: string;
+    workspace: string;
+    cwd?: string;
+    targetAgent: string;
+    role?: string;
+}
+export interface OrchestrationQueuedQuestionRecord {
+    taskId: string;
+    questionId: string;
+    enqueuedAt: string;
+}
+export interface OrchestrationCoordinatorQuestionStateRecord {
+    activePackageId?: string;
+    queuedQuestions: OrchestrationQueuedQuestionRecord[];
+}
+export interface OrchestrationCoordinatorRouteContextRecord {
+    coordinatorSession: string;
+    chatKey: string;
+    accountId?: string;
+    replyContextToken?: string;
+    updatedAt: string;
+}
+export interface OrchestrationHumanQuestionPackageMessageRecord {
+    messageId: string;
+    kind: "initial" | "follow_up";
+    promptText: string;
+    createdAt: string;
+    taskQuestions?: Array<{
+        taskId: string;
+        questionId: string;
+    }>;
+    routeChatKey?: string;
+    routeAccountId?: string;
+    routeReplyContextToken?: string;
+    deliveredAt?: string;
+    deliveredChatKey?: string;
+    deliveryAccountId?: string;
+    lastDeliveryError?: string;
+}
+export interface OrchestrationHumanQuestionPackageRecord {
+    packageId: string;
+    coordinatorSession: string;
+    status: "active" | "closed";
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+    initialTaskIds: string[];
+    openTaskIds: string[];
+    resolvedTaskIds: string[];
+    messages: OrchestrationHumanQuestionPackageMessageRecord[];
+    awaitingReplyMessageId?: string;
+}
+export interface OrchestrationState {
+    tasks: Record<string, OrchestrationTaskRecord>;
+    workerBindings: Record<string, WorkerBindingRecord>;
+    groups: Record<string, OrchestrationGroupRecord>;
+    humanQuestionPackages: Record<string, OrchestrationHumanQuestionPackageRecord>;
+    coordinatorQuestionState: Record<string, OrchestrationCoordinatorQuestionStateRecord>;
+    coordinatorRoutes: Record<string, OrchestrationCoordinatorRouteContextRecord>;
+    externalCoordinators: Record<string, ExternalCoordinatorRecord>;
+}
+export declare function createEmptyOrchestrationState(): OrchestrationState;

package/dist/plugin-api.d.ts

@@ -0,0 +1,8 @@
+export type { ChannelPluginDefinition } from "./channels/plugin.js";
+export type { ChannelFactory, CreateChannelDeps } from "./channels/create-channel.js";
+export type { ChannelStartInput, ConsumerLock, ConsumerLockMetadata, ConsumerLockOptions, CoordinatorMessageInput, MessageChannelRuntime, OrchestrationDeliveryCallbacks, OutboundQuota, } from "./channels/types.js";
+export type { ChannelCliInput, ChannelCliIo, ChannelCliParseResult, ChannelCliProvider, ChannelCliValidationIssue, } from "./channels/cli/provider.js";
+export type { ChannelRuntimeConfig } from "./config/types.js";
+export type { AppLogger } from "./logging/app-logger.js";
+export type { WeacpxPlugin } from "./plugins/types.js";
+export { WEACPX_PLUGIN_API_VERSION, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION, } from "./plugins/types.js";

package/dist/plugin-api.js

@@ -0,0 +1,180 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __promiseAll = (args) => Promise.all(args);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/plugins/compatibility.ts
+function normalizeCoreVersionForCompat(version) {
+  const dashIdx = version.indexOf("-");
+  const plusIdx = version.indexOf("+");
+  const cutPositions = [dashIdx, plusIdx].filter((i) => i >= 0);
+  if (cutPositions.length === 0)
+    return version;
+  return version.slice(0, Math.min(...cutPositions));
+}
+function compareSemver(a, b) {
+  const lhs = parseSemverStrict(a);
+  const rhs = parseSemverStrict(b);
+  for (let i = 0;i < 3; i += 1) {
+    if (lhs[i] < rhs[i])
+      return -1;
+    if (lhs[i] > rhs[i])
+      return 1;
+  }
+  return 0;
+}
+function parseSemverStrict(value) {
+  const match = SEMVER_RE.exec(value);
+  if (!match)
+    throw new Error(`malformed semver: ${value}`);
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function parseRange(requirement) {
+  const trimmed = requirement.trim();
+  if (!trimmed)
+    throw new Error("empty version requirement");
+  if (trimmed.startsWith(">=")) {
+    return { kind: "gte", base: parseSemverStrict(trimmed.slice(2).trim()), raw: trimmed };
+  }
+  if (trimmed.startsWith("^")) {
+    return { kind: "caret", base: parseSemverStrict(trimmed.slice(1).trim()), raw: trimmed };
+  }
+  if (trimmed.startsWith(">") || trimmed.startsWith("<") || trimmed.startsWith("~") || trimmed.includes(" ")) {
+    throw new Error(`unsupported version requirement: ${requirement}`);
+  }
+  return { kind: "exact", base: parseSemverStrict(trimmed), raw: trimmed };
+}
+function isVersionSatisfied(current, requirement) {
+  const range = parseRange(requirement);
+  const cur = parseSemverStrict(current);
+  switch (range.kind) {
+    case "exact":
+      return cur[0] === range.base[0] && cur[1] === range.base[1] && cur[2] === range.base[2];
+    case "gte":
+      return cmpTuple(cur, range.base) >= 0;
+    case "caret":
+      if (cmpTuple(cur, range.base) < 0)
+        return false;
+      if (range.base[0] !== 0)
+        return cur[0] === range.base[0];
+      if (range.base[1] !== 0)
+        return cur[0] === 0 && cur[1] === range.base[1];
+      return cur[0] === 0 && cur[1] === 0 && cur[2] === range.base[2];
+  }
+}
+function cmpTuple(a, b) {
+  for (let i = 0;i < 3; i += 1) {
+    if (a[i] < b[i])
+      return -1;
+    if (a[i] > b[i])
+      return 1;
+  }
+  return 0;
+}
+function validatePluginCompatibility(metadata, context) {
+  const { packageName, currentWeacpxVersion } = context;
+  const apiVersion = metadata.apiVersion;
+  if (typeof apiVersion !== "number") {
+    throw new Error(`插件 ${packageName} 缺少必需字段 apiVersion`);
+  }
+  if (!WEACPX_PLUGIN_API_SUPPORTED_VERSIONS.includes(apiVersion)) {
+    const supported = WEACPX_PLUGIN_API_SUPPORTED_VERSIONS.join(", ");
+    throw new Error(`插件 ${packageName} 使用不支持的 apiVersion ${apiVersion}; supported: ${supported}; ` + `请安装与当前 weacpx 兼容的插件版本 (install a compatible plugin)`);
+  }
+  if (!currentWeacpxVersion || currentWeacpxVersion === "unknown") {
+    return;
+  }
+  const normalizedCurrent = normalizeCoreVersionForCompat(currentWeacpxVersion);
+  if (metadata.minWeacpxVersion !== undefined) {
+    if (typeof metadata.minWeacpxVersion !== "string") {
+      throw new Error(`插件 ${packageName} 元数据非法：minWeacpxVersion 必须是字符串 (invalid plugin metadata)`);
+    }
+    let satisfied;
+    try {
+      satisfied = compareSemver(normalizedCurrent, metadata.minWeacpxVersion) >= 0;
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`插件 ${packageName} 元数据非法：minWeacpxVersion (${detail}) (invalid plugin metadata)`);
+    }
+    if (!satisfied) {
+      throw new Error(`插件 ${packageName} requires weacpx >=${metadata.minWeacpxVersion}; ` + `current is ${currentWeacpxVersion}; upgrade weacpx`);
+    }
+  }
+  if (metadata.compatibleWeacpxVersions !== undefined) {
+    if (typeof metadata.compatibleWeacpxVersions !== "string") {
+      throw new Error(`插件 ${packageName} 元数据非法：compatibleWeacpxVersions 必须是字符串 (invalid plugin metadata)`);
+    }
+    let satisfied;
+    try {
+      satisfied = isVersionSatisfied(normalizedCurrent, metadata.compatibleWeacpxVersions);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`插件 ${packageName} 元数据非法：compatibleWeacpxVersions (${detail}) (invalid plugin metadata)`);
+    }
+    if (!satisfied) {
+      throw new Error(`插件 ${packageName} requires weacpx ${metadata.compatibleWeacpxVersions}; ` + `current is ${currentWeacpxVersion}; upgrade weacpx`);
+    }
+  }
+}
+var WEACPX_PLUGIN_API_VERSION = 1, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION = "0.4.0", SEMVER_RE;
+var init_compatibility = __esm(() => {
+  WEACPX_PLUGIN_API_SUPPORTED_VERSIONS = [1];
+  SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+});
+
+// src/plugins/types.ts
+var init_types = __esm(() => {
+  init_compatibility();
+});
+
+// src/plugin-api.ts
+init_types();
+export {
+  WEACPX_PLUGIN_MIN_CORE_VERSION,
+  WEACPX_PLUGIN_API_VERSION,
+  WEACPX_PLUGIN_API_SUPPORTED_VERSIONS
+};

package/dist/plugins/compatibility.d.ts

@@ -0,0 +1,16 @@
+export declare const WEACPX_PLUGIN_API_VERSION: 1;
+export declare const WEACPX_PLUGIN_API_SUPPORTED_VERSIONS: readonly number[];
+export declare const WEACPX_PLUGIN_MIN_CORE_VERSION: "0.4.0";
+export declare function normalizeCoreVersionForCompat(version: string): string;
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+export declare function isVersionSatisfied(current: string, requirement: string): boolean;
+export interface PluginCompatibilityMetadata {
+    apiVersion?: unknown;
+    minWeacpxVersion?: unknown;
+    compatibleWeacpxVersions?: unknown;
+}
+export interface PluginCompatibilityContext {
+    packageName: string;
+    currentWeacpxVersion: string;
+}
+export declare function validatePluginCompatibility(metadata: PluginCompatibilityMetadata, context: PluginCompatibilityContext): void;

package/dist/plugins/known-plugins.d.ts

@@ -0,0 +1,9 @@
+export interface KnownPlugin {
+    packageName: string;
+    channels: string[];
+    description: string;
+    official: true;
+}
+export declare function listKnownPlugins(): KnownPlugin[];
+export declare function findKnownPluginByChannel(channelType: string): KnownPlugin | null;
+export declare function getMovedChannelInstallHint(channelType: string): string | null;

package/dist/plugins/types.d.ts

@@ -0,0 +1,18 @@
+import type { ChannelPluginDefinition } from "../channels/plugin.js";
+import { WEACPX_PLUGIN_API_VERSION, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION } from "./compatibility.js";
+export { WEACPX_PLUGIN_API_VERSION, WEACPX_PLUGIN_API_SUPPORTED_VERSIONS, WEACPX_PLUGIN_MIN_CORE_VERSION, };
+export interface WeacpxPlugin {
+    apiVersion: 1;
+    name?: string;
+    /**
+     * Minimum weacpx core version required by this plugin (e.g. "0.3.3").
+     * First-party plugins must declare this; third-party plugins are encouraged to.
+     */
+    minWeacpxVersion?: string;
+    /**
+     * Optional explicit weacpx core compatibility range, e.g. ">=0.3.3" or "^0.3.3".
+     * If both `minWeacpxVersion` and `compatibleWeacpxVersions` are set, both must hold.
+     */
+    compatibleWeacpxVersions?: string;
+    channels?: ChannelPluginDefinition[];
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function readVersion(moduleUrl?: string): string;

package/dist/weixin/agent/interface.d.ts

@@ -0,0 +1,54 @@
+import type { ChannelMediaAttachment, OutboundChannelMedia } from "../../channels/media-types.js";
+/**
+ * Agent interface — any AI backend that can handle a chat message.
+ *
+ * Implement this interface to connect WeChat to your own AI service.
+ * The WeChat bridge calls `chat()` for each inbound message and sends
+ * the returned response back to the user.
+ */
+export interface Agent {
+    /** Process a single message and return a reply. */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /** Return true when the text begins with a command prefix handled by this agent. */
+    isKnownCommand?(text: string): boolean;
+    /** Clear/reset the session for a given conversation. */
+    clearSession?(conversationId: string): void | Promise<void>;
+}
+export interface ChatRequest {
+    /** Inbound Weixin account id that received this message. */
+    accountId: string;
+    /** Conversation / user identifier. Use this to maintain per-user context. */
+    conversationId: string;
+    /** Text content of the message. */
+    text: string;
+    /** Attached media file(s) (image, audio, video, or generic file). */
+    media?: ChannelMediaAttachment | ChannelMediaAttachment[];
+    /**
+     * Optional callback for streaming text out during long-running agent
+     * processing. When the channel delivers any non-empty reply segment,
+     * callers may treat it as the text output channel for that turn and
+     * suppress `ChatResponse.text`.
+     */
+    reply?: (text: string) => Promise<void>;
+    /** Latest inbound Weixin context token for follow-up replies in the same chat. */
+    replyContextToken?: string;
+    /** Channel-provided facts for command authorization and routing policy. */
+    metadata?: ChatRequestMetadata;
+}
+export interface ChatRequestMetadata {
+    channel?: string;
+    chatType?: "direct" | "group";
+    senderId?: string;
+    senderName?: string;
+    groupId?: string;
+    isOwner?: boolean;
+}
+export interface ChatResponse {
+    /**
+     * Final reply text when no streamed `reply()` output was delivered for
+     * the same turn. May contain markdown and will be normalized before send.
+     */
+    text?: string;
+    /** Reply media file(s). */
+    media?: OutboundChannelMedia | OutboundChannelMedia[];
+}

package/dist/weixin/api/api.d.ts

@@ -0,0 +1,48 @@
+import type { BaseInfo, GetUploadUrlReq, GetUploadUrlResp, GetUpdatesReq, GetUpdatesResp, SendMessageReq, SendTypingReq, GetConfigResp } from "./types.js";
+export type WeixinApiOptions = {
+    baseUrl: string;
+    token?: string;
+    timeoutMs?: number;
+    /** Long-poll timeout for getUpdates (server may hold the request up to this). */
+    longPollTimeoutMs?: number;
+};
+/** Build the `base_info` payload included in every API request. */
+export declare function buildBaseInfo(): BaseInfo;
+/**
+ * GET fetch wrapper: send a GET request to a Weixin API endpoint with timeout + abort.
+ * Query parameters should already be encoded in `endpoint`.
+ * Returns the raw response text on success; throws on HTTP error or timeout.
+ */
+export declare function apiGetFetch(params: {
+    baseUrl: string;
+    endpoint: string;
+    timeoutMs: number;
+    label: string;
+}): Promise<string>;
+/**
+ * Long-poll getUpdates. Server should hold the request until new messages or timeout.
+ *
+ * On client-side timeout (no server response within timeoutMs), returns an empty response
+ * with ret=0 so the caller can simply retry. This is normal for long-poll.
+ */
+export declare function getUpdates(params: GetUpdatesReq & {
+    baseUrl: string;
+    token?: string;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+}): Promise<GetUpdatesResp>;
+/** Get a pre-signed CDN upload URL for a file. */
+export declare function getUploadUrl(params: GetUploadUrlReq & WeixinApiOptions): Promise<GetUploadUrlResp>;
+/** Send a single message downstream. */
+export declare function sendMessage(params: WeixinApiOptions & {
+    body: SendMessageReq;
+}): Promise<void>;
+/** Fetch bot config (includes typing_ticket) for a given user. */
+export declare function getConfig(params: WeixinApiOptions & {
+    ilinkUserId: string;
+    contextToken?: string;
+}): Promise<GetConfigResp>;
+/** Send a typing indicator to a user. */
+export declare function sendTyping(params: WeixinApiOptions & {
+    body: SendTypingReq;
+}): Promise<void>;

package/dist/weixin/api/config-cache.d.ts

@@ -0,0 +1,18 @@
+/** Subset of getConfig fields that we actually need; add new fields here as needed. */
+export interface CachedConfig {
+    typingTicket: string;
+}
+/**
+ * Per-user getConfig cache with periodic random refresh (within 24h) and
+ * exponential-backoff retry (up to 1h) on failure.
+ */
+export declare class WeixinConfigManager {
+    private apiOpts;
+    private log;
+    private cache;
+    constructor(apiOpts: {
+        baseUrl: string;
+        token?: string;
+    }, log: (msg: string) => void);
+    getForUser(userId: string, contextToken?: string): Promise<CachedConfig>;
+}

package/dist/weixin/api/session-guard.d.ts

@@ -0,0 +1,15 @@
+/** Error code returned by the server when the bot session has expired. */
+export declare const SESSION_EXPIRED_ERRCODE = -14;
+/** Pause all inbound/outbound API calls for `accountId` for one hour. */
+export declare function pauseSession(accountId: string): void;
+/** Returns `true` when the bot is still within its one-hour cooldown window. */
+export declare function isSessionPaused(accountId: string): boolean;
+/** Milliseconds remaining until the pause expires (0 when not paused). */
+export declare function getRemainingPauseMs(accountId: string): number;
+/** Throw if the session is currently paused. Call before any API request. */
+export declare function assertSessionActive(accountId: string): void;
+/**
+ * Reset internal state — only for tests.
+ * @internal
+ */
+export declare function _resetForTest(): void;