@botlearn-course/daemon 0.0.1

package/dist/file-candidates.js

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { open, readdir } from "node:fs/promises";
+import path from "node:path";
+import { redactSecretString } from "./redaction.js";
+const DEFAULT_MAX_FILES = 50;
+// 与后端 settings.daemon_max_file_bytes 默认一致。
+const DEFAULT_MAX_FILE_BYTES = 50 * 1024 * 1024;
+// 与后端 MAX_PREVIEW_CHARS 一致。
+const DEFAULT_MAX_PREVIEW_CHARS = 4000;
+const DEFAULT_MAX_DEPTH = 8;
+// 文本启发式：前 4KiB 不含 NUL 字节即视为文本，可取 preview。
+const TEXT_SNIFF_BYTES = 4096;
+// 与后端 _is_safe_relative_path 同规：非空、非绝对、无反斜杠、无 .. 段、无空段。
+function isSafeRelativePath(rel) {
+    if (!rel || rel.startsWith("/") || rel.includes("\\"))
+        return false;
+    const segments = rel.split("/");
+    return segments.every((seg) => seg !== "" && seg !== "..");
+}
+async function sha256File(absPath) {
+    const hash = createHash("sha256");
+    const stream = createReadStream(absPath);
+    for await (const chunk of stream)
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+async function readPreview(absPath, maxPreviewChars) {
+    const handle = await open(absPath, "r");
+    try {
+        const sniff = Buffer.alloc(TEXT_SNIFF_BYTES);
+        const { bytesRead } = await handle.read(sniff, 0, TEXT_SNIFF_BYTES, 0);
+        if (sniff.subarray(0, bytesRead).includes(0))
+            return null;
+        // 预览最多 maxPreviewChars 字符；UTF-8 下 4 字节/字符封顶，读够即可。
+        const want = maxPreviewChars * 4;
+        let buf = sniff.subarray(0, bytesRead);
+        if (bytesRead === TEXT_SNIFF_BYTES && want > TEXT_SNIFF_BYTES) {
+            const more = Buffer.alloc(want - TEXT_SNIFF_BYTES);
+            const extra = await handle.read(more, 0, more.length, TEXT_SNIFF_BYTES);
+            buf = Buffer.concat([buf, more.subarray(0, extra.bytesRead)]);
+        }
+        const text = buf.toString("utf8").replace(/�+$/, "");
+        return redactSecretString(text.slice(0, maxPreviewChars));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * 递归扫描 workspace 产出文件候选。
+ * 跳过：符号链接、隐藏项（`.` 开头）、node_modules、超深、超大、相对路径不安全的项。
+ * 达到 maxFiles 上限后停止并标记 truncated。
+ */
+export async function scanWorkspaceFiles(workspaceDir, limits = {}) {
+    const maxFiles = limits.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxFileBytes = limits.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    const maxPreviewChars = limits.maxPreviewChars ?? DEFAULT_MAX_PREVIEW_CHARS;
+    const maxDepth = limits.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const files = [];
+    let truncated = false;
+    let stop = false;
+    async function walk(dir, depth) {
+        if (stop)
+            return;
+        if (depth > maxDepth) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (stop)
+                return;
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            if (entry.isSymbolicLink())
+                continue;
+            const absPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(absPath, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = path.relative(workspaceDir, absPath).split(path.sep).join("/");
+            if (!isSafeRelativePath(rel))
+                continue;
+            let sizeBytes;
+            try {
+                const handle = await open(absPath, "r");
+                try {
+                    sizeBytes = (await handle.stat()).size;
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch {
+                continue;
+            }
+            if (sizeBytes > maxFileBytes) {
+                truncated = true;
+                continue;
+            }
+            if (files.length >= maxFiles) {
+                truncated = true;
+                stop = true;
+                return;
+            }
+            let sha256;
+            let previewText;
+            try {
+                sha256 = await sha256File(absPath);
+                previewText = await readPreview(absPath, maxPreviewChars);
+            }
+            catch {
+                truncated = true;
+                continue;
+            }
+            files.push({
+                absPath,
+                event: "created",
+                path: rel,
+                name: entry.name,
+                size_bytes: sizeBytes,
+                sha256,
+                ...(previewText !== null && previewText !== "" ? { preview_text: previewText } : {}),
+            });
+        }
+    }
+    await walk(workspaceDir, 0);
+    return { files, truncated };
+}
+/**
+ * 扫描并逐个上报文件候选。单文件上报失败只 warn 不中断；返回成功上报数。
+ */
+export async function reportFileCandidates(client, agentRunId, workspaceDir, log, limits) {
+    const { files, truncated } = await scanWorkspaceFiles(workspaceDir, limits);
+    if (truncated) {
+        log.warn("workspace file scan truncated", { agentRunId, reported: files.length });
+    }
+    let reported = 0;
+    let uploaded = 0;
+    let failed = 0;
+    for (const { absPath, ...candidate } of files) {
+        try {
+            const record = await client.postFile(agentRunId, candidate);
+            reported += 1;
+            if (client.uploadFileContent) {
+                if (!record)
+                    throw new Error("file candidate response is missing its id");
+                await client.uploadFileContent(agentRunId, record.id, absPath, candidate.mime_type);
+                uploaded += 1;
+            }
+        }
+        catch (err) {
+            failed += 1;
+            log.warn("file candidate report failed", {
+                agentRunId,
+                path: candidate.path,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { reported, uploaded, failed, truncated };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 库导出面（spec §4）：类型 + 各模块公共 API。
+ * CLI 入口在 cli.ts（bin），此处仅供程序化使用。
+ */
+export * from "./types.js";
+export * from "./auth-store.js";
+export * from "./course-client.js";
+export * from "./agent-service-client.js";
+export * from "./run-dispatcher.js";
+export * from "./run-queue.js";
+export * from "./workspace.js";
+export * from "./transcript.js";
+export * from "./file-candidates.js";
+export * from "./doctor.js";
+export * from "./log.js";
+export * from "./redaction.js";
+export * from "./runtime-profile.js";
+export * from "./runtimes/index.js";
+export * from "./runtimes/engine.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * 库导出面（spec §4）：类型 + 各模块公共 API。
+ * CLI 入口在 cli.ts（bin），此处仅供程序化使用。
+ */
+export * from "./types.js";
+export * from "./auth-store.js";
+export * from "./course-client.js";
+export * from "./agent-service-client.js";
+export * from "./run-dispatcher.js";
+export * from "./run-queue.js";
+export * from "./workspace.js";
+export * from "./transcript.js";
+export * from "./file-candidates.js";
+export * from "./doctor.js";
+export * from "./log.js";
+export * from "./redaction.js";
+export * from "./runtime-profile.js";
+export * from "./runtimes/index.js";
+export * from "./runtimes/engine.js";

package/dist/log.d.ts

@@ -0,0 +1,20 @@
+type Level = "info" | "warn" | "error" | "debug";
+export interface Logger {
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+}
+export interface LogFileEntry {
+    path: string;
+    name: string;
+    sizeBytes: number;
+    mtimeMs: number;
+    active: boolean;
+}
+export declare function formatLogLine(level: Level, msg: string, fields: Record<string, unknown> | undefined, date?: Date): string;
+export declare function listDaemonLogFiles(logFile?: string): LogFileEntry[];
+export declare function rotateLogIfNeeded(logFile?: string, nextBytes?: number, maxBytes?: number, keep?: number): void;
+export declare const log: Logger;
+export declare const LOG_FILE_PATH: string;
+export {};

package/dist/log.js

@@ -0,0 +1,154 @@
+import { appendFileSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { daemonHome } from "./auth-store.js";
+import { redactSecretsDeep } from "./redaction.js";
+const LOG_DIR = path.join(daemonHome(), "logs");
+const LOG_FILE = path.join(LOG_DIR, "daemon.log");
+const LOG_ROTATE_MAX_BYTES = 10 * 1024 * 1024;
+const LOG_ROTATE_KEEP = 20;
+let inited = false;
+function ensureDir() {
+    if (inited)
+        return;
+    try {
+        mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // best-effort
+    }
+    inited = true;
+}
+function formatValue(value) {
+    if (value instanceof Error)
+        return JSON.stringify(value.stack ?? value.message);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean" || value === null)
+        return String(value);
+    if (value === undefined)
+        return "undefined";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return JSON.stringify(String(value));
+    }
+}
+export function formatLogLine(level, msg, fields, date = new Date()) {
+    const detail = Object.entries(fields ?? {})
+        .map(([key, value]) => `${key}=${formatValue(value)}`)
+        .join(" ");
+    const prefix = `[${level.toUpperCase()}] ${msg}`;
+    const suffix = `ts=${date.toISOString()}`;
+    return detail ? `${prefix} ${detail} ${suffix}` : `${prefix} ${suffix}`;
+}
+function rotatedName(file, date = new Date()) {
+    const stamp = date.toISOString().replace(/[:.]/g, "-");
+    return `${file}.${stamp}.${process.pid}`;
+}
+export function listDaemonLogFiles(logFile = LOG_FILE) {
+    const dir = path.dirname(logFile);
+    const base = path.basename(logFile);
+    const entries = [];
+    try {
+        const st = statSync(logFile);
+        if (st.isFile()) {
+            entries.push({
+                path: logFile,
+                name: base,
+                sizeBytes: st.size,
+                mtimeMs: st.mtimeMs,
+                active: true,
+            });
+        }
+    }
+    catch {
+        // no active log
+    }
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return entries;
+    }
+    for (const name of names) {
+        if (!name.startsWith(`${base}.`))
+            continue;
+        const file = path.join(dir, name);
+        try {
+            const st = statSync(file);
+            if (!st.isFile())
+                continue;
+            entries.push({
+                path: file,
+                name,
+                sizeBytes: st.size,
+                mtimeMs: st.mtimeMs,
+                active: false,
+            });
+        }
+        catch {
+            // ignore disappearing files
+        }
+    }
+    return entries.sort((a, b) => {
+        if (a.active !== b.active)
+            return a.active ? -1 : 1;
+        return b.mtimeMs - a.mtimeMs || b.name.localeCompare(a.name);
+    });
+}
+export function rotateLogIfNeeded(logFile = LOG_FILE, nextBytes = 0, maxBytes = LOG_ROTATE_MAX_BYTES, keep = LOG_ROTATE_KEEP) {
+    let currentSize = 0;
+    try {
+        const st = statSync(logFile);
+        if (!st.isFile())
+            return;
+        currentSize = st.size;
+    }
+    catch {
+        return;
+    }
+    if (currentSize + nextBytes <= maxBytes)
+        return;
+    try {
+        renameSync(logFile, rotatedName(logFile));
+    }
+    catch {
+        return;
+    }
+    const rotated = listDaemonLogFiles(logFile).filter((entry) => !entry.active);
+    for (const entry of rotated.slice(Math.max(0, keep))) {
+        try {
+            unlinkSync(entry.path);
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+}
+function write(level, msg, fields) {
+    ensureDir();
+    // 所有 fields 值序列化前先深度脱敏，token 类值绝不落盘/上屏。
+    const safeFields = fields === undefined ? undefined : redactSecretsDeep(fields);
+    const line = formatLogLine(level, msg, safeFields);
+    try {
+        rotateLogIfNeeded(LOG_FILE, Buffer.byteLength(line) + 1);
+        appendFileSync(LOG_FILE, line + "\n", { mode: 0o600 });
+    }
+    catch {
+        // ignore log write errors
+    }
+    // 同步镜像到 stderr，前台运行时可直接观察。
+    process.stderr.write(line + "\n");
+}
+export const log = {
+    info: (msg, fields) => write("info", msg, fields),
+    warn: (msg, fields) => write("warn", msg, fields),
+    error: (msg, fields) => write("error", msg, fields),
+    debug: (msg, fields) => {
+        if (process.env.BOTLEARN_DAEMON_DEBUG)
+            write("debug", msg, fields);
+    },
+};
+export const LOG_FILE_PATH = LOG_FILE;

package/dist/path-env.d.ts

@@ -0,0 +1,8 @@
+export declare function commonDaemonPathEntries(home?: string | undefined): string[];
+export declare function mergePathEntries(basePath: string | undefined, extras: string[]): string;
+/**
+ * GUI-launched macOS apps inherit a sparse launchd PATH and do not read the
+ * user's shell profile. Add common per-user CLI install locations so runtime
+ * adapters can find tools installed by uv/pipx, cargo, bun, npm, etc.
+ */
+export declare function augmentProcessPath(): void;

package/dist/path-env.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+const COMMON_USER_BIN_RELATIVE_PATHS = [
+    ".local/bin",
+    ".cargo/bin",
+    ".bun/bin",
+    ".deno/bin",
+    ".npm-global/bin",
+    ".yarn/bin",
+    ".pnpm",
+    ".pyenv/shims",
+    ".rye/shims",
+    ".pixi/bin",
+];
+const COMMON_SYSTEM_BIN_PATHS = process.platform === "darwin"
+    ? ["/opt/homebrew/bin", "/opt/homebrew/sbin", "/usr/local/bin", "/usr/local/sbin"]
+    : ["/usr/local/bin", "/usr/local/sbin"];
+export function commonDaemonPathEntries(home = process.env.HOME) {
+    const userEntries = home
+        ? COMMON_USER_BIN_RELATIVE_PATHS.map((entry) => path.join(home, entry))
+        : [];
+    return [...COMMON_SYSTEM_BIN_PATHS, ...userEntries];
+}
+export function mergePathEntries(basePath, extras) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of [...(basePath ?? "").split(path.delimiter), ...extras]) {
+        const entry = raw.trim();
+        if (!entry || seen.has(entry))
+            continue;
+        seen.add(entry);
+        out.push(entry);
+    }
+    return out.join(path.delimiter);
+}
+/**
+ * GUI-launched macOS apps inherit a sparse launchd PATH and do not read the
+ * user's shell profile. Add common per-user CLI install locations so runtime
+ * adapters can find tools installed by uv/pipx, cargo, bun, npm, etc.
+ */
+export function augmentProcessPath() {
+    process.env.PATH = mergePathEntries(process.env.PATH, commonDaemonPathEntries(process.env.HOME));
+}

package/dist/redaction.d.ts

@@ -0,0 +1,24 @@
+export declare const REDACTED = "[REDACTED]";
+export declare const RUNTIME_FAILURE_TAIL_LIMIT: number;
+/** key 命中即整值脱敏（深度脱敏用）。 */
+export declare const SECRET_KEY_RE: RegExp;
+/** Replace exact injected credentials and common encodings before persistence. */
+export declare function redactInjectedCredentials(text: string, additionalSecrets?: readonly string[]): string;
+/** Refuse raw workspace bytes that contain an injected credential or common encoding. */
+export declare function assertNoInjectedCredentials(data: Buffer, additionalSecrets?: readonly string[]): void;
+export declare function redactSecretString(text: string, additionalSecrets?: readonly string[]): string;
+/**
+ * 深度脱敏：对象 key 命中 SECRET_KEY_RE → 整值替换；字符串走 redactSecretString；
+ * 递归数组/对象。超过 depth 的容器整体替换为 REDACTED（宁可截断不可泄露）。
+ */
+export declare function redactSecretsDeep(value: unknown, depth?: number, additionalSecrets?: readonly string[]): unknown;
+/** runtime 失败文本脱敏 + 尾部截断（stderr/stdout tail、错误信息）。 */
+export declare function sanitizeRuntimeFailureText(value: string, limit?: number): string;
+export declare function tailText(value: string, limit: number): string;
+/** argv 脱敏：逐段 sanitize（512 上限），secret-value flag 的下一个参数整体替换。 */
+export declare function safeCommand(argv: string[]): string[];
+export declare function errorInfo(err: unknown): {
+    error_name?: string;
+    error_message: string;
+};
+export declare function truncateText(value: string, maxChars: number): string;

package/dist/redaction.js

@@ -0,0 +1,158 @@
+export const REDACTED = "[REDACTED]";
+export const RUNTIME_FAILURE_TAIL_LIMIT = 8 * 1024;
+const INJECTED_CREDENTIAL_ENV_NAMES = [
+    "BOTLEARN_AGENT_SERVICE_RUN_TOKEN",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "DEEPSEEK_API_KEY",
+    "BOTLEARN_DEEPSEEK_TUI_TOKEN",
+    "GEMINI_API_KEY",
+];
+const MIN_EXACT_SECRET_CHARS = 8;
+/** key 命中即整值脱敏（深度脱敏用）。 */
+export const SECRET_KEY_RE = /token|secret|private.?key|api.?key|authorization|password|credential/i;
+const SECRET_KEY_NAME_SOURCE = "(?:openai[_-]?api[_-]?key|anthropic[_-]?api[_-]?key|x-api-key|access[_-]?token|refresh[_-]?token|api[_-]?key|apikey|password|secret|token)";
+const SECRET_FLAG_SOURCE = "--(?:api-key|api_key|apikey|token|access-token|access_token|refresh-token|refresh_token|password|secret)";
+const QUOTED_JSON_SECRET_PATTERN = new RegExp(`(["'])(${SECRET_KEY_NAME_SOURCE})\\1(\\s*:\\s*)(["'])([^"'\\\\]*(?:\\\\.[^"'\\\\]*)*)\\4`, "gi");
+const QUOTED_ARGV_SECRET_PATTERN = new RegExp(`(["'])(${SECRET_FLAG_SOURCE})\\1(\\s*,\\s*)(["'])([^"'\\\\]*(?:\\\\.[^"'\\\\]*)*)\\4`, "gi");
+// blic_ 是课程 install code 前缀，与 runtime token 前缀一并脱敏。
+const SECRET_PREFIX_PATTERN = /\b(blic_|drt_|dit_|gho_|ghp_|sk-)[A-Za-z0-9_-]+/g;
+const SECRET_VALUE_PATTERNS = [
+    [/\b(Bearer\s+)[^\s"']+/gi, `$1${REDACTED}`],
+    [new RegExp(`(^|[\\s])(${SECRET_FLAG_SOURCE})=([^\\s"']+)`, "gi"), `$1$2=${REDACTED}`],
+    [new RegExp(`(^|[\\s])(${SECRET_FLAG_SOURCE})(\\s+)([^\\s"']+)`, "gi"), `$1$2$3${REDACTED}`],
+    [
+        /\b((?:openai|anthropic)[_-]?api[_-]?key|x-api-key|access[_-]?token|refresh[_-]?token|api[_-]?key|apikey|password|secret|token)(\s*[:=]\s*)[^\s"']+/gi,
+        `$1$2${REDACTED}`,
+    ],
+    [SECRET_PREFIX_PATTERN, `$1${REDACTED}`],
+];
+const SECRET_VALUE_FLAGS = new Set([
+    "--api-key",
+    "--api_key",
+    "--apikey",
+    "--token",
+    "--access-token",
+    "--access_token",
+    "--refresh-token",
+    "--refresh_token",
+    "--password",
+    "--secret",
+]);
+/** 轻量字符串脱敏：Bearer / token= / --token 形态 / 已知 token 前缀。 */
+function injectedCredentialVariants(additionalSecrets = [], env = process.env) {
+    const values = [
+        ...INJECTED_CREDENTIAL_ENV_NAMES.map((name) => env[name]),
+        ...additionalSecrets,
+    ].filter((value) => typeof value === "string" && value.length >= MIN_EXACT_SECRET_CHARS);
+    const variants = new Set();
+    for (const value of values) {
+        variants.add(value);
+        variants.add(Buffer.from(value, "utf8").toString("base64"));
+        variants.add(Buffer.from(value, "utf8").toString("base64url"));
+        variants.add(Buffer.from(value, "utf8").toString("hex"));
+        const encoded = encodeURIComponent(value);
+        if (encoded !== value)
+            variants.add(encoded);
+    }
+    return [...variants].sort((left, right) => right.length - left.length);
+}
+/** Replace exact injected credentials and common encodings before persistence. */
+export function redactInjectedCredentials(text, additionalSecrets = []) {
+    let output = text;
+    for (const value of injectedCredentialVariants(additionalSecrets)) {
+        output = output.split(value).join(REDACTED);
+    }
+    return output;
+}
+/** Refuse raw workspace bytes that contain an injected credential or common encoding. */
+export function assertNoInjectedCredentials(data, additionalSecrets = []) {
+    for (const value of injectedCredentialVariants(additionalSecrets)) {
+        if (data.includes(Buffer.from(value, "utf8"))) {
+            throw new Error("workspace file contains an injected credential");
+        }
+    }
+}
+export function redactSecretString(text, additionalSecrets = []) {
+    return redactInjectedCredentials(text, additionalSecrets)
+        .replace(/\b(Bearer\s+)[^\s"']+/gi, `$1${REDACTED}`)
+        .replace(new RegExp(`(^|[\\s])(${SECRET_FLAG_SOURCE})=([^\\s"']+)`, "gi"), `$1$2=${REDACTED}`)
+        .replace(new RegExp(`(^|[\\s])(${SECRET_FLAG_SOURCE})(\\s+)([^\\s"']+)`, "gi"), `$1$2$3${REDACTED}`)
+        .replace(/\b(token=)[^\s"']+/gi, `$1${REDACTED}`)
+        .replace(SECRET_PREFIX_PATTERN, `$1${REDACTED}`);
+}
+const DEFAULT_REDACT_DEPTH = 8;
+/**
+ * 深度脱敏：对象 key 命中 SECRET_KEY_RE → 整值替换；字符串走 redactSecretString；
+ * 递归数组/对象。超过 depth 的容器整体替换为 REDACTED（宁可截断不可泄露）。
+ */
+export function redactSecretsDeep(value, depth = DEFAULT_REDACT_DEPTH, additionalSecrets = []) {
+    if (typeof value === "string")
+        return redactSecretString(value, additionalSecrets);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (value instanceof Error) {
+        // 保持 Error 实例：log 的 formatValue 依赖 instanceof Error 分支序列化 stack。
+        const copy = new Error(redactSecretString(value.message, additionalSecrets));
+        copy.name = value.name;
+        if (value.stack)
+            copy.stack = redactSecretString(value.stack, additionalSecrets);
+        return copy;
+    }
+    if (value instanceof Date)
+        return value;
+    if (depth <= 0)
+        return REDACTED;
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecretsDeep(item, depth - 1, additionalSecrets));
+    }
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        out[key] = SECRET_KEY_RE.test(key)
+            ? REDACTED
+            : redactSecretsDeep(v, depth - 1, additionalSecrets);
+    }
+    return out;
+}
+/** runtime 失败文本脱敏 + 尾部截断（stderr/stdout tail、错误信息）。 */
+export function sanitizeRuntimeFailureText(value, limit = RUNTIME_FAILURE_TAIL_LIMIT) {
+    let out = redactInjectedCredentials(value);
+    out = out.replace(QUOTED_JSON_SECRET_PATTERN, (_match, keyQuote, key, colon, valueQuote) => `${keyQuote}${key}${keyQuote}${colon}${valueQuote}${REDACTED}${valueQuote}`);
+    out = out.replace(QUOTED_ARGV_SECRET_PATTERN, (_match, flagQuote, flag, comma, valueQuote) => `${flagQuote}${flag}${flagQuote}${comma}${valueQuote}${REDACTED}${valueQuote}`);
+    for (const [pattern, replacement] of SECRET_VALUE_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return tailText(out, limit);
+}
+export function tailText(value, limit) {
+    return value.length > limit ? value.slice(-limit) : value;
+}
+/** argv 脱敏：逐段 sanitize（512 上限），secret-value flag 的下一个参数整体替换。 */
+export function safeCommand(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const part = argv[i];
+        out.push(sanitizeRuntimeFailureText(part, 512));
+        if (SECRET_VALUE_FLAGS.has(part.toLowerCase()) && i + 1 < argv.length) {
+            out.push(REDACTED);
+            i++;
+        }
+    }
+    return out;
+}
+export function errorInfo(err) {
+    if (err instanceof Error) {
+        return {
+            error_name: err.name || "Error",
+            error_message: sanitizeRuntimeFailureText(err.message, 2048),
+        };
+    }
+    return { error_message: sanitizeRuntimeFailureText(String(err), 2048) };
+}
+export function truncateText(value, maxChars) {
+    if (value.length <= maxChars)
+        return value;
+    return `${value.slice(0, maxChars)}…(truncated)`;
+}

package/dist/run-dispatcher.d.ts

@@ -0,0 +1,43 @@
+import { type ScanLimits } from "./file-candidates.js";
+import { type Logger } from "./log.js";
+import { type CourseRuntimeProfile, type CourseRuntime, type RunEvent, type RunFileRecord, type RunStartPayload } from "./types.js";
+export interface RunDispatcherOptions {
+    defaultRuntimeId?: string;
+    log?: Logger;
+    scanLimits?: ScanLimits;
+    now?: () => number;
+}
+export interface RunReportingClient {
+    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postFile(agentRunId: string, file: import("./types.js").RunFileCandidate): Promise<RunFileRecord | void>;
+    uploadFileContent?(agentRunId: string, fileId: string, absPath: string, mimeType?: string): Promise<RunFileRecord>;
+    getRunRuntimeProfile?(agentRunId: string): Promise<CourseRuntimeProfile>;
+}
+/**
+ * Run dispatcher：把 Course Service 下发的 run.start 交给 runtime，
+ * 并把 runtime 输出归一化成 run.block / run.message / run.completed 回报 Course Service。
+ *
+ * - 串行：同一 agent_instance 经 RunQueue 排队。
+ * - 取消：AbortController；runtime 抛错归一化为 run.failed。
+ * - 服务端 409（run 已终态）→ abort 并静默停止后续上报。
+ * - daemon 不推进进度，只汇报事实。
+ */
+export declare class RunDispatcher {
+    private readonly client;
+    private readonly runtimes;
+    private readonly queue;
+    private readonly inflight;
+    private readonly defaultRuntimeId;
+    private readonly log;
+    private readonly scanLimits?;
+    private readonly now;
+    constructor(client: RunReportingClient, runtimes: Map<string, CourseRuntime>, opts?: RunDispatcherOptions);
+    /** 排队执行一个 run。返回的 Promise 不 reject（失败已归一化回报为 run.failed）。 */
+    dispatch(payload: RunStartPayload): Promise<void>;
+    cancel(agentRunId: string): boolean;
+    cancelAll(): void;
+    get activeCount(): number;
+    /** 等待所有 run（含排队中的）结束；超时返回 false。 */
+    drain(timeoutMs: number): Promise<boolean>;
+    private execute;
+}