@kin-tio/cli 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ This file records important user-visible changes after the first public release.
 
 ## Unreleased
 
+## 0.7.1
+
+- Made `kintio ilink start` use the managed background daemon by default while
+  retaining `--foreground` for external service managers, simplified
+  `kintio ilink list` to reusable provider account IDs, rejected Node.js below
+  24 before application startup, and added sanitized Codex request diagnostics
+  ([#65](https://github.com/Gkxie/kintio/issues/65)).
+
 ## 0.7.0
 
 - Added `kintio ilink login`, which reuses the iLink enrollment state machine

package/README.md

@@ -78,7 +78,8 @@ kintio ilink start
 ```
 
 `ilink login` performs one encrypted enrollment, starts no listener, and exits. `ilink start` then runs provider
-polling and the host Agent in the foreground without Hono or a TCP listener. Both commands
+polling and the host Agent through the background daemon without Hono or a TCP listener.
+Use `--foreground` only when a service manager needs to own the process. Both commands
 use `~/.kintio` by default and accept `--home`. With multiple accounts, use `ilink list`
 and pass the displayed provider ID or account key through `--account`. Repeated `start`
 commands add accounts to the live runtime; `stop` removes one.

package/README.zh-CN.md

@@ -54,7 +54,8 @@ kintio ilink start
 ```
 
 `ilink login` 完成一次扫码、加密保存凭据后退出，不会自行启动监听；`ilink start` 不启动 Hono 或 TCP 端口，
-只以前台方式运行 iLink 长轮询和宿主 Agent。两者默认使用 `~/.kintio`。
+而是通过后台守护进程运行 iLink 长轮询和宿主 Agent。由外部进程管理器托管时可显式使用
+`--foreground`。两者默认使用 `~/.kintio`。
 存在多个账号时，先用 `kintio ilink list` 查看账号，再通过 `--account` 指定
 `start`、`stop` 或 `delete` 的目标；正在运行时可继续执行 `start` 增加监听账号。
 

package/bin/kintio.js

@@ -1,3 +1,13 @@
 #!/usr/bin/env node
 
-await import('../dist/cli.js');
+const currentNode = process.versions.node;
+const nodeMajor = Number.parseInt(currentNode.split('.')[0] || '', 10);
+if (!Number.isSafeInteger(nodeMajor) || nodeMajor < 24) {
+  process.stderr.write(
+    `Kintio requires Node.js 24 or newer; current runtime is v${currentNode}.\n` +
+    'Install Node.js 24+, then reinstall @kin-tio/cli in that Node environment.\n',
+  );
+  process.exitCode = 1;
+} else {
+  await import('../dist/cli.js');
+}

package/dist/daemon.js

@@ -4,13 +4,18 @@ import { resolveProjectRoot } from './src/config.js';
 import { runNativeDaemon } from './src/runtime/native-daemon.js';
 const home = process.env.KINTIO_HOME;
 const configFile = process.env.KINTIO_CONFIG_FILE;
+const mode = process.env.KINTIO_DAEMON_MODE || 'service';
 if (!home || !configFile) {
     throw new Error('KINTIO_HOME and KINTIO_CONFIG_FILE are required for daemon mode');
 }
+if (mode !== 'service' && mode !== 'ilink') {
+    throw new Error(`Unsupported Kintio daemon mode: ${mode}`);
+}
 try {
     await runNativeDaemon({
         home: path.resolve(home),
         configFile: path.resolve(configFile),
+        mode,
         packageRoot: resolveProjectRoot(import.meta.url),
     });
 }

package/dist/ilink.js

@@ -0,0 +1,53 @@
+import { KINTIO_PACKAGE_ROOT, loadIlinkRuntimeConfig, } from './src/config.js';
+import { startIlinkCliRuntime } from './src/ilink/cli-start.js';
+import { installManagedSkill } from './src/runtime/managed-skill.js';
+const config = loadIlinkRuntimeConfig();
+installManagedSkill({
+    packageRoot: KINTIO_PACKAGE_ROOT,
+    workingDirectory: config.codex.workingDirectory,
+});
+const controller = new AbortController();
+let resolveParentShutdown;
+const parentShutdown = new Promise((resolve) => { resolveParentShutdown = resolve; });
+const shutdown = () => {
+    controller.abort();
+    resolveParentShutdown();
+};
+process.once('SIGINT', shutdown);
+process.once('SIGTERM', shutdown);
+const handleMessage = (message) => {
+    if (message === 'shutdown')
+        shutdown();
+};
+process.on('message', handleMessage);
+process.once('disconnect', shutdown);
+if (process.env.KINTIO_MANAGED_WORKER === '1' && !process.connected)
+    shutdown();
+try {
+    const result = await startIlinkCliRuntime({
+        background: true,
+        config,
+        signal: controller.signal,
+        stdout: (text) => process.stdout.write(text),
+        onStarted() {
+            process.send?.({ type: 'ready', pid: process.pid });
+        },
+    });
+    if (result === 0 && process.connected) {
+        process.send?.({ type: 'shutdown-request', pid: process.pid });
+        await parentShutdown;
+    }
+    process.exitCode = result === 130 ? 0 : result;
+}
+catch (error) {
+    console.error('[ilink] process failed', error);
+    process.exitCode = 1;
+}
+finally {
+    process.off('SIGINT', shutdown);
+    process.off('SIGTERM', shutdown);
+    process.off('disconnect', shutdown);
+    process.off('message', handleMessage);
+    if (process.connected)
+        process.disconnect();
+}

package/dist/src/cli.js

@@ -62,22 +62,22 @@ Options:
 `;
 const ILINK_START_HELP = `Usage: kintio ilink start [options]
 
-Run iLink long polling and the host Agent in the foreground without starting
+Run iLink long polling and the host Agent in the background without starting
 Hono or opening a TCP listener. This command does not require setup or an
 environment file. One account is selected automatically; multiple accounts
-require --account. While this runtime is active, additional start commands add
-accounts to the same process.
+require --account. Additional start commands add accounts to the same process.
 
 Options:
   --account <id>        Provider account ID or Kintio account key
+  --foreground          Keep the iLink-only Runtime attached to this terminal
   --home <directory>     Instance directory (default: ~/.kintio)
   --config <file>        Optional environment overrides
   -h, --help             Show this help
 `;
 const ILINK_STOP_HELP = `Usage: kintio ilink stop [options]
 
-Stop one iLink account. Stopping the last account also exits a foreground
-"kintio ilink start" runtime. One account is selected automatically; multiple
+Stop one iLink account. Stopping the last account also stops the background
+iLink-only Runtime. One account is selected automatically; multiple
 accounts require --account.
 
 Options:
@@ -411,7 +411,7 @@ async function probeDaemon(location) {
         return undefined;
     }
 }
-function assertDaemonInstance(location, packageRoot) {
+function assertDaemonInstance(location, packageRoot, mode) {
     const daemon = readDaemonRecord(location.home);
     if (!daemon)
         throw new Error('Kintio daemon record is missing');
@@ -419,6 +419,9 @@ function assertDaemonInstance(location, packageRoot) {
         !samePath(daemon.packageRoot, packageRoot)) {
         throw new Error('Kintio is running with another config or installation; use "kintio restart" to switch deliberately');
     }
+    if (mode && daemon.mode !== mode) {
+        throw new Error(`Kintio is already running in ${daemon.mode} mode; stop it before starting ${mode} mode`);
+    }
 }
 async function withLifecycleLock(location, task) {
     const dataDirectory = ensureContainedDirectory(location.home, path.join(location.home, 'data'));
@@ -474,18 +477,19 @@ async function rollbackLaunch(location, daemon) {
     }
     removeLaunchMetadata(location, daemon.pid);
 }
-async function start(location, runtime, restart) {
-    const environment = processEnvironment(location, runtime);
+async function startBackgroundDaemon(location, runtime, environment, mode, restart) {
     const timeout = parseStartTimeout(environment.KINTIO_START_TIMEOUT_MS);
     return withLifecycleLock(location, async () => {
         const existing = await probeDaemon(location);
         if (existing && !restart) {
-            assertDaemonInstance(location, runtime.packageRoot);
+            assertDaemonInstance(location, runtime.packageRoot, mode);
             if (existing.phase !== 'running') {
                 await waitUntilRunning(location, Date.now() + timeout);
             }
-            runtime.stdout(`Kintio is already running (PID ${existing.workerPid || existing.daemonPid}).\n`);
-            return 0;
+            return {
+                alreadyRunning: true,
+                pid: existing.workerPid || existing.daemonPid,
+            };
         }
         if (existing) {
             await stopDaemon(location, DAEMON_STOP_TIMEOUT_MS);
@@ -495,7 +499,7 @@ async function start(location, runtime, restart) {
             file: process.execPath,
             args: [path.join(runtime.packageRoot, 'dist/daemon.js')],
             cwd: location.home,
-            env: environment,
+            env: { ...environment, KINTIO_DAEMON_MODE: mode },
         });
         try {
             await waitUntilRunning(location, deadline);
@@ -504,8 +508,39 @@ async function start(location, runtime, restart) {
             await rollbackLaunch(location, daemon);
             throw error;
         }
-        return 0;
+        const running = await requestControl(location.home, 'ping');
+        return {
+            alreadyRunning: false,
+            pid: running.workerPid || running.daemonPid,
+        };
+    });
+}
+async function start(location, runtime, restart) {
+    const result = await startBackgroundDaemon(location, runtime, processEnvironment(location, runtime), 'service', restart);
+    if (result.alreadyRunning) {
+        runtime.stdout(`Kintio is already running (PID ${result.pid}).\n`);
+    }
+    return 0;
+}
+function ilinkDaemonEnvironment(location, runtime) {
+    const config = loadIlinkRuntimeConfig({
+        environment: { ...runtime.env },
+        envFile: location.configFile,
+        root: location.home,
     });
+    refreshManagedSkill(config.codex.workingDirectory, runtime);
+    return {
+        ...runtime.env,
+        KINTIO_HOME: location.home,
+        KINTIO_CONFIG_FILE: location.configFile,
+        NODE_ENV: 'production',
+    };
+}
+async function startIlinkDaemon(location, runtime) {
+    const result = await startBackgroundDaemon(location, runtime, ilinkDaemonEnvironment(location, runtime), 'ilink', false);
+    if (!result.alreadyRunning) {
+        runtime.stdout(`Kintio iLink runtime is running in background (PID ${result.pid}).\n`);
+    }
 }
 async function waitUntilRunning(location, deadline) {
     let lastError = 'daemon did not publish control state';
@@ -648,6 +683,7 @@ export async function runCli(args, overrides = {}) {
                 'no-follow': { type: 'boolean' },
                 'qr-output': { type: 'string' },
                 account: { type: 'string' },
+                foreground: { type: 'boolean' },
                 yes: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
                 version: { type: 'boolean', short: 'v' },
@@ -719,6 +755,9 @@ export async function runCli(args, overrides = {}) {
         if (parsed.values.yes && (command !== 'ilink' || subcommand !== 'delete')) {
             throw new Error('--yes is valid only for "kintio ilink delete"');
         }
+        if (parsed.values.foreground && (command !== 'ilink' || subcommand !== 'start')) {
+            throw new Error('--foreground is valid only for "kintio ilink start"');
+        }
         const location = instanceLocation(parsed.values, runtime);
         const qrOutputPath = parsed.values['qr-output'] === undefined
             ? undefined
@@ -748,6 +787,7 @@ export async function runCli(args, overrides = {}) {
                         signal,
                     });
                 }
+                const foreground = Boolean(parsed.values.foreground);
                 const commandResult = await runtime.ilinkAccount({
                     command: subcommand,
                     ...(parsed.values.account ? { selector: parsed.values.account } : {}),
@@ -756,18 +796,54 @@ export async function runCli(args, overrides = {}) {
                     packageRoot: runtime.packageRoot,
                     signal,
                     stdout: runtime.stdout,
+                    ...(subcommand === 'start'
+                        ? { deferStandaloneStart: !foreground }
+                        : {}),
                 });
-                if (subcommand !== 'start' || !commandResult.startForeground)
-                    return 0;
-                return await runtime.ilinkStart({
-                    config: loadIlinkRuntimeConfig({
+                if (subcommand === 'start' && commandResult.runtimeRequired) {
+                    const runtimeConfig = loadIlinkRuntimeConfig({
                         environment: { ...runtime.env },
                         envFile: location.configFile,
                         root: location.home,
-                    }),
-                    signal,
-                    stdout: runtime.stdout,
-                });
+                    });
+                    if (foreground) {
+                        refreshManagedSkill(runtimeConfig.codex.workingDirectory, runtime);
+                        return await runtime.ilinkStart({
+                            config: runtimeConfig,
+                            signal,
+                            stdout: runtime.stdout,
+                        });
+                    }
+                    if (!commandResult.selectedAccountKey) {
+                        throw new Error('iLink start did not resolve an account identity');
+                    }
+                    await startIlinkDaemon(location, runtime);
+                    await runtime.ilinkAccount({
+                        command: 'start',
+                        selector: commandResult.selectedAccountKey,
+                        config: enrollmentConfig,
+                        packageRoot: runtime.packageRoot,
+                        signal,
+                        stdout: runtime.stdout,
+                    });
+                    return 0;
+                }
+                if ((subcommand === 'stop' || subcommand === 'delete') &&
+                    commandResult.runningCount === 0 &&
+                    readDaemonRecord(location.home)?.mode === 'ilink') {
+                    await withLifecycleLock(location, async () => {
+                        if (readDaemonRecord(location.home)?.mode === 'ilink') {
+                            try {
+                                await stopDaemon(location, DAEMON_STOP_TIMEOUT_MS);
+                            }
+                            catch (error) {
+                                if (readDaemonRecord(location.home))
+                                    throw error;
+                            }
+                        }
+                    });
+                }
+                return 0;
             });
         }
         if (command === 'setup')
@@ -793,7 +869,7 @@ export async function runCli(args, overrides = {}) {
                 return 0;
             }
             assertDaemonInstance(location, runtime.packageRoot);
-            runtime.stdout(`Kintio is ${existing.phase} ` +
+            runtime.stdout(`Kintio is ${existing.phase} in ${readDaemonRecord(location.home)?.mode || 'service'} mode ` +
                 `(daemon PID ${existing.daemonPid}` +
                 `${existing.workerPid ? `, worker PID ${existing.workerPid}` : ''}).` +
                 `${existing.message ? ` ${existing.message}` : ''}\n`);

package/dist/src/ilink/cli-accounts.js

@@ -22,11 +22,11 @@ function selectAccount(accounts, selector, runtimeActive) {
     }
     return matches[0];
 }
-export async function runIlinkAccountCommand({ command, selector, confirmed = false, config, packageRoot, signal, stdout, openControl, }) {
+export async function runIlinkAccountCommand({ command, selector, confirmed = false, config, packageRoot, signal, stdout, openControl, deferStandaloneStart = false, }) {
     if (!openControl && !fs.existsSync(config.state.databaseFile)) {
         if (command === 'list') {
             stdout('No iLink accounts enrolled.\n');
-            return { startForeground: false, runningCount: 0 };
+            return { runtimeRequired: false, runningCount: 0 };
         }
         throw new Error('No iLink account is enrolled; run "kintio ilink login" first');
     }
@@ -37,14 +37,21 @@ export async function runIlinkAccountCommand({ command, selector, confirmed = fa
         const runtimeActive = control.mode === 'runtime';
         if (command === 'list') {
             stdout(accounts.length
-                ? `${choices(accounts, runtimeActive)}\n`
+                ? `${accounts.map((account) => account.providerAccountId).join('\n')}\n`
                 : 'No iLink accounts enrolled.\n');
             return {
-                startForeground: false,
+                runtimeRequired: false,
                 runningCount: accounts.filter((account) => account.runtimeEnabled).length,
             };
         }
         const account = selectAccount(accounts, selector, runtimeActive);
+        if (command === 'start' && control.mode === 'standalone' && deferStandaloneStart) {
+            return {
+                runtimeRequired: true,
+                runningCount: 0,
+                selectedAccountKey: account.accountKey,
+            };
+        }
         if (command === 'delete' && !confirmed) {
             throw new Error(`Deleting ${JSON.stringify(account.providerAccountId)} permanently removes the account, ` +
                 'credentials, conversations, messages, media, send records, and audit records; ' +
@@ -56,8 +63,9 @@ export async function runIlinkAccountCommand({ command, selector, confirmed = fa
         stdout(`${command === 'delete' ? 'Deleted' : command === 'start' ? 'Started' : 'Stopped'} ` +
             `${JSON.stringify(account.providerAccountId)}.\n`);
         return {
-            startForeground: command === 'start' && control.mode === 'standalone',
+            runtimeRequired: command === 'start' && control.mode === 'standalone',
             runningCount: result.runningCount,
+            ...(command === 'start' ? { selectedAccountKey: account.accountKey } : {}),
         };
     }
     finally {

package/dist/src/ilink/cli-start.js

@@ -44,7 +44,10 @@ export async function startIlinkCliRuntime(options) {
     });
     try {
         await runtime.start();
-        options.stdout('Kintio iLink runtime is active. Press Ctrl-C to stop.\n');
+        await options.onStarted?.();
+        options.stdout(options.background
+            ? 'Kintio iLink runtime is active.\n'
+            : 'Kintio iLink runtime is active. Press Ctrl-C to stop.\n');
         const reason = await Promise.race([
             waitForAbort(options.signal).then(() => 'signal'),
             stopRequested.then(() => 'account-stop'),

package/dist/src/runtime/daemon-protocol.js

@@ -19,6 +19,7 @@ const daemonRecordSchema = z.strictObject({
     runId,
     daemonPid: positiveInteger,
     configFile: absolutePath,
+    mode: z.enum(['service', 'ilink']).default('service'),
     packageRoot: absolutePath,
     token,
 });

package/dist/src/runtime/native-daemon.js

@@ -56,7 +56,7 @@ function forceKill(worker) {
     if (worker.exitCode === null && worker.signalCode === null)
         worker.kill('SIGKILL');
 }
-export async function runNativeDaemon({ home, configFile, packageRoot, environment = process.env, }) {
+export async function runNativeDaemon({ home, configFile, packageRoot, mode = 'service', environment = process.env, }) {
     const instanceHome = path.resolve(home);
     const instanceConfig = path.resolve(configFile);
     const dataDirectory = ensurePrivateDirectory(path.join(instanceHome, 'data'));
@@ -140,7 +140,7 @@ export async function runNativeDaemon({ home, configFile, packageRoot, environme
         if (phase === 'stopping' || phase === 'failed')
             return;
         phase = 'starting';
-        const child = spawn(process.execPath, [path.join(instancePackageRoot, 'dist/index.js')], {
+        const child = spawn(process.execPath, [path.join(instancePackageRoot, mode === 'ilink' ? 'dist/ilink.js' : 'dist/index.js')], {
             cwd: instanceHome,
             env: {
                 ...environment,
@@ -181,7 +181,7 @@ export async function runNativeDaemon({ home, configFile, packageRoot, environme
         readyTimer.unref?.();
         child.stdout?.on('data', (chunk) => log.write(chunk));
         child.stderr?.on('data', (chunk) => log.write(chunk));
-        child.once('message', (message) => {
+        child.on('message', (message) => {
             if (worker === child &&
                 !readinessExpired &&
                 phase !== 'stopping' &&
@@ -195,6 +195,13 @@ export async function runNativeDaemon({ home, configFile, packageRoot, environme
                 phase = 'running';
                 lastError = undefined;
             }
+            if (worker === child &&
+                phase === 'running' &&
+                message && typeof message === 'object' &&
+                'type' in message && message.type === 'shutdown-request' &&
+                'pid' in message && message.pid === child.pid) {
+                void shutdown();
+            }
         });
         child.once('error', (error) => log.line(`worker spawn error: ${error.message}`));
         workerExit = new Promise((resolve) => {
@@ -307,6 +314,7 @@ export async function runNativeDaemon({ home, configFile, packageRoot, environme
             runId,
             daemonPid: process.pid,
             configFile: instanceConfig,
+            mode,
             packageRoot: instancePackageRoot,
             token,
         });

package/dist/src/runtime.js

@@ -192,8 +192,9 @@ export async function createRuntime({ config, logger = console, onIlinkStopReque
                         await ilinkListener?.refresh();
                     const runningCount = enrollment.accounts
                         .listRuntimeAccountsWithSecrets().length;
-                    if (!enabled && runningCount === 0)
-                        onIlinkStopRequested?.();
+                    if (!enabled && runningCount === 0 && onIlinkStopRequested) {
+                        setImmediate(onIlinkStopRequested);
+                    }
                     return {
                         account: {
                             accountKey: account.accountKey,
@@ -211,8 +212,9 @@ export async function createRuntime({ config, logger = console, onIlinkStopReque
                         await ilinkListener?.refresh();
                     const runningCount = enrollment.accounts
                         .listRuntimeAccountsWithSecrets().length;
-                    if (runningCount === 0)
-                        onIlinkStopRequested?.();
+                    if (runningCount === 0 && onIlinkStopRequested) {
+                        setImmediate(onIlinkStopRequested);
+                    }
                     return {
                         account: {
                             accountKey: account.accountKey,

package/dist/src/services/codex-app-server.js

@@ -207,10 +207,19 @@ export class CodexAppServer {
             this.#pending.delete(message.id);
             const rpcError = asRecord(message.error);
             if (rpcError) {
-                const error = new Error(`Codex app-server request failed: ${pending.method}`);
-                if (typeof rpcError.code === 'number' && Number.isSafeInteger(rpcError.code)) {
-                    error.code = rpcError.code;
-                }
+                const code = typeof rpcError.code === 'number' && Number.isSafeInteger(rpcError.code)
+                    ? rpcError.code
+                    : undefined;
+                const errorData = asRecord(rpcError.data);
+                const category = codexFailureLabel(errorData?.codexErrorInfo ?? rpcError.codexErrorInfo);
+                const diagnostic = [
+                    ...(code === undefined ? [] : [`code ${code}`]),
+                    ...(category ? [`category ${category}`] : []),
+                ];
+                const error = new Error(`Codex app-server request failed: ${pending.method}` +
+                    (diagnostic.length ? ` (${diagnostic.join('; ')})` : ''));
+                if (code !== undefined)
+                    error.code = code;
                 pending.reject(error);
             }
             else {

package/dist/src/version.js

@@ -1 +1 @@
-export const KINTIO_VERSION = '0.7.0';
+export const KINTIO_VERSION = '0.7.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kin-tio/cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "license": "Apache-2.0",
   "author": "XIE YU",
   "packageManager": "pnpm@10.34.5",