@botlearn-course/daemon 0.0.13-beta.1 → 0.0.14

package/dist/runtimes/engine.d.ts

@@ -1,6 +1,7 @@
 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";
+import type { PreparedRuntimeSkillProvider, RuntimeSkillEvent } from "../runtime-skills.js";
 /**
  * 内部引擎契约：CLI/ACP 基类实现的是 pull-style options + 回调，
  * 由 wrapEngineAdapter 折叠成对外的 CourseRuntime（sink 语义）。
@@ -34,19 +35,28 @@ export type RuntimeStatusEvent = {
 };
 export interface EngineRunOptions {
     text: string;
+    /** Full durable conversation bootstrap, used only if a resumed native thread is missing. */
+    recoveryText?: string;
     /** runtime 原生会话 id（resume 用）；null 表示新会话。 */
     sessionId: string | null;
     cwd: string;
+    /** Daemon-owned state directory for runtime metadata that the model must not mutate. */
+    runtimeStateDir?: string;
     signal: AbortSignal;
     extraArgs?: string[];
     systemContext?: string;
     onBlock?: (block: StreamBlock) => void;
     onStatus?: (event: RuntimeStatusEvent) => void;
     env?: NodeJS.ProcessEnv;
+    /** Control-side binding. Runtime adapters must not copy its credential into child env. */
+    skillProvider?: PreparedRuntimeSkillProvider;
+    onSkillEvent?: (event: RuntimeSkillEvent) => Promise<void>;
 }
 export interface EngineRunResult {
     text: string;
     newSessionId: string;
+    /** Model identity returned by the runtime API for this turn. */
+    model?: string;
     costUsd?: number;
     usage?: RuntimeUsage;
     /** adapter 自身在 emit 前丢弃的进度计数；不包含 accepted，避免 dispatcher 重复计数。 */

package/dist/runtimes/engine.js

@@ -152,14 +152,14 @@ export function wrapEngineAdapter(id, engine, opts) {
             const payload = run.payload;
             // DeepSeek persists and replays the native thread history. The durable Course Service
             // conversation is recovery/bootstrap data, not a second history to inject on every turn.
-            // Agent Service activations intentionally start a fresh local server because their model
-            // credential expires with the turn, so a cached thread id cannot suppress durable context.
-            const managedActivation = Boolean(run.runtimeEnv?.BOTLEARN_AGENT_SERVICE_ACTIVATION_ID?.trim());
-            const resumesDeepseekThread = id === "deepseek-tui" && !managedActivation && Boolean(run.nativeSessionId?.trim());
+            const resumesDeepseekThread = id === "deepseek-tui" && Boolean(run.nativeSessionId?.trim());
             const learnerInput = resumesDeepseekThread
                 ? renderCurrentLearnerRequest(payload)
                 : renderConversationInput(payload);
             const text = renderInputAttachments(run, learnerInput);
+            const recoveryText = resumesDeepseekThread
+                ? renderInputAttachments(run, renderConversationInput(payload))
+                : undefined;
             if (!text.trim()) {
                 throw new RuntimeExecutionError("empty task brief");
             }
@@ -190,10 +190,16 @@ export function wrapEngineAdapter(id, engine, opts) {
             };
             const result = await engine.run({
                 text,
+                ...(recoveryText !== undefined ? { recoveryText } : {}),
                 sessionId: run.nativeSessionId ?? null,
                 cwd: run.workspaceDir,
+                ...(run.runtimeStateDir ? { runtimeStateDir: run.runtimeStateDir } : {}),
                 signal,
                 ...(run.runtimeEnv ? { env: run.runtimeEnv } : {}),
+                ...(run.skillProvider ? { skillProvider: run.skillProvider } : {}),
+                ...(run.skillProvider && sink.skillEvent
+                    ? { onSkillEvent: (event) => sink.skillEvent(event) }
+                    : {}),
                 ...(extraArgs.length > 0 ? { extraArgs } : {}),
                 ...(systemContext !== undefined ? { systemContext } : {}),
                 onBlock: (block) => {
@@ -232,9 +238,10 @@ export function wrapEngineAdapter(id, engine, opts) {
             if (result.progressDispositions) {
                 await sink.progressDispositions?.(result.progressDispositions);
             }
-            if (result.usage || result.costUsd !== undefined) {
+            if (result.model || result.usage || result.costUsd !== undefined) {
                 await sink.usage?.({
                     ...(result.usage ?? {}),
+                    ...(result.model ? { model: result.model } : {}),
                     ...(result.costUsd !== undefined ? { cost_usd: result.costUsd } : {}),
                 });
             }

package/dist/runtimes/progress.d.ts

@@ -28,6 +28,8 @@ export interface ProgressMcpConfigOptions {
      * config, and a path writes a sanitized runtime-readable config below that root.
      */
     managedRoot?: string | null;
+    /** Activation-scoped daemon socket exposed through the clean-env course_skills relay. */
+    courseSkillsSocketPath?: string;
     platform?: NodeJS.Platform;
 }
 export declare class ProgressMcpConfigError extends Error {

package/dist/runtimes/progress.js

@@ -141,6 +141,7 @@ export function createProgressMcpConfig(options = {}) {
         throw new ProgressMcpConfigError("managed progress MCP config cannot preserve an existing DeepSeek MCP config");
     }
     const serverPath = fileURLToPath(new URL("../mcp/report-progress-server.js", import.meta.url));
+    const courseSkillsRelayPath = fileURLToPath(new URL("../mcp/course-skills-relay.js", import.meta.url));
     const baseConfigPath = managedRoot
         ? null
         : options.baseConfigPath === undefined
@@ -151,6 +152,12 @@ export function createProgressMcpConfig(options = {}) {
     if (Object.hasOwn(baseServers, "botlearn")) {
         throw new ProgressMcpConfigError("DeepSeek MCP server key 'botlearn' is reserved for BotLearn progress reporting");
     }
+    const courseSkillsSocketPath = options.courseSkillsSocketPath
+        ? validCourseSkillsSocketPath(options.courseSkillsSocketPath)
+        : undefined;
+    if (courseSkillsSocketPath && Object.hasOwn(baseServers, "course_skills")) {
+        throw new ProgressMcpConfigError("DeepSeek MCP server key 'course_skills' is reserved for BotLearn Course Skills");
+    }
     const dir = mkdtempSync(path.join(managedRoot ?? tmpdir(), "botlearn-progress-mcp-"));
     const configPath = path.join(dir, "mcp.json");
     const stagingPath = path.join(dir, ".mcp.json.tmp");
@@ -170,6 +177,25 @@ export function createProgressMcpConfig(options = {}) {
                 enabled: true,
                 required: false,
             },
+            ...(courseSkillsSocketPath
+                ? {
+                    course_skills: {
+                        command: "/usr/bin/env",
+                        args: [
+                            "-i",
+                            `PATH=${minimalPath}`,
+                            process.execPath,
+                            courseSkillsRelayPath,
+                            "--socket",
+                            courseSkillsSocketPath,
+                        ],
+                        env: {},
+                        disabled: false,
+                        enabled: true,
+                        required: true,
+                    },
+                }
+                : {}),
         },
     };
     try {
@@ -186,6 +212,14 @@ export function createProgressMcpConfig(options = {}) {
         throw error;
     }
 }
+function validCourseSkillsSocketPath(value) {
+    if (!path.isAbsolute(value)
+        || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > 240) {
+        throw new ProgressMcpConfigError("course_skills MCP socket path must be a bounded absolute path");
+    }
+    return value;
+}
 function resolveManagedProgressRoot(explicit) {
     if (explicit === null)
         return null;

package/dist/tool-observation.d.ts

@@ -0,0 +1,21 @@
+import type { RuntimeBlock } from "./types.js";
+export declare const AGENT_TOOL_OBSERVATION_SCHEMA_VERSION = "agent-tool-observation/0.1";
+export interface ToolObservationPayload extends Record<string, unknown> {
+    schema_version: typeof AGENT_TOOL_OBSERVATION_SCHEMA_VERSION;
+    kind: "tool_call" | "tool_result";
+    runtime: string;
+    status: "started" | "completed" | "error";
+    name?: string;
+    detail_preview?: string;
+    detail_truncated: boolean;
+    redacted: boolean;
+}
+/**
+ * Project a provider tool envelope into durable teacher evidence.
+ *
+ * The projection is deliberately lossy: only operational argument/result fields survive,
+ * credentials are removed, host paths become workspace-relative, and the JSON preview is
+ * bounded. Provider reasoning, message text, request IDs, and arbitrary envelope metadata
+ * never cross this boundary.
+ */
+export declare function buildToolObservation(block: RuntimeBlock, runtime: string, workspaceDir: string): ToolObservationPayload | null;

package/dist/tool-observation.js

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { REDACTED, redactSecretsDeep, } from "./redaction.js";
+export const AGENT_TOOL_OBSERVATION_SCHEMA_VERSION = "agent-tool-observation/0.1";
+const DETAIL_MAX_CHARS = 4_000;
+const MAX_PROJECT_DEPTH = 8;
+const SAFE_TOOL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,79}$/;
+const CALL_FIELDS = new Set([
+    "arguments",
+    "args",
+    "input",
+    "command",
+    "cmd",
+    "cwd",
+    "path",
+    "file_path",
+    "query",
+    "url",
+    "pattern",
+    "patch",
+    "changes",
+    "edits",
+]);
+const RESULT_FIELDS = new Set([
+    "result",
+    "output",
+    "stdout",
+    "stderr",
+    "exit_code",
+    "status",
+    "status_code",
+    "error",
+    "diff",
+    "path",
+    "file_path",
+    "bytes",
+]);
+/**
+ * Project a provider tool envelope into durable teacher evidence.
+ *
+ * The projection is deliberately lossy: only operational argument/result fields survive,
+ * credentials are removed, host paths become workspace-relative, and the JSON preview is
+ * bounded. Provider reasoning, message text, request IDs, and arbitrary envelope metadata
+ * never cross this boundary.
+ */
+export function buildToolObservation(block, runtime, workspaceDir) {
+    if (block.kind !== "tool_call" && block.kind !== "tool_result")
+        return null;
+    const fields = block.kind === "tool_call" ? CALL_FIELDS : RESULT_FIELDS;
+    const projected = collectAllowedFields(block.raw, fields);
+    if (typeof block.text === "string" && block.text) {
+        projected[block.kind === "tool_call" ? "target" : "summary"] = block.text;
+    }
+    const normalized = normalizeWorkspacePaths(redactSecretsDeep(projected), path.resolve(workspaceDir));
+    const serialized = Object.keys(projected).length > 0
+        ? JSON.stringify(normalized, null, 2)
+        : "";
+    const detailTruncated = serialized.length > DETAIL_MAX_CHARS;
+    const detailPreview = detailTruncated
+        ? `${serialized.slice(0, DETAIL_MAX_CHARS - 1)}…`
+        : serialized;
+    return {
+        schema_version: AGENT_TOOL_OBSERVATION_SCHEMA_VERSION,
+        kind: block.kind,
+        runtime,
+        status: block.kind === "tool_call"
+            ? "started"
+            : block.status === "error"
+                ? "error"
+                : "completed",
+        ...(block.name && SAFE_TOOL_NAME.test(block.name) ? { name: block.name } : {}),
+        ...(detailPreview ? { detail_preview: detailPreview } : {}),
+        detail_truncated: detailTruncated,
+        redacted: detailPreview.includes(REDACTED),
+    };
+}
+function collectAllowedFields(value, allowed, depth = 0, out = {}) {
+    if (value === null || typeof value !== "object" || depth >= MAX_PROJECT_DEPTH) {
+        return out;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value.slice(0, 50)) {
+            collectAllowedFields(item, allowed, depth + 1, out);
+        }
+        return out;
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (allowed === RESULT_FIELDS
+            && key === "content"
+            && value.type === "tool_result") {
+            if (!("content" in out))
+                out.content = item;
+            continue;
+        }
+        if (allowed.has(key)) {
+            if (!(key in out))
+                out[key] = item;
+            continue;
+        }
+        collectAllowedFields(item, allowed, depth + 1, out);
+    }
+    return out;
+}
+function normalizeWorkspacePaths(value, workspaceDir) {
+    if (typeof value === "string") {
+        const normalizedWorkspace = workspaceDir.replaceAll("\\", "/").replace(/\/+$/, "");
+        const normalizedValue = value.replaceAll("\\", "/");
+        return normalizedValue
+            .replaceAll(`${normalizedWorkspace}/`, "")
+            .replaceAll(normalizedWorkspace, ".");
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => normalizeWorkspacePaths(item, workspaceDir));
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        normalizeWorkspacePaths(item, workspaceDir),
+    ]));
+}

package/dist/types.d.ts

@@ -5,6 +5,7 @@
  * `services/course-api/botlearn_course/schemas.py` 的 daemon 契约严格对齐。
  */
 import type { ProgressStatus } from "./mcp/report-progress.js";
+import type { PreparedRuntimeSkillProvider, RuntimeSkillEvent } from "./runtime-skills.js";
 export interface RunInputAttachment {
     attachment_id: string;
     filename: string;
@@ -53,7 +54,7 @@ export interface RunStartPayload {
  * `POST /daemon/runs/{id}/events` 接受的事件类型。
  * 与后端 DaemonRunEventIn.type 的 Literal 严格一致 —— 发送其他类型会得到 422。
  */
-export type RunEventType = "run.accepted" | "run.started" | "run.block" | "run.message" | "run.completed" | "run.failed" | "run.cancelled";
+export type RunEventType = "run.accepted" | "run.started" | "run.block" | "run.observation" | "run.message" | "run.completed" | "run.failed" | "run.cancelled";
 export interface RunEvent {
     type: RunEventType;
     /** End-to-end correlation id assigned by Course Service. */
@@ -125,7 +126,10 @@ export interface AppliedRunRuntimeProfile {
 export interface RuntimeContentBlock {
     kind: "text_delta" | "text" | "thinking" | "tool_call" | "tool_result" | "status" | "error";
     text?: string;
-    /** Safe provider-normalized tool identifier. Raw arguments/results stay in the transcript only. */
+    /**
+     * Safe provider-normalized tool identifier. Raw envelopes stay local; the dispatcher may
+     * derive a separate bounded/redacted teacher observation from explicit operation fields.
+     */
     name?: string;
     /** Public lifecycle metadata; never carries provider reasoning or tool output. */
     phase?: "in_progress" | "completed";
@@ -149,13 +153,26 @@ export interface RuntimeProgressDispositions {
 }
 /** Content-free model usage; adapters populate only fields actually reported upstream. */
 export interface RuntimeUsage {
+    /** Model identity resolved by the runtime/provider, not inferred by the daemon. */
+    model?: string;
     input_tokens?: number;
     cached_input_tokens?: number;
     output_tokens?: number;
+    reasoning_tokens?: number;
     total_tokens?: number;
     cost_usd?: number;
     provider_request_ids?: string[];
 }
+/** Content-free shape of one runtime-native completion. */
+export interface RuntimeCompletionSummary {
+    assistant_message_count: number;
+    reasoning_message_count: number;
+    assistant_content_present: boolean;
+    reasoning_content_present: boolean;
+    tool_call_count: number;
+    turn_status?: string;
+    finish_reason?: string;
+}
 export interface RuntimeAuthProbe {
     checked: boolean;
     ok: boolean;
@@ -179,12 +196,16 @@ export interface CourseRuntimeSink {
     usage?(usage: RuntimeUsage): Promise<void>;
     /** Persist the runtime-native thread/session id before a terminal turn event is emitted. */
     runtimeSession?(sessionId: string): Promise<void>;
+    /** Content-free technical evidence from the control-side Runtime Skill Provider. */
+    skillEvent?(event: RuntimeSkillEvent): Promise<void>;
 }
 /** 一次 run 的本地执行上下文：服务器 payload + daemon 本地准备产物。 */
 export interface RunExecution {
     payload: RunStartPayload;
     /** Runtime cwd. Managed persistent sessions reuse one session-scoped workspace. */
     workspaceDir: string;
+    /** Daemon-owned state directory for one managed RuntimeSession; never exposed to the model. */
+    runtimeStateDir?: 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. */
@@ -193,6 +214,8 @@ export interface RunExecution {
     runtimeEnv?: NodeJS.ProcessEnv;
     /** Verified learner files materialized beneath the runtime workspace. */
     inputAttachments?: MaterializedInputAttachment[];
+    /** Activation-scoped provider held by the daemon control process, never runtime env. */
+    skillProvider?: PreparedRuntimeSkillProvider;
 }
 export interface CourseRuntime {
     id: string;
@@ -224,7 +247,10 @@ export interface RuntimeFailureSummary {
     stderr_tail?: string;
     stdout_tail?: string;
     error_name?: string;
+    error_code?: string;
     error_message?: string;
+    model?: string;
+    completion?: RuntimeCompletionSummary;
 }
 export interface RuntimeModule {
     id: string;

package/package.json

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