shennian 0.2.87 → 0.2.89

package/dist/src/channels/wechat-channel/observer.d.ts

@@ -0,0 +1,64 @@
+import type { WeChatChannelHelperCommandName, WeChatChannelHelperResponse } from './helper-protocol.js';
+import type { WeChatChannelRuntime, WeChatChannelBindingConfig } from './runtime.js';
+import type { WeChatChannelApiClient, WeChatChannelObservedMessage } from './client.js';
+import { type WeChatConversationListFingerprint } from './fingerprint.js';
+export type WeChatChannelHelperTransport = {
+    request<T = unknown>(command: WeChatChannelHelperCommandName, params?: Record<string, unknown>, traceId?: string): Promise<WeChatChannelHelperResponse<T>>;
+};
+export type WeChatChannelWindowInfo = {
+    windowId: string;
+    appName?: string | null;
+    title?: string | null;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        coordinateSpace?: string;
+    };
+};
+export type WeChatChannelScreenshot = {
+    mimeType: string;
+    dataBase64: string;
+    width: number;
+    height: number;
+    windowId?: string | null;
+};
+export type WeChatChannelOcrBlock = {
+    text?: string;
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        coordinateSpace?: string;
+    };
+    confidence?: number;
+};
+export type WeChatChannelOcrResult = {
+    blocks?: WeChatChannelOcrBlock[];
+    visibleConversationFingerprints?: WeChatConversationListFingerprint[];
+};
+export type WeChatChannelObserveApi = Pick<WeChatChannelApiClient, 'observe'>;
+export type HelperBackedObserveOptions = {
+    runtime: WeChatChannelRuntime;
+    binding: WeChatChannelBindingConfig;
+    helper: WeChatChannelHelperTransport;
+    api: WeChatChannelObserveApi;
+    traceId?: string;
+    localLedgerTailAnchors?: unknown[];
+};
+export declare function observeWeChatChannelBindingViaHelper(options: HelperBackedObserveOptions): Promise<WeChatChannelObservedMessage[]>;
+export declare function ensureHelperPreflight(helper: WeChatChannelHelperTransport, traceId?: string): Promise<void>;
+export declare function focusWeChatWindow(helper: WeChatChannelHelperTransport, traceId?: string): Promise<WeChatChannelWindowInfo>;
+export declare function openConversationInVisibleList(input: {
+    helper: WeChatChannelHelperTransport;
+    window: WeChatChannelWindowInfo;
+    binding: WeChatChannelBindingConfig;
+    traceId?: string;
+}): Promise<{
+    opened: boolean;
+    reason: string;
+}>;
+export declare function captureWeChatWindow(helper: WeChatChannelHelperTransport, windowId: string, traceId?: string): Promise<WeChatChannelScreenshot>;
+export declare function recognizeWeChatScreenshot(helper: WeChatChannelHelperTransport, screenshot: WeChatChannelScreenshot, traceId?: string): Promise<WeChatChannelOcrResult>;

package/dist/src/channels/wechat-channel/observer.js

@@ -0,0 +1,118 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @arch docs/features/wechat-rpa-helper-runtime.md
+// @test src/__tests__/wechat-channel-observer.test.ts
+import { matchWeChatConversationFingerprints, } from './fingerprint.js';
+export async function observeWeChatChannelBindingViaHelper(options) {
+    await ensureHelperPreflight(options.helper, options.traceId);
+    const window = await focusWeChatWindow(options.helper, options.traceId);
+    await openConversationInVisibleList({
+        helper: options.helper,
+        window,
+        binding: options.binding,
+        traceId: options.traceId,
+    });
+    const capture = await captureWeChatWindow(options.helper, window.windowId, options.traceId);
+    const ocr = await recognizeWeChatScreenshot(options.helper, capture, options.traceId);
+    const decision = await options.api.observe(options.runtime, options.binding, {
+        screenshots: [{
+                captureIndex: 0,
+                mimeType: capture.mimeType,
+                dataBase64: capture.dataBase64,
+                width: capture.width,
+                height: capture.height,
+            }],
+        edgeOcrBlocks: ocr.blocks ?? [],
+        visibleConversationFingerprints: ocr.visibleConversationFingerprints ?? [],
+        localLedgerTailAnchors: options.localLedgerTailAnchors ?? [],
+    });
+    return decision.observedMessages ?? [];
+}
+export async function ensureHelperPreflight(helper, traceId) {
+    const response = await helper.request('permissions.check', {}, traceId);
+    assertHelperOk(response, 'permissions.check');
+    const result = response.result ?? {};
+    if (result.screenRecording === false)
+        throw new Error('permission_screen_recording_missing');
+    if (result.accessibility === false)
+        throw new Error('permission_accessibility_missing');
+    if (result.automation === false)
+        throw new Error('permission_automation_missing');
+    if (result.wechatRunning === false)
+        throw new Error('wechat_not_running');
+    if (result.wechatWindowAvailable === false)
+        throw new Error('wechat_window_unavailable');
+}
+export async function focusWeChatWindow(helper, traceId) {
+    const response = await helper.request('windows.list', {}, traceId);
+    assertHelperOk(response, 'windows.list');
+    const window = (response.result?.windows ?? []).find(isWeChatWindow);
+    if (!window)
+        throw new Error('wechat_window_unavailable');
+    const focus = await helper.request('windows.focus', { windowId: window.windowId }, traceId);
+    assertHelperOk(focus, 'windows.focus');
+    return window;
+}
+export async function openConversationInVisibleList(input) {
+    const capture = await captureWeChatWindow(input.helper, input.window.windowId, input.traceId);
+    const ocr = await recognizeWeChatScreenshot(input.helper, capture, input.traceId);
+    const match = matchWeChatConversationFingerprints({
+        visibleItems: ocr.visibleConversationFingerprints ?? [],
+        targets: [{
+                bindingId: input.binding.bindingId,
+                conversationDisplayName: input.binding.conversationDisplayName,
+            }],
+    })[0];
+    if (!match)
+        return { opened: false, reason: 'conversation_not_visible' };
+    const center = bboxCenter(match.item.bbox);
+    if (!center)
+        return { opened: false, reason: 'conversation_bbox_missing' };
+    const click = await input.helper.request('mouse.click', {
+        x: center.x,
+        y: center.y,
+        coordinateSpace: center.coordinateSpace,
+        windowId: input.window.windowId,
+    }, input.traceId);
+    assertHelperOk(click, 'mouse.click');
+    return { opened: true, reason: match.reason };
+}
+export async function captureWeChatWindow(helper, windowId, traceId) {
+    const response = await helper.request('windows.capture', { windowId, scope: 'full-window' }, traceId);
+    assertHelperOk(response, 'windows.capture');
+    const result = response.result;
+    if (!result?.dataBase64 || !result.mimeType || !result.width || !result.height) {
+        throw new Error('helper_invalid_response: windows.capture missing screenshot data');
+    }
+    return result;
+}
+export async function recognizeWeChatScreenshot(helper, screenshot, traceId) {
+    const response = await helper.request('ocr.recognize', {
+        mimeType: screenshot.mimeType,
+        dataBase64: screenshot.dataBase64,
+        width: screenshot.width,
+        height: screenshot.height,
+    }, traceId);
+    assertHelperOk(response, 'ocr.recognize');
+    return response.result ?? {};
+}
+function assertHelperOk(response, command) {
+    if (!response.ok)
+        throw new Error(`${response.errorCode || 'helper_command_failed'}: ${response.errorSummary || command}`);
+}
+function isWeChatWindow(window) {
+    const haystack = `${window.appName || ''} ${window.title || ''}`.toLowerCase();
+    return haystack.includes('wechat') || haystack.includes('微信');
+}
+function bboxCenter(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const bbox = value;
+    const x = Number(bbox.x);
+    const y = Number(bbox.y);
+    const width = Number(bbox.width);
+    const height = Number(bbox.height);
+    if (![x, y, width, height].every(Number.isFinite))
+        return null;
+    const coordinateSpace = typeof bbox.coordinateSpace === 'string' ? bbox.coordinateSpace : undefined;
+    return { x: x + width / 2, y: y + height / 2, coordinateSpace };
+}

package/dist/src/channels/wechat-channel/outbound-ledger.d.ts

@@ -0,0 +1,66 @@
+import type { WeChatChannelObservedMessage } from './client.js';
+export type WeChatChannelOutboundStatus = 'queued' | 'sending' | 'sent_unconfirmed' | 'confirmed_echo' | 'failed' | 'stale' | 'manual_review';
+export type WeChatChannelOutboundRecord = {
+    replyId: string;
+    idempotencyKey: string;
+    bindingId: string;
+    runtimeId: string;
+    sessionId: string;
+    conversationName: string;
+    replyBaseRevision: number;
+    textNormalized?: string;
+    attachmentLocalRefs?: string[];
+    createdAt: string;
+    queuedAt?: string;
+    sentAt?: string;
+    confirmedAt?: string;
+    sendStatus: WeChatChannelOutboundStatus;
+    expectedEchoAnchor?: string;
+    confirmedEchoAnchor?: string;
+    observeAttemptsAfterSent?: number;
+    failureCode?: string;
+    lastErrorSummary?: string;
+};
+export type WeChatChannelOutboundLedger = {
+    version: 1;
+    runtimeId: string;
+    records: WeChatChannelOutboundRecord[];
+};
+export type EchoClassificationResult = {
+    remainingMessages: WeChatChannelObservedMessage[];
+    confirmedRecords: WeChatChannelOutboundRecord[];
+    manualReviewRecords: WeChatChannelOutboundRecord[];
+};
+export declare function loadWeChatChannelOutboundLedger(filePath: string, runtimeId: string): WeChatChannelOutboundLedger;
+export declare function saveWeChatChannelOutboundLedger(filePath: string, ledger: WeChatChannelOutboundLedger): void;
+export declare function enqueueWeChatOutboundReply(input: {
+    ledger: WeChatChannelOutboundLedger;
+    replyId: string;
+    idempotencyKey: string;
+    bindingId: string;
+    runtimeId: string;
+    sessionId: string;
+    conversationName: string;
+    replyBaseRevision: number;
+    text?: string;
+    attachmentLocalRefs?: string[];
+    now?: Date;
+}): WeChatChannelOutboundRecord;
+export declare function guardWeChatOutboundRevision(input: {
+    record: WeChatChannelOutboundRecord;
+    currentLastInboundRevision: number;
+    now?: Date;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'stale';
+};
+export declare function markWeChatOutboundSentUnconfirmed(record: WeChatChannelOutboundRecord, now?: Date): void;
+export declare function classifyWeChatOutboundEchoes(input: {
+    ledger: WeChatChannelOutboundLedger;
+    bindingId: string;
+    messages: WeChatChannelObservedMessage[];
+    now?: Date;
+}): EchoClassificationResult;
+export declare function suppressSelfOnlyWeChatMessages(messages: WeChatChannelObservedMessage[]): WeChatChannelObservedMessage[];

package/dist/src/channels/wechat-channel/outbound-ledger.js

@@ -0,0 +1,112 @@
+// @arch docs/features/wechat-rpa-outbound-ledger.md
+// @test src/__tests__/wechat-channel-outbound-ledger.test.ts
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeWeChatAnchorText, weChatTextSimilarity } from './anchor.js';
+const MAX_OUTBOUND_RECORDS = 500;
+const MANUAL_REVIEW_AFTER_OBSERVE_ATTEMPTS = 2;
+const MANUAL_REVIEW_AFTER_MS = 10 * 60 * 1000;
+export function loadWeChatChannelOutboundLedger(filePath, runtimeId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed?.version === 1 && parsed.runtimeId === runtimeId && Array.isArray(parsed.records))
+            return parsed;
+    }
+    catch { }
+    return { version: 1, runtimeId, records: [] };
+}
+export function saveWeChatChannelOutboundLedger(filePath, ledger) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    ledger.records = ledger.records.slice(-MAX_OUTBOUND_RECORDS);
+    fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2));
+}
+export function enqueueWeChatOutboundReply(input) {
+    const existing = input.ledger.records.find((record) => record.idempotencyKey === input.idempotencyKey);
+    if (existing)
+        return existing;
+    const now = (input.now ?? new Date()).toISOString();
+    const textNormalized = normalizeWeChatAnchorText(input.text);
+    const record = {
+        replyId: input.replyId,
+        idempotencyKey: input.idempotencyKey,
+        bindingId: input.bindingId,
+        runtimeId: input.runtimeId,
+        sessionId: input.sessionId,
+        conversationName: input.conversationName,
+        replyBaseRevision: input.replyBaseRevision,
+        textNormalized: textNormalized || undefined,
+        attachmentLocalRefs: input.attachmentLocalRefs ?? [],
+        createdAt: now,
+        queuedAt: now,
+        sendStatus: 'queued',
+        expectedEchoAnchor: textNormalized || undefined,
+        observeAttemptsAfterSent: 0,
+    };
+    input.ledger.records.push(record);
+    return record;
+}
+export function guardWeChatOutboundRevision(input) {
+    if (input.currentLastInboundRevision <= input.record.replyBaseRevision)
+        return { ok: true };
+    input.record.sendStatus = 'stale';
+    input.record.failureCode = 'reply_revision_stale';
+    input.record.lastErrorSummary = 'Inbound revision advanced before reply send';
+    input.record.confirmedAt = input.record.confirmedAt;
+    return { ok: false, reason: 'stale' };
+}
+export function markWeChatOutboundSentUnconfirmed(record, now = new Date()) {
+    record.sendStatus = 'sent_unconfirmed';
+    record.sentAt = now.toISOString();
+    record.observeAttemptsAfterSent = 0;
+}
+export function classifyWeChatOutboundEchoes(input) {
+    const now = input.now ?? new Date();
+    const confirmedRecords = [];
+    const manualReviewRecords = [];
+    const pendingRecords = input.ledger.records.filter((record) => record.bindingId === input.bindingId && record.sendStatus === 'sent_unconfirmed');
+    const consumedMessageIndexes = new Set();
+    for (const record of pendingRecords) {
+        const matchIndex = input.messages.findIndex((message, index) => !consumedMessageIndexes.has(index) && isOutboundEcho(record, message));
+        if (matchIndex >= 0) {
+            consumedMessageIndexes.add(matchIndex);
+            const message = input.messages[matchIndex];
+            record.sendStatus = 'confirmed_echo';
+            record.confirmedAt = now.toISOString();
+            record.confirmedEchoAnchor = normalizeWeChatAnchorText(message.anchorText || message.normalizedText || message.textExcerpt || '') || undefined;
+            confirmedRecords.push(record);
+            continue;
+        }
+        record.observeAttemptsAfterSent = (record.observeAttemptsAfterSent ?? 0) + 1;
+        if (shouldMoveOutboundToManualReview(record, now)) {
+            record.sendStatus = 'manual_review';
+            record.failureCode = 'echo_confirmation_timeout';
+            record.lastErrorSummary = 'Sent reply echo was not confirmed after observe threshold';
+            manualReviewRecords.push(record);
+        }
+    }
+    return {
+        remainingMessages: input.messages.filter((_, index) => !consumedMessageIndexes.has(index)),
+        confirmedRecords,
+        manualReviewRecords,
+    };
+}
+export function suppressSelfOnlyWeChatMessages(messages) {
+    return messages.filter((message) => message.senderRole !== 'self');
+}
+function isOutboundEcho(record, message) {
+    if (message.senderRole !== 'self')
+        return false;
+    const expected = record.expectedEchoAnchor || record.textNormalized || '';
+    const actual = normalizeWeChatAnchorText(message.anchorText || message.normalizedText || message.textExcerpt || '');
+    if (!expected || !actual)
+        return false;
+    return weChatTextSimilarity(expected, actual) >= 0.9;
+}
+function shouldMoveOutboundToManualReview(record, now) {
+    if ((record.observeAttemptsAfterSent ?? 0) >= MANUAL_REVIEW_AFTER_OBSERVE_ATTEMPTS)
+        return true;
+    if (!record.sentAt)
+        return false;
+    const sentAt = new Date(record.sentAt).getTime();
+    return Number.isFinite(sentAt) && now.getTime() - sentAt >= MANUAL_REVIEW_AFTER_MS;
+}

package/dist/src/channels/wechat-channel/preflight.d.ts

@@ -0,0 +1,37 @@
+import { type WeChatChannelHelperReady, type WeChatChannelHelperErrorCode } from './helper-protocol.js';
+import type { WeChatChannelRuntime, WeChatChannelBindingConfig } from './runtime.js';
+export type WeChatChannelPreflightSeverity = 'blocking' | 'warning';
+export type WeChatChannelPreflightCode = 'ok' | 'mac_only' | 'enterprise_required' | 'privacy_consent_required' | 'server_decision_unavailable' | 'same_machine_required' | 'local_agent_unavailable' | 'helper_not_ready' | WeChatChannelHelperErrorCode;
+export type WeChatChannelPreflightCheck = {
+    code: WeChatChannelPreflightCode;
+    ok: boolean;
+    severity: WeChatChannelPreflightSeverity;
+    message: string;
+};
+export type WeChatChannelPreflightInput = {
+    platform: string;
+    accountTier?: string | null;
+    privacyConsentAccepted?: boolean;
+    serverDecisionAvailable?: boolean;
+    currentMachineId?: string | null;
+    localAgentMachineId?: string | null;
+    localAgentAvailable?: boolean;
+    runtime: WeChatChannelRuntime;
+    binding?: WeChatChannelBindingConfig | null;
+    expectedHelperVersion: string;
+    helperReady?: WeChatChannelHelperReady | null;
+    permissions?: {
+        screenRecording?: boolean;
+        accessibility?: boolean;
+        automation?: boolean;
+        wechatRunning?: boolean;
+        wechatWindowAvailable?: boolean;
+    } | null;
+};
+export type WeChatChannelPreflightResult = {
+    ok: boolean;
+    canEnable: boolean;
+    status: 'ready' | 'blocked';
+    checks: WeChatChannelPreflightCheck[];
+};
+export declare function evaluateWeChatChannelPreflight(input: WeChatChannelPreflightInput): WeChatChannelPreflightResult;

package/dist/src/channels/wechat-channel/preflight.js

@@ -0,0 +1,48 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @arch docs/features/wechat-rpa-helper-runtime.md
+// @test src/__tests__/wechat-channel-preflight.test.ts
+import { validateWeChatChannelHelperReady, } from './helper-protocol.js';
+export function evaluateWeChatChannelPreflight(input) {
+    const checks = [];
+    checks.push(blockingCheck(input.platform === 'darwin', 'mac_only', '当前阶段微信 Channel 只支持 macOS。'));
+    checks.push(blockingCheck(input.accountTier === 'enterprise', 'enterprise_required', '当前阶段微信 Channel 仅企业版账号可用。'));
+    checks.push(blockingCheck(Boolean(input.privacyConsentAccepted), 'privacy_consent_required', '启用前需要确认微信 Channel 数据与隐私授权。'));
+    checks.push(blockingCheck(Boolean(input.serverDecisionAvailable), 'server_decision_unavailable', '服务端判断能力不可用，暂不能启用。'));
+    if (input.currentMachineId && input.runtime.machineId) {
+        checks.push(blockingCheck(input.currentMachineId === input.runtime.machineId, 'same_machine_required', '第一版只支持同机微信与同机神念运行时绑定。'));
+    }
+    if (input.localAgentMachineId && input.runtime.machineId) {
+        checks.push(blockingCheck(input.localAgentMachineId === input.runtime.machineId, 'same_machine_required', '绑定的 Agent 必须与微信运行时在同一台机器。'));
+    }
+    checks.push(blockingCheck(input.localAgentAvailable !== false, 'local_agent_unavailable', '本机 Agent 不可用，无法安全接管微信回复。'));
+    if (!input.helperReady) {
+        checks.push(blockingCheck(false, 'helper_not_ready', 'macOS helper 未就绪。'));
+    }
+    else {
+        const validation = validateWeChatChannelHelperReady(input.helperReady, input.expectedHelperVersion);
+        if (!validation.ok) {
+            checks.push(blockingCheck(false, validation.errorCode, validation.errorSummary));
+        }
+        else {
+            checks.push(blockingCheck(true, 'ok', 'macOS helper 版本与能力检查通过。'));
+        }
+    }
+    const permissions = input.permissions;
+    if (permissions) {
+        checks.push(blockingCheck(permissions.screenRecording !== false, 'permission_screen_recording_missing', '缺少屏幕录制权限。'));
+        checks.push(blockingCheck(permissions.accessibility !== false, 'permission_accessibility_missing', '缺少辅助功能权限。'));
+        checks.push(blockingCheck(permissions.automation !== false, 'permission_automation_missing', '缺少自动化控制权限。'));
+        checks.push(blockingCheck(permissions.wechatRunning !== false, 'wechat_not_running', '微信未运行。'));
+        checks.push(blockingCheck(permissions.wechatWindowAvailable !== false, 'wechat_window_unavailable', '微信窗口不可用。'));
+    }
+    const blockingFailures = checks.filter((check) => !check.ok && check.severity === 'blocking');
+    return {
+        ok: blockingFailures.length === 0,
+        canEnable: blockingFailures.length === 0,
+        status: blockingFailures.length === 0 ? 'ready' : 'blocked',
+        checks,
+    };
+}
+function blockingCheck(ok, code, message) {
+    return { ok, code: ok ? 'ok' : code, severity: 'blocking', message };
+}

package/dist/src/channels/wechat-channel/runner.d.ts

@@ -0,0 +1,34 @@
+import type { WeChatChannelRuntime, WeChatChannelBindingConfig } from './runtime.js';
+import { type WeChatChannelApiClient, type WeChatChannelObservedMessage } from './client.js';
+import { type WeChatChannelHelperClientOptions } from './helper-client.js';
+import type { WeChatChannelHelperTransport } from './observer.js';
+import { WeChatChannelScheduler, type WeChatChannelSchedulerTickResult } from './scheduler.js';
+export type WeChatChannelProductRunnerOptions = {
+    runtime: WeChatChannelRuntime;
+    workDir: string;
+    api?: WeChatChannelApiClient;
+    helper?: WeChatChannelHelperTransport & {
+        start?: () => Promise<unknown>;
+        stop?: () => Promise<void>;
+    };
+    helperClientOptions?: WeChatChannelHelperClientOptions;
+    ledgerPath?: string;
+    outboundLedgerPath?: string;
+    onInboundMessages?: (binding: WeChatChannelBindingConfig, messages: WeChatChannelObservedMessage[]) => Promise<void> | void;
+};
+export declare class WeChatChannelProductRunner {
+    private options;
+    readonly scheduler: WeChatChannelScheduler;
+    readonly helper: WeChatChannelHelperTransport & {
+        start?: () => Promise<unknown>;
+        stop?: () => Promise<void>;
+    };
+    private helperStarted;
+    constructor(options: WeChatChannelProductRunnerOptions);
+    start(): Promise<void>;
+    tick(): Promise<WeChatChannelSchedulerTickResult | void>;
+    stop(): Promise<void>;
+    private ensureHelperStarted;
+}
+export declare function createWeChatChannelProductRunner(options: WeChatChannelProductRunnerOptions): WeChatChannelProductRunner;
+export declare function buildLocalLedgerTailAnchors(ledgerPath: string, runtimeId: string, bindingId: string, limit?: number): Array<Record<string, unknown>>;

package/dist/src/channels/wechat-channel/runner.js

@@ -0,0 +1,84 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @test src/__tests__/wechat-channel-runner.test.ts
+import path from 'node:path';
+import { createWeChatChannelApiClient, } from './client.js';
+import { WeChatChannelHelperClient } from './helper-client.js';
+import { resolveWeChatChannelHelperAsset, WECHAT_CHANNEL_HELPER_VERSION } from './helper-assets.js';
+import { observeWeChatChannelBindingViaHelper } from './observer.js';
+import { WeChatChannelScheduler } from './scheduler.js';
+import { loadWeChatChannelLedger } from './ledger.js';
+export class WeChatChannelProductRunner {
+    options;
+    scheduler;
+    helper;
+    helperStarted = false;
+    constructor(options) {
+        this.options = options;
+        const api = options.api ?? createWeChatChannelApiClient();
+        this.helper = options.helper ?? createHelperClient(options.helperClientOptions);
+        this.scheduler = new WeChatChannelScheduler({
+            runtime: options.runtime,
+            workDir: options.workDir,
+            api,
+            ledgerPath: options.ledgerPath,
+            outboundLedgerPath: options.outboundLedgerPath,
+            onInboundMessages: options.onInboundMessages,
+            observeBinding: (binding) => observeWeChatChannelBindingViaHelper({
+                runtime: options.runtime,
+                binding,
+                helper: this.helper,
+                api,
+                localLedgerTailAnchors: buildLocalLedgerTailAnchors(options.ledgerPath ?? defaultLedgerPath(options.workDir, options.runtime.runtimeId), options.runtime.runtimeId, binding.bindingId),
+            }),
+        });
+    }
+    async start() {
+        await this.ensureHelperStarted();
+        await this.scheduler.start();
+    }
+    async tick() {
+        await this.ensureHelperStarted();
+        return this.scheduler.tick();
+    }
+    async stop() {
+        this.scheduler.stop();
+        if (this.helperStarted && this.helper.stop)
+            await this.helper.stop();
+        this.helperStarted = false;
+    }
+    async ensureHelperStarted() {
+        if (this.helperStarted)
+            return;
+        if (this.helper.start)
+            await this.helper.start();
+        this.helperStarted = true;
+    }
+}
+export function createWeChatChannelProductRunner(options) {
+    return new WeChatChannelProductRunner(options);
+}
+export function buildLocalLedgerTailAnchors(ledgerPath, runtimeId, bindingId, limit = 3) {
+    const ledger = loadWeChatChannelLedger(ledgerPath, runtimeId);
+    const recent = ledger.bindings[bindingId]?.recent ?? [];
+    return recent.slice(-limit).map((message) => ({
+        stableMessageKey: message.stableMessageKey,
+        senderRole: message.senderRole,
+        kind: message.kind,
+        anchorText: message.anchorText ?? message.normalizedText ?? message.textExcerpt ?? null,
+        anchorMetadata: message.anchorMetadata ?? null,
+    }));
+}
+function createHelperClient(options) {
+    if (options)
+        return new WeChatChannelHelperClient(options);
+    const resolved = resolveWeChatChannelHelperAsset();
+    if (!resolved.ok)
+        throw new Error(`${resolved.reasonCode}: ${resolved.message}`);
+    return new WeChatChannelHelperClient({
+        helperPath: resolved.helperPath,
+        expectedHelperVersion: resolved.version || WECHAT_CHANNEL_HELPER_VERSION,
+    });
+}
+function defaultLedgerPath(workDir, runtimeId) {
+    return path.join(workDir, 'wechat-channel', `${runtimeId}.ledger.json`);
+}

package/dist/src/channels/wechat-channel/runtime.d.ts

@@ -0,0 +1,45 @@
+export declare const WECHAT_CHANNEL_RUNTIME_KIND: "wechat_channel";
+export declare const WECHAT_CHANNEL_RUNTIME_VERSION = 1;
+export declare const WECHAT_CHANNEL_RECENT_MESSAGE_WINDOW = 20;
+export declare const WECHAT_CHANNEL_DEFAULT_POLL_INTERVAL_MS: number;
+export declare const WECHAT_CHANNEL_MIN_POLL_INTERVAL_MS: number;
+export declare const WECHAT_CHANNEL_MAX_POLL_INTERVAL_MS: number;
+export type WeChatChannelForegroundPolicy = 'polite' | 'work';
+export type WeChatChannelRuntimePolicy = {
+    kind: typeof WECHAT_CHANNEL_RUNTIME_KIND;
+    runtimeVersion: number;
+    platform: 'darwin';
+    pollIntervalMs: number;
+    minPollIntervalMs: number;
+    maxPollIntervalMs: number;
+    recentMessageWindow: number;
+    requiresServerDecision: true;
+    requiresMacHelper: true;
+    productRuntimeUsesLabFacade: false;
+};
+export type WeChatChannelBindingConfig = {
+    bindingId: string;
+    sessionId: string;
+    conversationDisplayName: string;
+    enabled: boolean;
+    allowReply: boolean;
+    downloadMedia: boolean;
+};
+export type WeChatChannelRuntimeConfig = {
+    runtimeId: string;
+    machineId: string;
+    pollIntervalMs?: number | null;
+    foregroundPolicy?: WeChatChannelForegroundPolicy | null;
+    bindings?: WeChatChannelBindingConfig[] | null;
+};
+export type WeChatChannelRuntime = {
+    kind: typeof WECHAT_CHANNEL_RUNTIME_KIND;
+    runtimeId: string;
+    machineId: string;
+    foregroundPolicy: WeChatChannelForegroundPolicy;
+    policy: WeChatChannelRuntimePolicy;
+    bindings: WeChatChannelBindingConfig[];
+};
+export declare function defaultWeChatChannelRuntimePolicy(pollIntervalMs?: number | null): WeChatChannelRuntimePolicy;
+export declare function normalizeWeChatChannelPollIntervalMs(value?: number | null): number;
+export declare function createWeChatChannelRuntime(config: WeChatChannelRuntimeConfig): WeChatChannelRuntime;