@jsonstudio/rcc 0.89.1803 → 0.89.1959

package/dist/utils/process-lifecycle-logger.js

@@ -0,0 +1,151 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import os from 'os';
+import path from 'path';
+const DEFAULT_LOG_DIR = path.join(os.homedir(), '.routecodex', 'logs');
+const DEFAULT_LOG_PATH = path.join(DEFAULT_LOG_DIR, 'process-lifecycle.jsonl');
+let writeQueue = Promise.resolve();
+function parseBool(value, defaultValue) {
+    if (typeof value !== 'string') {
+        return defaultValue;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        return defaultValue;
+    }
+    if (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on') {
+        return true;
+    }
+    if (normalized === '0' || normalized === 'false' || normalized === 'no' || normalized === 'off') {
+        return false;
+    }
+    return defaultValue;
+}
+function resolveLogPath() {
+    const envPath = process.env.ROUTECODEX_PROCESS_LIFECYCLE_LOG || process.env.RCC_PROCESS_LIFECYCLE_LOG;
+    if (typeof envPath === 'string' && envPath.trim()) {
+        return envPath.trim();
+    }
+    return DEFAULT_LOG_PATH;
+}
+function shouldConsoleLog() {
+    return parseBool(process.env.ROUTECODEX_PROCESS_LIFECYCLE_CONSOLE || process.env.RCC_PROCESS_LIFECYCLE_CONSOLE, true);
+}
+function serializeUnknown(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const primitiveType = typeof value;
+    if (primitiveType === 'string' || primitiveType === 'number' || primitiveType === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serializeUnknown(item));
+    }
+    if (value instanceof Error) {
+        const out = {
+            name: value.name,
+            message: value.message
+        };
+        if (value.stack) {
+            out.stack = value.stack;
+        }
+        return out;
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+function buildRecord(event) {
+    return {
+        ts: new Date().toISOString(),
+        pid: process.pid,
+        ppid: process.ppid,
+        event: event.event,
+        source: event.source,
+        ...(event.details ? { details: serializeUnknown(event.details) } : {})
+    };
+}
+function formatConsoleLine(record) {
+    const details = record.details && typeof record.details === 'object' && !Array.isArray(record.details)
+        ? record.details
+        : null;
+    const parts = [];
+    if (details) {
+        for (const key of ['signal', 'targetPid', 'port', 'result', 'reason']) {
+            const value = details[key];
+            if (value !== undefined && value !== null && value !== '') {
+                parts.push(`${key}=${String(value)}`);
+            }
+        }
+    }
+    const suffix = parts.length ? ` ${parts.join(' ')}` : '';
+    return `[routecodex.lifecycle][${record.ts}] ${record.event} source=${record.source}${suffix}`;
+}
+function printBlue(line) {
+    const canColor = Boolean(process.stdout?.isTTY);
+    if (canColor) {
+        console.log(`\x1b[94m${line}\x1b[0m`);
+        return;
+    }
+    console.log(line);
+}
+async function appendRecord(record) {
+    const logPath = resolveLogPath();
+    const dir = path.dirname(logPath);
+    if (!fsSync.existsSync(dir)) {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    await fs.appendFile(logPath, `${JSON.stringify(record)}\n`, 'utf8');
+}
+function appendRecordSync(record) {
+    try {
+        const logPath = resolveLogPath();
+        const dir = path.dirname(logPath);
+        if (!fsSync.existsSync(dir)) {
+            fsSync.mkdirSync(dir, { recursive: true });
+        }
+        fsSync.appendFileSync(logPath, `${JSON.stringify(record)}\n`, 'utf8');
+    }
+    catch {
+        // Never throw from lifecycle logging.
+    }
+}
+function enqueueWrite(task) {
+    writeQueue = writeQueue.then(async () => {
+        try {
+            await task();
+        }
+        catch {
+            // Never throw from lifecycle logging.
+        }
+    });
+}
+export function logProcessLifecycle(event) {
+    const record = buildRecord(event);
+    if (shouldConsoleLog()) {
+        printBlue(formatConsoleLine(record));
+    }
+    enqueueWrite(async () => {
+        await appendRecord(record);
+    });
+}
+export function logProcessLifecycleSync(event) {
+    const record = buildRecord(event);
+    if (shouldConsoleLog()) {
+        printBlue(formatConsoleLine(record));
+    }
+    appendRecordSync(record);
+}
+export async function flushProcessLifecycleLogQueue() {
+    try {
+        await writeQueue;
+    }
+    catch {
+        // Never throw from lifecycle logging.
+    }
+}
+//# sourceMappingURL=process-lifecycle-logger.js.map

package/dist/utils/process-lifecycle-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-lifecycle-logger.js","sourceRoot":"","sources":["../../src/utils/process-lifecycle-logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/runtime-exit-forensics.d.ts

@@ -0,0 +1,30 @@
+export type RuntimeExitMarker = {
+    kind: string;
+    code: number | null;
+    signal?: string;
+    message?: string;
+    recordedAt: string;
+};
+export type RuntimeLifecycleState = {
+    runId: string;
+    pid: number;
+    port: number;
+    startedAt: string;
+    buildVersion?: string;
+    buildMode?: string;
+    exit?: RuntimeExitMarker;
+};
+export type UngracefulInference = {
+    shouldReport: boolean;
+    reason: string;
+};
+export declare function resolveRuntimeLifecyclePath(port: number, routeCodexHomeDir?: string): string;
+export declare function safeReadRuntimeLifecycle(filePath: string): RuntimeLifecycleState | null;
+export declare function safeWriteRuntimeLifecycle(filePath: string, state: RuntimeLifecycleState): boolean;
+export declare function safeMarkRuntimeExit(filePath: string, marker: RuntimeExitMarker): boolean;
+export declare function isPidAliveForForensics(pid: number): boolean;
+export declare function inferUngracefulPreviousExit(args: {
+    previous: RuntimeLifecycleState | null;
+    currentPid: number;
+    isPidAlive?: (pid: number) => boolean;
+}): UngracefulInference;

package/dist/utils/runtime-exit-forensics.js

@@ -0,0 +1,101 @@
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+function normalizePort(port) {
+    return Number.isFinite(port) && port > 0 ? Math.floor(port) : 0;
+}
+export function resolveRuntimeLifecyclePath(port, routeCodexHomeDir) {
+    const home = routeCodexHomeDir || path.join(homedir(), '.routecodex');
+    return path.join(home, 'state', 'runtime-lifecycle', `server-${normalizePort(port)}.json`);
+}
+function ensureParentDir(filePath) {
+    const dir = path.dirname(filePath);
+    if (!fsSync.existsSync(dir)) {
+        fsSync.mkdirSync(dir, { recursive: true });
+    }
+}
+export function safeReadRuntimeLifecycle(filePath) {
+    try {
+        if (!fsSync.existsSync(filePath)) {
+            return null;
+        }
+        const raw = fsSync.readFileSync(filePath, 'utf8');
+        if (!raw.trim()) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        const pid = Number(parsed.pid);
+        const port = Number(parsed.port);
+        const runId = String(parsed.runId || '').trim();
+        if (!Number.isFinite(pid) || pid <= 0 || !Number.isFinite(port) || port <= 0 || !runId) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function safeWriteRuntimeLifecycle(filePath, state) {
+    try {
+        ensureParentDir(filePath);
+        fsSync.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function safeMarkRuntimeExit(filePath, marker) {
+    try {
+        const existing = safeReadRuntimeLifecycle(filePath);
+        if (!existing) {
+            return false;
+        }
+        const next = {
+            ...existing,
+            exit: marker
+        };
+        return safeWriteRuntimeLifecycle(filePath, next);
+    }
+    catch {
+        return false;
+    }
+}
+export function isPidAliveForForensics(pid) {
+    if (!Number.isFinite(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function inferUngracefulPreviousExit(args) {
+    const previous = args.previous;
+    if (!previous) {
+        return { shouldReport: false, reason: 'no_previous_state' };
+    }
+    if (previous.exit) {
+        return { shouldReport: false, reason: 'previous_exit_recorded' };
+    }
+    const previousPid = Number(previous.pid);
+    if (!Number.isFinite(previousPid) || previousPid <= 0) {
+        return { shouldReport: false, reason: 'invalid_previous_pid' };
+    }
+    if (Number(previousPid) === Number(args.currentPid)) {
+        return { shouldReport: false, reason: 'same_pid_reentry' };
+    }
+    const isPidAlive = args.isPidAlive ?? isPidAliveForForensics;
+    if (isPidAlive(previousPid)) {
+        return { shouldReport: false, reason: 'previous_pid_alive' };
+    }
+    return { shouldReport: true, reason: 'previous_missing_exit_marker_pid_dead' };
+}
+//# sourceMappingURL=runtime-exit-forensics.js.map

package/dist/utils/runtime-exit-forensics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-exit-forensics.js","sourceRoot":"","sources":["../../src/utils/runtime-exit-forensics.ts"],"names":[],"mappings":"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"}

package/dist/utils/shutdown-caller-context.d.ts

@@ -0,0 +1,22 @@
+interface ShutdownCallerContext {
+    source: string;
+    requestTs: string;
+    remoteIp?: string;
+    method?: string;
+    path?: string;
+    userAgent?: string;
+    forwardedFor?: string;
+    origin?: string;
+    referer?: string;
+    authPresent?: boolean;
+    callerPid?: string;
+    callerTs?: string;
+    callerCwd?: string;
+    callerCmd?: string;
+}
+export declare function setShutdownCallerContext(value: ShutdownCallerContext): void;
+export declare function clearShutdownCallerContext(): void;
+export declare function getShutdownCallerContext(opts?: {
+    maxAgeMs?: number;
+}): ShutdownCallerContext | null;
+export type { ShutdownCallerContext };

package/dist/utils/shutdown-caller-context.js

@@ -0,0 +1,25 @@
+const DEFAULT_MAX_AGE_MS = 120_000;
+let cached = null;
+export function setShutdownCallerContext(value) {
+    cached = {
+        value: { ...value },
+        setAtMs: Date.now()
+    };
+}
+export function clearShutdownCallerContext() {
+    cached = null;
+}
+export function getShutdownCallerContext(opts) {
+    if (!cached) {
+        return null;
+    }
+    const maxAgeMs = Number.isFinite(opts?.maxAgeMs) && opts?.maxAgeMs > 0
+        ? Number(opts?.maxAgeMs)
+        : DEFAULT_MAX_AGE_MS;
+    if (Date.now() - cached.setAtMs > maxAgeMs) {
+        cached = null;
+        return null;
+    }
+    return { ...cached.value };
+}
+//# sourceMappingURL=shutdown-caller-context.js.map

package/dist/utils/shutdown-caller-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown-caller-context.js","sourceRoot":"","sources":["../../src/utils/shutdown-caller-context.ts"],"names":[],"mappings":"AAiBA,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAEnC,IAAI,MAAM,GAA6D,IAAI,CAAC;AAE5E,MAAM,UAAU,wBAAwB,CAAC,KAA4B;IACnE,MAAM,GAAG;QACP,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE;QACnB,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;KACpB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,0BAA0B;IACxC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAA4B;IACnE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAK,IAAI,EAAE,QAAmB,GAAG,CAAC;QAChF,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;QACxB,CAAC,CAAC,kBAAkB,CAAC;IACvB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC;QAC3C,MAAM,GAAG,IAAI,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;AAC7B,CAAC"}

package/docs/PROVIDERS_BUILTIN.md

@@ -87,6 +87,14 @@
 - 关键点：`auth.type: "iflow-oauth"` + `auth.tokenFile`；`compatibilityProfile: "chat:iflow"`
 - 你需要：先完成一次 OAuth 登录生成 tokenFile
 
+### DeepSeek Web（账号）
+
+- 样本：`configsamples/provider/deepseek/config.v1.json`
+- 建议配置：`type: "openai"` + `compatibilityProfile: "chat:deepseek-web"`
+- 认证字段：`auth.type: "deepseek-account"`，并通过 `auth.entries[*].tokenFile` 提供账号 token 文件（支持多账号轮转）
+- 可选参数：`deepseek.strictToolRequired`、`deepseek.textToolFallback`、`deepseek.powTimeoutMs`、`deepseek.powMaxAttempts`、`deepseek.sessionReuseTtlMs`
+- 说明：Provider 层负责账号登录/会话/PoW/传输；工具调用标准化由 llmswitch-core compat 完成
+
 ### Kimi（API Key）
 
 - 样本：`configsamples/provider/kimi/config.v1.json`

package/docs/PROVIDER_TYPES.md

@@ -31,10 +31,12 @@
 }
 ```
 
-### OpenAI-compatible（例如 GLM/Qwen/Kimi 等）
+### OpenAI-compatible（例如 GLM/Qwen/Kimi/DeepSeek Web 等）
 
 仍然建议 `type: "openai"`，并通过 `compatibilityProfile` 做最小字段适配：
 
+- DeepSeek Web 账号模式建议：`type: "openai"` + `compatibilityProfile: "chat:deepseek-web"` + `auth.type = "deepseek-account"`。
+
 ```jsonc
 {
   "id": "qwen",

package/docs/SERVERTOOL_PRE_COMMAND_HOOKS.md

@@ -0,0 +1,85 @@
+# ServerTool Pre-Command Hooks
+
+## Goal
+
+在 `tool_call` 下发到客户端执行前，做一层可注册的 `pre_command` 拦截（不消费工具调用、不替代执行），用于：
+
+- 参数形状清理（例如 `exec_command` 参数规范化）
+- 预执行审计（shell side-effect 记录）
+- 与 Claude Code `PreToolUse` 类似的“执行前 hook”能力
+
+## Activation (runtime)
+
+优先级最高的激活方式是路由指令（与 `stopMessage` 同路径）：
+
+- `<**precommand:<file://precommand/your-script.sh>**>`：激活预执行脚本
+- `<**precommand:clear**>`：清除当前 precommand 状态
+- `<**precommand**>` / `<**precommand:on**>`：加载默认脚本（默认 `default.sh`，可用 `ROUTECODEX_PRECOMMAND_DEFAULT_SCRIPT` 覆盖）
+
+脚本必须位于 `~/.routecodex/precommand` 下（支持 `ROUTECODEX_USER_DIR` 覆盖根目录）。
+
+运行时会把 hook event JSON 通过 stdin 和环境变量 `ROUTECODEX_PRE_COMMAND_HOOK_EVENT` 传给脚本：
+
+- 脚本输出空内容：不改参数
+- 脚本输出 JSON：用于改写工具参数（支持 `toolArguments`/`arguments` 或直接输出参数对象）
+
+## Config file (fallback)
+
+当未激活 runtime precommand 时，回退读取：`~/.routecodex/hooks/pre-command-hooks.json`
+
+可覆盖：
+
+- `ROUTECODEX_PRE_COMMAND_HOOKS_FILE`
+- `RCC_PRE_COMMAND_HOOKS_FILE`
+- `LLMSWITCH_PRE_COMMAND_HOOKS_FILE`
+
+示例：
+
+```json
+{
+  "enabled": true,
+  "hooks": [
+    {
+      "id": "normalize-npm-cmd",
+      "tool": "exec_command",
+      "priority": 10,
+      "cmdRegex": "^npm\\s+",
+      "jq": ".cmd = (\"set -euo pipefail; \" + .cmd)"
+    },
+    {
+      "id": "audit-pre-command",
+      "tool": ["exec_command", "shell"],
+      "priority": 20,
+      "shell": "cat >> ~/.routecodex/logs/pre-command-audit.jsonl"
+    }
+  ]
+}
+```
+
+## `jq` 注册（shell 操作）
+
+可直接用 `jq` 向 hooks 文件追加注册项：
+
+```bash
+HOOK_FILE="${ROUTECODEX_PRE_COMMAND_HOOKS_FILE:-$HOME/.routecodex/hooks/pre-command-hooks.json}"
+mkdir -p "$(dirname "$HOOK_FILE")"
+[ -f "$HOOK_FILE" ] || printf '{"enabled":true,"hooks":[]}' > "$HOOK_FILE"
+
+jq '.hooks += [
+  {
+    "id": "block-applypatch-via-exec",
+    "tool": "exec_command",
+    "priority": 5,
+    "cmdRegex": "apply_patch",
+    "jq": ".cmd = \"echo \\\"Warning: use apply_patch tool\\\"; \" + .cmd"
+  }
+]' "$HOOK_FILE" > "$HOOK_FILE.tmp" && mv "$HOOK_FILE.tmp" "$HOOK_FILE"
+```
+
+## Runtime behavior
+
+- 执行顺序：`priority` 升序，`priority` 相同按注册顺序。
+- `jq` action：把当前 arguments JSON 作为输入，输出 JSON 对象作为新的 tool arguments。
+- `shell` action：以 hook event JSON 作为 stdin 执行 shell 命令（用于审计/旁路记录）。
+- 失败策略：hook 报错记为 trace（`error`），不阻断原工具调用下发。
+- trace：通过 servertool hook trace 通道记录 `match/miss/error`。