@botlearn-course/daemon 0.0.1 → 0.0.2

package/README.md

@@ -47,7 +47,7 @@ run 的 `runtime.id` 决定用哪个 adapter 执行；未指定时默认 `codex`
 | `claude-code` | Claude Code | `claude` | `BOTLEARN_CLAUDE_BIN` | doctor 会额外探测登录状态 |
 | `gemini` | Gemini CLI | `gemini` | `BOTLEARN_GEMINI_BIN` | |
 | `kimi-cli` | Kimi CLI | `kimi` | `BOTLEARN_KIMI_CLI_BIN` | |
-| `deepseek-tui` | DeepSeek TUI | `deepseek` | `BOTLEARN_DEEPSEEK_TUI_BIN` | |
+| `deepseek-tui` | DeepSeek TUI | `deepseek` | `BOTLEARN_DEEPSEEK_TUI_BIN` | Linux/macOS 本地 server 会保留现有 MCP 配置并注入零依赖 `report_progress`；`botlearn` 是保留 server key。Windows 因固定 runtime 无法保证 MCP clean-env，首版 fail closed、不注入 progress |
 | `hermes-agent` | Hermes Agent | `hermes-acp` | `BOTLEARN_HERMES_AGENT_BIN` | ACP stdio 协议 |
 | `openclaw-acp` | OpenClaw (ACP) | `openclaw` | `BOTLEARN_OPENCLAW_BIN` | 还需配置 `BOTLEARN_OPENCLAW_URL`（可选 `BOTLEARN_OPENCLAW_TOKEN` / `BOTLEARN_OPENCLAW_AGENT`），二进制或 URL 缺失时 doctor 标记不可用 |
 | `fake` | 假 runtime | 无 | — | 仅测试/演示用：产出确定性文本与一个 `draft.md`。默认隐藏，只有 `BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME=1` 时才注册并上报 |
@@ -93,6 +93,8 @@ runtime 凭据。
   终态前把完整文件上传到 Course Service 的受保护存储。
 - 每个 run 在独立 workspace 内执行并有超时上限；runtime 进程在取消/超时后会被终止
   （SIGTERM → SIGKILL）。
+- `report_progress` MCP 子进程以 clean environment 启动，不继承 Course 控制字段或模型凭据；
+  transcript 与 Course event 只保留严格归一化后的 `summary` / `status`，不保存原始 tool arguments。
 - `course logout` 只删除本机凭据；要让服务端立即吊销该 daemon，请在前端 daemon 列表执行
   revoke。
 - 本包 production 依赖为零，发布 tarball 只包含 `dist/`、`README.md`、`package.json`、

package/dist/cli.d.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 import { type Logger } from "./log.js";
 import type { RunStartPayload } from "./types.js";
-/** Keep the run-scoped Course credential out of runtime subprocess environments. */
-export declare function clearAgentServiceControlEnv(env?: NodeJS.ProcessEnv): void;
+export { clearAgentServiceControlEnv } from "./runtime-env.js";
 export interface CliArgs {
     positional: string[];
     flags: Record<string, string | boolean>;

package/dist/cli.js

@@ -11,6 +11,7 @@ import { log } from "./log.js";
 import { augmentProcessPath } from "./path-env.js";
 import { redactSecretString } from "./redaction.js";
 import { RunDispatcher } from "./run-dispatcher.js";
+import { clearAgentServiceControlEnv } from "./runtime-env.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)
@@ -46,17 +47,7 @@ Agent Service sandbox environment:
 // 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 { clearAgentServiceControlEnv } from "./runtime-env.js";
 export function parseCliArgs(argv) {
     const positional = [];
     const flags = {};

package/dist/course-client.js

@@ -1,4 +1,4 @@
-import { redactSecretString } from "./redaction.js";
+import { redactSecretString, redactSecretsDeep } from "./redaction.js";
 export class CourseClientError extends Error {
     status;
     constructor(status, message) {
@@ -100,7 +100,9 @@ export class CourseClient {
         return this.request("GET", "/api/v1/daemon/runs/next");
     }
     async postEvent(agentRunId, event) {
-        await this.request("POST", `/api/v1/daemon/runs/${agentRunId}/events`, event);
+        const credentials = [this.accessToken, this.refreshToken].filter((value) => typeof value === "string");
+        const sanitized = redactSecretsDeep(event, 8, credentials);
+        await this.request("POST", `/api/v1/daemon/runs/${agentRunId}/events`, sanitized);
     }
     async postFile(agentRunId, file) {
         return this.request("POST", `/api/v1/daemon/runs/${agentRunId}/files`, file);

package/dist/index.d.ts

@@ -15,5 +15,7 @@ export * from "./doctor.js";
 export * from "./log.js";
 export * from "./redaction.js";
 export * from "./runtime-profile.js";
+export * from "./runtime-env.js";
+export * from "./mcp/report-progress.js";
 export * from "./runtimes/index.js";
 export * from "./runtimes/engine.js";

package/dist/index.js

@@ -15,5 +15,7 @@ export * from "./doctor.js";
 export * from "./log.js";
 export * from "./redaction.js";
 export * from "./runtime-profile.js";
+export * from "./runtime-env.js";
+export * from "./mcp/report-progress.js";
 export * from "./runtimes/index.js";
 export * from "./runtimes/engine.js";

package/dist/mcp/report-progress-server.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc?: unknown;
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+/** Pure JSON-RPC request handler used by both stdio and deterministic unit tests. */
+export declare function handleReportProgressRequest(request: JsonRpcRequest): JsonRpcResponse | null;
+export declare function runReportProgressStdioServer(): void;
+export {};

package/dist/mcp/report-progress-server.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { normalizeProgressReport, ProgressValidationError, REPORT_PROGRESS_INPUT_SCHEMA, } from "./report-progress.js";
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+const TOOL = {
+    name: "report_progress",
+    description: "Report a concise, learner-visible execution phase update. This does not complete course progress.",
+    inputSchema: REPORT_PROGRESS_INPUT_SCHEMA,
+};
+function responseId(value) {
+    return typeof value === "string" || typeof value === "number" || value === null ? value : null;
+}
+function toolError(code, message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    schemaVersion: "tool-result/0.1",
+                    ok: false,
+                    code,
+                    error: { message },
+                    evidence: [],
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+/** Pure JSON-RPC request handler used by both stdio and deterministic unit tests. */
+export function handleReportProgressRequest(request) {
+    if (request.id === undefined)
+        return null;
+    const id = responseId(request.id);
+    if (request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+        return { jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } };
+    }
+    if (request.method === "initialize") {
+        const requested = request.params && typeof request.params === "object"
+            ? request.params.protocolVersion
+            : undefined;
+        return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+                protocolVersion: typeof requested === "string" && requested.length > 0
+                    ? requested
+                    : DEFAULT_PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: "botlearn-report-progress", version: "0.1.0" },
+            },
+        };
+    }
+    if (request.method === "tools/list") {
+        return { jsonrpc: "2.0", id, result: { tools: [TOOL] } };
+    }
+    if (request.method === "tools/call") {
+        const params = request.params && typeof request.params === "object"
+            ? request.params
+            : {};
+        if (params.name !== TOOL.name) {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: toolError("unknown_tool", "Unknown tool"),
+            };
+        }
+        try {
+            const progress = normalizeProgressReport(params.arguments);
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                schemaVersion: "tool-result/0.1",
+                                ok: true,
+                                code: "progress_reported",
+                                data: progress,
+                                evidence: [],
+                            }),
+                        },
+                    ],
+                    isError: false,
+                },
+            };
+        }
+        catch (error) {
+            if (!(error instanceof ProgressValidationError))
+                throw error;
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: toolError("invalid_progress", error.message),
+            };
+        }
+    }
+    return { jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } };
+}
+export function runReportProgressStdioServer() {
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let response;
+        try {
+            response = handleReportProgressRequest(JSON.parse(line));
+        }
+        catch {
+            response = {
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32700, message: "Parse error" },
+            };
+        }
+        if (response)
+            process.stdout.write(`${JSON.stringify(response)}\n`);
+    });
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule())
+    runReportProgressStdioServer();

package/dist/mcp/report-progress.d.ts

@@ -0,0 +1,29 @@
+export declare const PROGRESS_STATUSES: readonly ["in_progress", "completed"];
+export type ProgressStatus = (typeof PROGRESS_STATUSES)[number];
+export interface ProgressReport {
+    summary: string;
+    status: ProgressStatus;
+}
+export declare const MAX_PROGRESS_EVENTS_PER_ATTEMPT = 64;
+export declare const REPORT_PROGRESS_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["summary", "status"];
+    readonly properties: {
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 240;
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["in_progress", "completed"];
+        };
+    };
+};
+export declare class ProgressValidationError extends Error {
+    constructor(message: string);
+}
+/** Strict shared normalizer: Unicode trim, exact fields/types, then code-point length. */
+export declare function normalizeProgressReport(value: unknown): ProgressReport;
+export declare function tryNormalizeProgressReport(value: unknown): ProgressReport | null;

package/dist/mcp/report-progress.js

@@ -0,0 +1,60 @@
+export const PROGRESS_STATUSES = ["in_progress", "completed"];
+export const MAX_PROGRESS_EVENTS_PER_ATTEMPT = 64;
+export const REPORT_PROGRESS_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["summary", "status"],
+    properties: {
+        summary: {
+            type: "string",
+            minLength: 1,
+            maxLength: 240,
+        },
+        status: {
+            type: "string",
+            enum: PROGRESS_STATUSES,
+        },
+    },
+};
+// Unicode White_Space plus BOM/ZWNBSP, matching the platform's user-facing trim behavior.
+const UNICODE_WHITESPACE_AT_EDGES = /^(?:\p{White_Space}|\uFEFF)+|(?:\p{White_Space}|\uFEFF)+$/gu;
+const MAX_PROGRESS_CODE_POINTS = 240;
+export class ProgressValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProgressValidationError";
+    }
+}
+/** Strict shared normalizer: Unicode trim, exact fields/types, then code-point length. */
+export function normalizeProgressReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ProgressValidationError("progress arguments must be an object");
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.length !== 2 || keys[0] !== "status" || keys[1] !== "summary") {
+        throw new ProgressValidationError("progress arguments must contain only summary and status");
+    }
+    if (typeof record.summary !== "string") {
+        throw new ProgressValidationError("progress summary must be a string");
+    }
+    if (record.status !== "in_progress" && record.status !== "completed") {
+        throw new ProgressValidationError("progress status is invalid");
+    }
+    const summary = record.summary.replace(UNICODE_WHITESPACE_AT_EDGES, "");
+    const length = Array.from(summary).length;
+    if (length < 1 || length > MAX_PROGRESS_CODE_POINTS) {
+        throw new ProgressValidationError("progress summary must contain 1 to 240 Unicode code points");
+    }
+    return { summary, status: record.status };
+}
+export function tryNormalizeProgressReport(value) {
+    try {
+        return normalizeProgressReport(value);
+    }
+    catch (error) {
+        if (error instanceof ProgressValidationError)
+            return null;
+        throw error;
+    }
+}

package/dist/run-dispatcher.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { CourseClientError, isRunTerminal } from "./course-client.js";
 import { reportFileCandidates } from "./file-candidates.js";
 import { log as defaultLog } from "./log.js";
+import { MAX_PROGRESS_EVENTS_PER_ATTEMPT, tryNormalizeProgressReport, } from "./mcp/report-progress.js";
 import { errorInfo, redactSecretString, truncateText } from "./redaction.js";
 import { missingRunCapabilities } from "./runtime-capabilities.js";
 import { RunQueue } from "./run-queue.js";
@@ -90,6 +91,15 @@ export class RunDispatcher {
         let profileApplied = false;
         let toolCalls = 0;
         let toolLimitExceeded = false;
+        let progressEvents = 0;
+        let lastProgressKey = null;
+        const progressDisposition = {
+            accepted: 0,
+            deduplicated: 0,
+            invalid: 0,
+            over_limit: 0,
+            server_rejected: 0,
+        };
         const startedAt = this.now();
         const usage = () => ({
             wall_time_ms: Math.max(0, this.now() - startedAt),
@@ -178,7 +188,74 @@ export class RunDispatcher {
             // 上一次真正上了 wire 的块 kind：thinking/status 只在 kind 切换时上报一次，避免刷屏。
             let lastReportedKind = null;
             const sink = {
+                progressDispositions: async (dispositions) => {
+                    progressDisposition.invalid += dispositions.invalid;
+                    progressDisposition.deduplicated += dispositions.deduplicated;
+                    progressDisposition.over_limit += dispositions.over_limit;
+                },
                 block: async (block) => {
+                    if (block.kind === "progress") {
+                        const normalized = tryNormalizeProgressReport({
+                            summary: block.summary,
+                            status: block.status,
+                        });
+                        if (!normalized) {
+                            progressDisposition.invalid += 1;
+                            return;
+                        }
+                        // Redact before the local transcript and every reporting client boundary.
+                        const progress = tryNormalizeProgressReport({
+                            summary: redactSecretString(normalized.summary),
+                            status: normalized.status,
+                        });
+                        // Redaction can expand a token marker past 240 code points; never truncate or send it.
+                        if (!progress) {
+                            progressDisposition.invalid += 1;
+                            return;
+                        }
+                        const key = `${progress.status}\0${progress.summary}`;
+                        if (key === lastProgressKey) {
+                            progressDisposition.deduplicated += 1;
+                            return;
+                        }
+                        if (progressEvents >= MAX_PROGRESS_EVENTS_PER_ATTEMPT) {
+                            progressDisposition.over_limit += 1;
+                            return;
+                        }
+                        lastProgressKey = key;
+                        progressEvents += 1;
+                        transcript.writeBlock({
+                            kind: "progress",
+                            runtime: runtime.id,
+                            summary: progress.summary,
+                            status: progress.status,
+                        });
+                        if (serverTerminal)
+                            return;
+                        try {
+                            await send({
+                                type: "run.block",
+                                payload: {
+                                    schema_version: "agent-progress/0.1",
+                                    kind: "progress",
+                                    runtime: runtime.id,
+                                    summary: progress.summary,
+                                    status: progress.status,
+                                },
+                            });
+                            if (!serverTerminal)
+                                progressDisposition.accepted += 1;
+                        }
+                        catch (error) {
+                            if (error instanceof CourseClientError &&
+                                (error.status === 400 || error.status === 422)) {
+                                progressDisposition.server_rejected += 1;
+                                return;
+                            }
+                            throw error;
+                        }
+                        return;
+                    }
                     transcript.writeBlock(block);
                     if (block.kind === "tool_call") {
                         toolCalls += 1;
@@ -288,6 +365,13 @@ export class RunDispatcher {
                 clearTimeout(timer);
             if (profileApplied)
                 cleanupRunRuntimeProfile(runId);
+            if (Object.values(progressDisposition).some((count) => count > 0)) {
+                this.log.info("progress event dispositions", {
+                    agentRunId: runId,
+                    runtime: runtimeId,
+                    ...progressDisposition,
+                });
+            }
             this.inflight.delete(runId);
         }
     }

package/dist/runtime-env.d.ts

@@ -0,0 +1,4 @@
+/** Remove Course control-plane coordinates before any model/runtime child is created. */
+export declare function clearAgentServiceControlEnv(env?: NodeJS.ProcessEnv): void;
+/** Copy an environment for a runtime child without leaking Agent Service control values. */
+export declare function runtimeChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/runtime-env.js

@@ -0,0 +1,17 @@
+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",
+];
+/** Remove Course control-plane coordinates before any model/runtime child is created. */
+export function clearAgentServiceControlEnv(env = process.env) {
+    for (const key of AGENT_SERVICE_CONTROL_ENV_KEYS)
+        delete env[key];
+}
+/** Copy an environment for a runtime child without leaking Agent Service control values. */
+export function runtimeChildEnv(env = process.env) {
+    const childEnv = { ...env };
+    clearAgentServiceControlEnv(childEnv);
+    return childEnv;
+}

package/dist/runtimes/deepseek-tui.d.ts

@@ -2,13 +2,15 @@ import { spawn } from "node:child_process";
 import { type ProbeDeps } from "./probe.js";
 import { type EngineAdapter, type EngineRunOptions, type EngineRunResult } from "./engine.js";
 import type { RuntimeModule, RuntimeProbe } from "../types.js";
-interface DeepseekAdapterDeps {
+export interface DeepseekAdapterDeps {
     binary?: string;
     /** 测试注入：使用现成的兼容 server，不 spawn `deepseek`。 */
     serverUrl?: string;
     authToken?: string;
     fetchFn?: typeof fetch;
     spawnFn?: typeof spawn;
+    /** External servers must explicitly attest compatible progress tool events. */
+    progressEventMapping?: boolean;
 }
 /** 解析 PATH 上的 `deepseek` dispatcher CLI。 */
 export declare function resolveDeepseekCommand(deps?: ProbeDeps): string | null;
@@ -28,6 +30,8 @@ export declare class DeepseekTuiAdapter implements EngineAdapter {
     private readonly explicitAuthToken;
     private readonly fetchFn;
     private readonly spawnFn;
+    readonly progressEventMappingEnabled: boolean;
+    readonly progressPromptInjectionEnabled: boolean;
     private resolvedBinary;
     constructor(deps?: DeepseekAdapterDeps);
     run(opts: EngineRunOptions): Promise<EngineRunResult>;
@@ -41,10 +45,10 @@ export declare class DeepseekTuiAdapter implements EngineAdapter {
     private createThread;
     private patchThreadSystemContext;
     private startTurnAndReadEvents;
+    private interruptTurn;
     private readEvents;
     private requestJson;
 }
 /** 仅测试用：清空进程池。 */
 export declare function __resetDeepseekTuiPoolForTests(): void;
 export declare const deepseekTuiModule: RuntimeModule;
-export {};