@botlearn-course/daemon 0.0.1 → 0.0.2

package/dist/runtimes/progress.js

@@ -0,0 +1,339 @@
+import { existsSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_PROGRESS_EVENTS_PER_ATTEMPT, tryNormalizeProgressReport, } from "../mcp/report-progress.js";
+export const DEEPSEEK_PROGRESS_TOOL_ALIASES = new Set([
+    "report_progress",
+    "mcp_botlearn_report_progress",
+    "mcp__botlearn__report_progress",
+]);
+export const DEEPSEEK_PROGRESS_SYSTEM_INSTRUCTION = [
+    "BotLearn execution progress reporting:",
+    "- Use report_progress only when a meaningful user-visible execution phase starts or completes.",
+    "- Use status in_progress at phase start and completed only when that execution phase actually ends.",
+    "- Short tasks need no progress report; do not report every command, file read, or retry.",
+    "- Keep summary concise and user-facing. Never include hidden reasoning, chain of thought, secrets, tokens, prompts, raw command output, or large code excerpts.",
+    "- completed means only that an execution phase ended. It does not complete a course task, checkpoint, learning objective, or human review.",
+    "- If report_progress fails, continue the main task and do not bypass it through another tool.",
+].join("\n");
+export class ProgressMcpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProgressMcpConfigError";
+    }
+}
+export function createDeepseekProgressState() {
+    return {
+        emitted: 0,
+        lastProgressKey: null,
+        callIds: new Set(),
+        limitReported: false,
+        invalid: 0,
+        duplicate: 0,
+        overLimit: 0,
+    };
+}
+/** Return only adapter-side drops; emitted blocks are counted by RunDispatcher after reporting. */
+export function deepseekProgressDispositions(state) {
+    if (state.invalid + state.duplicate + state.overLimit === 0)
+        return undefined;
+    return {
+        invalid: state.invalid,
+        deduplicated: state.duplicate,
+        over_limit: state.overLimit,
+    };
+}
+export function progressSystemContext(systemContext) {
+    const context = systemContext?.trim();
+    return context
+        ? `${context}\n\n${DEEPSEEK_PROGRESS_SYSTEM_INSTRUCTION}`
+        : DEEPSEEK_PROGRESS_SYSTEM_INSTRUCTION;
+}
+/**
+ * Recognize a progress tool start and emit only a typed, whitelisted block. Invalid,
+ * duplicate, and over-budget calls remain handled so no generic tool card leaks arguments.
+ */
+export function adaptDeepseekProgressStarted(payload, seq, state) {
+    const tool = extractTool(payload);
+    if (!tool.name || !DEEPSEEK_PROGRESS_TOOL_ALIASES.has(tool.name)) {
+        return { matched: false };
+    }
+    for (const id of tool.ids)
+        state.callIds.add(id);
+    const progress = tryNormalizeProgressReport(tool.arguments);
+    if (!progress) {
+        state.invalid += 1;
+        return { matched: true };
+    }
+    const key = progressKey(progress);
+    if (state.lastProgressKey === key) {
+        state.duplicate += 1;
+        return { matched: true };
+    }
+    if (state.emitted >= MAX_PROGRESS_EVENTS_PER_ATTEMPT) {
+        state.overLimit += 1;
+        if (!state.limitReported) {
+            state.limitReported = true;
+            return { matched: true, limitExceeded: true };
+        }
+        return { matched: true };
+    }
+    state.lastProgressKey = key;
+    state.emitted += 1;
+    return { matched: true, block: { kind: "progress", seq, progress } };
+}
+/** Suppress the result for a recognized progress call, including result envelopes with only ids. */
+export function isDeepseekProgressCompletion(payload, state) {
+    const tool = extractTool(payload);
+    const namedProgress = Boolean(tool.name && DEEPSEEK_PROGRESS_TOOL_ALIASES.has(tool.name));
+    const matchingIds = tool.ids.filter((id) => state.callIds.has(id));
+    for (const id of matchingIds)
+        state.callIds.delete(id);
+    return namedProgress || matchingIds.length > 0;
+}
+/**
+ * DeepSeek MCP auto-injection uses a stdio server launched through `env -i`, so it cannot
+ * inherit Course or model credentials from the DeepSeek process.
+ */
+export function progressMcpAutoInjectionSupported(platform = process.platform) {
+    // DeepSeek overlays config.env on an inherited process environment. Windows has no
+    // env -i equivalent in the fixed runtime, so fail closed instead of handing provider
+    // credentials to the progress MCP process.
+    return platform !== "win32";
+}
+export function resolveExistingDeepseekMcpConfig(env = process.env, home = homedir()) {
+    const explicit = env.DEEPSEEK_MCP_CONFIG?.trim();
+    if (explicit)
+        return resolveMcpPath(explicit, home);
+    const defaultConfigPath = path.join(home, ".deepseek", "config.toml");
+    const explicitConfigPath = env.DEEPSEEK_CONFIG_PATH?.trim()
+        ? resolveMcpPath(env.DEEPSEEK_CONFIG_PATH.trim(), home)
+        : null;
+    const configPath = explicitConfigPath
+        && (existsSync(explicitConfigPath) || !existsSync(defaultConfigPath))
+        ? explicitConfigPath
+        : defaultConfigPath;
+    const configured = readConfiguredMcpPath(configPath, home, env.DEEPSEEK_PROFILE?.trim());
+    if (configured)
+        return configured;
+    const defaultPath = path.join(home, ".deepseek", "mcp.json");
+    return existsSync(defaultPath) ? defaultPath : null;
+}
+/** Create an ephemeral config that preserves a user's existing MCP servers and settings. */
+export function createProgressMcpConfig(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (!progressMcpAutoInjectionSupported(platform)) {
+        throw new ProgressMcpConfigError("report_progress MCP auto-injection is unavailable on Windows because clean child env isolation cannot be guaranteed");
+    }
+    const serverPath = fileURLToPath(new URL("../mcp/report-progress-server.js", import.meta.url));
+    const baseConfigPath = options.baseConfigPath === undefined
+        ? resolveExistingDeepseekMcpConfig()
+        : options.baseConfigPath;
+    const baseConfig = loadBaseMcpConfig(baseConfigPath);
+    const baseServers = mergeMcpServerFields(baseConfig);
+    if (Object.hasOwn(baseServers, "botlearn")) {
+        throw new ProgressMcpConfigError("DeepSeek MCP server key 'botlearn' is reserved for BotLearn progress reporting");
+    }
+    const dir = mkdtempSync(path.join(tmpdir(), "botlearn-progress-mcp-"));
+    const configPath = path.join(dir, "mcp.json");
+    const stagingPath = path.join(dir, ".mcp.json.tmp");
+    const minimalPath = "/usr/bin:/bin";
+    const baseSettings = { ...baseConfig };
+    delete baseSettings.servers;
+    delete baseSettings.mcpServers;
+    const config = {
+        ...baseSettings,
+        servers: {
+            ...baseServers,
+            botlearn: {
+                command: "/usr/bin/env",
+                args: ["-i", `PATH=${minimalPath}`, process.execPath, serverPath],
+                env: {},
+                disabled: false,
+                enabled: true,
+                required: false,
+            },
+        },
+    };
+    try {
+        writeFileSync(stagingPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+        renameSync(stagingPath, configPath);
+        return { dir, path: configPath };
+    }
+    catch (error) {
+        rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+function loadBaseMcpConfig(configPath) {
+    if (!configPath)
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("root must be a JSON object");
+        }
+        const record = parsed;
+        if (record.servers !== undefined
+            && (!record.servers || typeof record.servers !== "object" || Array.isArray(record.servers))) {
+            throw new Error("servers must be a JSON object");
+        }
+        if (record.mcpServers !== undefined
+            && (!record.mcpServers
+                || typeof record.mcpServers !== "object"
+                || Array.isArray(record.mcpServers))) {
+            throw new Error("mcpServers must be a JSON object");
+        }
+        return record;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProgressMcpConfigError(`Cannot preserve existing DeepSeek MCP config ${configPath}: ${message}`);
+    }
+}
+function mergeMcpServerFields(config) {
+    const servers = objectField(config, "servers") ?? {};
+    const compatibleServers = objectField(config, "mcpServers") ?? {};
+    const duplicate = Object.keys(servers).find((name) => Object.hasOwn(compatibleServers, name));
+    if (duplicate) {
+        throw new ProgressMcpConfigError(`DeepSeek MCP server '${duplicate}' is defined in both servers and mcpServers`);
+    }
+    return { ...compatibleServers, ...servers };
+}
+function readConfiguredMcpPath(configPath, home, selectedProfile) {
+    if (!existsSync(configPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProgressMcpConfigError(`Cannot read DeepSeek config ${configPath}: ${message}`);
+    }
+    let section = "root";
+    let rootValue = null;
+    let profileValue = null;
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const table = /^\[\s*([^\]]+?)\s*\]\s*(?:#.*)?$/.exec(trimmed);
+        if (table) {
+            const profile = parseProfileTableName(table[1] ?? "", configPath);
+            section = selectedProfile && profile === selectedProfile ? "selected_profile" : "other";
+            continue;
+        }
+        if (section === "other")
+            continue;
+        const match = /^mcp_config_path\s*=\s*(.*?)\s*$/.exec(trimmed);
+        if (!match)
+            continue;
+        const value = parseTomlPathValue(match[1] ?? "", configPath);
+        const resolved = value ? resolveMcpPath(value, home) : null;
+        if (section === "selected_profile")
+            profileValue = resolved;
+        else
+            rootValue = resolved;
+    }
+    return profileValue ?? rootValue;
+}
+function parseProfileTableName(raw, configPath) {
+    const bare = /^profiles\s*\.\s*([A-Za-z0-9_-]+)$/.exec(raw);
+    if (bare)
+        return bare[1] ?? null;
+    const doubleQuoted = /^profiles\s*\.\s*("(?:\\.|[^"\\])*")$/.exec(raw);
+    if (doubleQuoted) {
+        try {
+            return JSON.parse(doubleQuoted[1]);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ProgressMcpConfigError(`Invalid profile table in ${configPath}: ${message}`);
+        }
+    }
+    const singleQuoted = /^profiles\s*\.\s*'([^']*)'$/.exec(raw);
+    return singleQuoted?.[1] ?? null;
+}
+function parseTomlPathValue(raw, configPath) {
+    const doubleQuoted = /^("(?:\\.|[^"\\])*")\s*(?:#.*)?$/.exec(raw);
+    if (doubleQuoted) {
+        try {
+            return JSON.parse(doubleQuoted[1]);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ProgressMcpConfigError(`Invalid mcp_config_path in ${configPath}: ${message}`);
+        }
+    }
+    const singleQuoted = /^'([^']*)'\s*(?:#.*)?$/.exec(raw);
+    if (singleQuoted)
+        return singleQuoted[1] ?? "";
+    return raw.replace(/\s+#.*$/, "").trim();
+}
+function resolveMcpPath(value, home) {
+    if (value === "~")
+        return home;
+    if (value.startsWith("~/") || value.startsWith("~\\")) {
+        return path.join(home, value.slice(2));
+    }
+    return path.resolve(value);
+}
+export function cleanupProgressMcpConfig(config) {
+    if (config)
+        rmSync(config.dir, { recursive: true, force: true });
+}
+function progressKey(progress) {
+    return `${progress.status}\0${progress.summary}`;
+}
+function extractTool(payload) {
+    if (!payload || typeof payload !== "object")
+        return { ids: [] };
+    const root = payload;
+    const embedded = objectField(root, "payload");
+    const candidates = [
+        root,
+        objectField(root, "tool"),
+        embedded,
+        objectField(embedded, "tool"),
+    ].filter((candidate) => candidate !== undefined);
+    let name;
+    let args;
+    for (const candidate of candidates) {
+        name ??= stringField(candidate, "name") ?? stringField(candidate, "tool_name");
+        if (args === undefined) {
+            if (Object.hasOwn(candidate, "input"))
+                args = candidate.input;
+            else if (Object.hasOwn(candidate, "arguments"))
+                args = candidate.arguments;
+        }
+    }
+    const ids = new Set();
+    for (const candidate of candidates) {
+        for (const key of ["id", "call_id", "tool_call_id", "item_id"]) {
+            const value = stringField(candidate, key);
+            if (value)
+                ids.add(value);
+        }
+        const item = objectField(candidate, "item");
+        const itemId = stringField(item, "id");
+        if (itemId)
+            ids.add(itemId);
+    }
+    return {
+        ...(name ? { name } : {}),
+        ...(args !== undefined ? { arguments: args } : {}),
+        ids: [...ids],
+    };
+}
+function objectField(value, key) {
+    const field = value?.[key];
+    return field && typeof field === "object" && !Array.isArray(field)
+        ? field
+        : undefined;
+}
+function stringField(value, key) {
+    const field = value?.[key];
+    return typeof field === "string" ? field : undefined;
+}

package/dist/transcript.js

@@ -15,6 +15,12 @@ export class TranscriptWriter {
     }
     writeBlock(block) {
         const record = { type: "block", kind: block.kind };
+        if (block.kind === "progress") {
+            record.summary = redactSecretString(block.summary);
+            record.status = block.status;
+            this.append(record);
+            return;
+        }
         if (block.text !== undefined)
             record.text = redactSecretString(block.text);
         if (block.raw !== undefined)

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * 本包不依赖 BotCord Hub/room/owner-chat 语义；wire 类型与后端
  * `backend/botlearn_course/schemas.py` 的 daemon 契约严格对齐。
  */
+import type { ProgressStatus } from "./mcp/report-progress.js";
 /** `GET /daemon/runs/next` 下发的 run.start 载荷（snake_case，与后端 RunStartPayloadOut 一致）。 */
 export interface RunStartPayload {
     agent_run_id: string;
@@ -106,12 +107,27 @@ export interface AppliedRunRuntimeProfile {
     skillsRoot: string;
     skillRefs: string[];
 }
-/** runtime adapter 产出的归一化块。wire 上只透传 text 与 kind；raw 仅进本地 transcript。 */
-export interface RuntimeBlock {
+/** runtime adapter 产出的普通归一化块；raw 仅进本地 transcript。 */
+export interface RuntimeContentBlock {
     kind: "text_delta" | "text" | "thinking" | "tool_call" | "tool_result" | "status" | "error";
     text?: string;
     raw?: unknown;
 }
+/** 已由 provider adapter 严格归一化、无 provider raw envelope 的进度遥测。 */
+export interface RuntimeProgressBlock {
+    kind: "progress";
+    runtime: string;
+    summary: string;
+    status: ProgressStatus;
+    raw?: never;
+}
+export type RuntimeBlock = RuntimeContentBlock | RuntimeProgressBlock;
+/** runtime adapter 在发出进度块前丢弃的非内容处置计数。 */
+export interface RuntimeProgressDispositions {
+    invalid: number;
+    deduplicated: number;
+    over_limit: number;
+}
 export interface RuntimeAuthProbe {
     checked: boolean;
     ok: boolean;
@@ -129,6 +145,8 @@ export interface CourseRuntimeSink {
     block(block: RuntimeBlock): Promise<void>;
     message(text: string): Promise<void>;
     file(file: RunFileCandidate): Promise<void>;
+    /** 可选的 run-scoped 内部遥测；不得包含 summary 或 provider raw envelope。 */
+    progressDispositions?(dispositions: RuntimeProgressDispositions): Promise<void>;
 }
 /** 一次 run 的本地执行上下文：服务器 payload + daemon 本地准备产物。 */
 export interface RunExecution {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botlearn-course/daemon",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Lightweight BotLearn Course daemon: run course tasks on your own machine with your own agent runtime (BYOA).",
   "type": "module",
   "bin": {