@botlearn-course/daemon 0.0.1

package/dist/cli.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { hostname } from "node:os";
+import { fileURLToPath } from "node:url";
+import { authFilePath, clearAuth, machineFingerprint, readAuth, writeAuth } from "./auth-store.js";
+import { AgentServiceRunClient } from "./agent-service-client.js";
+import { CourseClient, isAuthFailure, loginCourseDaemon } from "./course-client.js";
+import { runCourseDoctor } from "./doctor.js";
+import { log } from "./log.js";
+import { augmentProcessPath } from "./path-env.js";
+import { redactSecretString } from "./redaction.js";
+import { RunDispatcher } from "./run-dispatcher.js";
+import { RUNTIME_MODULES, detectAvailableRuntimeIds, fakeRuntimeEnabled, } from "./runtimes/index.js";
+const pkg = createRequire(import.meta.url)("../package.json");
+const HELP = `botlearn-course-daemon ${pkg.version} — run BotLearn Course tasks on your own machine (BYOA)
+
+Usage:
+  botlearn-course-daemon course login --api-url <url> --code <blic_xxx> [--label <name>]
+  botlearn-course-daemon course start [--once] [--poll-interval-ms <ms>]
+  botlearn-course-daemon course logout
+  botlearn-course-daemon course doctor
+  botlearn-course-daemon agent-service run
+  botlearn-course-daemon --help | --version
+
+Commands:
+  course login    Bind this machine to BotLearn Course using a one-time
+                  install code. Writes <daemon-home>/auth.json (0600).
+  course start    Poll Course Service, execute assigned runs with local
+                  agent runtimes, report run events back.
+  course logout   Delete the local daemon credential (auth.json).
+  course doctor   Probe installed runtimes and local auth state.
+
+Environment:
+  BOTLEARN_COURSE_API_URL   default --api-url for course login
+  BOTLEARN_DAEMON_HOME      state dir (default ~/.botlearn-course/daemon)
+  BOTLEARN_DAEMON_DEBUG     enable debug logging
+  BOTLEARN_<ID>_BIN         override a runtime binary path (e.g. BOTLEARN_CODEX_BIN)
+
+Agent Service sandbox environment:
+  BOTLEARN_COURSE_API_URL
+  BOTLEARN_AGENT_SERVICE_RUN_ID
+  BOTLEARN_AGENT_SERVICE_RUN_TOKEN
+  BOTLEARN_AGENT_SERVICE_WORKER_ID`;
+// ---------------------------------------------------------------
+// flag parser（极简：--k v / --k=v / 布尔开关）
+// ---------------------------------------------------------------
+const BOOLEAN_FLAGS = new Set(["once", "help", "version"]);
+const AGENT_SERVICE_CONTROL_ENV_KEYS = [
+    "BOTLEARN_COURSE_API_URL",
+    "BOTLEARN_AGENT_SERVICE_RUN_ID",
+    "BOTLEARN_AGENT_SERVICE_RUN_TOKEN",
+    "BOTLEARN_AGENT_SERVICE_WORKER_ID",
+];
+/** Keep the run-scoped Course credential out of runtime subprocess environments. */
+export function clearAgentServiceControlEnv(env = process.env) {
+    for (const key of AGENT_SERVICE_CONTROL_ENV_KEYS)
+        delete env[key];
+}
+export function parseCliArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (token === "-V" || token === "-v") {
+            flags.version = true;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            positional.push(token);
+            continue;
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf("=");
+        if (eq >= 0) {
+            flags[body.slice(0, eq)] = body.slice(eq + 1);
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(body)) {
+            flags[body] = true;
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+            flags[body] = next;
+            i += 1;
+        }
+        else {
+            flags[body] = true;
+        }
+    }
+    return { positional, flags };
+}
+function stringFlag(args, name) {
+    const value = args.flags[name];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberFlag(args, name, fallback) {
+    const raw = stringFlag(args, name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+// 默认 sleep 切成小片轮询 isStopping，让 SIGINT 不用等完整个退避窗口。
+async function interruptibleSleep(ms, isStopping) {
+    const deadline = Date.now() + ms;
+    while (!isStopping()) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return;
+        await new Promise((r) => setTimeout(r, Math.min(remaining, 200)));
+    }
+}
+export async function runPollLoop(deps) {
+    const logger = deps.log ?? log;
+    const maxBackoffMs = deps.maxBackoffMs ?? 60_000;
+    const sleep = deps.sleep ?? ((ms) => interruptibleSleep(ms, deps.isStopping));
+    let failures = 0;
+    while (!deps.isStopping()) {
+        let payload;
+        try {
+            payload = await deps.claimNextRun();
+        }
+        catch (err) {
+            if (isAuthFailure(err))
+                return "auth_failure";
+            const backoffMs = Math.min(deps.pollIntervalMs * 2 ** failures, maxBackoffMs);
+            failures += 1;
+            logger.warn("course run claim failed; backing off", {
+                error: err instanceof Error ? redactSecretString(err.message) : String(err),
+                backoffMs,
+            });
+            await sleep(backoffMs);
+            continue;
+        }
+        failures = 0;
+        if (payload) {
+            const runId = payload.agent_run_id;
+            const task = deps.dispatch(payload).catch((err) => {
+                logger.error("course run dispatch failed", {
+                    agentRunId: runId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+            if (deps.once) {
+                await task;
+                return "once";
+            }
+            // 有任务：立即继续 claim，run 在后台并发执行。
+            continue;
+        }
+        if (deps.once)
+            return "once";
+        await sleep(deps.pollIntervalMs);
+    }
+    return "stopped";
+}
+// ---------------------------------------------------------------
+// 子命令
+// ---------------------------------------------------------------
+function defaultLoginLabel() {
+    const name = hostname().replace(/\.local$/, "").trim();
+    return name || "daemon";
+}
+async function cmdLogin(args) {
+    const courseApiUrl = stringFlag(args, "api-url") ?? process.env.BOTLEARN_COURSE_API_URL;
+    const code = stringFlag(args, "code");
+    if (!courseApiUrl || !code) {
+        console.error("usage: botlearn-course-daemon course login --api-url <url> --code <blic_xxx> [--label <name>]");
+        return 1;
+    }
+    augmentProcessPath();
+    const auth = await loginCourseDaemon({
+        courseApiUrl,
+        code,
+        label: stringFlag(args, "label") ?? defaultLoginLabel(),
+        machineFingerprint: machineFingerprint(),
+        capabilities: { poll: true, runtimes: await detectAvailableRuntimeIds() },
+    });
+    writeAuth(auth);
+    console.log(`BotLearn Course daemon linked as ${auth.daemonId}`);
+    return 0;
+}
+async function cmdStart(args) {
+    const auth = readAuth();
+    if (!auth) {
+        console.error("not linked to BotLearn Course");
+        console.error("run: botlearn-course-daemon course login --api-url <url> --code <blic_xxx>");
+        return 1;
+    }
+    augmentProcessPath();
+    const pollIntervalMs = numberFlag(args, "poll-interval-ms", 2_000);
+    const once = args.flags.once === true;
+    const client = CourseClient.fromAuth(auth, { onAuthRefreshed: writeAuth });
+    const runtimes = new Map();
+    for (const mod of RUNTIME_MODULES) {
+        if (mod.hidden && !fakeRuntimeEnabled())
+            continue;
+        runtimes.set(mod.id, mod.create());
+    }
+    const dispatcher = new RunDispatcher(client, runtimes);
+    let stopping = false;
+    let signalCount = 0;
+    const onSignal = (sig) => {
+        signalCount += 1;
+        if (signalCount > 1) {
+            // 二次信号：不再等待 drain，取消所有 run 立即退出。
+            dispatcher.cancelAll();
+            process.exit(130);
+        }
+        stopping = true;
+        log.info("course daemon signal received; draining", { sig });
+    };
+    process.on("SIGINT", () => onSignal("SIGINT"));
+    process.on("SIGTERM", () => onSignal("SIGTERM"));
+    console.log(`BotLearn Course daemon polling ${auth.courseApiUrl}`);
+    const exit = await runPollLoop({
+        claimNextRun: () => client.claimNextRun(),
+        dispatch: (payload) => dispatcher.dispatch(payload),
+        isStopping: () => stopping,
+        pollIntervalMs,
+        once,
+        log,
+    });
+    if (exit === "auth_failure") {
+        clearAuth();
+        console.error("daemon credentials expired or revoked — run `botlearn-course-daemon course login` again");
+        return 1;
+    }
+    // 停止 claim 后先等 inflight 排空；超时强制取消再给 5s 收尾。
+    if (!(await dispatcher.drain(10_000))) {
+        log.warn("drain timed out; cancelling in-flight runs", { active: dispatcher.activeCount });
+        dispatcher.cancelAll();
+        await dispatcher.drain(5_000);
+    }
+    return 0;
+}
+function cmdLogout() {
+    const removed = clearAuth();
+    console.log(removed
+        ? `removed local daemon credentials (${authFilePath()})`
+        : "no local daemon credentials found");
+    console.log("note: to revoke this daemon server-side, use the daemon list in the frontend");
+    return 0;
+}
+async function cmdDoctor() {
+    augmentProcessPath();
+    const result = await runCourseDoctor({ includeHidden: fakeRuntimeEnabled() });
+    console.log(result.text);
+    // doctor 是诊断不是校验：即使 0 个 runtime 可用也 exit 0。
+    return 0;
+}
+async function cmdAgentServiceRun() {
+    const courseApiUrl = process.env.BOTLEARN_COURSE_API_URL;
+    const agentRunId = process.env.BOTLEARN_AGENT_SERVICE_RUN_ID;
+    const runToken = process.env.BOTLEARN_AGENT_SERVICE_RUN_TOKEN;
+    const workerId = process.env.BOTLEARN_AGENT_SERVICE_WORKER_ID;
+    if (!courseApiUrl || !agentRunId || !runToken || !workerId) {
+        console.error("Agent Service sandbox environment is incomplete");
+        return 1;
+    }
+    augmentProcessPath();
+    const client = new AgentServiceRunClient(courseApiUrl, agentRunId, runToken, workerId);
+    const payload = await client.getRun();
+    if (payload.agent_run_id !== agentRunId) {
+        throw new Error("Agent Service run payload does not match requested run");
+    }
+    clearAgentServiceControlEnv();
+    const runtimes = new Map();
+    for (const mod of RUNTIME_MODULES) {
+        if (mod.hidden && !fakeRuntimeEnabled())
+            continue;
+        runtimes.set(mod.id, mod.create());
+    }
+    const dispatcher = new RunDispatcher(client, runtimes);
+    const heartbeat = setInterval(() => {
+        void client.heartbeat().catch((err) => {
+            log.warn("Agent Service heartbeat failed", {
+                agentRunId,
+                error: err instanceof Error ? redactSecretString(err.message) : String(err),
+            });
+        });
+    }, 20_000);
+    if (typeof heartbeat.unref === "function")
+        heartbeat.unref();
+    try {
+        await client.heartbeat();
+        await dispatcher.dispatch(payload);
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------
+// 入口
+// ---------------------------------------------------------------
+export async function runCli(argv) {
+    const args = parseCliArgs(argv);
+    if (args.flags.version === true) {
+        console.log(pkg.version);
+        return 0;
+    }
+    if (args.flags.help === true || args.positional[0] === "help") {
+        console.log(HELP);
+        return 0;
+    }
+    const [command, sub] = args.positional;
+    if (command === "course") {
+        switch (sub) {
+            case "login":
+                return cmdLogin(args);
+            case "start":
+                return cmdStart(args);
+            case "logout":
+                return cmdLogout();
+            case "doctor":
+                return cmdDoctor();
+            default:
+                console.error(HELP);
+                return 1;
+        }
+    }
+    if (command === "agent-service" && sub === "run") {
+        return cmdAgentServiceRun();
+    }
+    console.error(HELP);
+    return 1;
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    runCli(process.argv.slice(2))
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(redactSecretString(message));
+        process.exit(1);
+    });
+}

package/dist/course-client.d.ts

@@ -0,0 +1,46 @@
+import type { CourseRuntimeProfile, DaemonAuth, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
+export declare class CourseClientError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** 401：daemon 凭据失效（refresh 也救不回来），调用方应引导重新 login。 */
+export declare function isAuthFailure(err: unknown): boolean;
+/** 409：run 在服务端已进入终态（如用户取消），后续上报应静默停止。 */
+export declare function isRunTerminal(err: unknown): boolean;
+export interface CourseClientOptions {
+    refreshToken?: string;
+    onAuthRefreshed?: (auth: DaemonAuth) => void;
+}
+/**
+ * Course Service HTTP 客户端。
+ *
+ * Course Service 是真相源；client 只用短期 access token 回报已分配给本 daemon 的 run。
+ * 第一版用 POST poll/events，不做 WS。401 时自动用 refresh token 换新并单次重试。
+ */
+export declare class CourseClient {
+    private readonly baseUrl;
+    private accessToken;
+    private refreshToken?;
+    private readonly onAuthRefreshed?;
+    constructor(baseUrl: string, accessToken: string, opts?: CourseClientOptions);
+    static fromAuth(auth: DaemonAuth, opts?: Omit<CourseClientOptions, "refreshToken">): CourseClient;
+    setAccessToken(token: string): void;
+    private url;
+    fetchJson<T>(method: string, p: string, body: unknown, accessToken: string | null): Promise<T>;
+    private refreshAuth;
+    private request;
+    /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */
+    claimNextRun(): Promise<RunStartPayload | null>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord | void>;
+    getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
+}
+export interface LoginOptions {
+    courseApiUrl: string;
+    code: string;
+    label?: string;
+    machineFingerprint?: string;
+    capabilities?: Record<string, unknown>;
+}
+export declare function loginCourseDaemon(opts: LoginOptions): Promise<DaemonAuth>;
+export declare function refreshCourseDaemonSession(courseApiUrl: string, refreshToken: string): Promise<DaemonAuth>;

package/dist/course-client.js

@@ -0,0 +1,143 @@
+import { redactSecretString } from "./redaction.js";
+export class CourseClientError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "CourseClientError";
+    }
+}
+/** 401：daemon 凭据失效（refresh 也救不回来），调用方应引导重新 login。 */
+export function isAuthFailure(err) {
+    return err instanceof CourseClientError && err.status === 401;
+}
+/** 409：run 在服务端已进入终态（如用户取消），后续上报应静默停止。 */
+export function isRunTerminal(err) {
+    return err instanceof CourseClientError && err.status === 409;
+}
+// 错误信息里只保留响应文本前 500 字符，且先脱敏——绝不回显请求体（可能含 code/token）。
+const ERROR_BODY_MAX_CHARS = 500;
+/**
+ * Course Service HTTP 客户端。
+ *
+ * Course Service 是真相源；client 只用短期 access token 回报已分配给本 daemon 的 run。
+ * 第一版用 POST poll/events，不做 WS。401 时自动用 refresh token 换新并单次重试。
+ */
+export class CourseClient {
+    baseUrl;
+    accessToken;
+    refreshToken;
+    onAuthRefreshed;
+    constructor(baseUrl, accessToken, opts = {}) {
+        this.baseUrl = baseUrl;
+        this.accessToken = accessToken;
+        this.refreshToken = opts.refreshToken;
+        this.onAuthRefreshed = opts.onAuthRefreshed;
+    }
+    static fromAuth(auth, opts = {}) {
+        return new CourseClient(auth.courseApiUrl, auth.accessToken, {
+            ...opts,
+            refreshToken: auth.refreshToken,
+        });
+    }
+    setAccessToken(token) {
+        this.accessToken = token;
+    }
+    // courseApiUrl 可能是 host 根，也可能已带 /api/v1 —— 去重避免拼出 /api/v1/api/v1。
+    url(p) {
+        const base = this.baseUrl.replace(/\/+$/, "");
+        if (base.endsWith("/api/v1") && p.startsWith("/api/v1/")) {
+            return `${base}${p.slice("/api/v1".length)}`;
+        }
+        return `${base}${p}`;
+    }
+    async fetchJson(method, p, body, accessToken) {
+        const res = await fetch(this.url(p), {
+            method,
+            headers: {
+                ...(accessToken ? { authorization: `Bearer ${accessToken}` } : {}),
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            const detail = redactSecretString(text.slice(0, ERROR_BODY_MAX_CHARS));
+            throw new CourseClientError(res.status, `${method} ${p} -> ${res.status} ${detail}`);
+        }
+        const raw = await res.text();
+        return (raw ? JSON.parse(raw) : null);
+    }
+    async refreshAuth() {
+        if (!this.refreshToken)
+            return false;
+        try {
+            const auth = await refreshCourseDaemonSession(this.baseUrl, this.refreshToken);
+            this.accessToken = auth.accessToken;
+            this.refreshToken = auth.refreshToken;
+            this.onAuthRefreshed?.(auth);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async request(method, p, body) {
+        try {
+            return await this.fetchJson(method, p, body, this.accessToken);
+        }
+        catch (err) {
+            if (!(err instanceof CourseClientError) || err.status !== 401)
+                throw err;
+            const refreshed = await this.refreshAuth();
+            if (!refreshed)
+                throw err;
+            return await this.fetchJson(method, p, body, this.accessToken);
+        }
+    }
+    /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */
+    async claimNextRun() {
+        return this.request("GET", "/api/v1/daemon/runs/next");
+    }
+    async postEvent(agentRunId, event) {
+        await this.request("POST", `/api/v1/daemon/runs/${agentRunId}/events`, event);
+    }
+    async postFile(agentRunId, file) {
+        return this.request("POST", `/api/v1/daemon/runs/${agentRunId}/files`, file);
+    }
+    async getRunRuntimeProfile(agentRunId) {
+        return this.request("GET", `/api/v1/daemon/runs/${agentRunId}/runtime-profile`);
+    }
+}
+function authFromResponse(baseUrl, raw) {
+    const daemonId = raw.daemonId ?? raw.daemon_id;
+    const userId = raw.userId ?? raw.user_id;
+    const accessToken = raw.accessToken ?? raw.access_token;
+    const refreshToken = raw.refreshToken ?? raw.refresh_token;
+    if (!daemonId || !userId || !accessToken || !refreshToken) {
+        throw new Error("daemon auth response is missing required fields");
+    }
+    return {
+        daemonId,
+        userId,
+        label: raw.label ?? "",
+        accessToken,
+        refreshToken,
+        courseApiUrl: raw.courseApiUrl ?? raw.course_api_url ?? baseUrl,
+    };
+}
+export async function loginCourseDaemon(opts) {
+    const client = new CourseClient(opts.courseApiUrl, "");
+    const raw = await client.fetchJson("POST", "/api/v1/daemon/login", {
+        code: opts.code,
+        label: opts.label ?? "",
+        machine_fingerprint: opts.machineFingerprint,
+        capabilities: opts.capabilities ?? {},
+    }, null);
+    return authFromResponse(opts.courseApiUrl, raw);
+}
+export async function refreshCourseDaemonSession(courseApiUrl, refreshToken) {
+    const client = new CourseClient(courseApiUrl, "");
+    const raw = await client.fetchJson("POST", "/api/v1/daemon/session", { refresh_token: refreshToken }, null);
+    return authFromResponse(courseApiUrl, raw);
+}

package/dist/doctor.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimeProbeEntry } from "./types.js";
+export interface DoctorResult {
+    text: string;
+    availableCount: number;
+    totalCount: number;
+}
+export declare function renderRuntimeTable(entries: RuntimeProbeEntry[]): string[];
+export interface CourseDoctorOptions {
+    includeHidden?: boolean;
+    /** 探测函数注入点（测试用）；缺省走真实 registry probe。 */
+    detect?: (opts: {
+        includeHidden?: boolean;
+    }) => Promise<RuntimeProbeEntry[]>;
+}
+export declare function runCourseDoctor(opts?: CourseDoctorOptions): Promise<DoctorResult>;

package/dist/doctor.js

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { authFilePath, readAuth } from "./auth-store.js";
+import { detectRuntimes, getRuntimeModule } from "./runtimes/index.js";
+function pad(s, n) {
+    return s + " ".repeat(Math.max(0, n - s.length));
+}
+// token 绝不出现在 doctor 输出：Auth 区只显示非敏感身份字段。
+function renderAuthSection() {
+    const lines = ["Auth"];
+    const file = authFilePath();
+    const auth = readAuth();
+    if (!auth) {
+        const state = existsSync(file) ? "unreadable" : "missing";
+        lines.push(`  auth.json: ${state} (${file})`);
+        lines.push("  run: botlearn-course-daemon course login --api-url <url> --code <blic_xxx>");
+        return lines;
+    }
+    lines.push(`  auth.json: present (${file})`);
+    lines.push(`  courseApiUrl: ${auth.courseApiUrl}`);
+    lines.push(`  daemonId: ${auth.daemonId}`);
+    lines.push(`  label: ${auth.label || "—"}`);
+    return lines;
+}
+export function renderRuntimeTable(entries) {
+    const lines = [];
+    const rows = entries.map((e) => ({
+        runtime: e.id,
+        name: e.displayName,
+        status: e.result.available ? "ok" : "missing",
+        version: e.result.version ?? "—",
+        path: e.result.path ?? "—",
+    }));
+    const widths = {
+        runtime: Math.max(7, ...rows.map((r) => r.runtime.length)),
+        name: Math.max(4, ...rows.map((r) => r.name.length)),
+        status: Math.max(6, ...rows.map((r) => r.status.length)),
+        version: Math.max(7, ...rows.map((r) => r.version.length)),
+    };
+    lines.push(`${pad("RUNTIME", widths.runtime)}  ${pad("NAME", widths.name)}  ${pad("STATUS", widths.status)}  ${pad("VERSION", widths.version)}  PATH`);
+    for (let i = 0; i < rows.length; i += 1) {
+        const r = rows[i];
+        const e = entries[i];
+        lines.push(`${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`);
+        if (!e.result.available && e.installHint) {
+            lines.push(`    → ${e.installHint}`);
+        }
+        if (e.result.auth) {
+            const auth = e.result.auth;
+            const authStatus = auth.checked ? (auth.ok ? "ok" : "failed") : "skipped";
+            lines.push(`    auth ${authStatus}: ${auth.message ?? ""}`.trimEnd());
+        }
+    }
+    return lines;
+}
+export async function runCourseDoctor(opts = {}) {
+    const detect = opts.detect ?? detectRuntimes;
+    const entries = await detect({ includeHidden: opts.includeHidden });
+    // 登录态探测可能昂贵（真实调用一次 CLI），只在 doctor 里对可用 runtime 补跑；
+    // 注入的 entry 已带 auth 时保留，避免测试注入被覆盖。
+    for (const e of entries) {
+        if (!e.result.available || e.result.auth)
+            continue;
+        const probeAuth = getRuntimeModule(e.id)?.probeAuth;
+        if (!probeAuth)
+            continue;
+        try {
+            e.result.auth = await probeAuth();
+        }
+        catch (err) {
+            e.result.auth = {
+                checked: true,
+                ok: false,
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    const availableCount = entries.filter((e) => e.result.available).length;
+    const lines = [];
+    lines.push(...renderAuthSection());
+    lines.push("");
+    lines.push("Runtimes");
+    lines.push(...renderRuntimeTable(entries));
+    lines.push(`\n${availableCount}/${entries.length} runtimes available`);
+    return { text: lines.join("\n"), availableCount, totalCount: entries.length };
+}

package/dist/file-candidates.d.ts

@@ -0,0 +1,34 @@
+import type { Logger } from "./log.js";
+import type { RunFileCandidate, RunFileRecord } from "./types.js";
+export interface ScanLimits {
+    maxFiles?: number;
+    maxFileBytes?: number;
+    maxPreviewChars?: number;
+    maxDepth?: number;
+}
+export interface ScannedFile extends RunFileCandidate {
+    absPath: string;
+}
+export interface FileReportingClient {
+    postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord | void>;
+    uploadFileContent?(agentRunId: string, fileId: string, absPath: string, mimeType?: string): Promise<RunFileRecord>;
+}
+export interface FileReportResult {
+    reported: number;
+    uploaded: number;
+    failed: number;
+    truncated: boolean;
+}
+/**
+ * 递归扫描 workspace 产出文件候选。
+ * 跳过：符号链接、隐藏项（`.` 开头）、node_modules、超深、超大、相对路径不安全的项。
+ * 达到 maxFiles 上限后停止并标记 truncated。
+ */
+export declare function scanWorkspaceFiles(workspaceDir: string, limits?: ScanLimits): Promise<{
+    files: ScannedFile[];
+    truncated: boolean;
+}>;
+/**
+ * 扫描并逐个上报文件候选。单文件上报失败只 warn 不中断；返回成功上报数。
+ */
+export declare function reportFileCandidates(client: FileReportingClient, agentRunId: string, workspaceDir: string, log: Logger, limits?: ScanLimits): Promise<FileReportResult>;