@botlearn-course/daemon 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OURACA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @botlearn-course/daemon
+
+BotLearn Course 的轻量本机 daemon：把课程任务（run）分发到你自己机器上的 agent runtime 执行
+（BYOA，Bring Your Own Agent）。daemon 用 install code 绑定你的 BotLearn 账号，然后轮询
+Course API 领取分配给本机的 run，在隔离工作区内调用本机已登录的 CLI runtime（Codex、
+Claude Code、Gemini 等）完成任务，并把过程事件与产出文件候选回传给课程服务。
+
+- 零 production 依赖，只用 Node 内建模块（Node >= 20）。
+- 凭据只存本机，不经过第三方；runtime 复用你本机已有的登录状态。
+
+## 安装与使用
+
+无需安装，直接用 `npx`：
+
+```bash
+# 1. 环境自检：探测各 runtime 的安装 / 版本 / 登录状态
+npx @botlearn-course/daemon@latest course doctor
+
+# 2. 登录：用前端「我的 Daemon」页面生成的 install code 绑定本机
+npx @botlearn-course/daemon@latest course login --api-url <course-api-url> --code <blic_xxx> [--label <名称>]
+
+# 3. 启动：前台轮询并执行分配给本机的 run（Ctrl+C 优雅退出）
+npx @botlearn-course/daemon@latest course start [--once] [--poll-interval-ms <ms>]
+
+# 4. 登出：删除本机凭据文件
+npx @botlearn-course/daemon@latest course logout
+```
+
+命令说明：
+
+| 命令 | 说明 |
+| --- | --- |
+| `course login` | 用 install code 换取 daemon 凭据并写入本机 `auth.json`。`--api-url` 缺省时读 `BOTLEARN_COURSE_API_URL`；`--label` 缺省为本机 hostname。成功后打印 daemon id。 |
+| `course start` | 读取 `auth.json`，轮询 Course API 领取 run 并执行。`--once` 只领取一次（有 run 则等它执行完再退出）；`--poll-interval-ms` 调整空轮询间隔。凭据过期/被吊销时提示重新 login 并退出。 |
+| `course logout` | 删除本机 `auth.json`。服务端吊销请在前端 daemon 列表操作。 |
+| `course doctor` | 打印 Auth 状态（不含 token）与 runtime 探测表（安装路径 / 版本 / 登录状态 / 安装提示）。 |
+| `--help` / `--version` | 帮助与版本。 |
+
+## 支持的 runtime
+
+run 的 `runtime.id` 决定用哪个 adapter 执行；未指定时默认 `codex`。runtime 不可用时 run 会
+直接失败（不做静默回退），请先用 `course doctor` 确认目标 runtime 可用。
+
+| runtime id | 名称 | 依赖的本机命令 | 二进制覆盖变量 | 说明 |
+| --- | --- | --- | --- | --- |
+| `codex` | Codex CLI | `codex` | `BOTLEARN_CODEX_BIN` | 默认 runtime |
+| `claude-code` | Claude Code | `claude` | `BOTLEARN_CLAUDE_BIN` | doctor 会额外探测登录状态 |
+| `gemini` | Gemini CLI | `gemini` | `BOTLEARN_GEMINI_BIN` | |
+| `kimi-cli` | Kimi CLI | `kimi` | `BOTLEARN_KIMI_CLI_BIN` | |
+| `deepseek-tui` | DeepSeek TUI | `deepseek` | `BOTLEARN_DEEPSEEK_TUI_BIN` | |
+| `hermes-agent` | Hermes Agent | `hermes-acp` | `BOTLEARN_HERMES_AGENT_BIN` | ACP stdio 协议 |
+| `openclaw-acp` | OpenClaw (ACP) | `openclaw` | `BOTLEARN_OPENCLAW_BIN` | 还需配置 `BOTLEARN_OPENCLAW_URL`（可选 `BOTLEARN_OPENCLAW_TOKEN` / `BOTLEARN_OPENCLAW_AGENT`），二进制或 URL 缺失时 doctor 标记不可用 |
+| `fake` | 假 runtime | 无 | — | 仅测试/演示用：产出确定性文本与一个 `draft.md`。默认隐藏，只有 `BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME=1` 时才注册并上报 |
+
+各 runtime 的登录（API key / OAuth）沿用你本机已有的配置 —— daemon 不保存、不代管任何
+runtime 凭据。
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `BOTLEARN_COURSE_API_URL` | `course login --api-url` 缺省值 |
+| `BOTLEARN_DAEMON_HOME` | 覆盖本地状态根目录（默认 `~/.botlearn-course/daemon`；测试/多实例用） |
+| `BOTLEARN_DAEMON_DEBUG` | 非空时输出 debug 级日志 |
+| `BOTLEARN_<X>_BIN` | 覆盖某个 runtime 的二进制路径，各 runtime 的变量名见上表（如 `BOTLEARN_CLAUDE_BIN`），以 `course doctor` 输出为准 |
+| `BOTLEARN_OPENCLAW_URL` | OpenClaw gateway 地址（`openclaw-acp` 必需） |
+| `BOTLEARN_OPENCLAW_TOKEN` | OpenClaw gateway token（可选） |
+| `BOTLEARN_OPENCLAW_AGENT` | OpenClaw agent 名称（可选） |
+| `BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME` | 设为 `1` 时启用测试用 `fake` runtime |
+
+## 本地文件布局与权限
+
+所有状态位于 `~/.botlearn-course/daemon`（可用 `BOTLEARN_DAEMON_HOME` 覆盖）：
+
+```text
+~/.botlearn-course/daemon/          # 0700
+  auth.json                         # 0600，daemon 凭据（access/refresh token、courseApiUrl）
+  machine-id                        # 0600，首次运行生成的机器指纹
+  logs/                             # 0700
+    daemon.log                      # 0600，按 10MiB 轮转，保留 20 个历史文件
+  workspaces/<agent_run_id>/        # 每个 run 一个隔离目录，0700
+    work/                           # runtime 的工作目录（cwd），产出文件候选从这里扫描
+    transcript.jsonl                # 本地执行记录（脱敏后写入）
+```
+
+## 安全说明
+
+- `auth.json` 是敏感凭据文件（0600），token 只存本机、只发给你 login 时指定的 Course API；
+  日志、transcript、doctor 输出、错误信息在写出前都会经过脱敏（token / api key / 密码等
+  字段与常见 token 形态一律替换为 `[REDACTED]`）。
+- 文件扫描只访问 workspace 内路径；包含 `..`、绝对路径或反斜杠的路径会被拒绝。本机
+  BYOA daemon 上报相对路径、大小、sha256 和脱敏 preview；Agent Service sandbox 还会在
+  终态前把完整文件上传到 Course Service 的受保护存储。
+- 每个 run 在独立 workspace 内执行并有超时上限；runtime 进程在取消/超时后会被终止
+  （SIGTERM → SIGKILL）。
+- `course logout` 只删除本机凭据；要让服务端立即吊销该 daemon，请在前端 daemon 列表执行
+  revoke。
+- 本包 production 依赖为零，发布 tarball 只包含 `dist/`、`README.md`、`package.json`、
+  `LICENSE`（CI 发布前强制校验）。
+
+## 发布
+
+在 GitHub Actions 中手动运行 `Publish Course Daemon`。`version` 留空时，CI 读取 npm 的
+`latest` 版本并自动增加 patch；包尚不存在时首次发布为 `0.0.1`。只有需要指定
+major、minor 或 prerelease 时才填写精确 SemVer（例如 `1.0.0` 或 `1.1.0-rc.1`）。
+
+所有正式版发布到 npm dist-tag `latest`，prerelease 发布到 `next`。CI 会串行化发布并在
+上传前确认目标版本尚不存在，避免并发任务重复发布同一个版本。

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

@@ -0,0 +1,18 @@
+import type { CourseRuntimeProfile, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
+/** Run-scoped client used only inside an Agent Service sandbox. */
+export declare class AgentServiceRunClient {
+    private readonly baseUrl;
+    private readonly agentRunId;
+    private readonly runToken;
+    private readonly workerId;
+    constructor(baseUrl: string, agentRunId: string, runToken: string, workerId: string);
+    private url;
+    private request;
+    getRun(): Promise<RunStartPayload>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord>;
+    uploadFileContent(agentRunId: string, fileId: string, absPath: string, mimeType?: string): Promise<RunFileRecord>;
+    getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
+    heartbeat(): Promise<void>;
+    private assertRunId;
+}

package/dist/agent-service-client.js

@@ -0,0 +1,108 @@
+import { CourseClientError } from "./course-client.js";
+import { readFile } from "node:fs/promises";
+import { assertNoInjectedCredentials, redactSecretString, redactSecretsDeep, } from "./redaction.js";
+const ERROR_BODY_MAX_CHARS = 500;
+/** Run-scoped client used only inside an Agent Service sandbox. */
+export class AgentServiceRunClient {
+    baseUrl;
+    agentRunId;
+    runToken;
+    workerId;
+    constructor(baseUrl, agentRunId, runToken, workerId) {
+        this.baseUrl = baseUrl;
+        this.agentRunId = agentRunId;
+        this.runToken = runToken;
+        this.workerId = workerId;
+    }
+    url(path) {
+        const base = this.baseUrl.replace(/\/+$/, "");
+        if (base.endsWith("/api/v1") && path.startsWith("/api/v1/")) {
+            return `${base}${path.slice("/api/v1".length)}`;
+        }
+        return `${base}${path}`;
+    }
+    async request(method, path, body) {
+        const response = await fetch(this.url(path), {
+            method,
+            headers: {
+                authorization: `Bearer ${this.runToken}`,
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new CourseClientError(response.status, `${method} ${path} -> ${response.status} ${redactSecretString(text.slice(0, ERROR_BODY_MAX_CHARS))}`);
+        }
+        const raw = await response.text();
+        return (raw ? JSON.parse(raw) : null);
+    }
+    async getRun() {
+        return this.request("GET", `/api/v1/agent-service/runs/${this.agentRunId}`);
+    }
+    async postEvent(agentRunId, event) {
+        this.assertRunId(agentRunId);
+        const sanitized = redactSecretsDeep(event, 8, [this.runToken]);
+        await this.request("POST", `/api/v1/agent-service/runs/${agentRunId}/events`, sanitized);
+    }
+    async postFile(agentRunId, file) {
+        this.assertRunId(agentRunId);
+        const sanitized = redactSecretsDeep(file, 8, [this.runToken]);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            try {
+                return await this.request("POST", `/api/v1/agent-service/runs/${agentRunId}/files`, sanitized);
+            }
+            catch (err) {
+                const retryable = !(err instanceof CourseClientError) || err.status === 429 || err.status >= 500;
+                if (!retryable || attempt === 2)
+                    throw err;
+                await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+            }
+        }
+        throw new Error("unreachable");
+    }
+    async uploadFileContent(agentRunId, fileId, absPath, mimeType) {
+        this.assertRunId(agentRunId);
+        const data = await readFile(absPath);
+        assertNoInjectedCredentials(data, [this.runToken]);
+        const path = `/api/v1/agent-service/runs/${agentRunId}/files/${fileId}/content`;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            let response;
+            try {
+                response = await fetch(this.url(path), {
+                    method: "PUT",
+                    headers: {
+                        authorization: `Bearer ${this.runToken}`,
+                        "content-type": mimeType ?? "application/octet-stream",
+                    },
+                    body: data,
+                });
+            }
+            catch (err) {
+                if (attempt === 2)
+                    throw err;
+                await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+                continue;
+            }
+            if (response.ok)
+                return (await response.json());
+            const text = await response.text().catch(() => "");
+            const error = new CourseClientError(response.status, `PUT ${path} -> ${response.status} ${redactSecretString(text.slice(0, ERROR_BODY_MAX_CHARS))}`);
+            if (attempt === 2 || (response.status !== 429 && response.status < 500))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
+        }
+        throw new Error("unreachable");
+    }
+    async getRunRuntimeProfile(agentRunId) {
+        this.assertRunId(agentRunId);
+        return this.request("GET", `/api/v1/agent-service/runs/${agentRunId}/runtime-profile`);
+    }
+    async heartbeat() {
+        await this.request("POST", `/api/v1/agent-service/runs/${this.agentRunId}/heartbeat`, { worker_id: this.workerId });
+    }
+    assertRunId(value) {
+        if (value !== this.agentRunId)
+            throw new Error("Agent Service run client cannot cross runs");
+    }
+}

package/dist/auth-store.d.ts

@@ -0,0 +1,16 @@
+import type { DaemonAuth } from "./types.js";
+/**
+ * 本地身份与状态目录（spec §5）。
+ * 可用 BOTLEARN_DAEMON_HOME 覆盖根目录（测试 / 多实例）。
+ */
+export declare function daemonHome(): string;
+export declare function ensureDaemonHome(): string;
+export declare function authFilePath(): string;
+export declare function writeAuth(auth: DaemonAuth): void;
+export declare function readAuth(): DaemonAuth | null;
+export declare function clearAuth(): boolean;
+/**
+ * 稳定的本机指纹：首次生成 randomUUID 并持久化到 <home>/machine-id（0600），
+ * 之后跨进程 / 跨重启保持不变，供 login 上报。
+ */
+export declare function machineFingerprint(): string;

package/dist/auth-store.js

@@ -0,0 +1,106 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomBytes, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+/**
+ * 本地身份与状态目录（spec §5）。
+ * 可用 BOTLEARN_DAEMON_HOME 覆盖根目录（测试 / 多实例）。
+ */
+export function daemonHome() {
+    const override = process.env.BOTLEARN_DAEMON_HOME;
+    if (override && override.trim())
+        return override;
+    return path.join(homedir(), ".botlearn-course", "daemon");
+}
+export function ensureDaemonHome() {
+    const home = daemonHome();
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    // recursive mkdir 只对新建目录生效 mode，已存在目录需 best-effort 收紧。
+    try {
+        chmodSync(home, 0o700);
+    }
+    catch {
+        // Windows 等不支持 chmod 时忽略。
+    }
+    return home;
+}
+export function authFilePath() {
+    return path.join(daemonHome(), "auth.json");
+}
+// 原子写：先写同目录 tmp 文件（0600）再 rename，读方永远看不到半写状态。
+function writeFileAtomic(file, content) {
+    const tmp = `${file}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+    try {
+        writeFileSync(tmp, content, { encoding: "utf8", mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // tmp 可能尚未创建。
+        }
+        throw err;
+    }
+    // writeFileSync 的 mode 受 umask 影响之外还可能被目标文件旧权限覆盖（rename 保留 tmp 权限，
+    // 但 Windows 无 chmod），这里再收紧一次。
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows 等不支持 chmod 时忽略。
+    }
+}
+export function writeAuth(auth) {
+    ensureDaemonHome();
+    writeFileAtomic(authFilePath(), JSON.stringify(auth, null, 2));
+}
+export function readAuth() {
+    const file = authFilePath();
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        return parsed;
+    }
+    catch {
+        // 损坏的 auth.json 视同未登录，由 CLI 引导重新 login。
+        return null;
+    }
+}
+export function clearAuth() {
+    const file = authFilePath();
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 稳定的本机指纹：首次生成 randomUUID 并持久化到 <home>/machine-id（0600），
+ * 之后跨进程 / 跨重启保持不变，供 login 上报。
+ */
+export function machineFingerprint() {
+    ensureDaemonHome();
+    const file = path.join(daemonHome(), "machine-id");
+    if (existsSync(file)) {
+        try {
+            const value = readFileSync(file, "utf8").trim();
+            if (value)
+                return value;
+        }
+        catch {
+            // 读失败则重新生成。
+        }
+    }
+    const id = randomUUID();
+    writeFileAtomic(file, `${id}\n`);
+    return id;
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { type Logger } from "./log.js";
+import type { RunStartPayload } from "./types.js";
+/** Keep the run-scoped Course credential out of runtime subprocess environments. */
+export declare function clearAgentServiceControlEnv(env?: NodeJS.ProcessEnv): void;
+export interface CliArgs {
+    positional: string[];
+    flags: Record<string, string | boolean>;
+}
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export type PollLoopExit = "stopped" | "once" | "auth_failure";
+export interface PollLoopDeps {
+    claimNextRun(): Promise<RunStartPayload | null>;
+    /** dispatch 的 Promise 由调用方保证不 reject（RunDispatcher 语义）。 */
+    dispatch(payload: RunStartPayload): Promise<void>;
+    isStopping(): boolean;
+    pollIntervalMs: number;
+    once?: boolean;
+    maxBackoffMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: Logger;
+}
+export declare function runPollLoop(deps: PollLoopDeps): Promise<PollLoopExit>;
+export declare function runCli(argv: string[]): Promise<number>;