@kin-tio/cli 0.6.0

package/dist/src/config.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseEnv } from 'node:util';
+import { isPathInside } from './lib/path-identity.js';
+export function resolveProjectRoot(moduleUrl) {
+    const moduleDirectory = path.dirname(fileURLToPath(moduleUrl));
+    const parentDirectory = path.dirname(moduleDirectory);
+    return path.basename(parentDirectory) === 'dist'
+        ? path.dirname(parentDirectory)
+        : parentDirectory;
+}
+export const KINTIO_PACKAGE_ROOT = resolveProjectRoot(import.meta.url);
+export const FORCE_ABORT_TIMEOUT_MS = 5_000;
+const MAX_SHUTDOWN_TIMEOUT_MS = 120_000;
+export const WORKER_GRACEFUL_TIMEOUT_MS = MAX_SHUTDOWN_TIMEOUT_MS + FORCE_ABORT_TIMEOUT_MS + 2_000;
+export const DAEMON_STOP_TIMEOUT_MS = WORKER_GRACEFUL_TIMEOUT_MS + 5_000 + 3_000;
+export function parseStartTimeout(value) {
+    const timeout = Number(value || 30_000);
+    if (!Number.isInteger(timeout) || timeout < 1_000 || timeout > 120_000) {
+        throw new Error('KINTIO_START_TIMEOUT_MS must be an integer between 1000 and 120000');
+    }
+    return timeout;
+}
+function resolveInstanceRoot(environment = process.env, fallback = path.join(os.homedir(), '.kintio')) {
+    return path.resolve(environment.KINTIO_HOME || fallback);
+}
+export function resolveStateFiles(environment = process.env, root = resolveInstanceRoot(environment), fileExists = fs.existsSync) {
+    const configuredDatabaseFile = environment.KINTIO_DB_FILE ||
+        environment.TALKFERRY_DB_FILE ||
+        environment.HARNESS_DB_FILE ||
+        environment.WECOM_DB_FILE;
+    const defaultDatabaseFile = path.join(root, 'data/kintio.sqlite');
+    const talkFerryDatabaseFile = path.join(root, 'data/talkferry.sqlite');
+    const legacyDatabaseFile = path.join(root, 'data/wecom.sqlite');
+    const existingDefaultFiles = [
+        defaultDatabaseFile,
+        talkFerryDatabaseFile,
+        legacyDatabaseFile,
+    ].filter(fileExists);
+    if (!configuredDatabaseFile && existingDefaultFiles.length > 1) {
+        const names = existingDefaultFiles.map((file) => path.relative(root, file)).join(', ');
+        throw new Error(`Multiple default state databases exist (${names}); set KINTIO_DB_FILE explicitly`);
+    }
+    const databaseFile = path.resolve(root, configuredDatabaseFile || existingDefaultFiles[0] || defaultDatabaseFile);
+    const originalDatabaseSelection = databaseFile === legacyDatabaseFile ||
+        (!environment.KINTIO_DB_FILE &&
+            !environment.TALKFERRY_DB_FILE &&
+            Boolean(environment.HARNESS_DB_FILE || environment.WECOM_DB_FILE));
+    const talkFerryDatabaseSelection = !originalDatabaseSelection && (databaseFile === talkFerryDatabaseFile ||
+        (!environment.KINTIO_DB_FILE && Boolean(environment.TALKFERRY_DB_FILE)));
+    return Object.freeze({
+        databaseFile,
+        lockFile: path.join(path.dirname(databaseFile), originalDatabaseSelection
+            ? 'wecom.lock'
+            : talkFerryDatabaseSelection
+                ? 'talkferry.lock'
+                : 'kintio.lock'),
+    });
+}
+function loadEnvironmentFile(filePath, environment) {
+    try {
+        const parsed = parseEnv(fs.readFileSync(filePath, 'utf8'));
+        for (const [name, value] of Object.entries(parsed)) {
+            const key = process.platform === 'win32' ? name.toUpperCase() : name;
+            if (environment[key] === undefined)
+                environment[key] = value;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function copyEnvironment(environment) {
+    if (process.platform !== 'win32')
+        return { ...environment };
+    return Object.fromEntries(Object.entries(environment).map(([name, value]) => [name.toUpperCase(), value]));
+}
+function parsePort(value) {
+    const port = Number(value ?? 8888);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error('PORT must be an integer between 1 and 65535');
+    }
+    return port;
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === '') {
+        return fallback;
+    }
+    if (/^(1|true|yes|on)$/i.test(value)) {
+        return true;
+    }
+    if (/^(0|false|no|off)$/i.test(value)) {
+        return false;
+    }
+    throw new Error(`Invalid boolean value: ${value}`);
+}
+function parsePositiveInteger(value, fallback, name, maximum = Number.MAX_SAFE_INTEGER) {
+    const parsed = Number(value ?? fallback);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    if (parsed > maximum)
+        throw new Error(`${name} must not exceed ${maximum}`);
+    return parsed;
+}
+function parseAllowedUserIds(value) {
+    const parsed = String(value || '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (parsed.includes('*')) {
+        throw new Error('WECOM_ALLOWED_USER_IDS does not support wildcard entries');
+    }
+    return Object.freeze(parsed);
+}
+function parseBoundedText(value, fallback, name, maxBytes) {
+    const parsed = value === undefined ? fallback : String(value);
+    if (Buffer.byteLength(parsed, 'utf8') > maxBytes) {
+        throw new Error(`${name} must not exceed ${maxBytes} UTF-8 bytes`);
+    }
+    return parsed;
+}
+export function createConfig(environment = process.env, root, platform = process.platform) {
+    environment = copyEnvironment(environment);
+    const instanceRoot = path.resolve(root || resolveInstanceRoot(environment));
+    const port = parsePort(environment.PORT);
+    const callbackToken = environment.WECOM_CALLBACK_TOKEN || '';
+    const encodingAesKey = environment.WECOM_ENCODING_AES_KEY || '';
+    const corpId = (environment.WECOM_CORP_ID || '').trim();
+    const kfSecret = (environment.WECOM_KF_SECRET || '').trim();
+    if (Boolean(callbackToken) !== Boolean(encodingAesKey)) {
+        throw new Error('WECOM_CALLBACK_TOKEN and WECOM_ENCODING_AES_KEY must be configured together');
+    }
+    if (callbackToken && !/^[A-Za-z0-9]{1,32}$/.test(callbackToken)) {
+        throw new Error('WECOM_CALLBACK_TOKEN must contain 1 to 32 letters or digits');
+    }
+    if (encodingAesKey && !/^[A-Za-z0-9]{43}$/.test(encodingAesKey)) {
+        throw new Error('WECOM_ENCODING_AES_KEY must contain 43 letters or digits');
+    }
+    if (Boolean(corpId) !== Boolean(kfSecret)) {
+        throw new Error('WECOM_CORP_ID and WECOM_KF_SECRET must be configured together');
+    }
+    const apiEnabled = Boolean(corpId && kfSecret);
+    if (apiEnabled && !String(environment.ILINK_ENABLED ?? '').trim()) {
+        throw new Error('ILINK_ENABLED must be explicitly true or false when WeChat KF API is enabled');
+    }
+    const ilinkEnabled = parseBoolean(environment.ILINK_ENABLED, false);
+    const codexEnabled = parseBoolean(environment.CODEX_ENABLED, apiEnabled || ilinkEnabled);
+    const ilinkStorageKey = String(environment.ILINK_STORAGE_KEY || '').trim();
+    if (ilinkStorageKey && !/^[A-Za-z0-9_-]{43}$/u.test(ilinkStorageKey)) {
+        throw new Error('ILINK_STORAGE_KEY must be a canonical 32-byte base64url value');
+    }
+    const { databaseFile, lockFile } = resolveStateFiles(environment, instanceRoot);
+    const codexWorkingDirectory = path.resolve(instanceRoot, environment.CODEX_WORKING_DIRECTORY ||
+        'codex-workspace');
+    const ilinkStorageKeyFile = path.resolve(instanceRoot, environment.ILINK_STORAGE_KEY_FILE ||
+        path.join(path.dirname(databaseFile), 'ilink-storage.key'));
+    const codexImageTempDirectory = path.resolve(instanceRoot, environment.CODEX_IMAGE_TMP_DIR ||
+        'data/codex-input');
+    if (platform === 'win32') {
+        for (const [name, filePath] of [
+            ['KINTIO_DB_FILE', databaseFile],
+            ['Kintio state lock', lockFile],
+            ['ILINK_STORAGE_KEY_FILE', ilinkStorageKeyFile],
+            ['CODEX_IMAGE_TMP_DIR', codexImageTempDirectory],
+        ]) {
+            if (!isPathInside(instanceRoot, filePath)) {
+                throw new Error(`${name} must stay inside KINTIO_HOME on Windows`);
+            }
+        }
+    }
+    const apiTimeoutMs = parsePositiveInteger(environment.WECOM_API_TIMEOUT_MS, 10_000, 'WECOM_API_TIMEOUT_MS', 120_000);
+    const shutdownTimeoutMs = parsePositiveInteger(environment.SHUTDOWN_TIMEOUT_MS, 10_000, 'SHUTDOWN_TIMEOUT_MS', MAX_SHUTDOWN_TIMEOUT_MS);
+    if (shutdownTimeoutMs < 1_000) {
+        throw new Error('SHUTDOWN_TIMEOUT_MS must be at least 1000');
+    }
+    return Object.freeze({
+        port,
+        wecom: Object.freeze({
+            callbackToken,
+            encodingAesKey,
+            expectedReceiveId: environment.WECOM_RECEIVE_ID || corpId,
+            api: Object.freeze({
+                enabled: apiEnabled,
+                corpId,
+                kfSecret,
+                baseUrl: environment.WECOM_API_BASE_URL || 'https://qyapi.weixin.qq.com',
+                timeoutMs: apiTimeoutMs,
+                observeMs: parsePositiveInteger(environment.WECOM_MCP_OBSERVE_MS, 5_000, 'WECOM_MCP_OBSERVE_MS', 20_000),
+            }),
+            allowedUserIds: parseAllowedUserIds(environment.WECOM_ALLOWED_USER_IDS),
+            authorization: Object.freeze({
+                trigger: parseBoundedText(environment.WECOM_AUTH_TRIGGER, '', 'WECOM_AUTH_TRIGGER', 128),
+                requiredConsecutive: parsePositiveInteger(environment.WECOM_AUTH_TRIGGER_COUNT, 3, 'WECOM_AUTH_TRIGGER_COUNT'),
+                confirmationText: parseBoundedText(environment.WECOM_AUTH_CONFIRMATION, 'Code accepted. You can continue the conversation.', 'WECOM_AUTH_CONFIRMATION', 2048),
+            }),
+        }),
+        ilink: Object.freeze({
+            enabled: ilinkEnabled,
+            storageKey: ilinkStorageKey,
+            storageKeyFile: ilinkStorageKeyFile,
+            baseUrl: environment.ILINK_BASE_URL || 'https://ilinkai.weixin.qq.com/',
+            apiTimeoutMs: parsePositiveInteger(environment.ILINK_API_TIMEOUT_MS, 15_000, 'ILINK_API_TIMEOUT_MS', 120_000),
+            longPollTimeoutMs: parsePositiveInteger(environment.ILINK_LONG_POLL_TIMEOUT_MS, 35_000, 'ILINK_LONG_POLL_TIMEOUT_MS', 120_000),
+            maxAccounts: parsePositiveInteger(environment.ILINK_MAX_ACCOUNTS, 20, 'ILINK_MAX_ACCOUNTS', 1_000),
+        }),
+        state: Object.freeze({
+            databaseFile,
+            lockFile,
+            shutdownTimeoutMs,
+        }),
+        codex: Object.freeze({
+            enabled: codexEnabled,
+            imageTempDirectory: codexImageTempDirectory,
+            workingDirectory: codexWorkingDirectory,
+            generatedImageDirectory: path.join(codexWorkingDirectory, 'generated_images'),
+        }),
+    });
+}
+export function loadConfig(options = {}) {
+    const environment = copyEnvironment(options.environment || process.env);
+    const configuredEnvFile = options.envFile || environment.KINTIO_CONFIG_FILE;
+    const defaultRoot = path.join(path.resolve(options.homeDirectory || os.homedir()), '.kintio');
+    const initialRoot = path.resolve(options.root ||
+        environment.KINTIO_HOME ||
+        (configuredEnvFile
+            ? path.dirname(path.resolve(configuredEnvFile))
+            : defaultRoot));
+    const envFile = path.resolve(configuredEnvFile || path.join(initialRoot, '.env'));
+    loadEnvironmentFile(envFile, environment);
+    const root = path.resolve(options.root || environment.KINTIO_HOME || initialRoot);
+    return createConfig(environment, root);
+}

package/dist/src/domain/message.js

@@ -0,0 +1,23 @@
+export const MESSAGE_ORIGINS = {
+    CUSTOMER: 'customer',
+    SYSTEM: 'system',
+    UNKNOWN: 'unknown',
+};
+export const COMMON_MESSAGE_TYPES = {
+    TEXT: 'text',
+    EVENT: 'event',
+    UNKNOWN: 'unknown',
+};
+export function isProcessableCustomerMessage(message) {
+    return message.origin === MESSAGE_ORIGINS.CUSTOMER &&
+        Boolean(message.type.trim()) &&
+        message.type !== COMMON_MESSAGE_TYPES.EVENT &&
+        message.type !== COMMON_MESSAGE_TYPES.UNKNOWN;
+}
+export function isSystemEvent(message) {
+    return message.origin === MESSAGE_ORIGINS.SYSTEM &&
+        message.type === COMMON_MESSAGE_TYPES.EVENT;
+}
+export function renderMessageForAgent(message) {
+    return String(message.summary || message.text || '[Channel message: no readable summary]');
+}

package/dist/src/domain/send-contract.js

@@ -0,0 +1,205 @@
+import { isIP } from 'node:net';
+const SEND_TYPES = [
+    'text',
+    'image',
+    'link',
+    'miniprogram',
+    'location',
+];
+export const SEND_TOOL_NAMES = [
+    'send_text',
+    'send_image',
+    'send_link',
+    'send_miniprogram',
+    'send_location',
+];
+const TOOL_TYPES = new Map(SEND_TOOL_NAMES.map((name, index) => [name, SEND_TYPES[index]]));
+const MEDIA_REFERENCE = /^(?:media|artifact):(?:0|[1-9]\d?)$/u;
+const MAX_TEXT_BYTES = 2048;
+export class SendContractError extends Error {
+    code;
+    constructor(message, code = 'invalid_send_intent') {
+        super(message);
+        this.name = 'SendContractError';
+        this.code = code;
+    }
+}
+function fail(message, code) {
+    throw new SendContractError(message, code);
+}
+function requiredText(value, label, maxBytes) {
+    const result = String(value ?? '').trim();
+    if (!result)
+        fail(`${label} cannot be empty`);
+    if (Buffer.byteLength(result, 'utf8') > maxBytes) {
+        fail(`${label} exceeds ${maxBytes} UTF-8 bytes`);
+    }
+    return result;
+}
+function optionalText(value, label, maxBytes) {
+    const result = String(value ?? '').trim();
+    if (Buffer.byteLength(result, 'utf8') > maxBytes) {
+        fail(`${label} exceeds ${maxBytes} UTF-8 bytes`);
+    }
+    return result;
+}
+function privateIpv4(hostname) {
+    const octets = hostname.split('.').map(Number);
+    if (octets.length !== 4 || octets.some((item) => !Number.isInteger(item))) {
+        return false;
+    }
+    const a = octets[0];
+    const b = octets[1];
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 0) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && [18, 19, 51].includes(b)) ||
+        (a === 203 && b === 0) ||
+        a >= 224);
+}
+function privateIpv6(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+    if (normalized === '::' || normalized === '::1')
+        return true;
+    if (/^(?:fc|fd|fe[89ab])/u.test(normalized))
+        return true;
+    if (normalized.startsWith('::ffff:'))
+        return true;
+    const mapped = normalized.match(/(?:^|:)ffff:(\d+\.\d+\.\d+\.\d+)$/u);
+    return mapped?.[1] ? privateIpv4(mapped[1]) : false;
+}
+function publicHttpUrl(value, label) {
+    let url;
+    try {
+        url = new URL(String(value || ''));
+    }
+    catch {
+        fail(`${label} must be a valid public HTTP(S) URL`);
+    }
+    const hostname = url.hostname.toLowerCase();
+    const ipVersion = isIP(hostname.replace(/^\[|\]$/gu, ''));
+    const forbiddenName = !ipVersion &&
+        (!hostname.includes('.') ||
+            hostname === 'localhost' ||
+            hostname.endsWith('.localhost') ||
+            hostname.endsWith('.local') ||
+            hostname.endsWith('.internal'));
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        forbiddenName ||
+        (ipVersion === 4 && privateIpv4(hostname)) ||
+        (ipVersion === 6 && privateIpv6(hostname))) {
+        fail(`${label} must be a valid public HTTP(S) URL`);
+    }
+    if (Buffer.byteLength(url.toString(), 'utf8') > 2048) {
+        fail(`${label} exceeds 2048 UTF-8 bytes`);
+    }
+    return url.toString();
+}
+export function normalizeMediaCatalog(mediaCatalog = []) {
+    if (!Array.isArray(mediaCatalog) || mediaCatalog.length > 100) {
+        fail('Media catalog must contain at most 100 entries', 'invalid_media_catalog');
+    }
+    const seen = new Set();
+    return Object.freeze(mediaCatalog.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            fail('Media catalog entries must be objects', 'invalid_media_catalog');
+        }
+        const record = item;
+        const extra = Object.keys(record).filter((key) => !['ref', 'kind'].includes(key));
+        if (extra.length) {
+            fail(`Media catalog must not expose ${extra.join(', ')}`, 'unsafe_media_catalog');
+        }
+        const ref = String(record.ref || '');
+        const kind = String(record.kind || '');
+        if (!MEDIA_REFERENCE.test(ref) || kind !== 'image' || seen.has(ref)) {
+            fail('Media catalog requires unique media:N image references', 'invalid_media_catalog');
+        }
+        seen.add(ref);
+        return Object.freeze({ ref, kind: 'image' });
+    }));
+}
+function normalizeText(input) {
+    return Object.freeze({
+        type: 'text',
+        content: requiredText(input?.content, 'Text content', MAX_TEXT_BYTES),
+    });
+}
+function normalizeImage(input, mediaCatalog, allowUnboundMediaReference) {
+    const mediaRef = String(input?.mediaRef || '');
+    if (!MEDIA_REFERENCE.test(mediaRef)) {
+        fail('Image reference must use media:N', 'invalid_media_reference');
+    }
+    if (!allowUnboundMediaReference &&
+        !mediaCatalog.some((entry) => entry.ref === mediaRef)) {
+        fail('Image reference is not available in this turn', 'invalid_media_reference');
+    }
+    return Object.freeze({ type: 'image', mediaRef });
+}
+function normalizeLink(input) {
+    return Object.freeze({
+        type: 'link',
+        title: requiredText(input?.title, 'Link title', 128),
+        description: optionalText(input?.description, 'Link description', 512),
+        url: publicHttpUrl(input?.url, 'Link URL'),
+    });
+}
+function normalizeMiniProgram(input) {
+    const appId = String(input?.appId || '').trim();
+    if (!/^wx[A-Za-z0-9]{16}$/u.test(appId)) {
+        fail('Mini-program appId must use wx followed by 16 letters or digits');
+    }
+    const pagePath = requiredText(input?.pagePath, 'Mini-program pagePath', 1024);
+    if (/^[a-z][a-z\d+.-]*:\/\//iu.test(pagePath) ||
+        pagePath.includes('..') ||
+        /[\u0000-\u001f\u007f]/u.test(pagePath)) {
+        fail('Mini-program pagePath is invalid');
+    }
+    return Object.freeze({
+        type: 'miniprogram',
+        appId,
+        title: requiredText(input?.title, 'Mini-program title', 64),
+        pagePath,
+        sourceUrl: publicHttpUrl(input?.sourceUrl, 'Mini-program source URL'),
+    });
+}
+function normalizeLocation(input) {
+    const latitude = Number(input?.latitude);
+    const longitude = Number(input?.longitude);
+    if (!Number.isFinite(latitude) || latitude < -90 || latitude > 90) {
+        fail('Location latitude must be between -90 and 90');
+    }
+    if (!Number.isFinite(longitude) || longitude < -180 || longitude > 180) {
+        fail('Location longitude must be between -180 and 180');
+    }
+    return Object.freeze({
+        type: 'location',
+        name: requiredText(input?.name, 'Location name', 128),
+        address: requiredText(input?.address, 'Location address', 512),
+        latitude,
+        longitude,
+    });
+}
+export function normalizeSendIntent(typeOrToolName, input, options = {}) {
+    const type = TOOL_TYPES.get(typeOrToolName) || String(typeOrToolName || '');
+    if (!SEND_TYPES.includes(type)) {
+        fail(`Unsupported send type: ${type || 'unknown'}`, 'unsupported_send_type');
+    }
+    const mediaCatalog = normalizeMediaCatalog(options.mediaCatalog || []);
+    if (type === 'text')
+        return normalizeText(input);
+    if (type === 'image') {
+        return normalizeImage(input, mediaCatalog, options.allowUnboundMediaReference === true);
+    }
+    if (type === 'link')
+        return normalizeLink(input);
+    if (type === 'miniprogram')
+        return normalizeMiniProgram(input);
+    return normalizeLocation(input);
+}