@kin-tio/cli 0.6.0

package/dist/src/mcp/wechat-kf-executor.js

@@ -0,0 +1,295 @@
+import { normalizeSendIntent, } from '../domain/send-contract.js';
+import { AgentSessionError, } from '../state/sqlite-store.js';
+import { WecomApiError } from '../services/wecom-api.js';
+function exactPayload(message, mediaId = '') {
+    switch (message.type) {
+        case 'text':
+            return { msgtype: 'text', text: { content: message.content } };
+        case 'image':
+            return { msgtype: 'image', image: { media_id: mediaId } };
+        case 'link':
+            return {
+                msgtype: 'link',
+                link: {
+                    title: message.title,
+                    desc: message.description,
+                    url: message.url,
+                    thumb_media_id: mediaId,
+                },
+            };
+        case 'miniprogram':
+            return {
+                msgtype: 'miniprogram',
+                miniprogram: {
+                    appid: message.appId,
+                    title: message.title,
+                    pagepath: message.pagePath,
+                    thumb_media_id: mediaId,
+                },
+            };
+        case 'location': {
+            const { type, ...location } = message;
+            return { msgtype: type, location };
+        }
+    }
+}
+function attemptError(attempt) {
+    if (attempt.status === 'failed' && attempt.failType === 13) {
+        return {
+            kind: 'sensitive_content',
+            message: 'The channel rejected this message as potentially sensitive content. Do not send unlawful content; if the request is legitimate, revise the wording before deciding whether to try once more.',
+            failType: 13,
+        };
+    }
+    if (attempt.status === 'failed') {
+        return {
+            kind: 'wechat_delivery_failed',
+            message: attempt.errorMessage || 'Channel message delivery failed',
+            ...(attempt.errorCode ? { code: attempt.errorCode } : {}),
+            ...(attempt.failType ? { failType: attempt.failType } : {}),
+        };
+    }
+    if (attempt.status === 'uncertain') {
+        return {
+            kind: 'uncertain_result',
+            message: attempt.errorMessage || 'Channel API result is uncertain',
+            ...(attempt.errorCode ? { code: attempt.errorCode } : {}),
+        };
+    }
+    return undefined;
+}
+function receipt(attempt) {
+    const status = attempt.status === 'failed'
+        ? 'failed'
+        : attempt.status === 'uncertain'
+            ? 'uncertain'
+            : 'accepted';
+    const error = attemptError(attempt);
+    return {
+        status,
+        attemptId: attempt.attemptId,
+        sendIndex: attempt.sendIndex,
+        type: attempt.type,
+        providerMessageId: attempt.providerMessageId,
+        ...(error ? { error } : {}),
+    };
+}
+function definitive(error) {
+    return error instanceof WecomApiError && error.code !== undefined;
+}
+export class WechatKfToolExecutor {
+    #store;
+    #api;
+    #media;
+    #observeMs;
+    #pollMs;
+    #sleep;
+    #logger;
+    #ilinkOffers;
+    #draining;
+    #rerun = false;
+    #closed = false;
+    constructor({ store, apiClient, mediaGateway, observeMs = 5_000, pollMs = 100, sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)), logger = console, ilinkOffers, }) {
+        this.#store = store;
+        this.#api = apiClient;
+        this.#media = mediaGateway;
+        this.#observeMs = Math.max(0, Math.min(Number(observeMs) || 0, 20_000));
+        this.#pollMs = Math.max(10, Math.min(Number(pollMs) || 100, 1_000));
+        this.#sleep = sleep;
+        this.#logger = logger;
+        this.#ilinkOffers = ilinkOffers;
+    }
+    async #payload(sessionToken, toolName, input) {
+        const session = this.#store.getAgentSession(sessionToken);
+        const artifactRef = String(input.mediaRef || '').startsWith('artifact:')
+            ? [{ ref: String(input.mediaRef), kind: 'image' }]
+            : [];
+        const intent = normalizeSendIntent(toolName, input, {
+            mediaCatalog: [
+                ...session.mediaCatalog.map(({ ref, kind }) => ({ ref, kind })),
+                ...artifactRef,
+            ],
+        });
+        let mediaId = '';
+        let metadata;
+        try {
+            if (intent.type === 'image') {
+                if (intent.mediaRef.startsWith('artifact:')) {
+                    const artifact = this.#store.getAgentArtifact(sessionToken, intent.mediaRef);
+                    metadata = artifact.metadata;
+                    mediaId = (await this.#media.upload({
+                        kind: 'image',
+                        bytes: artifact.bytes,
+                        filename: artifact.filename,
+                        contentType: artifact.contentType,
+                    })).media_id;
+                }
+                else {
+                    const source = session.mediaCatalog.find((item) => item.ref === intent.mediaRef);
+                    if (!source) {
+                        throw new AgentSessionError('The image reference is unavailable in this agent session', 'invalid_media_reference');
+                    }
+                    mediaId = await this.#media.cloneForSend({
+                        kind: 'image',
+                        sourceMediaId: source.mediaId,
+                        filename: source.filename,
+                    });
+                }
+            }
+            else if (intent.type === 'link' || intent.type === 'miniprogram') {
+                mediaId = await this.#media.getCardThumbnailMediaId();
+            }
+        }
+        catch (error) {
+            if (error instanceof AgentSessionError)
+                throw error;
+            throw new AgentSessionError(`Media preparation failed before send_msg was called: ${error instanceof Error ? error.message : String(error)}`, 'media_preparation_failed');
+        }
+        return {
+            type: intent.type,
+            payload: exactPayload(intent, mediaId),
+            ...(metadata ? { metadata } : {}),
+        };
+    }
+    async #observe(attemptId) {
+        const deadline = Date.now() + this.#observeMs;
+        let current = this.#store.getAttempt(attemptId);
+        if (!current)
+            throw new Error(`Missing WeChat attempt ${attemptId}`);
+        while (current.status === 'accepted' && Date.now() < deadline) {
+            await this.#sleep(Math.min(this.#pollMs, Math.max(1, deadline - Date.now())));
+            current = this.#store.getAttempt(attemptId);
+            if (!current)
+                throw new Error(`Missing WeChat attempt ${attemptId}`);
+        }
+        return current;
+    }
+    async #transmit(attempt, observe) {
+        let completed;
+        try {
+            if (!attempt.payload)
+                throw new Error('Pending channel attempt has no payload');
+            const result = await this.#api.sendPreparedMessage({
+                toUser: attempt.peerId,
+                openKfId: attempt.accountKey,
+                payload: attempt.payload,
+                messageId: attempt.clientMessageId,
+            });
+            const providerMessageId = String(result.msgid || '');
+            if (!providerMessageId) {
+                throw new Error('The channel API accepted the request without returning msgid');
+            }
+            completed = this.#store.completeSend(attempt.attemptId, {
+                providerMessageId,
+            });
+        }
+        catch (error) {
+            return definitive(error)
+                ? this.#store.failSend(attempt.attemptId, error)
+                : this.#store.markSendUncertain(attempt.attemptId, error);
+        }
+        return observe ? this.#observe(attempt.attemptId) : completed;
+    }
+    async #sendPrepared({ sessionToken, type, payload, metadata, }) {
+        const attempt = this.#store.reserveAgentSend({
+            sessionToken,
+            sentType: type,
+            payload,
+            metadata,
+        });
+        return receipt(await this.#transmit(attempt, true));
+    }
+    async execute(toolName, input) {
+        const sessionToken = String(input.session || '');
+        const session = this.#store.getAgentSession(sessionToken);
+        if (session.channel !== 'wechat_kf') {
+            throw new AgentSessionError('Agent session is bound to another channel', 'wrong_channel');
+        }
+        if (toolName === 'offer_weixin_bot_channel') {
+            if (!this.#ilinkOffers) {
+                throw new AgentSessionError('iLink channel invitations are unavailable', 'ilink_unavailable');
+            }
+            const offered = await this.#ilinkOffers.offer(sessionToken);
+            try {
+                const uploaded = await this.#media.upload({
+                    kind: 'image',
+                    bytes: offered.png,
+                    filename: 'weixin-ilink-login.png',
+                    contentType: 'image/png',
+                });
+                const result = await this.#sendPrepared({
+                    sessionToken,
+                    type: 'image',
+                    payload: { msgtype: 'image', image: { media_id: uploaded.media_id } },
+                    metadata: { tool: toolName, offerId: offered.offerId },
+                });
+                if (result.status === 'failed')
+                    this.#ilinkOffers.cancel(offered.offerId);
+                return result;
+            }
+            catch (error) {
+                this.#ilinkOffers.cancel(offered.offerId);
+                throw error;
+            }
+        }
+        const { session: _session, ...argumentsWithoutSession } = input;
+        const prepared = await this.#payload(sessionToken, toolName, argumentsWithoutSession);
+        return this.#sendPrepared({
+            sessionToken,
+            type: prepared.type,
+            payload: prepared.payload,
+            metadata: {
+                ...(prepared.metadata || {}),
+                tool: prepared.metadata ? 'generated_image' : toolName,
+            },
+        });
+    }
+    kick() {
+        if (this.#closed)
+            return Promise.resolve();
+        this.#rerun = true;
+        this.#draining ||= this.#runDrain().finally(() => {
+            this.#draining = undefined;
+            if (this.#rerun && !this.#closed)
+                void this.kick();
+        });
+        return this.waitForIdle();
+    }
+    async #runDrain() {
+        do {
+            this.#rerun = false;
+            await this.#drain();
+        } while (this.#rerun && !this.#closed);
+    }
+    async #drain() {
+        while (!this.#closed) {
+            const attempt = this.#store.beginNextSend('wechat_kf');
+            if (!attempt)
+                return;
+            const settled = await this.#transmit(attempt, false);
+            if (settled.status === 'accepted') {
+                this.#logger.info?.(`[wechat-kf-mcp] accepted type=${attempt.type} attempt=${attempt.attemptId}`);
+            }
+            else if (settled.status === 'failed') {
+                this.#logger.warn?.(`[wechat-kf-mcp] failed attempt=${attempt.attemptId}`);
+            }
+            else {
+                this.#logger.error?.(`[wechat-kf-mcp] uncertain attempt=${attempt.attemptId}`);
+            }
+        }
+    }
+    async waitForIdle() {
+        while (this.#draining)
+            await this.#draining;
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        await this.kick();
+        this.#closed = true;
+    }
+    abort() {
+        this.#closed = true;
+        this.#rerun = false;
+    }
+}

package/dist/src/mcp/wechat-kf-server.js

@@ -0,0 +1,208 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as z from 'zod/v4';
+import { KINTIO_VERSION } from '../version.js';
+import { WechatKfToolExecutor, } from './wechat-kf-executor.js';
+const TOOL_ANNOTATIONS = Object.freeze({
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+});
+const SEND_TYPES = [
+    'text',
+    'image',
+    'link',
+    'miniprogram',
+    'location',
+];
+const ATTEMPT_ID = /^sa_[A-Za-z0-9_-]+$/u;
+const SAFE_CODE = /^[A-Za-z0-9_.:-]{1,128}$/u;
+const ERROR_KINDS = [
+    'sensitive_content',
+    'wechat_delivery_failed',
+    'uncertain_result',
+    'invalid_agent_session',
+    'closed_agent_session',
+    'expired_agent_session',
+    'stale_agent_session',
+    'send_budget_exceeded',
+    'wrong_channel',
+    'invalid_media_reference',
+    'media_preparation_failed',
+    'ilink_unavailable',
+    'invalid_send_intent',
+    'invalid_media_catalog',
+    'unsafe_media_catalog',
+    'unsupported_send_type',
+    'wechat_tool_error',
+];
+const SAFE_ERROR_MESSAGES = {
+    sensitive_content: 'The channel rejected this message as potentially sensitive content. Do not send unlawful content; if the request is legitimate, revise the wording before deciding whether to try once more.',
+    wechat_delivery_failed: 'The channel rejected this message.',
+    uncertain_result: 'The delivery result is uncertain and the message may already have been sent. Do not retry merely because the outcome is unknown.',
+    invalid_agent_session: 'The conversation capability is invalid. Wait for the host runtime to provide a new session.',
+    closed_agent_session: 'The conversation session is closed. Wait for the host runtime to provide a new session.',
+    expired_agent_session: 'The conversation session expired. Wait for the host runtime to provide a new session.',
+    stale_agent_session: 'This conversation direction is stale. Continue from the participant\'s latest message.',
+    send_budget_exceeded: 'The reply budget for this conversation is exhausted. Stop sending.',
+    wrong_channel: 'This session does not belong to the WeChat KF adapter.',
+    invalid_media_reference: 'This conversation cannot use the requested image reference.',
+    media_preparation_failed: 'Media preparation failed before any message was sent.',
+    ilink_unavailable: 'An independent iLink Bot conversation cannot be established right now.',
+    invalid_send_intent: 'The message parameters do not satisfy the adapter requirements.',
+    invalid_media_catalog: 'The conversation media catalog is invalid.',
+    unsafe_media_catalog: 'The conversation media catalog contains unsafe fields.',
+    unsupported_send_type: 'This adapter does not support the requested message type.',
+    wechat_tool_error: 'The adapter tool could not execute this operation.',
+};
+const EXECUTOR_ERROR_SCHEMA = z.strictObject({
+    kind: z.string(),
+    message: z.string(),
+    code: z.union([z.string(), z.number()]).optional(),
+    failType: z.number().int().optional(),
+});
+const EXECUTOR_RECEIPT_SCHEMA = z.strictObject({
+    status: z.enum(['accepted', 'failed', 'uncertain']),
+    attemptId: z.string().regex(ATTEMPT_ID),
+    sendIndex: z.number().int().min(0).max(999),
+    type: z.enum(SEND_TYPES),
+    providerMessageId: z.string().max(512),
+    error: EXECUTOR_ERROR_SCHEMA.optional(),
+});
+const ERROR_OUTPUT_SCHEMA = z.strictObject({
+    kind: z.enum(ERROR_KINDS),
+    message: z.string(),
+    code: z.union([
+        z.string().regex(SAFE_CODE),
+        z.number().finite(),
+    ]).optional(),
+    failType: z.number().int().nonnegative().optional(),
+});
+const RECEIPT_SCHEMA = z.strictObject({
+    status: z.enum(['accepted', 'failed', 'uncertain']),
+    attemptId: z.string().max(128),
+    sendIndex: z.number().int().min(-1).max(999),
+    type: z.enum(SEND_TYPES),
+    providerMessageId: z.string().max(512),
+    error: ERROR_OUTPUT_SCHEMA.optional(),
+});
+function response(result, isError = false) {
+    return {
+        ...(isError ? { isError: true } : {}),
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+        structuredContent: result,
+    };
+}
+function safeErrorKind(status, kind, failType = 0) {
+    if (status === 'failed' && failType === 13)
+        return 'sensitive_content';
+    if (ERROR_KINDS.includes(kind || '')) {
+        return kind;
+    }
+    return status === 'uncertain' ? 'uncertain_result' : 'wechat_delivery_failed';
+}
+function safeCode(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    return typeof value === 'string' && SAFE_CODE.test(value) ? value : undefined;
+}
+function safeReceipt(value) {
+    const parsed = EXECUTOR_RECEIPT_SCHEMA.parse(value);
+    const { error, ...base } = parsed;
+    if (base.status === 'accepted')
+        return base;
+    const failType = Number.isInteger(error?.failType) && Number(error?.failType) >= 0
+        ? Number(error?.failType)
+        : 0;
+    const kind = safeErrorKind(base.status, error?.kind, failType);
+    const code = safeCode(error?.code);
+    return {
+        ...base,
+        error: {
+            kind,
+            message: SAFE_ERROR_MESSAGES[kind],
+            ...(code !== undefined ? { code } : {}),
+            ...(failType ? { failType } : {}),
+        },
+    };
+}
+function toolFailure(error, type) {
+    const errorCode = error && typeof error === 'object' && 'code' in error
+        ? String(error.code || '')
+        : '';
+    const kind = ERROR_KINDS.includes(errorCode)
+        ? errorCode
+        : 'wechat_tool_error';
+    const result = {
+        status: 'failed',
+        attemptId: '',
+        sendIndex: -1,
+        type,
+        providerMessageId: '',
+        error: { kind, message: SAFE_ERROR_MESSAGES[kind] },
+    };
+    return response(result, true);
+}
+function toolResult(result) {
+    const safe = safeReceipt(result);
+    return response({ ...safe }, safe.status === 'failed');
+}
+function toolType(name) {
+    if (name === 'offer_weixin_bot_channel' || name === 'send_image')
+        return 'image';
+    const type = name.replace(/^send_/u, '');
+    return SEND_TYPES.includes(type)
+        ? type
+        : 'text';
+}
+function register(server, executor, name, definition) {
+    server.registerTool(name, {
+        ...definition,
+        outputSchema: RECEIPT_SCHEMA,
+        annotations: TOOL_ANNOTATIONS,
+    }, async (input) => {
+        try {
+            return toolResult(await executor.execute(name, input));
+        }
+        catch (error) {
+            return toolFailure(error, toolType(name));
+        }
+    });
+}
+const SESSION = z.string().regex(/^ws_[A-Za-z0-9_-]{32}$/u);
+const TOOL_DEFINITIONS = [
+    [
+        'offer_weixin_bot_channel',
+        'Offer an optional independent Weixin iLink Bot channel by sending a login QR image to the bound conversation. Use only after the user clearly asks to switch or establish that channel.',
+        {},
+    ],
+    ['send_text', 'Send one WeChat text message.', { content: z.string().min(1) }],
+    ['send_image', 'Send one available image referenced by media:N or artifact:N.', {
+            mediaRef: z.string().regex(/^(?:media|artifact):(?:0|[1-9]\d?)$/u),
+        }],
+    ['send_link', 'Send one native WeChat link card.', {
+            title: z.string().min(1), description: z.string(), url: z.string().url(),
+        }],
+    ['send_miniprogram', 'Send one verified WeChat mini-program card.', {
+            appId: z.string().regex(/^wx[A-Za-z0-9]{16}$/u),
+            title: z.string().min(1), pagePath: z.string().min(1).max(1024),
+            sourceUrl: z.string().url(),
+        }],
+    ['send_location', 'Send one native WeChat location card.', {
+            name: z.string().min(1), address: z.string().min(1),
+            latitude: z.number().min(-90).max(90),
+            longitude: z.number().min(-180).max(180),
+        }],
+];
+export function createWechatKfMcpServer(executor) {
+    const server = new McpServer({ name: 'wechat-kf-tools', version: KINTIO_VERSION }, {
+        instructions: 'These tools execute real WeChat KF channel API calls for the bound conversation. accepted means the API accepted the request, not confirmed client delivery. uncertain means the message may already have been sent and must not be repeated merely because the outcome is unknown. The server never selects another recipient or retries automatically.',
+    });
+    for (const [name, description, inputSchema] of TOOL_DEFINITIONS) {
+        register(server, executor, name, {
+            description,
+            inputSchema: { session: SESSION, ...inputSchema },
+        });
+    }
+    return server;
+}

package/dist/src/routes/wecom.js

@@ -0,0 +1,89 @@
+import { bodyLimit } from 'hono/body-limit';
+import { extractXmlTag } from '../lib/xml.js';
+const MAX_BODY_BYTES = 1024 * 1024;
+function getCallbackParameters(context, includeEchoString) {
+    const parameters = {
+        signature: context.req.query('msg_signature') || '',
+        timestamp: context.req.query('timestamp') || '',
+        nonce: context.req.query('nonce') || '',
+        encrypted: '',
+    };
+    if (includeEchoString) {
+        parameters.encrypted = context.req.query('echostr') || '';
+    }
+    return parameters;
+}
+function hasAuthenticationQuery(context) {
+    return (context.req.query('msg_signature') !== undefined ||
+        context.req.query('echostr') !== undefined);
+}
+export function registerWecomRoutes(app, { wecomCrypto, logger, messageProcessor, }) {
+    app.get('/', (context) => {
+        if (!hasAuthenticationQuery(context)) {
+            return context.text('hello world');
+        }
+        const parameters = getCallbackParameters(context, true);
+        const { signature, timestamp, nonce, encrypted } = parameters;
+        if (!signature || !timestamp || !nonce || !encrypted) {
+            return context.text('missing callback parameters', 400);
+        }
+        if (!wecomCrypto.verifySignature(signature, timestamp, nonce, encrypted)) {
+            return context.text('invalid signature', 403);
+        }
+        try {
+            const { message } = wecomCrypto.decryptMessage(encrypted);
+            logger.info('[wecom] callback URL verification succeeded');
+            return context.text(message);
+        }
+        catch (error) {
+            logger.error(`[wecom] callback URL verification failed: ${error instanceof Error ? error.message : String(error)}`);
+            return context.text('invalid encrypted payload', 400);
+        }
+    });
+    app.post('/', bodyLimit({
+        maxSize: MAX_BODY_BYTES,
+        onError: (context) => context.text('request body is too large', 413),
+    }), async (context) => {
+        const parameters = getCallbackParameters(context, false);
+        try {
+            const body = await context.req.text();
+            const encrypted = extractXmlTag(body, 'Encrypt');
+            if (!parameters.signature ||
+                !parameters.timestamp ||
+                !parameters.nonce ||
+                !encrypted) {
+                return context.text('invalid callback request', 400);
+            }
+            if (!wecomCrypto.verifySignature(parameters.signature, parameters.timestamp, parameters.nonce, encrypted)) {
+                return context.text('invalid signature', 403);
+            }
+            const { message } = wecomCrypto.decryptMessage(encrypted);
+            const event = extractXmlTag(message, 'Event') || 'unknown';
+            const openKfId = extractXmlTag(message, 'OpenKfId') || 'unknown';
+            const callbackToken = extractXmlTag(message, 'Token');
+            logger.info(`[wecom] accepted callback event=${event}`);
+            if (event === 'kf_msg_or_event' && messageProcessor) {
+                if (callbackToken && openKfId !== 'unknown') {
+                    let accepted = false;
+                    try {
+                        accepted = messageProcessor.enqueue({ callbackToken, openKfId });
+                    }
+                    catch (error) {
+                        logger.error(`[wecom] callback sync registration failed: ${error instanceof Error ? error.message : String(error)}`);
+                        return context.text('service unavailable', 503);
+                    }
+                    if (!accepted)
+                        return context.text('service unavailable', 503);
+                }
+                else {
+                    logger.warn?.('[wecom] callback did not contain Token and OpenKfId; message sync skipped');
+                }
+            }
+            return context.text('success');
+        }
+        catch (error) {
+            logger.error(`[wecom] callback processing failed: ${error instanceof Error ? error.message : String(error)}`);
+            return context.text('invalid callback request', 400);
+        }
+    });
+}