@botlearn-course/daemon 0.0.3 → 0.0.5

package/README.md

@@ -39,8 +39,10 @@ npx @botlearn-course/daemon@latest course logout
 包内还包含供 BotLearn 托管 E2B Template 使用的内部命令
 `botlearn-sandbox-supervisor agent-service session`。它不是 BYOA 用户入口：生产环境只允许由
 Agent Service 以固定 argv 启动，通过 stdin 接收一次性 bootstrap，并把 daemon/runtime 分别降权
-到 `botlearn-control`/`user` UID。`agent-service session --bootstrap-stdin` 同样属于受 supervisor
-保护的内部协议，不应直接暴露给课程任务或 workspace shell。
+到 `botlearn-control`/`user` UID。E2B Template 通过 root-owned 固定 launcher 将 DeepSeek
+单向降权为 `user` 并设置 `no_new_privs`；runtime 用户本身没有 sudo 权限。
+`agent-service session --bootstrap-stdin` 同样属于受 supervisor 保护的内部协议，不应直接暴露给
+课程任务或 workspace shell。
 
 ## 支持的 runtime
 

package/dist/agent-service-client.d.ts

@@ -5,6 +5,7 @@ export declare class AgentServiceRunClient {
     private readonly agentRunId;
     private readonly runToken;
     private readonly workerId;
+    private traceId;
     constructor(baseUrl: string, agentRunId: string, runToken: string, workerId: string);
     private url;
     private request;

package/dist/agent-service-client.js

@@ -8,6 +8,7 @@ export class AgentServiceRunClient {
     agentRunId;
     runToken;
     workerId;
+    traceId;
     constructor(baseUrl, agentRunId, runToken, workerId) {
         this.baseUrl = baseUrl;
         this.agentRunId = agentRunId;
@@ -26,6 +27,7 @@ export class AgentServiceRunClient {
             method,
             headers: {
                 authorization: `Bearer ${this.runToken}`,
+                ...(this.traceId ? { "x-trace-id": this.traceId } : {}),
                 ...(body !== undefined ? { "content-type": "application/json" } : {}),
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -38,10 +40,13 @@ export class AgentServiceRunClient {
         return (raw ? JSON.parse(raw) : null);
     }
     async getRun() {
-        return this.request("GET", `/api/v1/agent-service/runs/${this.agentRunId}`);
+        const payload = await this.request("GET", `/api/v1/agent-service/runs/${this.agentRunId}`);
+        this.traceId = payload.trace_id;
+        return payload;
     }
     async postEvent(agentRunId, event) {
         this.assertRunId(agentRunId);
+        this.traceId = event.trace_id ?? this.traceId;
         const sanitized = redactSecretsDeep(event, 8, [this.runToken]);
         await this.request("POST", `/api/v1/agent-service/runs/${agentRunId}/events`, sanitized);
     }
@@ -73,6 +78,7 @@ export class AgentServiceRunClient {
                     method: "PUT",
                     headers: {
                         authorization: `Bearer ${this.runToken}`,
+                        ...(this.traceId ? { "x-trace-id": this.traceId } : {}),
                         "content-type": mimeType ?? "application/octet-stream",
                     },
                     body: data,

package/dist/course-client.d.ts

@@ -26,7 +26,7 @@ export declare class CourseClient {
     static fromAuth(auth: DaemonAuth, opts?: Omit<CourseClientOptions, "refreshToken">): CourseClient;
     setAccessToken(token: string): void;
     private url;
-    fetchJson<T>(method: string, p: string, body: unknown, accessToken: string | null): Promise<T>;
+    fetchJson<T>(method: string, p: string, body: unknown, accessToken: string | null, traceId?: string): Promise<T>;
     private refreshAuth;
     private request;
     /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */

package/dist/course-client.js

@@ -51,11 +51,12 @@ export class CourseClient {
         }
         return `${base}${p}`;
     }
-    async fetchJson(method, p, body, accessToken) {
+    async fetchJson(method, p, body, accessToken, traceId) {
         const res = await fetch(this.url(p), {
             method,
             headers: {
                 ...(accessToken ? { authorization: `Bearer ${accessToken}` } : {}),
+                ...(traceId ? { "x-trace-id": traceId } : {}),
                 ...(body !== undefined ? { "content-type": "application/json" } : {}),
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -82,9 +83,9 @@ export class CourseClient {
             return false;
         }
     }
-    async request(method, p, body) {
+    async request(method, p, body, traceId) {
         try {
-            return await this.fetchJson(method, p, body, this.accessToken);
+            return await this.fetchJson(method, p, body, this.accessToken, traceId);
         }
         catch (err) {
             if (!(err instanceof CourseClientError) || err.status !== 401)
@@ -92,7 +93,7 @@ export class CourseClient {
             const refreshed = await this.refreshAuth();
             if (!refreshed)
                 throw err;
-            return await this.fetchJson(method, p, body, this.accessToken);
+            return await this.fetchJson(method, p, body, this.accessToken, traceId);
         }
     }
     /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */
@@ -102,7 +103,7 @@ export class CourseClient {
     async postEvent(agentRunId, 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);
+        await this.request("POST", `/api/v1/daemon/runs/${agentRunId}/events`, sanitized, event.trace_id);
     }
     async postFile(agentRunId, file) {
         return this.request("POST", `/api/v1/daemon/runs/${agentRunId}/files`, file);

package/dist/redaction.js

@@ -13,6 +13,12 @@ const INJECTED_CREDENTIAL_ENV_NAMES = [
 const MIN_EXACT_SECRET_CHARS = 8;
 /** key 命中即整值脱敏（深度脱敏用）。 */
 export const SECRET_KEY_RE = /token|secret|private.?key|api.?key|authorization|password|credential/i;
+const SAFE_NUMERIC_TELEMETRY_KEYS = new Set([
+    "input_tokens",
+    "cached_input_tokens",
+    "output_tokens",
+    "total_tokens",
+]);
 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");
@@ -110,9 +116,15 @@ export function redactSecretsDeep(value, depth = DEFAULT_REDACT_DEPTH, additiona
     }
     const out = {};
     for (const [key, v] of Object.entries(value)) {
-        out[key] = SECRET_KEY_RE.test(key)
-            ? REDACTED
-            : redactSecretsDeep(v, depth - 1, additionalSecrets);
+        out[key] =
+            SAFE_NUMERIC_TELEMETRY_KEYS.has(key)
+                && typeof v === "number"
+                && Number.isFinite(v)
+                && v >= 0
+                ? v
+                : SECRET_KEY_RE.test(key)
+                    ? REDACTED
+                    : redactSecretsDeep(v, depth - 1, additionalSecrets);
     }
     return out;
 }

package/dist/run-dispatcher.js

@@ -97,6 +97,8 @@ export class RunDispatcher {
     }
     async execute(payload) {
         const runId = payload.agent_run_id;
+        const traceId = payload.trace_id ?? runId;
+        const runtimeId = payload.runtime.id ?? this.defaultRuntimeId;
         const controller = new AbortController();
         this.inflight.set(runId, controller);
         if (this.pendingCancellations.delete(runId))
@@ -111,6 +113,11 @@ export class RunDispatcher {
         let profileApplied = false;
         let toolCalls = 0;
         let toolLimitExceeded = false;
+        let runtimeUsage = {};
+        let modelStartedAt;
+        let modelFinishedAt;
+        let filePersistStartedAt;
+        let filePersistFinishedAt;
         let progressEvents = 0;
         let lastProgressKey = null;
         const progressDisposition = {
@@ -121,15 +128,46 @@ export class RunDispatcher {
             server_rejected: 0,
         };
         const startedAt = this.now();
-        const usage = () => ({
-            wall_time_ms: Math.max(0, this.now() - startedAt),
-            tool_calls: toolCalls,
-        });
+        const usage = () => {
+            const inputTokens = runtimeUsage.input_tokens;
+            const outputTokens = runtimeUsage.output_tokens;
+            const totalTokens = runtimeUsage.total_tokens
+                ?? (inputTokens !== undefined || outputTokens !== undefined
+                    ? (inputTokens ?? 0) + (outputTokens ?? 0)
+                    : undefined);
+            const providerReported = inputTokens !== undefined
+                || runtimeUsage.cached_input_tokens !== undefined
+                || outputTokens !== undefined
+                || runtimeUsage.cost_usd !== undefined;
+            return {
+                schema_version: "agent-run-usage/0.1",
+                runtime: runtimeId,
+                ...(payload.runtime.model ? { model: payload.runtime.model } : {}),
+                usage_source: providerReported ? "mixed" : "worker_measured",
+                ...runtimeUsage,
+                ...(totalTokens !== undefined ? { total_tokens: totalTokens } : {}),
+                tool_calls: toolCalls,
+                worker_wall_time_ms: Math.max(0, this.now() - startedAt),
+                ...(modelStartedAt !== undefined && modelFinishedAt !== undefined
+                    ? { model_wall_time_ms: Math.max(0, modelFinishedAt - modelStartedAt) }
+                    : {}),
+                ...(filePersistStartedAt !== undefined && filePersistFinishedAt !== undefined
+                    ? {
+                        file_persist_time_ms: Math.max(0, filePersistFinishedAt - filePersistStartedAt),
+                    }
+                    : {}),
+            };
+        };
         const send = async (event) => {
             if (serverTerminal)
                 return;
             seq += 1;
-            const outgoing = { ...event, seq, event_id: event.event_id ?? randomUUID() };
+            const outgoing = {
+                ...event,
+                trace_id: traceId,
+                seq,
+                event_id: event.event_id ?? randomUUID(),
+            };
             for (let attempt = 0; attempt < 3; attempt += 1) {
                 try {
                     await this.client.postEvent(runId, outgoing);
@@ -162,8 +200,29 @@ export class RunDispatcher {
                     error: err instanceof Error ? err.message : String(err),
                 });
             }
+            finally {
+                const terminalUsage = event.payload?.usage && typeof event.payload.usage === "object"
+                    ? event.payload.usage
+                    : usage();
+                this.log.info("agent run terminal", {
+                    ...terminalUsage,
+                    agentRunId: runId,
+                    traceId,
+                    runtime: runtimeId,
+                    model: payload.runtime.model,
+                    status: event.type,
+                    errorType: event.payload?.error_type,
+                });
+            }
         };
-        const runtimeId = payload.runtime.id ?? this.defaultRuntimeId;
+        this.log.info("agent run started", {
+            agentRunId: runId,
+            traceId,
+            courseRunId: payload.course_run_id,
+            runtime: runtimeId,
+            model: payload.runtime.model,
+            persistentSession: Boolean(this.persistentSession),
+        });
         try {
             await send({ type: "run.started" });
             const runtime = this.runtimes.get(runtimeId);
@@ -214,6 +273,18 @@ export class RunDispatcher {
                     progressDisposition.deduplicated += dispositions.deduplicated;
                     progressDisposition.over_limit += dispositions.over_limit;
                 },
+                usage: async (reported) => {
+                    runtimeUsage = {
+                        ...runtimeUsage,
+                        ...reported,
+                        provider_request_ids: [
+                            ...new Set([
+                                ...(runtimeUsage.provider_request_ids ?? []),
+                                ...(reported.provider_request_ids ?? []),
+                            ]),
+                        ].slice(0, 10),
+                    };
+                },
                 block: async (block) => {
                     if (block.kind === "progress") {
                         const normalized = tryNormalizeProgressReport({
@@ -314,19 +385,25 @@ export class RunDispatcher {
                     this.persistentSession?.persistNativeSession(sessionId);
                 },
             };
-            await runtime.run({
-                payload,
-                workspaceDir,
-                ...(persistentTurn
-                    ? {
-                        nativeSessionId: persistentTurn.nativeSessionId,
-                        contextRevision: persistentTurn.contextRevision,
-                        ...(persistentTurn.runtimeEnv
-                            ? { runtimeEnv: persistentTurn.runtimeEnv }
-                            : {}),
-                    }
-                    : {}),
-            }, sink, controller.signal);
+            modelStartedAt = this.now();
+            try {
+                await runtime.run({
+                    payload,
+                    workspaceDir,
+                    ...(persistentTurn
+                        ? {
+                            nativeSessionId: persistentTurn.nativeSessionId,
+                            contextRevision: persistentTurn.contextRevision,
+                            ...(persistentTurn.runtimeEnv
+                                ? { runtimeEnv: persistentTurn.runtimeEnv }
+                                : {}),
+                        }
+                        : {}),
+                }, sink, controller.signal);
+            }
+            finally {
+                modelFinishedAt = this.now();
+            }
             clearTimeout(timer);
             if (serverTerminal)
                 return;
@@ -339,7 +416,14 @@ export class RunDispatcher {
                 : DEFAULT_MAX_OUTPUT_CHARS;
             const output = redactSecretString(truncateText(finalText, maxOutputChars));
             transcript.writeFinal(output);
-            const fileReport = await reportFileCandidates(this.client, runId, workspaceDir, this.log, this.scanLimits);
+            filePersistStartedAt = this.now();
+            let fileReport;
+            try {
+                fileReport = await reportFileCandidates(this.client, runId, workspaceDir, this.log, this.scanLimits);
+            }
+            finally {
+                filePersistFinishedAt = this.now();
+            }
             if (this.client.uploadFileContent && (fileReport.failed > 0 || fileReport.truncated)) {
                 throw new RuntimeExecutionError(fileReport.truncated
                     ? "workspace file collection was truncated"

package/dist/runtime-env.d.ts

@@ -7,3 +7,19 @@ export declare function runtimeChildIdentity(env?: NodeJS.ProcessEnv): {
     uid?: number;
     gid?: number;
 };
+/**
+ * Build the fixed control-to-runtime privilege boundary used by the E2B Template.
+ *
+ * A non-root botlearn-control daemon cannot use spawn({ uid }) directly. The Template
+ * therefore grants it one sudoers command: a root-owned launcher that accepts only the
+ * immutable DeepSeek dispatcher and sets no_new_privs as the unprivileged runtime user.
+ * BYOA processes do not set BOTLEARN_RUNTIME_USER and retain their direct-spawn behavior.
+ */
+export declare function runtimeChildLaunch(binary: string, args: string[], env?: NodeJS.ProcessEnv): {
+    binary: string;
+    args: string[];
+    identity: {
+        uid?: number;
+        gid?: number;
+    };
+};

package/dist/runtime-env.js

@@ -8,11 +8,19 @@ const AGENT_SERVICE_CONTROL_ENV_KEYS = [
     "BOTLEARN_AGENT_SERVICE_SESSION_TOKEN",
 ];
 const AGENT_SERVICE_SUPERVISOR_ENV_KEYS = [
+    "BOTLEARN_DAEMON_HOME",
     "BOTLEARN_RUNTIME_UID",
     "BOTLEARN_RUNTIME_GID",
+    "BOTLEARN_RUNTIME_USER",
+    "BOTLEARN_RUNTIME_GROUP",
+    "BOTLEARN_RUNTIME_HOME",
+    "BOTLEARN_RUNTIME_LAUNCHER",
     "BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT",
     "BOTLEARN_AGENT_SERVICE_PROFILE_ROOT",
 ];
+const RUNTIME_USER_PATTERN = /^[a-z_][a-z0-9_-]{0,31}$/;
+const RUNTIME_SUDO_BINARY = "/usr/bin/sudo";
+const MANAGED_RUNTIME_LAUNCHER = "/usr/local/bin/botlearn-runtime-launcher";
 /** 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)
@@ -21,9 +29,12 @@ export function clearAgentServiceControlEnv(env = process.env) {
 /** Copy an environment for a runtime child without leaking Agent Service control values. */
 export function runtimeChildEnv(env = process.env) {
     const childEnv = { ...env };
+    const runtimeHome = childEnv.BOTLEARN_RUNTIME_HOME;
     clearAgentServiceControlEnv(childEnv);
     for (const key of AGENT_SERVICE_SUPERVISOR_ENV_KEYS)
         delete childEnv[key];
+    if (runtimeHome)
+        childEnv.HOME = runtimeHome;
     return childEnv;
 }
 /** Run model processes as the Template's untrusted runtime UID when configured. */
@@ -38,3 +49,44 @@ export function runtimeChildIdentity(env = process.env) {
     }
     return { uid, gid };
 }
+/**
+ * Build the fixed control-to-runtime privilege boundary used by the E2B Template.
+ *
+ * A non-root botlearn-control daemon cannot use spawn({ uid }) directly. The Template
+ * therefore grants it one sudoers command: a root-owned launcher that accepts only the
+ * immutable DeepSeek dispatcher and sets no_new_privs as the unprivileged runtime user.
+ * BYOA processes do not set BOTLEARN_RUNTIME_USER and retain their direct-spawn behavior.
+ */
+export function runtimeChildLaunch(binary, args, env = process.env) {
+    const runtimeUser = env.BOTLEARN_RUNTIME_USER;
+    if (runtimeUser === undefined) {
+        return { binary, args, identity: runtimeChildIdentity(env) };
+    }
+    if (!RUNTIME_USER_PATTERN.test(runtimeUser)) {
+        throw new Error("invalid supervisor-provided runtime user");
+    }
+    const runtimeGroup = env.BOTLEARN_RUNTIME_GROUP;
+    if (runtimeGroup === undefined || !RUNTIME_USER_PATTERN.test(runtimeGroup)) {
+        throw new Error("invalid supervisor-provided runtime group");
+    }
+    if (env.BOTLEARN_RUNTIME_LAUNCHER !== MANAGED_RUNTIME_LAUNCHER) {
+        throw new Error("invalid supervisor-provided runtime launcher");
+    }
+    return {
+        binary: RUNTIME_SUDO_BINARY,
+        args: [
+            "-n",
+            "-H",
+            "-E",
+            "-u",
+            runtimeUser,
+            "-g",
+            runtimeGroup,
+            "--",
+            MANAGED_RUNTIME_LAUNCHER,
+            binary,
+            ...args,
+        ],
+        identity: {},
+    };
+}

package/dist/runtimes/codex.js

@@ -210,20 +210,20 @@ export class CodexAdapter extends NdjsonStreamAdapter {
             return;
         }
         if (obj.type === "turn.completed") {
-            // usage 成功与失败的 turn 都会报。input_tokens 含缓存部分，
-            // miss = input_tokens - cached_input_tokens。仅本地诊断用。
+            // usage 成功与失败的 turn 都会报；input_tokens 已包含缓存部分。
             const usage = obj.usage;
             if (usage && typeof usage === "object") {
                 const input = numOrUndefined(usage.input_tokens);
                 const cached = numOrUndefined(usage.cached_input_tokens);
                 const output = numOrUndefined(usage.output_tokens);
-                const hit = cached;
-                const miss = input !== undefined ? Math.max(0, input - (cached ?? 0)) : undefined;
-                if (hit !== undefined || miss !== undefined || output !== undefined) {
+                if (input !== undefined || cached !== undefined || output !== undefined) {
                     ctx.state.usage = {
-                        ...(hit !== undefined ? { inputCacheHitTokens: hit } : {}),
-                        ...(miss !== undefined ? { inputCacheMissTokens: miss } : {}),
-                        ...(output !== undefined ? { outputTokens: output } : {}),
+                        ...(input !== undefined ? { input_tokens: input } : {}),
+                        ...(cached !== undefined ? { cached_input_tokens: cached } : {}),
+                        ...(output !== undefined ? { output_tokens: output } : {}),
+                        ...(input !== undefined || output !== undefined
+                            ? { total_tokens: (input ?? 0) + (output ?? 0) }
+                            : {}),
                     };
                 }
             }

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

@@ -1,7 +1,7 @@
 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";
+import type { RuntimeModule, RuntimeProbe, RuntimeUsage } from "../types.js";
 export interface DeepseekAdapterDeps {
     binary?: string;
     /** 测试注入：使用现成的兼容 server，不 spawn `deepseek`。 */
@@ -51,4 +51,6 @@ export declare class DeepseekTuiAdapter implements EngineAdapter {
 }
 /** 仅测试用：清空进程池。 */
 export declare function __resetDeepseekTuiPoolForTests(): void;
+/** Accept both OpenAI-compatible and canonical usage fields from terminal SSE frames. */
+export declare function extractDeepseekUsage(payload: any): RuntimeUsage | undefined;
 export declare const deepseekTuiModule: RuntimeModule;

package/dist/runtimes/deepseek-tui.js

@@ -3,7 +3,7 @@ import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import net from "node:net";
 import { MAX_PROGRESS_EVENTS_PER_ATTEMPT } from "../mcp/report-progress.js";
-import { runtimeChildEnv, runtimeChildIdentity } from "../runtime-env.js";
+import { runtimeChildEnv, runtimeChildLaunch } from "../runtime-env.js";
 import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
 import { adaptDeepseekProgressStarted, cleanupProgressMcpConfig, createDeepseekProgressState, createProgressMcpConfig, deepseekProgressDispositions, isDeepseekProgressCompletion, progressMcpAutoInjectionSupported, progressSystemContext, } from "./progress.js";
 import { consoleLogger, wrapEngineAdapter, } from "./engine.js";
@@ -144,6 +144,7 @@ export class DeepseekTuiAdapter {
                 ...(runResult.progressDispositions
                     ? { progressDispositions: runResult.progressDispositions }
                     : {}),
+                ...(runResult.usage ? { usage: runResult.usage } : {}),
                 ...(error ? { error } : {}),
             };
         }
@@ -197,21 +198,24 @@ export class DeepseekTuiAdapter {
         const progressMcpConfig = this.progressPromptInjectionEnabled
             ? createProgressMcpConfig()
             : undefined;
+        const binary = this.resolveBinary();
+        const args = [
+            "serve",
+            "--http",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            "--auth-token",
+            token,
+        ];
+        const launch = runtimeChildLaunch(binary, args);
         let child;
         try {
-            child = this.spawnFn(this.resolveBinary(), [
-                "serve",
-                "--http",
-                "--host",
-                "127.0.0.1",
-                "--port",
-                String(port),
-                "--auth-token",
-                token,
-            ], {
+            child = this.spawnFn(launch.binary, launch.args, {
                 cwd: opts.cwd,
                 env: this.spawnEnv(opts, progressMcpConfig?.path),
-                ...runtimeChildIdentity(),
+                ...launch.identity,
                 stdio: ["ignore", "pipe", "pipe"],
                 // 自成进程组：解析到的二进制可能是会再 spawn 真实 deepseek-tui
                 // server 的 dispatcher，shutdown 必须对整组发信号而非仅直接子进程。
@@ -410,6 +414,7 @@ export class DeepseekTuiAdapter {
             let seq = 0;
             let text = "";
             let errorText = "";
+            let usage;
             let capped = false;
             const progressState = createDeepseekProgressState();
             const append = (chunk) => {
@@ -477,6 +482,7 @@ export class DeepseekTuiAdapter {
                     opts.onStatus?.({ kind: "thinking", phase: "updated", label });
                 }
                 else if (isDeepseekTerminalEvent(eventName, payload)) {
+                    usage = extractDeepseekUsage(payload);
                     opts.onStatus?.({ kind: "thinking", phase: "stopped" });
                     return true;
                 }
@@ -500,6 +506,7 @@ export class DeepseekTuiAdapter {
                             text: text.trim(),
                             ...(errorText ? { error: errorText } : {}),
                             ...(progressDispositions ? { progressDispositions } : {}),
+                            ...(usage ? { usage } : {}),
                         };
                     }
                 }
@@ -514,6 +521,7 @@ export class DeepseekTuiAdapter {
                 text: text.trim(),
                 ...(errorText ? { error: errorText } : {}),
                 ...(progressDispositions ? { progressDispositions } : {}),
+                ...(usage ? { usage } : {}),
             };
         };
     }
@@ -583,6 +591,51 @@ function isDeepseekTerminalEvent(eventName, payload) {
         embedded === "turn.done" ||
         embedded === "done");
 }
+function nonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+/** Accept both OpenAI-compatible and canonical usage fields from terminal SSE frames. */
+export function extractDeepseekUsage(payload) {
+    const candidates = [
+        payload?.usage,
+        payload?.payload?.usage,
+        payload?.turn?.usage,
+        payload?.payload?.turn?.usage,
+    ];
+    const raw = candidates.find((value) => value && typeof value === "object");
+    if (!raw)
+        return undefined;
+    const input = nonNegativeNumber(raw.input_tokens ?? raw.prompt_tokens);
+    const cached = nonNegativeNumber(raw.cached_input_tokens
+        ?? raw.prompt_cache_hit_tokens
+        ?? raw.prompt_tokens_details?.cached_tokens);
+    const output = nonNegativeNumber(raw.output_tokens ?? raw.completion_tokens);
+    const total = nonNegativeNumber(raw.total_tokens)
+        ?? (input !== undefined || output !== undefined ? (input ?? 0) + (output ?? 0) : undefined);
+    const cost = nonNegativeNumber(raw.cost_usd ?? raw.cost);
+    const requestId = stringField(payload, "request_id")
+        ?? stringField(payload, "x_request_id")
+        ?? stringField(payload?.payload, "request_id")
+        ?? stringField(payload?.payload, "x_request_id");
+    if (input === undefined
+        && cached === undefined
+        && output === undefined
+        && total === undefined
+        && cost === undefined
+        && !requestId) {
+        return undefined;
+    }
+    return {
+        ...(input !== undefined ? { input_tokens: input } : {}),
+        ...(cached !== undefined ? { cached_input_tokens: cached } : {}),
+        ...(output !== undefined ? { output_tokens: output } : {}),
+        ...(total !== undefined ? { total_tokens: total } : {}),
+        ...(cost !== undefined ? { cost_usd: cost } : {}),
+        ...(requestId ? { provider_request_ids: [requestId] } : {}),
+    };
+}
 function isToolStarted(eventName, payload) {
     const itemKind = payload?.payload?.item?.kind ?? payload?.item?.kind;
     return ((eventName === "item.started" &&

package/dist/runtimes/engine.d.ts

@@ -1,4 +1,4 @@
-import { type CourseRuntime, type RuntimeFailureSummary, type RuntimeProgressDispositions } from "../types.js";
+import { type CourseRuntime, type RuntimeFailureSummary, type RuntimeProgressDispositions, type RuntimeUsage } from "../types.js";
 import type { Logger } from "../log.js";
 import type { ProgressReport } from "../mcp/report-progress.js";
 /**
@@ -43,6 +43,7 @@ export interface EngineRunResult {
     text: string;
     newSessionId: string;
     costUsd?: number;
+    usage?: RuntimeUsage;
     /** adapter 自身在 emit 前丢弃的进度计数；不包含 accepted，避免 dispatcher 重复计数。 */
     progressDispositions?: RuntimeProgressDispositions;
     /** 非空表示硬失败；由包装层折叠为 RuntimeExecutionError。 */

package/dist/runtimes/engine.js

@@ -144,6 +144,12 @@ export function wrapEngineAdapter(id, engine, opts) {
             if (result.progressDispositions) {
                 await sink.progressDispositions?.(result.progressDispositions);
             }
+            if (result.usage || result.costUsd !== undefined) {
+                await sink.usage?.({
+                    ...(result.usage ?? {}),
+                    ...(result.costUsd !== undefined ? { cost_usd: result.costUsd } : {}),
+                });
+            }
             await sink.runtimeSession?.(result.newSessionId);
             if (result.error) {
                 throw new RuntimeExecutionError(result.error, "runtime_error", result.runtimeFailure);

package/dist/runtimes/ndjson-stream.d.ts

@@ -1,4 +1,5 @@
 import { type EngineAdapter, type EngineRunOptions, type EngineRunResult, type RuntimeStatusEvent, type StreamBlock } from "./engine.js";
+import type { RuntimeUsage } from "../types.js";
 import type { Logger } from "../log.js";
 /** 单轮执行期间穿过事件回调的可变状态；基类据此组装最终 EngineRunResult。 */
 export interface NdjsonRunState {
@@ -13,12 +14,8 @@ export interface NdjsonRunState {
     assistantTextCapped: boolean;
     costUsd?: number;
     errorText?: string;
-    /** 部分 CLI 会报告用量（如 Codex turn.completed.usage）；仅本地诊断用。 */
-    usage?: {
-        inputCacheHitTokens?: number;
-        inputCacheMissTokens?: number;
-        outputTokens?: number;
-    };
+    /** 部分 CLI 会报告用量（如 Codex turn.completed.usage）。 */
+    usage?: RuntimeUsage;
 }
 /** ndjson 分发循环递给子类的逐事件上下文。 */
 export interface NdjsonEventCtx {

package/dist/runtimes/ndjson-stream.js

@@ -183,6 +183,7 @@ export class NdjsonStreamAdapter {
             text,
             newSessionId: state.newSessionId,
             ...(state.costUsd !== undefined ? { costUsd: state.costUsd } : {}),
+            ...(state.usage ? { usage: state.usage } : {}),
             ...(state.errorText ? { error: state.errorText } : {}),
             ...(state.errorText
                 ? {

package/dist/sandbox-supervisor.d.ts

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

package/dist/sandbox-supervisor.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { execFileSync, spawn } from "node:child_process";
-import { chmodSync, chownSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { chmodSync, chownSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 const MAX_BOOTSTRAP_BYTES = 64 * 1024;
 const CONTROL_USER = "botlearn-control";
 const RUNTIME_USER = "user";
@@ -125,6 +126,10 @@ export async function runSandboxSupervisor(argv) {
                 BOTLEARN_DAEMON_HOME: CONTROL_HOME,
                 BOTLEARN_RUNTIME_UID: String(runtimeUid),
                 BOTLEARN_RUNTIME_GID: String(controlGid),
+                BOTLEARN_RUNTIME_USER: RUNTIME_USER,
+                BOTLEARN_RUNTIME_GROUP: CONTROL_USER,
+                BOTLEARN_RUNTIME_HOME: "/home/user",
+                BOTLEARN_RUNTIME_LAUNCHER: "/usr/local/bin/botlearn-runtime-launcher",
                 BOTLEARN_AGENT_SERVICE_WORKSPACE_ROOT: WORKSPACE,
                 BOTLEARN_AGENT_SERVICE_PROFILE_ROOT: RUNTIME_PROFILE_ROOT,
             },
@@ -164,7 +169,17 @@ export async function runSandboxSupervisor(argv) {
         releaseLock?.();
     }
 }
-if (process.argv[1]?.endsWith("sandbox-supervisor.js")) {
+export function isMainModule(entry = process.argv[1]) {
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
     runSandboxSupervisor(process.argv.slice(2))
         .then((code) => {
         process.exitCode = code;

package/dist/types.d.ts

@@ -8,6 +8,7 @@ import type { ProgressStatus } from "./mcp/report-progress.js";
 /** `GET /daemon/runs/next` 下发的 run.start 载荷（snake_case，与后端 RunStartPayloadOut 一致）。 */
 export interface RunStartPayload {
     agent_run_id: string;
+    trace_id?: string;
     course_run_id: string;
     lesson_id: string | null;
     task_id: string | null;
@@ -44,6 +45,8 @@ export interface RunStartPayload {
 export type RunEventType = "run.accepted" | "run.started" | "run.block" | "run.message" | "run.completed" | "run.failed" | "run.cancelled";
 export interface RunEvent {
     type: RunEventType;
+    /** End-to-end correlation id assigned by Course Service. */
+    trace_id?: string;
     /** Stable across retries; Course Service deduplicates within the current worker attempt. */
     event_id?: string;
     /** 1-based 单调递增。后端把 0/缺省视为「未设置」并自行计算，所以客户端 seq 必须从 1 开始。 */
@@ -128,6 +131,15 @@ export interface RuntimeProgressDispositions {
     deduplicated: number;
     over_limit: number;
 }
+/** Content-free model usage; adapters populate only fields actually reported upstream. */
+export interface RuntimeUsage {
+    input_tokens?: number;
+    cached_input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    cost_usd?: number;
+    provider_request_ids?: string[];
+}
 export interface RuntimeAuthProbe {
     checked: boolean;
     ok: boolean;
@@ -147,6 +159,8 @@ export interface CourseRuntimeSink {
     file(file: RunFileCandidate): Promise<void>;
     /** 可选的 run-scoped 内部遥测；不得包含 summary 或 provider raw envelope。 */
     progressDispositions?(dispositions: RuntimeProgressDispositions): Promise<void>;
+    /** Provider usage only; must never include prompts, model output, or raw envelopes. */
+    usage?(usage: RuntimeUsage): Promise<void>;
     /** Persist the runtime-native thread/session id before a terminal turn event is emitted. */
     runtimeSession?(sessionId: string): Promise<void>;
 }

package/package.json

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