@botlearn-course/daemon 0.0.13 → 0.0.15

package/README.md

@@ -114,8 +114,11 @@ runtime 凭据。
 - 本包 production 依赖为零，发布 tarball 只包含 `dist/`、`README.md`、`package.json`、
   `LICENSE`（CI 发布前强制校验）。
 - 托管 session 的 control token/reconnect state 位于 runtime UID 不可访问的 `0700` control home；
-  runtime workspace 独立可写，Prompt Pack/Skill 则通过 control-owned、group-readable 的只读视图
-  提供。长期模型 provider key 留在 Agent Service，runtime 只拿 generation-scoped proxy grant。
+  runtime workspace 独立可写。activation-scoped Skill Provider binding 只留在 daemon control
+  process 内存；DeepSeek 只通过 clean-env `course_skills` Unix Socket relay 按需读取当前授权
+  `SKILL.md`/reference，endpoint/token 不进入 runtime env、MCP config、state、workspace 或日志。
+  Prompt Pack 仍通过受信 system context 应用。长期模型 provider key 留在 Agent Service，runtime
+  只拿 generation-scoped proxy grant。
 
 ## 发布
 

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

@@ -1,4 +1,5 @@
 import { type Logger } from "./log.js";
+import { type RuntimeSkillProviderFactory } from "./runtime-skills.js";
 import { type PersistentSessionExecution, type PreparedPersistentTurn, type RunReportingClient } from "./run-dispatcher.js";
 import type { CourseRuntime, CourseRuntimeProfile, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
 export interface AgentServiceSandboxOptions {
@@ -11,6 +12,8 @@ export interface AgentServiceSandboxOptions {
     log?: Logger;
     random?: () => number;
     sleep?: (ms: number) => Promise<void>;
+    /** Test/provider injection; production uses the bounded HTTP Runtime Skill Provider. */
+    prepareSkillProvider?: RuntimeSkillProviderFactory;
 }
 /**
  * Long-running daemon client for one user-scoped managed sandbox (ADR-015).
@@ -24,6 +27,7 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private readonly log;
     private readonly random;
     private readonly sleep;
+    private readonly prepareSkillProvider;
     private readonly state;
     private readonly dispatcher;
     /** agent_run_id → TURN scope（session/attempt/activation），事件与文件帧路由用。 */
@@ -52,6 +56,15 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private stopped;
     private permanentFailure;
     private lifecycleChain;
+    private runtimeLogPolicy;
+    private runtimeLogHandshakeReady;
+    private runtimeLogWindowStartedAt;
+    private runtimeLogWindowEvents;
+    private runtimeLogWindowBytes;
+    private runtimeLogSuppressedEvents;
+    private runtimeLogSuppressedBytes;
+    private runtimeLogSendChain;
+    private readonly removeOperationalLogSink;
     constructor(options: AgentServiceSandboxOptions);
     prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
     persistNativeSession(nativeSessionId: string): void;
@@ -65,6 +78,8 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
     private connectOnce;
     private handleHello;
+    private forwardOperationalLog;
+    private queueRuntimeLog;
     private assertServerFrame;
     private handleServerFrame;
     /** sandbox.sync 只做对账：重放 spool、关闭待关 session、应用 drain/shutdown。 */

package/dist/agent-service-sandbox.js

@@ -2,10 +2,11 @@ import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readF
 import path from "node:path";
 import { ensureDaemonHome } from "./auth-store.js";
 import { AGENT_SERVICE_WS_SCHEMA, AGENT_SERVICE_WS_SUBPROTOCOL, createSandboxFrame, parseSandboxFrame, UnsupportedSandboxProtocolError, } from "./agent-service-ws-protocol.js";
-import { log as defaultLog } from "./log.js";
-import { availableRunCapabilities } from "./runtime-capabilities.js";
+import { log as defaultLog, setOperationalLogSink, } from "./log.js";
+import { availableRunCapabilities, runtimeSupportsCourseSkills, } from "./runtime-capabilities.js";
 import { activationRuntimeEnv, runtimeChildEnv } from "./runtime-env.js";
 import { redactSecretString } from "./redaction.js";
+import { parseRuntimeSkillProviderGrantSet, prepareRuntimeSkillProvider, RuntimeSkillProviderError, } from "./runtime-skills.js";
 import { RunDispatcher, } from "./run-dispatcher.js";
 import { ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, } from "./workspace.js";
 import { WebSocketClient, } from "./websocket-client.js";
@@ -16,6 +17,70 @@ const MAX_EVENT_ACK_WINDOW = 64;
 const LEGACY_EVENT_ACK_WINDOW = 1;
 /** 出站 seq 基址：seq = connection_epoch * SEQ_EPOCH_BASE + n，跨重连单调（合同 §1.1）。 */
 const SEQ_EPOCH_BASE = 1_000_000_000;
+const RUNTIME_LOG_WINDOW_MS = 60_000;
+const DISABLED_RUNTIME_LOG_POLICY = {
+    enabled: false,
+    maxEventBytes: 4096,
+    maxEventsPerMinute: 1,
+    maxBytesPerMinute: 4096,
+};
+function boundedUtf8(value, maxBytes) {
+    const encoded = Buffer.from(value, "utf8");
+    if (encoded.length <= maxBytes)
+        return value;
+    const suffix = "…[truncated]";
+    const budget = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+    return encoded.subarray(0, budget).toString("utf8").replace(/�$/u, "") + suffix;
+}
+function boundedLogFields(fields, maxBytes) {
+    if (!fields || maxBytes < 2)
+        return { bytes: 0 };
+    const bounded = {};
+    let truncated = false;
+    for (const [key, value] of Object.entries(fields)) {
+        bounded[key] = value;
+        let bytes;
+        try {
+            bytes = Buffer.byteLength(JSON.stringify(bounded), "utf8");
+        }
+        catch {
+            bytes = maxBytes + 1;
+        }
+        if (bytes > maxBytes) {
+            delete bounded[key];
+            truncated = true;
+            break;
+        }
+    }
+    if (truncated) {
+        const marked = { ...bounded, runtime_log_fields_truncated: true };
+        if (Buffer.byteLength(JSON.stringify(marked), "utf8") <= maxBytes) {
+            Object.assign(bounded, { runtime_log_fields_truncated: true });
+        }
+    }
+    if (!Object.keys(bounded).length)
+        return { bytes: 0 };
+    const bytes = Buffer.byteLength(JSON.stringify(bounded), "utf8");
+    return { fields: bounded, bytes };
+}
+function runtimeLogPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return DISABLED_RUNTIME_LOG_POLICY;
+    }
+    const raw = value;
+    const integer = (key, fallback, min, max) => {
+        const candidate = Number(raw[key]);
+        return Number.isSafeInteger(candidate) && candidate >= min && candidate <= max
+            ? candidate
+            : fallback;
+    };
+    return {
+        enabled: raw.enabled === true,
+        maxEventBytes: integer("max_event_bytes", 4096, 256, 16_384),
+        maxEventsPerMinute: integer("max_events_per_minute", 60, 1, 600),
+        maxBytesPerMinute: integer("max_bytes_per_minute", 131_072, 4096, 1_048_576),
+    };
+}
 function inputAttachmentGrant(value) {
     if (value === undefined || value === null)
         return undefined;
@@ -44,6 +109,9 @@ function inputAttachmentGrant(value) {
     }
     return { baseUrl: parsed.toString().replace(/\/$/, ""), token };
 }
+function runtimeSkillGrantKey(grants) {
+    return JSON.stringify(grants);
+}
 class SandboxClosedError extends Error {
     code;
     reason;
@@ -244,6 +312,7 @@ export class AgentServiceSandboxClient {
     log;
     random;
     sleep;
+    prepareSkillProvider;
     state;
     dispatcher;
     /** agent_run_id → TURN scope（session/attempt/activation），事件与文件帧路由用。 */
@@ -272,15 +341,29 @@ export class AgentServiceSandboxClient {
     stopped = false;
     permanentFailure = false;
     lifecycleChain = Promise.resolve();
+    runtimeLogPolicy = DISABLED_RUNTIME_LOG_POLICY;
+    runtimeLogHandshakeReady = false;
+    runtimeLogWindowStartedAt = 0;
+    runtimeLogWindowEvents = 0;
+    runtimeLogWindowBytes = 0;
+    runtimeLogSuppressedEvents = 0;
+    runtimeLogSuppressedBytes = 0;
+    runtimeLogSendChain = Promise.resolve();
+    removeOperationalLogSink;
     constructor(options) {
         this.options = options;
         this.log = options.log ?? defaultLog;
         this.random = options.random ?? Math.random;
         this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.prepareSkillProvider =
+            options.prepareSkillProvider ?? ((raw) => prepareRuntimeSkillProvider(raw));
         this.state = loadState(options.sandboxId, options.sandboxToken);
         this.dispatcher = new RunDispatcher(this, options.runtimes, {
             persistentSession: this,
         });
+        this.removeOperationalLogSink = setOperationalLogSink((entry) => {
+            this.forwardOperationalLog(entry);
+        });
     }
     prepareTurn(payload) {
         const scope = this.turnScopes.get(payload.agent_run_id);
@@ -318,6 +401,7 @@ export class AgentServiceSandboxClient {
             contextRevision,
             runtimeEnv,
             inputAttachmentGrant: activation.inputAttachmentGrant,
+            ...(activation.skillProvider ? { skillProvider: activation.skillProvider } : {}),
         };
     }
     persistNativeSession(nativeSessionId) {
@@ -440,6 +524,7 @@ export class AgentServiceSandboxClient {
                 await this.sleep(delay);
             }
         }
+        this.removeOperationalLogSink();
         if (this.permanentFailure) {
             throw new Error("Agent Service sandbox stopped after a permanent protocol failure");
         }
@@ -456,6 +541,8 @@ export class AgentServiceSandboxClient {
         this.activeSessionId = null;
         this.currentTurnSessionId = null;
         this.persist();
+        this.runtimeLogHandshakeReady = false;
+        this.removeOperationalLogSink();
         this.socket?.close(1000, "daemon_stopping");
     }
     async postEvent(agentRunId, event) {
@@ -631,6 +718,7 @@ export class AgentServiceSandboxClient {
             this.rejectPendingFiles(new Error("Agent Service file transport disconnected"));
             if (this.socket === socket)
                 this.socket = null;
+            this.runtimeLogHandshakeReady = false;
             if (socket.readyState === WebSocketClient.OPEN)
                 socket.close(1000, "reconnecting");
         }
@@ -675,6 +763,7 @@ export class AgentServiceSandboxClient {
             ? advertisedAckWindow
             : LEGACY_EVENT_ACK_WINDOW;
         this.maxUnackedEvents = Math.min(MAX_EVENT_ACK_WINDOW, ackWindow);
+        this.runtimeLogPolicy = runtimeLogPolicy(frame.payload.runtime_log_policy);
         this.persist();
         await this.sendControlFrame("sandbox.ready", {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
@@ -688,6 +777,73 @@ export class AgentServiceSandboxClient {
             resumed_sessions: Object.keys(this.state.sessions),
             spool_frames: this.spoolFrameCount(),
         });
+        this.runtimeLogHandshakeReady = true;
+    }
+    forwardOperationalLog(entry) {
+        const policy = this.runtimeLogPolicy;
+        if (!policy.enabled || !this.runtimeLogHandshakeReady)
+            return;
+        const message = boundedUtf8(entry.message, policy.maxEventBytes);
+        const messageBytes = Buffer.byteLength(message, "utf8");
+        const boundedFields = boundedLogFields(entry.fields, Math.max(0, policy.maxEventBytes - messageBytes));
+        const contentBytes = messageBytes + boundedFields.bytes;
+        const now = Date.now();
+        if (now - this.runtimeLogWindowStartedAt >= RUNTIME_LOG_WINDOW_MS) {
+            if (this.runtimeLogSuppressedEvents > 0) {
+                this.queueRuntimeLog({
+                    level: "warn",
+                    message: "sandbox runtime logs suppressed at daemon source",
+                    fields: {
+                        suppressed_count: this.runtimeLogSuppressedEvents,
+                        suppressed_bytes: this.runtimeLogSuppressedBytes,
+                    },
+                    timestamp: new Date(now).toISOString(),
+                });
+            }
+            this.runtimeLogWindowStartedAt = now;
+            this.runtimeLogWindowEvents = 0;
+            this.runtimeLogWindowBytes = 0;
+            this.runtimeLogSuppressedEvents = 0;
+            this.runtimeLogSuppressedBytes = 0;
+        }
+        if (this.runtimeLogWindowEvents >= policy.maxEventsPerMinute ||
+            this.runtimeLogWindowBytes + contentBytes > policy.maxBytesPerMinute) {
+            this.runtimeLogSuppressedEvents += 1;
+            this.runtimeLogSuppressedBytes += contentBytes;
+            return;
+        }
+        this.runtimeLogWindowEvents += 1;
+        this.runtimeLogWindowBytes += contentBytes;
+        this.queueRuntimeLog({
+            ...entry,
+            message,
+            fields: boundedFields.fields,
+        });
+    }
+    queueRuntimeLog(entry) {
+        this.runtimeLogSendChain = this.runtimeLogSendChain
+            .then(async () => {
+            if (!this.runtimeLogHandshakeReady || this.socket?.readyState !== WebSocketClient.OPEN) {
+                return;
+            }
+            await this.sendFrame(createSandboxFrame({
+                type: "sandbox.log",
+                sandboxId: this.options.sandboxId,
+                sandboxGeneration: this.sandboxGeneration,
+                connectionEpoch: this.connectionEpoch,
+                seq: this.nextOutboundSeq(),
+                payload: {
+                    level: entry.level,
+                    stream: "stderr",
+                    message: entry.message,
+                    emitted_at: entry.timestamp,
+                    ...(entry.fields ? { fields: entry.fields } : {}),
+                },
+            }));
+        })
+            .catch(() => {
+            // Sentry forwarding is best-effort and must not enter the daemon logger.
+        });
     }
     assertServerFrame(frame) {
         if (frame.sandbox_id !== this.options.sandboxId ||
@@ -849,33 +1005,59 @@ export class AgentServiceSandboxClient {
             await this.sendCommandAck(frame, "rejected", error instanceof Error ? error.message : "invalid_instructions");
             return;
         }
+        const rawSkillProvider = frame.payload.skill_provider;
+        const hasSkillProvider = rawSkillProvider !== undefined && rawSkillProvider !== null;
+        if (hasSkillProvider && !runtimeSupportsCourseSkills(runtimeId)) {
+            await this.sendCommandAck(frame, "rejected", "skill_provider_runtime_unsupported");
+            return;
+        }
+        let skillGrantKey;
+        if (hasSkillProvider) {
+            try {
+                skillGrantKey = runtimeSkillGrantKey(parseRuntimeSkillProviderGrantSet(rawSkillProvider));
+            }
+            catch (error) {
+                const code = error instanceof RuntimeSkillProviderError
+                    ? error.code
+                    : "skill_provider_binding_invalid";
+                await this.sendCommandAck(frame, "rejected", code);
+                return;
+            }
+        }
         const capabilities = Array.isArray(frame.payload.capabilities)
             ? frame.payload.capabilities.filter((item) => typeof item === "string" && item.length > 0)
             : [];
-        if (capabilities.length > 0) {
-            const workspace = ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
-            const available = new Set(availableRunCapabilities({
-                agent_run_id: "activation-probe",
-                course_run_id: session.courseRunId ?? "",
-                lesson_id: null,
-                task_id: null,
-                agent_instance_id: null,
-                runtime: { id: runtimeId },
-                input: {},
-                context: {},
-                limits: {},
-            }, workspace.workspaceDir));
-            const missing = capabilities.filter((item) => !available.has(item)).sort();
-            if (missing.length > 0) {
-                await this.sendCommandAck(frame, "rejected", `missing_capabilities:${missing.join(",")}`);
-                return;
+        let availableCapabilities;
+        const missingCapabilities = (required) => {
+            if (required.length === 0)
+                return [];
+            if (!availableCapabilities) {
+                const workspace = ensureRuntimeSessionDirectories(sessionId, this.sandboxGeneration);
+                availableCapabilities = new Set(availableRunCapabilities({
+                    agent_run_id: "activation-probe",
+                    course_run_id: session.courseRunId ?? "",
+                    lesson_id: null,
+                    task_id: null,
+                    agent_instance_id: null,
+                    runtime: { id: runtimeId },
+                    input: {},
+                    context: {},
+                    limits: {},
+                }, workspace.workspaceDir));
             }
+            return Array.from(new Set(required.filter((item) => !availableCapabilities.has(item)))).sort();
+        };
+        const missingDeclaredCapabilities = missingCapabilities(capabilities);
+        if (missingDeclaredCapabilities.length > 0) {
+            await this.sendCommandAck(frame, "rejected", `missing_capabilities:${missingDeclaredCapabilities.join(",")}`);
+            return;
         }
         const existingActivation = this.activationContexts.get(sessionId);
         if (existingActivation?.activationId === activationId) {
             if (this.activeSessionId !== sessionId ||
                 session.runtimeId !== runtimeId ||
-                session.contextRevision !== contextRevision) {
+                session.contextRevision !== contextRevision ||
+                existingActivation.skillGrantKey !== skillGrantKey) {
                 await this.sendCommandAck(frame, "rejected", "activation_redefinition");
                 return;
             }
@@ -891,6 +1073,25 @@ export class AgentServiceSandboxClient {
             await this.sendCommandAck(frame, "ok");
             return;
         }
+        let skillProvider;
+        if (hasSkillProvider) {
+            try {
+                skillProvider = await this.prepareSkillProvider(rawSkillProvider);
+            }
+            catch (error) {
+                const code = error instanceof RuntimeSkillProviderError
+                    ? error.code
+                    : "skill_provider_prepare_failed";
+                await this.sendCommandAck(frame, "rejected", code);
+                return;
+            }
+            const requiredBySkills = skillProvider.catalog.flatMap((entry) => entry.requiredCapabilities);
+            const missingSkillCapabilities = missingCapabilities(requiredBySkills);
+            if (missingSkillCapabilities.length > 0) {
+                await this.sendCommandAck(frame, "rejected", `missing_capabilities:${missingSkillCapabilities.join(",")}`);
+                return;
+            }
+        }
         // 同一时刻只允许一个 active session/activation。先撤销上一 workspace 的
         // runtime 访问并等待进程退出，再暴露新 workspace，避免同 UID 跨 Session 读取。
         const previousSessionId = this.activeSessionId;
@@ -920,6 +1121,8 @@ export class AgentServiceSandboxClient {
             runtimeEnv,
             instructions,
             inputAttachmentGrant: attachmentGrant,
+            ...(skillProvider ? { skillProvider } : {}),
+            ...(skillGrantKey ? { skillGrantKey } : {}),
         });
         this.activeSessionId = sessionId;
         this.persist();
@@ -1037,7 +1240,10 @@ export class AgentServiceSandboxClient {
             await this.sendCommandAck(frame, "rejected", "turn_scope_mismatch");
             return;
         }
-        this.dispatcher.cancel(frame.agent_run_id);
+        if (!this.dispatcher.cancel(frame.agent_run_id)) {
+            await this.sendCommandAck(frame, "rejected", "turn_not_running");
+            return;
+        }
         await this.sendCommandAck(frame, "ok");
     }
     /**

package/dist/agent-service-ws-protocol.d.ts

@@ -1,6 +1,6 @@
 export declare const AGENT_SERVICE_WS_SCHEMA: "botlearn-agent-sandbox-ws/0.2";
 export declare const AGENT_SERVICE_WS_SUBPROTOCOL: "botlearn-agent-sandbox.v2";
-export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.closed" | "turn.event" | "turn.file.report" | "sandbox.drained" | "pong" | "protocol.error";
+export type SandboxFrameType = "sandbox.hello" | "sandbox.sync" | "session.open" | "session.activate" | "turn.start" | "turn.cancel" | "session.close" | "sandbox.drain" | "sandbox.shutdown" | "event.ack" | "auth.rotate" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.closed" | "turn.event" | "turn.file.report" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
 export declare class UnsupportedSandboxProtocolError extends Error {
     readonly schemaVersion: unknown;
     constructor(schemaVersion: unknown);

package/dist/agent-service-ws-protocol.js

@@ -22,6 +22,7 @@ const FRAME_TYPES = new Set([
     "turn.event",
     "turn.file.report",
     "sandbox.drained",
+    "sandbox.log",
     "pong",
     "protocol.error",
 ]);

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/log.d.ts

@@ -1,4 +1,13 @@
 type Level = "info" | "warn" | "error" | "debug";
+export interface OperationalLogEntry {
+    level: Level;
+    message: string;
+    fields?: Record<string, unknown>;
+    timestamp: string;
+}
+export type OperationalLogSink = (entry: OperationalLogEntry) => void;
+/** One managed sandbox daemon runs per process, so it owns one ephemeral remote sink. */
+export declare function setOperationalLogSink(sink: OperationalLogSink): () => void;
 export interface Logger {
     info(msg: string, fields?: Record<string, unknown>): void;
     warn(msg: string, fields?: Record<string, unknown>): void;

package/dist/log.js

@@ -1,7 +1,7 @@
 import { appendFileSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { daemonHome } from "./auth-store.js";
-import { redactSecretsDeep } from "./redaction.js";
+import { redactSecretString, redactSecretsDeep } from "./redaction.js";
 const LOG_DIR = path.join(daemonHome(), "logs");
 const LOG_FILE = path.join(LOG_DIR, "daemon.log");
 const LOG_ROTATE_MAX_BYTES = 10 * 1024 * 1024;
@@ -18,6 +18,15 @@ function ensureDir() {
     }
     inited = true;
 }
+let operationalLogSink = null;
+/** One managed sandbox daemon runs per process, so it owns one ephemeral remote sink. */
+export function setOperationalLogSink(sink) {
+    operationalLogSink = sink;
+    return () => {
+        if (operationalLogSink === sink)
+            operationalLogSink = null;
+    };
+}
 function formatValue(value) {
     if (value instanceof Error)
         return JSON.stringify(value.stack ?? value.message);
@@ -131,7 +140,9 @@ function write(level, msg, fields) {
     ensureDir();
     // 所有 fields 值序列化前先深度脱敏，token 类值绝不落盘/上屏。
     const safeFields = fields === undefined ? undefined : redactSecretsDeep(fields);
-    const line = formatLogLine(level, msg, safeFields);
+    const safeMessage = redactSecretString(msg);
+    const timestamp = new Date();
+    const line = formatLogLine(level, safeMessage, safeFields, timestamp);
     try {
         rotateLogIfNeeded(LOG_FILE, Buffer.byteLength(line) + 1);
         appendFileSync(LOG_FILE, line + "\n", { mode: 0o600 });
@@ -141,6 +152,17 @@ function write(level, msg, fields) {
     }
     // 同步镜像到 stderr，前台运行时可直接观察。
     process.stderr.write(line + "\n");
+    try {
+        operationalLogSink?.({
+            level,
+            message: safeMessage,
+            fields: safeFields,
+            timestamp: timestamp.toISOString(),
+        });
+    }
+    catch {
+        // Observability must never affect daemon execution or recurse into the logger.
+    }
 }
 export const log = {
     info: (msg, fields) => write("info", msg, fields),

package/dist/mcp/course-skills-relay.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCourseSkillsRelay(argv?: string[]): void;

package/dist/mcp/course-skills-relay.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function runCourseSkillsRelay(argv = process.argv.slice(2)) {
+    const socketPath = relaySocketPath(argv);
+    const socket = net.createConnection({ path: socketPath });
+    const fail = () => {
+        process.stderr.write("course_skills relay unavailable\n");
+        process.exitCode = 1;
+    };
+    socket.once("error", fail);
+    socket.once("connect", () => {
+        process.stdin.pipe(socket);
+        socket.pipe(process.stdout);
+    });
+    socket.once("close", () => {
+        if (!process.stdin.readableEnded)
+            process.stdin.destroy();
+    });
+}
+function relaySocketPath(argv) {
+    if (argv.length !== 2 || argv[0] !== "--socket") {
+        throw new Error("course_skills relay requires --socket");
+    }
+    const value = argv[1] ?? "";
+    if (!path.isAbsolute(value)
+        || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > 240) {
+        throw new Error("course_skills relay socket is invalid");
+    }
+    return value;
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    try {
+        runCourseSkillsRelay();
+    }
+    catch {
+        process.stderr.write("course_skills relay configuration invalid\n");
+        process.exitCode = 1;
+    }
+}

package/dist/mcp/course-skills-server.d.ts

@@ -0,0 +1,49 @@
+import { type PreparedRuntimeSkillProvider, type RuntimeSkillCatalogEntry, type RuntimeSkillEvent } from "../runtime-skills.js";
+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;
+    };
+}
+export interface CourseSkillsMcpServer {
+    socketPath: string;
+    catalog: RuntimeSkillCatalogEntry[];
+    markApplied(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface CourseSkillsMcpServerOptions {
+    prepared: PreparedRuntimeSkillProvider;
+    onEvent(event: RuntimeSkillEvent): Promise<void>;
+    /**
+     * Managed Agent Service root. `undefined` auto-detects it; `null` is only for
+     * private same-UID tests/BYOA experiments.
+     */
+    managedRoot?: string | null;
+}
+export declare class CourseSkillsMcpRuntime {
+    private readonly options;
+    private readonly grantsByRef;
+    private readonly loadedSkills;
+    private readonly loadedReferences;
+    private referenceBytes;
+    constructor(options: CourseSkillsMcpServerOptions);
+    emitAppliedEvents(): Promise<void>;
+    handle(request: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    private loadSkill;
+    private loadReference;
+    private requireGrant;
+    private emit;
+    private emitLoadFailed;
+}
+export declare function startCourseSkillsMcpServer(options: CourseSkillsMcpServerOptions): Promise<CourseSkillsMcpServer>;
+export {};