@botlearn-course/daemon 0.0.1 → 0.0.3

package/dist/runtimes/openclaw-acp.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { runtimeChildEnv, runtimeChildIdentity } from "../runtime-env.js";
 import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
 import { sliceUtf8Bytes } from "./text-cap.js";
 import { consoleLogger, wrapEngineAdapter, } from "./engine.js";
@@ -384,7 +385,8 @@ export class OpenclawAcpAdapter {
             args.push("--token", gateway.token);
         const child = this.spawnFn(command, args, {
             stdio: ["pipe", "pipe", "pipe"],
-            env: { ...process.env },
+            env: runtimeChildEnv(this.env ?? process.env),
+            ...runtimeChildIdentity(),
         });
         installExitCleanupHook();
         const handle = {

package/dist/runtimes/progress.d.ts

@@ -0,0 +1,50 @@
+import type { ProgressStreamBlock } from "./engine.js";
+import type { RuntimeProgressDispositions } from "../types.js";
+export declare const DEEPSEEK_PROGRESS_TOOL_ALIASES: Set<string>;
+export declare const DEEPSEEK_PROGRESS_SYSTEM_INSTRUCTION: string;
+export interface DeepseekProgressState {
+    emitted: number;
+    lastProgressKey: string | null;
+    callIds: Set<string>;
+    limitReported: boolean;
+    invalid: number;
+    duplicate: number;
+    overLimit: number;
+}
+export interface DeepseekProgressStartedResult {
+    matched: boolean;
+    block?: ProgressStreamBlock;
+    limitExceeded?: true;
+}
+export interface ProgressMcpConfig {
+    dir: string;
+    path: string;
+}
+export interface ProgressMcpConfigOptions {
+    /** undefined auto-discovers explicit/default config; null creates a progress-only config. */
+    baseConfigPath?: string | null;
+    platform?: NodeJS.Platform;
+}
+export declare class ProgressMcpConfigError extends Error {
+    constructor(message: string);
+}
+export declare function createDeepseekProgressState(): DeepseekProgressState;
+/** Return only adapter-side drops; emitted blocks are counted by RunDispatcher after reporting. */
+export declare function deepseekProgressDispositions(state: DeepseekProgressState): RuntimeProgressDispositions | undefined;
+export declare function progressSystemContext(systemContext: string | undefined): string;
+/**
+ * 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 declare function adaptDeepseekProgressStarted(payload: unknown, seq: number, state: DeepseekProgressState): DeepseekProgressStartedResult;
+/** Suppress the result for a recognized progress call, including result envelopes with only ids. */
+export declare function isDeepseekProgressCompletion(payload: unknown, state: DeepseekProgressState): boolean;
+/**
+ * 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 declare function progressMcpAutoInjectionSupported(platform?: NodeJS.Platform): boolean;
+export declare function resolveExistingDeepseekMcpConfig(env?: NodeJS.ProcessEnv, home?: string): string | null;
+/** Create an ephemeral config that preserves a user's existing MCP servers and settings. */
+export declare function createProgressMcpConfig(options?: ProgressMcpConfigOptions): ProgressMcpConfig;
+export declare function cleanupProgressMcpConfig(config: ProgressMcpConfig | undefined): void;

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/sandbox-supervisor.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function acquireSessionSupervisorLock(runtimeSessionId: string, lockRoot?: string): (() => void) | null;
+export declare function runSandboxSupervisor(argv: string[]): Promise<number>;

package/dist/sandbox-supervisor.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, chownSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+const MAX_BOOTSTRAP_BYTES = 64 * 1024;
+const CONTROL_USER = "botlearn-control";
+const RUNTIME_USER = "user";
+const CONTROL_HOME = "/home/botlearn-control/.botlearn-course/daemon";
+const WORKSPACE = "/workspace";
+const RUNTIME_PROFILE_ROOT = "/run/botlearn-runtime-profiles";
+const SUPERVISOR_LOCK_ROOT = "/run/botlearn-sandbox-supervisors";
+const DAEMON_BINARY = "/usr/local/bin/botlearn-course-daemon";
+function numericId(flag, user) {
+    const output = execFileSync("/usr/bin/id", [flag, user], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    const value = Number(output);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`sandbox supervisor could not resolve ${flag} for ${user}`);
+    }
+    return value;
+}
+async function readOneShotBootstrap() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.length;
+        if (size > MAX_BOOTSTRAP_BYTES) {
+            throw new Error("sandbox supervisor bootstrap exceeds size limit");
+        }
+        chunks.push(bytes);
+    }
+    if (size === 0)
+        throw new Error("sandbox supervisor bootstrap is empty");
+    return Buffer.concat(chunks);
+}
+export function acquireSessionSupervisorLock(runtimeSessionId, lockRoot = SUPERVISOR_LOCK_ROOT) {
+    const lockDir = path.join(lockRoot, runtimeSessionId);
+    const pidFile = path.join(lockDir, "pid");
+    mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+    try {
+        mkdirSync(lockDir, { mode: 0o700 });
+    }
+    catch (error) {
+        if (!existsSync(pidFile))
+            throw error;
+        const existingPid = Number(readFileSync(pidFile, "utf8").trim());
+        if (Number.isInteger(existingPid) && existingPid > 1) {
+            try {
+                process.kill(existingPid, 0);
+                return null;
+            }
+            catch {
+                // Stale lock from a supervisor that no longer exists.
+            }
+        }
+        rmSync(lockDir, { recursive: true, force: true });
+        mkdirSync(lockDir, { mode: 0o700 });
+    }
+    writeFileSync(pidFile, `${process.pid}\n`, { mode: 0o600 });
+    return () => {
+        try {
+            if (Number(readFileSync(pidFile, "utf8").trim()) === process.pid) {
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // A replacement supervisor already owns or removed the lock.
+        }
+    };
+}
+function prepareDirectories(controlUid, controlGid, runtimeUid, runtimeSessionId, sessionGeneration) {
+    mkdirSync(CONTROL_HOME, { recursive: true, mode: 0o700 });
+    chownSync("/home/botlearn-control/.botlearn-course", controlUid, controlGid);
+    chownSync(CONTROL_HOME, controlUid, controlGid);
+    chmodSync(CONTROL_HOME, 0o700);
+    mkdirSync(RUNTIME_PROFILE_ROOT, { recursive: true, mode: 0o750 });
+    chownSync(RUNTIME_PROFILE_ROOT, controlUid, controlGid);
+    chmodSync(RUNTIME_PROFILE_ROOT, 0o750);
+    mkdirSync(WORKSPACE, { recursive: true, mode: 0o770 });
+    chownSync(WORKSPACE, runtimeUid, controlGid);
+    chmodSync(WORKSPACE, 0o770);
+    const sessionWorkspace = path.join(WORKSPACE, runtimeSessionId, `generation-${sessionGeneration}`);
+    mkdirSync(sessionWorkspace, { recursive: true, mode: 0o770 });
+    chownSync(path.join(WORKSPACE, runtimeSessionId), runtimeUid, controlGid);
+    chownSync(sessionWorkspace, runtimeUid, controlGid);
+    chmodSync(path.join(WORKSPACE, runtimeSessionId), 0o770);
+    chmodSync(sessionWorkspace, 0o770);
+}
+export async function runSandboxSupervisor(argv) {
+    if (argv.length !== 2 || argv[0] !== "agent-service" || argv[1] !== "session") {
+        throw new Error("sandbox supervisor only permits: agent-service session");
+    }
+    if (typeof process.getuid !== "function" || process.getuid() !== 0) {
+        throw new Error("sandbox supervisor must start as root");
+    }
+    const controlUid = numericId("-u", CONTROL_USER);
+    const controlGid = numericId("-g", CONTROL_USER);
+    const runtimeUid = numericId("-u", RUNTIME_USER);
+    const bootstrap = await readOneShotBootstrap();
+    let child;
+    let releaseLock = null;
+    try {
+        const decoded = JSON.parse(bootstrap.toString("utf8"));
+        const runtimeSessionId = decoded.runtimeSessionId;
+        const sessionGeneration = Number(decoded.sessionGeneration ?? 0);
+        if (typeof runtimeSessionId !== "string" ||
+            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(runtimeSessionId) ||
+            !Number.isInteger(sessionGeneration) ||
+            sessionGeneration < 1) {
+            throw new Error("sandbox supervisor bootstrap session scope is invalid");
+        }
+        releaseLock = acquireSessionSupervisorLock(runtimeSessionId);
+        if (releaseLock === null)
+            return 0;
+        prepareDirectories(controlUid, controlGid, runtimeUid, runtimeSessionId, sessionGeneration);
+        child = spawn(DAEMON_BINARY, ["agent-service", "session", "--bootstrap-stdin"], {
+            uid: controlUid,
+            gid: controlGid,
+            env: {
+                HOME: "/home/botlearn-control",
+                PATH: "/usr/local/bin:/usr/bin:/bin",
+                BOTLEARN_DAEMON_HOME: CONTROL_HOME,
+                BOTLEARN_RUNTIME_UID: String(runtimeUid),
+                BOTLEARN_RUNTIME_GID: String(controlGid),
+                BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT: WORKSPACE,
+                BOTLEARN_AGENT_SERVICE_PROFILE_ROOT: RUNTIME_PROFILE_ROOT,
+            },
+            stdio: ["pipe", "inherit", "inherit"],
+        });
+        if (child.stdin === null) {
+            child.kill("SIGKILL");
+            throw new Error("sandbox supervisor could not open daemon bootstrap pipe");
+        }
+        child.stdin.end(bootstrap);
+    }
+    catch (error) {
+        releaseLock?.();
+        throw error;
+    }
+    finally {
+        bootstrap.fill(0);
+    }
+    const forward = (signal) => {
+        if (!child.killed)
+            child.kill(signal);
+    };
+    process.once("SIGTERM", () => forward("SIGTERM"));
+    process.once("SIGINT", () => forward("SIGINT"));
+    try {
+        return await new Promise((resolve, reject) => {
+            child.once("error", reject);
+            child.once("exit", (code, signal) => {
+                if (signal)
+                    resolve(128);
+                else
+                    resolve(code ?? 1);
+            });
+        });
+    }
+    finally {
+        releaseLock?.();
+    }
+}
+if (process.argv[1]?.endsWith("sandbox-supervisor.js")) {
+    runSandboxSupervisor(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

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,12 +145,22 @@ 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>;
+    /** Persist the runtime-native thread/session id before a terminal turn event is emitted. */
+    runtimeSession?(sessionId: string): Promise<void>;
 }
 /** 一次 run 的本地执行上下文：服务器 payload + daemon 本地准备产物。 */
 export interface RunExecution {
     payload: RunStartPayload;
-    /** 本 run 的隔离工作区目录（runtime 的 cwd）。 */
+    /** Runtime cwd. Managed persistent sessions reuse one session-scoped workspace. */
     workspaceDir: string;
+    /** Runtime-native thread/session id to resume; null creates the first native session. */
+    nativeSessionId?: string | null;
+    /** Monotonic Course Service context revision accepted for this turn. */
+    contextRevision?: number;
+    /** Scoped runtime-only environment (for example a short-lived model proxy grant). */
+    runtimeEnv?: NodeJS.ProcessEnv;
 }
 export interface CourseRuntime {
     id: string;