@cjhyy/code-shell-host 0.9.44 → 0.9.46

package/README.md

@@ -12,7 +12,7 @@ retain that path, while Panel task hosts immediately return a typed `unavailable
 decision with an explicit unsupported reason. They never turn a yes/no confirmation
 into a user answer; Core retires asynchronous questions without injecting an answer
 or starting a follow-up run. This package does not implement
-Protocol v2, credential storage, automation scheduling or the later service moves.
+Protocol v2, credential storage, automation scheduling or output replay.
 
 Desktop bundles this package into its main process, so its dependency belongs in
 Desktop `devDependencies`. The production workspace materialization list used by
@@ -24,3 +24,45 @@ credential store, not Desktop's credential IPC/safeStorage service. Foreign
 safeStorage ciphertext fails closed; supported plaintext tags and legacy bare
 plaintext remain readable under the existing local store rules. This is not
 credential-service parity or a separate per-task vault.
+
+The first shared services live under `services/` and are exported from this package:
+
+- `readSkillInventory(cwd)` combines Core discovery and effective enablement; it
+  does not grant renderer file access or authorize mutations.
+- `probeMcp(config, { cwd, signal })` owns the bounded sibling probe and closes it
+  on completion, cancellation or timeout. The Core internal connection owns MCP
+  SDK imports and stdio process groups; Host imports only Core and Node builtins.
+- `probeConfiguredModel` owns Hub's existing tool-free, single-request connection
+  test. This is an ownership move, not a replacement for model metadata/listing.
+- `readSessionFile`/`readSessionFileSync` and candidate scanners share bounded
+  ordinary-file reads, safe IDs and identity checks. Roots are explicit; default
+  scanners use Core `sessionsRoot()`. Adapters retain their catalog semantics.
+
+Storage consumers import `@cjhyy/code-shell-host/session-files`; that entry does
+not load probes, model clients or skill inventory. List-only state reads retry
+at most twice after an ordinary file is atomically replaced, while single-session
+authorization reads reject identity changes. Desktop catalog state is capped at
+2 MiB; oversized entries are omitted with `SESSION_LIST_STATE_TOO_LARGE`, without
+logging state contents. Candidate discovery uses lstat and does not open transcripts.
+
+MCP adapters select their stdio policy explicitly: Desktop tolerates non-JSON
+launcher banners and valid JSON logger records that fail JSON-RPC validation;
+Hub remains strict. Both retain byte limits, cancellation and process cleanup.
+Optional HTTP GET/SSE diagnostics do not invalidate successful
+POST requests. Host returns neutral error codes and bounded safe detail; adapters
+choose local or server wording, and explicit credentials remain redacted.
+
+Preview redaction treats authentication fields (including apikey/x-apikey),
+envHeaders, bearerTokenEnvVar and explicit token argv as private at any length.
+Other env/envVars and argv values of at least eight characters are also private,
+including positional arguments; flag names are syntax. Short ordinary scalars
+such as DEBUG=1, MODE=read and LOG_LEVEL=info keep tool names and descriptions
+readable. Protocol/content-type headers remain ordinary text. This policy lives
+in Host and applies to both adapters.
+
+These explicit async methods do not change HostRuntime's synchronous lifecycle.
+Desktop retains path grants/cache/OAuth resolution; Hub retains HTTP authority,
+owner cancellation, review tokens, revision checks and mutation gates. Snapshot,
+journal, output replay, UI catalog and transcript formatting remain with their
+existing owners. See the [review evidence](../../../docs/todo/evidence/host-shared-services-cc-review-20261015.md)
+for review state and validation limits.

package/dist/index.d.ts

@@ -1,2 +1,6 @@
 export { HostRuntime, type HostAdapter, type HostService } from "./runtime.js";
+export { SessionFileError, assertSessionFileId, readSessionFile, readSessionFileSync, readSessionListState, readSessionListStateSync, statSessionFileSync, scanSessionDirectories, scanSessionDirectoriesSync, sessionListStorage, } from "./services/session-files.js";
+export { readSkillInventory } from "./services/skill-inventory.js";
+export { probeConfiguredModel, type ModelProbeCode, type ModelProbeResult, } from "./services/model-connection-probe.js";
 export { classifyHostRequest, interceptHostRequest, isHostAuthorityRequest, unsupportedAskUserDecision, unsupportedHostRequestResponse, unsupportedLoopbackAnswer, unsupportedLoopbackCapability, type HostApproval, type HostRequest, type ServeHostCapabilities, } from "./host-requests.js";
+export { probeMcp, mcpProbeTransport, type McpProbeResult } from "./services/mcp-probe.js";

package/dist/index.js

@@ -1,2 +1,6 @@
 export { HostRuntime } from "./runtime.js";
+export { SessionFileError, assertSessionFileId, readSessionFile, readSessionFileSync, readSessionListState, readSessionListStateSync, statSessionFileSync, scanSessionDirectories, scanSessionDirectoriesSync, sessionListStorage, } from "./services/session-files.js";
+export { readSkillInventory } from "./services/skill-inventory.js";
+export { probeConfiguredModel, } from "./services/model-connection-probe.js";
 export { classifyHostRequest, interceptHostRequest, isHostAuthorityRequest, unsupportedAskUserDecision, unsupportedHostRequestResponse, unsupportedLoopbackAnswer, unsupportedLoopbackCapability, } from "./host-requests.js";
+export { probeMcp, mcpProbeTransport } from "./services/mcp-probe.js";

package/dist/index.session-files.d.ts

@@ -0,0 +1,2 @@
+/** Filesystem custody only; importing storage must not load probes or skill inventory. */
+export { SessionFileError, assertSessionFileId, readSessionFile, readSessionFileSync, readSessionListState, readSessionListStateSync, statSessionFileSync, scanSessionDirectories, scanSessionDirectoriesSync, sessionListStorage, } from "./services/session-files.js";

package/dist/index.session-files.js

@@ -0,0 +1,2 @@
+/** Filesystem custody only; importing storage must not load probes or skill inventory. */
+export { SessionFileError, assertSessionFileId, readSessionFile, readSessionFileSync, readSessionListState, readSessionListStateSync, statSessionFileSync, scanSessionDirectories, scanSessionDirectoriesSync, sessionListStorage, } from "./services/session-files.js";

package/dist/services/mcp-probe.d.ts

@@ -0,0 +1,36 @@
+import { createMcpAuthenticatedFetch, type MCPServerConfig } from "@cjhyy/code-shell-core";
+export declare function mcpProbeTransport(config: {
+    transport?: "stdio" | "streamable-http" | "sse";
+    url?: string;
+}): "stdio" | "streamable-http" | "sse";
+export declare function mcpProbeTransport(config: Pick<MCPServerConfig, "transport" | "url">): NonNullable<MCPServerConfig["transport"]>;
+export interface McpProbeResult {
+    name: string;
+    status: "ok" | "error" | "cancelled";
+    checkedAt: string;
+    durationMs: number;
+    toolCount?: number;
+    truncated?: boolean;
+    tools?: {
+        name: string;
+        description?: string;
+        allowed: boolean;
+    }[];
+    error?: {
+        code: string;
+        message: string;
+        detail: string;
+        environment?: {
+            name: string;
+            field: string;
+        };
+    };
+}
+/** Explicit, bounded sibling connection; configuration reads never invoke this function. */
+export declare function probeMcp(config: MCPServerConfig, options: {
+    cwd: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    credentialAccess?: Parameters<typeof createMcpAuthenticatedFetch>[2];
+    stdioPolicy?: "strict" | "skip-banner";
+}): Promise<McpProbeResult>;

package/dist/services/mcp-probe.js

@@ -0,0 +1,297 @@
+import { isAbsolute } from "node:path";
+import { createMcpAuthenticatedFetch, localCredentialAccess, } from "@cjhyy/code-shell-core";
+import { createMcpProbeConnection, McpProbeConnectionError as ProbeFailure, } from "@cjhyy/code-shell-core/internal";
+const MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+const MAX_PREVIEW_TOOLS = 100;
+const MAX_TOOL_PAGES = 8;
+export function mcpProbeTransport(config) {
+    return config.transport ?? (config.url ? "streamable-http" : "stdio");
+}
+function rememberSecret(secrets, value) {
+    if (!value)
+        return;
+    secrets.add(value);
+    if (/^(Bearer|Basic|Token)\s+/i.test(value))
+        secrets.add(value.replace(/^(Bearer|Basic|Token)\s+/i, ""));
+    const match = /(?:token|secret|password|credentials?|api[-_]?key)=([^\s]+)/i.exec(value);
+    if (match?.[1])
+        secrets.add(match[1]);
+}
+function credentialField(name) {
+    const separated = name.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+    return /(?:^|[-_])(?:authorization|cookie|tokens?|secrets?|password|passwd|credentials?|key|auth|api[-_]?key|access[-_]?key)(?:$|[-_])/i.test(separated);
+}
+// Unlabelled env/argv can contain private configuration, including positional
+// credentials. Keep short ordinary scalars/launcher verbs intact, but hide values
+// of at least eight characters. Explicit authentication values have no minimum.
+function rememberPrivateConfig(secrets, value) {
+    if (value && value.length >= 8)
+        rememberSecret(secrets, value);
+}
+function redact(text, secrets, maximum) {
+    let safe = text;
+    for (const secret of [...secrets].sort((left, right) => right.length - left.length)) {
+        safe = safe.split(secret).join("[已隐藏]");
+    }
+    return safe.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "").slice(0, maximum);
+}
+function classify(error) {
+    if (error instanceof ProbeFailure)
+        return { code: error.code, message: error.message };
+    const status = error?.code;
+    const messages = [];
+    let current = error;
+    for (let depth = 0; current && depth < 4; depth++) {
+        messages.push(current instanceof Error ? current.message : String(current));
+        const item = current;
+        if (typeof item.code === "string")
+            messages.push(item.code);
+        current = item.cause;
+    }
+    const raw = messages.join(" ");
+    if (/ENOENT/.test(raw))
+        return {
+            code: "command_missing",
+            message: "找不到这个命令，请确认已安装并填写正确路径。",
+        };
+    if (/EACCES/.test(raw))
+        return { code: "permission_denied", message: "没有执行这个命令的权限。" };
+    if (/ECONNREFUSED/.test(raw))
+        return {
+            code: "connection_refused",
+            message: "目标服务拒绝连接，请检查地址、端口和服务状态。",
+        };
+    if (/ENOTFOUND|EAI_AGAIN/.test(raw))
+        return { code: "dns", message: "无法解析服务域名，请检查地址和当前网络。" };
+    if (/env var .* is not set/.test(raw))
+        return {
+            code: "environment_missing",
+            message: "配置引用的环境变量未设置，请检查环境变量名称和服务启动环境。",
+        };
+    if (/credential .*not found|credential .*empty|metadata is unavailable/.test(raw))
+        return {
+            code: "credential_missing",
+            message: "引用的凭据不存在或不可用，请检查凭据配置。",
+        };
+    if (/expired|oauth.*requires/i.test(raw))
+        return {
+            code: "credential_expired",
+            message: "认证凭据已过期或需要重新授权，请更新凭据。",
+        };
+    if (status === 401 ||
+        /\b401\b|unauthori[sz]ed|-32001|no auth provider/i.test(raw) ||
+        (error instanceof Error && error.name === "UnauthorizedError"))
+        return { code: "unauthorized", message: "服务拒绝了认证信息，请检查 API Key、请求头或凭据。" };
+    if (status === 403 || /\b403\b|forbidden/i.test(raw))
+        return { code: "forbidden", message: "当前凭据没有使用此服务的权限。" };
+    if (status === 404 || /\b404\b/.test(raw))
+        return { code: "not_found", message: "这个地址没有提供 MCP 服务，请确认完整的 MCP 接口地址。" };
+    if (status === 405 || /\b405\b|Unexpected content type|protocol|JSON/i.test(raw))
+        return { code: "protocol", message: "服务没有返回预期的 MCP 协议，请检查连接类型与接口地址。" };
+    if (/timed out|timeout|ETIMEDOUT/i.test(raw))
+        return {
+            code: "timeout",
+            message: "连接测试超时。首次运行包管理器可能需要下载依赖，可以稍后重试。",
+        };
+    if (/certificate|TLS|SSL/i.test(raw))
+        return { code: "tls", message: "服务的 HTTPS 证书验证失败，请检查证书和信任配置。" };
+    return {
+        code: "connection_failed",
+        message: "连接测试失败。请确认服务支持 MCP、命令可以启动，并检查服务日志。",
+    };
+}
+/** Explicit, bounded sibling connection; configuration reads never invoke this function. */
+export async function probeMcp(config, options) {
+    if (!isAbsolute(options.cwd))
+        throw new Error("MCP probe requires an absolute workspace");
+    config = structuredClone(config);
+    const started = Date.now();
+    const secrets = new Set();
+    for (const [name, value] of Object.entries(config.env ?? {})) {
+        if (credentialField(name))
+            rememberSecret(secrets, value);
+        else
+            rememberPrivateConfig(secrets, value);
+    }
+    const secretHeader = (name) => credentialField(name) ||
+        Object.keys(config.envHeaders ?? {}).some((header) => header.toLowerCase() === name.toLowerCase());
+    for (const [name, value] of Object.entries(config.headers ?? {}))
+        if (secretHeader(name))
+            rememberSecret(secrets, value);
+    // Flags are syntax; their explicit authentication values are always private.
+    // Other argv values follow the same conservative length rule as untyped env.
+    const args = config.args ?? [];
+    for (let index = 0; index < args.length; index++) {
+        const flag = /^--?([^=]+)(?:=(.*))?$/.exec(args[index]);
+        if (flag && credentialField(flag[1]))
+            rememberSecret(secrets, flag[2] ?? args[index + 1]);
+        if (!args[index].startsWith("-"))
+            rememberPrivateConfig(secrets, args[index]);
+        else if (args[index].includes("="))
+            rememberPrivateConfig(secrets, args[index].slice(args[index].indexOf("=") + 1));
+        const bearer = /\bBearer\s+(.+)/i.exec(args[index]);
+        if (bearer)
+            rememberSecret(secrets, bearer[1]);
+    }
+    for (const name of config.envVars ?? []) {
+        if (credentialField(name))
+            rememberSecret(secrets, process.env[name]);
+        else
+            rememberPrivateConfig(secrets, process.env[name]);
+    }
+    for (const name of [...Object.values(config.envHeaders ?? {}), config.bearerTokenEnvVar]) {
+        if (name)
+            rememberSecret(secrets, process.env[name]);
+    }
+    if (config.url) {
+        try {
+            const url = new URL(config.url);
+            const privateQueryValues = [...url.searchParams]
+                .filter(([name]) => /token|secret|password|credential|key|auth|^(access|code|sig|signature)$/i.test(name))
+                .map(([, value]) => value);
+            for (const value of [url.username, url.password, ...privateQueryValues]) {
+                rememberSecret(secrets, value);
+                try {
+                    rememberSecret(secrets, decodeURIComponent(value));
+                }
+                catch {
+                    /* The raw URL component is already hidden. */
+                }
+            }
+        }
+        catch {
+            /* Invalid URLs are classified below without returning the original value. */
+        }
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new ProbeFailure("timeout", "连接测试超时。首次运行包管理器可能需要下载依赖，可以稍后重试。")), options.timeoutMs ?? 10_000);
+    const cancel = () => controller.abort(new ProbeFailure("cancelled", "测试已取消。"));
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    if (options.signal?.aborted)
+        cancel();
+    let connection;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const onAbort = () => {
+        rejectAbort?.(controller.signal.reason);
+        if (connection)
+            void connection.close().catch(() => { });
+    };
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (controller.signal.aborted)
+            throw controller.signal.reason;
+        const mode = mcpProbeTransport(config);
+        if (!["stdio", "streamable-http", "sse"].includes(mode))
+            throw new ProbeFailure("unsupported_transport", "此内置服务由任务进程管理，不能创建独立测试连接。");
+        if (mode === "stdio" && !config.command)
+            throw new ProbeFailure("invalid_config", "请先填写启动命令。");
+        if (mode !== "stdio" && !config.url)
+            throw new ProbeFailure("invalid_config", "请先填写 MCP 接口地址。");
+        let totalBytes = 0;
+        const boundedFetch = (async (input, init) => {
+            const request = new Request(input, init);
+            for (const [name, value] of request.headers)
+                if (secretHeader(name))
+                    rememberSecret(secrets, value);
+            const signal = AbortSignal.any([request.signal, controller.signal]);
+            const response = await fetch(new Request(request, { signal, redirect: "error" }));
+            if (!response.body)
+                return response;
+            const body = response.body.pipeThrough(new TransformStream({
+                transform(chunk, stream) {
+                    totalBytes += chunk.byteLength;
+                    if (totalBytes > MAX_TOTAL_BYTES) {
+                        const error = new ProbeFailure("response_too_large", "服务返回的数据过大，测试已停止。");
+                        controller.abort(error);
+                        stream.error(error);
+                    }
+                    else
+                        stream.enqueue(chunk);
+                },
+            }));
+            return new Response(body, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        });
+        connection = createMcpProbeConnection({ ...config, transport: mode }, {
+            cwd: options.cwd,
+            stdioPolicy: options.stdioPolicy,
+            fetch: createMcpAuthenticatedFetch(config.name, config, options.credentialAccess ?? localCredentialAccess, boundedFetch),
+        });
+        const run = (async () => {
+            await connection.connect();
+            let cursor;
+            let toolCount = 0;
+            const tools = [];
+            const seen = new Set();
+            for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+                const result = await connection.listTools(cursor);
+                toolCount += result.tools.length;
+                for (const tool of result.tools) {
+                    if (tools.length >= MAX_PREVIEW_TOOLS)
+                        break;
+                    tools.push({
+                        name: redact(tool.name, secrets, 160),
+                        ...(tool.description ? { description: redact(tool.description, secrets, 600) } : {}),
+                        allowed: (config.allowedTools === undefined || config.allowedTools.includes(tool.name)) &&
+                            !(config.disabledTools ?? []).includes(tool.name),
+                    });
+                }
+                cursor = result.nextCursor;
+                if (!cursor)
+                    break;
+                if (seen.has(cursor))
+                    throw new ProbeFailure("invalid_protocol", "服务返回了重复的工具分页游标，测试已停止。");
+                seen.add(cursor);
+            }
+            return { toolCount, tools, truncated: !!cursor || tools.length < toolCount };
+        })();
+        const result = await Promise.race([run, aborted]);
+        return {
+            name: config.name,
+            status: "ok",
+            checkedAt: new Date().toISOString(),
+            durationMs: Date.now() - started,
+            ...result,
+        };
+    }
+    catch (cause) {
+        const failure = controller.signal.aborted ? controller.signal.reason : cause;
+        const classified = classify(failure);
+        const raw = failure instanceof Error ? failure.message : "";
+        const missing = /env var "([A-Za-z_][A-Za-z0-9_]{0,127})" \(from (envVars|envHeaders|bearerTokenEnvVar)\) is not set/.exec(raw);
+        const referenced = missing &&
+            (missing[2] === "envVars"
+                ? config.envVars?.includes(missing[1])
+                : missing[2] === "envHeaders"
+                    ? Object.values(config.envHeaders ?? {}).includes(missing[1])
+                    : config.bearerTokenEnvVar === missing[1]);
+        const environment = referenced && missing ? { name: missing[1], field: missing[2] } : undefined;
+        // SDK/provider error bodies can contain unrelated secrets. Never return raw
+        // stacks/bodies; expose bounded technical context and validated config names.
+        const error = {
+            ...classified,
+            detail: redact(`MCP probe: code=${classified.code}; transport=${mcpProbeTransport(config)}${environment ? `; env var "${environment.name}" (from ${environment.field}) is not set` : ""}`, secrets, 1200),
+            ...(environment ? { environment } : {}),
+        };
+        return {
+            name: config.name,
+            status: error.code === "cancelled" ? "cancelled" : "error",
+            checkedAt: new Date().toISOString(),
+            durationMs: Date.now() - started,
+            error,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", cancel);
+        controller.signal.removeEventListener("abort", onAbort);
+        controller.abort();
+        await connection?.close().catch(() => { });
+    }
+}

package/dist/services/model-connection-probe.d.ts

@@ -0,0 +1,20 @@
+/** A bounded, tool-free connectivity check through the same Core clients as real tasks. */
+import { type SettingsManager } from "@cjhyy/code-shell-core";
+type Settings = ReturnType<SettingsManager["get"]>;
+export type ModelProbeCode = "connected" | "missing_key" | "invalid_configuration" | "unauthorized" | "model_unavailable" | "rate_limited" | "provider_error" | "network_error" | "invalid_response" | "timeout" | "cancelled";
+export interface ModelProbeResult {
+    ok: boolean;
+    connectionId: string;
+    model: string;
+    latencyMs: number;
+    checkedAt: string;
+    code: ModelProbeCode;
+    message: string;
+    status?: number;
+}
+export declare function probeConfiguredModel(settings: Settings, id: string, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    transport?: typeof fetch;
+}): Promise<ModelProbeResult>;
+export {};

package/dist/services/model-connection-probe.js

@@ -0,0 +1,193 @@
+/** A bounded, tool-free connectivity check through the same Core clients as real tasks. */
+import { createLLMClient, resolveLLMConfigForTag, } from "@cjhyy/code-shell-core";
+import { getMergedCatalog } from "@cjhyy/code-shell-core/internal";
+const messages = {
+    connected: "连接成功，模型已正常返回响应。",
+    missing_key: "缺少有效的 API Key，请编辑连接并填写密钥。",
+    invalid_configuration: "连接配置不完整或不支持，请检查服务商、模型和服务地址。",
+    unauthorized: "服务商拒绝了凭据，请检查 API Key 与账号的模型访问权限。",
+    model_unavailable: "模型或接口不可用，请检查模型名称与服务地址。",
+    rate_limited: "服务商限制了请求，请检查账户额度或稍后重试。",
+    provider_error: "服务商暂时无法处理请求，请稍后重试。",
+    network_error: "无法连接服务，请检查服务器网络、服务地址与本地模型是否启动。",
+    invalid_response: "服务有响应，但没有返回有效的模型内容，请检查接口类型和模型。",
+    timeout: "连接测试超时，请检查服务地址与网络，或稍后重试。",
+    cancelled: "已取消连接测试。",
+};
+export async function probeConfiguredModel(settings, id, options = {}) {
+    const started = Date.now();
+    const connection = settings.modelConnections.find((item) => item.id === id && item.tag === "text");
+    const result = (code, status) => ({
+        ok: code === "connected",
+        connectionId: id,
+        model: connection?.model ?? "",
+        latencyMs: Math.max(0, Date.now() - started),
+        checkedAt: new Date().toISOString(),
+        code,
+        message: messages[code],
+        ...(status ? { status } : {}),
+    });
+    if (!connection)
+        return result("invalid_configuration");
+    const template = getMergedCatalog().find((entry) => entry.id === connection.catalogId);
+    // Core treats an omitted text protocol as OpenAI-compatible.
+    if (!template)
+        return result("invalid_configuration");
+    const credential = settings.credentials.find((item) => item.id === connection.credentialId);
+    if (template.needsKey !== false && !credential?.apiKey)
+        return result("missing_key");
+    // Narrowing prevents the resolver's fallback from testing a different connection.
+    const resolved = resolveLLMConfigForTag({ ...settings, modelConnections: [connection] }, "text", id);
+    if (!resolved)
+        return result("invalid_configuration");
+    try {
+        const endpoint = new URL(resolved.baseUrl ?? "");
+        if (!["https:", "http:"].includes(endpoint.protocol) ||
+            endpoint.username ||
+            endpoint.password ||
+            endpoint.search ||
+            endpoint.hash)
+            return result("invalid_configuration");
+    }
+    catch {
+        return result("invalid_configuration");
+    }
+    const controller = new AbortController();
+    const timeoutMs = Math.min(18_000, Math.max(1, options.timeoutMs ?? 18_000));
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    timer.unref();
+    const cancel = () => controller.abort();
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    if (options.signal?.aborted)
+        controller.abort();
+    let status;
+    let transportFailed = false;
+    let invalidResponse = false;
+    let requests = 0;
+    const transport = options.transport ?? globalThis.fetch;
+    const safeFetch = (async (input, init) => {
+        // SDK retries must never turn a connectivity check into multiple paid requests.
+        if (++requests > 1)
+            return failureResponse(503);
+        try {
+            const response = await transport(input, {
+                ...init,
+                redirect: "error",
+                signal: init?.signal
+                    ? AbortSignal.any([controller.signal, init.signal])
+                    : controller.signal,
+            });
+            status = response.status;
+            if (!response.ok) {
+                await response.body?.cancel();
+                // Provider error bodies can echo credentials. Never let them reach SDK logs.
+                return failureResponse(response.status);
+            }
+            const reader = response.body?.getReader();
+            if (!reader) {
+                invalidResponse = true;
+                return failureResponse(502);
+            }
+            const chunks = [];
+            let bytes = 0;
+            try {
+                while (true) {
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    bytes += next.value.byteLength;
+                    if (bytes > 1024 * 1024) {
+                        invalidResponse = true;
+                        await reader.cancel();
+                        return failureResponse(502);
+                    }
+                    chunks.push(next.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            const data = Buffer.concat(chunks);
+            // Invalid JSON must not cause an SDK exception containing the response body.
+            let safeBody;
+            try {
+                const payload = JSON.parse(data.toString("utf8"));
+                safeBody = JSON.stringify(payload, (_key, value) => typeof value === "string" && resolved.apiKey
+                    ? value.replaceAll(resolved.apiKey, "[redacted]")
+                    : value);
+            }
+            catch {
+                invalidResponse = true;
+                return failureResponse(502);
+            }
+            return new Response(safeBody, {
+                status: response.status,
+                headers: { "content-type": "application/json", "x-should-retry": "false" },
+            });
+        }
+        catch {
+            transportFailed = true;
+            return failureResponse(503);
+        }
+    });
+    let rejectAbort;
+    try {
+        const aborted = new Promise((_resolve, reject) => {
+            rejectAbort = () => reject(new Error("model probe aborted"));
+            controller.signal.addEventListener("abort", rejectAbort, { once: true });
+            if (controller.signal.aborted)
+                rejectAbort();
+        });
+        const request = async () => {
+            const client = await createLLMClient({ ...resolved, apiKey: resolved.apiKey ?? "codeshell-no-key", maxTokens: 32 }, { timeout: timeoutMs, retryMaxAttempts: 1, fetch: safeFetch });
+            return client.createMessage({
+                systemPrompt: "This is a connection test. Reply with OK.",
+                messages: [{ role: "user", content: "Reply OK." }],
+                tools: [],
+                reasoning: { mode: "off" },
+                maxTokens: 32,
+                requestVisible: false,
+                billingEnabled: false,
+                signal: controller.signal,
+            });
+        };
+        const response = await Promise.race([request(), aborted]);
+        return response.text?.trim() ? result("connected") : result("invalid_response");
+    }
+    catch {
+        if (timedOut)
+            return result("timeout");
+        if (controller.signal.aborted)
+            return result("cancelled");
+        if (invalidResponse)
+            return result("invalid_response");
+        if (transportFailed)
+            return result("network_error");
+        if (status === 401 || status === 403)
+            return result("unauthorized", status);
+        if (status === 400 || status === 404 || status === 422)
+            return result("model_unavailable", status);
+        if (status === 429)
+            return result("rate_limited", status);
+        if (status && status >= 500)
+            return result("provider_error", status);
+        return result("invalid_response", status);
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", cancel);
+        if (rejectAbort)
+            controller.signal.removeEventListener("abort", rejectAbort);
+        controller.abort();
+    }
+}
+function failureResponse(status) {
+    return Response.json({ error: { message: "Model connection check failed", type: "model_probe_error" } }, {
+        status,
+        headers: { "x-should-retry": "false" },
+    });
+}

package/dist/services/session-files.d.ts

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+export declare class SessionFileError extends Error {
+    readonly code: "invalid_path" | "forbidden" | "too_large" | "changed";
+    readonly subject?: "directory" | "file" | undefined;
+    constructor(code: "invalid_path" | "forbidden" | "too_large" | "changed", message: string, subject?: "directory" | "file" | undefined);
+}
+export declare function assertSessionFileId(id: string): void;
+export declare function readSessionFileSync(root: string, id: string, leaf: string, maximumBytes: number): string;
+/** Lists tolerate at most two ordinary-file atomic replacements, never directory changes. */
+export declare function readSessionListStateSync(root: string, id: string, maximumBytes: number): string;
+export declare function readSessionListState(root: string, id: string, maximumBytes: number): Promise<string>;
+export declare function statSessionFileSync(root: string, id: string, leaf: string, maximumBytes?: number): fs.Stats;
+/** Async counterpart for Electron main; never blocks its event loop on disk reads. */
+export declare function readSessionFile(root: string, id: string, leaf: string, maximumBytes: number): Promise<string>;
+export declare function scanSessionDirectoriesSync(root?: string): {
+    id: string;
+    mtime: number;
+}[];
+export declare function scanSessionDirectories(root?: string): Promise<{
+    id: string;
+    mtime: number;
+}[]>;
+/** Only filesystem custody. Core retains activity ordering, filters, cursor and tail previews. */
+export declare function sessionListStorage(root: string): {
+    candidates: () => {
+        dir: string;
+        lastActiveAt: number;
+        transcriptExists: boolean;
+    }[];
+    readState: (id: string, maximumBytes: number) => string;
+};

package/dist/services/session-files.js

@@ -0,0 +1,252 @@
+import * as fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { sessionsRoot } from "@cjhyy/code-shell-core";
+export class SessionFileError extends Error {
+    code;
+    subject;
+    constructor(code, message, subject) {
+        super(message);
+        this.code = code;
+        this.subject = subject;
+    }
+}
+export function assertSessionFileId(id) {
+    if (!/^[A-Za-z0-9_.-]{1,128}$/.test(id) || id === "." || id.includes(".."))
+        throw new SessionFileError("invalid_path", "Invalid session id");
+}
+function paths(root, id, leaf) {
+    assertSessionFileId(id);
+    if (!isAbsolute(root) ||
+        !/^[A-Za-z0-9_.-]{1,128}$/.test(leaf) ||
+        leaf === "." ||
+        leaf.includes(".."))
+        throw new SessionFileError("invalid_path", "Session files require an absolute root and a direct filename");
+    return { directory: join(root, id), file: join(root, id, leaf) };
+}
+function directory(info) {
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new SessionFileError("forbidden", "Session directory is not ordinary");
+    return info;
+}
+function ordinary(info, limit) {
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new SessionFileError("forbidden", "Session record is not an ordinary file");
+    if (!Number.isSafeInteger(limit) || limit < 0 || info.size > limit)
+        throw new SessionFileError("too_large", "Session record exceeds the read limit");
+    return info;
+}
+function same(before, after, subject = "directory") {
+    if (after.isSymbolicLink() || before.dev !== after.dev || before.ino !== after.ino)
+        throw new SessionFileError("changed", "Session storage changed during read", subject);
+}
+const directoryFlags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_DIRECTORY ?? 0);
+const fileFlags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+function withFileSync(root, id, leaf, limit, read) {
+    const path = paths(root, id, leaf);
+    const before = directory(fs.lstatSync(path.directory));
+    let dir, file;
+    try {
+        dir = fs.openSync(path.directory, directoryFlags);
+        same(before, fs.fstatSync(dir));
+        file = fs.openSync(process.platform === "linux" ? `/proc/self/fd/${dir}/${leaf}` : path.file, fileFlags);
+        const info = ordinary(fs.fstatSync(file), limit);
+        const value = read(file, info);
+        same(before, fs.lstatSync(path.directory));
+        same(info, fs.lstatSync(path.file), "file");
+        return value;
+    }
+    finally {
+        try {
+            if (file !== undefined)
+                fs.closeSync(file);
+        }
+        finally {
+            if (dir !== undefined)
+                fs.closeSync(dir);
+        }
+    }
+}
+export function readSessionFileSync(root, id, leaf, maximumBytes) {
+    return withFileSync(root, id, leaf, maximumBytes, (fd, info) => {
+        const data = Buffer.alloc(info.size);
+        let offset = 0;
+        while (offset < data.length) {
+            const bytes = fs.readSync(fd, data, offset, data.length - offset, offset);
+            if (!bytes)
+                break;
+            offset += bytes;
+        }
+        return data.subarray(0, offset).toString("utf8");
+    });
+}
+/** Lists tolerate at most two ordinary-file atomic replacements, never directory changes. */
+export function readSessionListStateSync(root, id, maximumBytes) {
+    const path = paths(root, id, "state.json");
+    const anchor = directory(fs.lstatSync(path.directory));
+    const fd = fs.openSync(path.directory, directoryFlags);
+    try {
+        same(anchor, fs.fstatSync(fd));
+        for (let attempt = 0;; attempt++) {
+            try {
+                const value = readSessionFileSync(root, id, "state.json", maximumBytes);
+                same(anchor, fs.lstatSync(path.directory));
+                return value;
+            }
+            catch (error) {
+                if (!(error instanceof SessionFileError) ||
+                    error.code !== "changed" ||
+                    error.subject !== "file")
+                    throw error;
+                same(anchor, fs.lstatSync(path.directory));
+                ordinary(fs.lstatSync(path.file), maximumBytes);
+                if (attempt >= 2)
+                    throw error;
+            }
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export async function readSessionListState(root, id, maximumBytes) {
+    const path = paths(root, id, "state.json");
+    const anchor = directory(await fsp.lstat(path.directory));
+    const handle = await fsp.open(path.directory, directoryFlags);
+    try {
+        same(anchor, await handle.stat());
+        for (let attempt = 0;; attempt++) {
+            try {
+                const value = await readSessionFile(root, id, "state.json", maximumBytes);
+                same(anchor, await fsp.lstat(path.directory));
+                return value;
+            }
+            catch (error) {
+                if (!(error instanceof SessionFileError) ||
+                    error.code !== "changed" ||
+                    error.subject !== "file")
+                    throw error;
+                same(anchor, await fsp.lstat(path.directory));
+                ordinary(await fsp.lstat(path.file), maximumBytes);
+                if (attempt >= 2)
+                    throw error;
+            }
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function statSessionFileSync(root, id, leaf, maximumBytes = Number.MAX_SAFE_INTEGER) {
+    return withFileSync(root, id, leaf, maximumBytes, (_fd, info) => info);
+}
+/** Async counterpart for Electron main; never blocks its event loop on disk reads. */
+export async function readSessionFile(root, id, leaf, maximumBytes) {
+    const path = paths(root, id, leaf);
+    const before = directory(await fsp.lstat(path.directory));
+    let dir, file;
+    try {
+        dir = await fsp.open(path.directory, directoryFlags);
+        same(before, await dir.stat());
+        file = await fsp.open(process.platform === "linux" ? `/proc/self/fd/${dir.fd}/${leaf}` : path.file, fileFlags);
+        const info = ordinary(await file.stat(), maximumBytes);
+        const data = Buffer.alloc(info.size);
+        let offset = 0;
+        while (offset < data.length) {
+            const { bytesRead } = await file.read(data, offset, data.length - offset, offset);
+            if (!bytesRead)
+                break;
+            offset += bytesRead;
+        }
+        same(before, await fsp.lstat(path.directory));
+        same(info, await fsp.lstat(path.file), "file");
+        return data.subarray(0, offset).toString("utf8");
+    }
+    finally {
+        try {
+            await file?.close();
+        }
+        finally {
+            await dir?.close();
+        }
+    }
+}
+export function scanSessionDirectoriesSync(root = resolve(sessionsRoot())) {
+    if (!isAbsolute(root))
+        throw new SessionFileError("invalid_path", "Session root must be absolute");
+    try {
+        return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+            try {
+                if (!entry.isDirectory())
+                    return [];
+                assertSessionFileId(entry.name);
+                const info = directory(fs.lstatSync(join(root, entry.name)));
+                return [{ id: entry.name, mtime: info.mtimeMs }];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export async function scanSessionDirectories(root = resolve(sessionsRoot())) {
+    if (!isAbsolute(root))
+        throw new SessionFileError("invalid_path", "Session root must be absolute");
+    try {
+        const entries = await fsp.readdir(root, { withFileTypes: true });
+        const candidates = await Promise.all(entries.map(async (entry) => {
+            try {
+                if (!entry.isDirectory())
+                    return [];
+                assertSessionFileId(entry.name);
+                const info = directory(await fsp.lstat(join(root, entry.name)));
+                return [{ id: entry.name, mtime: info.mtimeMs }];
+            }
+            catch {
+                return [];
+            }
+        }));
+        return candidates.flat();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+/** Only filesystem custody. Core retains activity ordering, filters, cursor and tail previews. */
+export function sessionListStorage(root) {
+    return {
+        candidates: () => scanSessionDirectoriesSync(root).flatMap(({ id }) => {
+            if (id.startsWith(".pending-") || id.startsWith("qchat-"))
+                return [];
+            try {
+                const state = ordinary(fs.lstatSync(join(root, id, "state.json")), 1024 * 1024);
+                let transcript;
+                try {
+                    transcript = ordinary(fs.lstatSync(join(root, id, "transcript.jsonl")), Number.MAX_SAFE_INTEGER);
+                }
+                catch (error) {
+                    if (!["ENOENT", "EACCES", "EPERM"].includes(error.code ?? ""))
+                        throw error;
+                }
+                return [
+                    {
+                        dir: id,
+                        lastActiveAt: transcript?.mtimeMs ?? state.mtimeMs,
+                        transcriptExists: !!transcript,
+                    },
+                ];
+            }
+            catch {
+                return [];
+            }
+        }),
+        readState: (id, maximumBytes) => readSessionListStateSync(root, id, maximumBytes),
+    };
+}

package/dist/services/skill-inventory.d.ts

@@ -0,0 +1,12 @@
+/** Discovery and effective toggles only. Grants and mutations belong to the adapter. */
+export declare function readSkillInventory(cwd: string, options?: {
+    refresh?: boolean;
+}): {
+    disabledSkills: string[];
+    disabledPlugins: string[];
+    disabledPluginHooks: string[];
+    skills: {
+        definition: import("@cjhyy/code-shell-core").SkillDefinition;
+        enabled: boolean;
+    }[];
+};

package/dist/services/skill-inventory.js

@@ -0,0 +1,18 @@
+import { SettingsManager, scanSkills, invalidateSkillCache } from "@cjhyy/code-shell-core";
+import { computeEffectiveDisabledLists } from "@cjhyy/code-shell-core/internal";
+import { isAbsolute } from "node:path";
+/** Discovery and effective toggles only. Grants and mutations belong to the adapter. */
+export function readSkillInventory(cwd, options = {}) {
+    if (!isAbsolute(cwd))
+        throw new Error("Skill inventory requires an absolute workspace");
+    if (options.refresh)
+        invalidateSkillCache();
+    const disabled = computeEffectiveDisabledLists(new SettingsManager(cwd, "full"), cwd);
+    const enabledPaths = new Set(scanSkills(cwd, disabled).map((skill) => skill.filePath));
+    // Keep project binding even when showing individually disabled skills/plugins.
+    const skills = scanSkills(cwd).map((definition) => ({
+        definition,
+        enabled: enabledPaths.has(definition.filePath),
+    }));
+    return { skills, ...disabled };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-host",
-  "version": "0.9.44",
+  "version": "0.9.46",
   "description": "Host-neutral capability registry and worker request dispatch for CodeShell hosts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./session-files": {
+      "types": "./dist/index.session-files.d.ts",
+      "import": "./dist/index.session-files.js"
     }
   },
   "files": [
@@ -21,7 +25,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },
   "dependencies": {
-    "@cjhyy/code-shell-core": "0.9.44"
+    "@cjhyy/code-shell-core": "0.9.46"
   },
   "engines": {
     "node": ">=20.10"