@botlearn-course/daemon 0.0.7 → 0.0.9

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

@@ -1,28 +1,36 @@
-export declare const AGENT_SERVICE_WS_SCHEMA: "botlearn-agent-sandbox-ws/0.1";
-export declare const AGENT_SERVICE_WS_SUBPROTOCOL: "botlearn-agent-sandbox.v1";
-export type SandboxFrameType = "session.hello" | "session.sync" | "turn.start" | "turn.cancel" | "session.drain" | "session.shutdown" | "event.ack" | "turn.file.upload_grant" | "auth.rotate" | "ping" | "session.ready" | "session.heartbeat" | "command.ack" | "turn.event" | "turn.file.prepare" | "turn.file.committed" | "session.drained" | "pong" | "protocol.error";
+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" | "turn.file.upload_grant" | "auth.rotate" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.closed" | "turn.event" | "turn.file.prepare" | "turn.file.committed" | "sandbox.drained" | "pong" | "protocol.error";
+export declare class UnsupportedSandboxProtocolError extends Error {
+    readonly schemaVersion: unknown;
+    constructor(schemaVersion: unknown);
+}
 export interface SandboxFrame {
     schema_version: typeof AGENT_SERVICE_WS_SCHEMA;
     type: SandboxFrameType;
     frame_id: string;
-    session_id: string;
-    session_generation: number;
+    sandbox_id: string;
+    sandbox_generation: number;
     connection_epoch: number;
     seq: number;
     sent_at: string;
+    runtime_session_id: string | null;
     agent_run_id: string | null;
     worker_attempt: number | null;
+    activation_id: string | null;
     payload: Record<string, unknown>;
 }
 export declare function parseSandboxFrame(raw: string, maxBytes?: number): SandboxFrame;
 export declare function createSandboxFrame(input: {
     type: SandboxFrameType;
-    sessionId: string;
-    sessionGeneration: number;
+    sandboxId: string;
+    sandboxGeneration: number;
     connectionEpoch: number;
     seq: number;
     payload?: Record<string, unknown>;
+    runtimeSessionId?: string;
     agentRunId?: string;
     workerAttempt?: number;
+    activationId?: string;
     frameId?: string;
 }): SandboxFrame;

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

@@ -1,27 +1,41 @@
 import { randomUUID } from "node:crypto";
-export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.1";
-export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v1";
+export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.2";
+export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v2";
 const FRAME_TYPES = new Set([
-    "session.hello",
-    "session.sync",
+    "sandbox.hello",
+    "sandbox.sync",
+    "session.open",
+    "session.activate",
     "turn.start",
     "turn.cancel",
-    "session.drain",
-    "session.shutdown",
+    "session.close",
+    "sandbox.drain",
+    "sandbox.shutdown",
     "event.ack",
     "turn.file.upload_grant",
     "auth.rotate",
     "ping",
-    "session.ready",
-    "session.heartbeat",
+    "sandbox.ready",
+    "sandbox.heartbeat",
     "command.ack",
+    "session.opened",
+    "session.closed",
     "turn.event",
     "turn.file.prepare",
     "turn.file.committed",
-    "session.drained",
+    "sandbox.drained",
     "pong",
     "protocol.error",
 ]);
+/** SESSION 帧：必须带 runtime_session_id；禁止 run/attempt。session.activate 额外必须带 activation_id。 */
+const SESSION_TYPES = new Set([
+    "session.open",
+    "session.activate",
+    "session.close",
+    "session.opened",
+    "session.closed",
+]);
+/** TURN 帧：必须带 runtime_session_id + agent_run_id + worker_attempt + activation_id 四元组。 */
 const TURN_TYPES = new Set([
     "turn.start",
     "turn.cancel",
@@ -35,22 +49,39 @@ const FRAME_KEYS = new Set([
     "schema_version",
     "type",
     "frame_id",
-    "session_id",
-    "session_generation",
+    "sandbox_id",
+    "sandbox_generation",
     "connection_epoch",
     "seq",
     "sent_at",
+    "runtime_session_id",
     "agent_run_id",
     "worker_attempt",
+    "activation_id",
     "payload",
 ]);
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export class UnsupportedSandboxProtocolError extends Error {
+    schemaVersion;
+    constructor(schemaVersion) {
+        super("unsupported sandbox WebSocket schema");
+        this.schemaVersion = schemaVersion;
+        this.name = "UnsupportedSandboxProtocolError";
+    }
+}
 function positiveInteger(value, label) {
     if (!Number.isInteger(value) || value < 1) {
         throw new Error(`${label} must be a positive integer`);
     }
     return value;
 }
+function nullableString(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string or null`);
+    return value;
+}
 export function parseSandboxFrame(raw, maxBytes = 262_144) {
     if (Buffer.byteLength(raw, "utf8") > maxBytes)
         throw new Error("frame exceeds size limit");
@@ -64,33 +95,60 @@ export function parseSandboxFrame(raw, maxBytes = 262_144) {
             throw new Error(`unknown sandbox WebSocket frame field: ${key}`);
     }
     if (value.schema_version !== AGENT_SERVICE_WS_SCHEMA) {
-        throw new Error("unsupported sandbox WebSocket schema");
+        throw new UnsupportedSandboxProtocolError(value.schema_version);
     }
     if (typeof value.type !== "string" || !FRAME_TYPES.has(value.type)) {
         throw new Error("unknown sandbox WebSocket frame type");
     }
     const type = value.type;
-    const agentRunId = typeof value.agent_run_id === "string" ? value.agent_run_id : null;
+    const runtimeSessionId = nullableString(value.runtime_session_id, "runtime_session_id");
+    const agentRunId = nullableString(value.agent_run_id, "agent_run_id");
     const workerAttempt = value.worker_attempt == null
         ? null
         : positiveInteger(value.worker_attempt, "worker_attempt");
-    if (TURN_TYPES.has(type) && (!agentRunId || workerAttempt === null)) {
-        throw new Error(`${type} requires turn fencing fields`);
+    const activationId = nullableString(value.activation_id, "activation_id");
+    if (activationId !== null && (activationId.length < 1 || activationId.length > 120)) {
+        throw new Error("activation_id length is invalid");
+    }
+    if (TURN_TYPES.has(type)) {
+        if (!runtimeSessionId || !agentRunId || workerAttempt === null || !activationId) {
+            throw new Error(`${type} requires the full turn scope`);
+        }
     }
-    if (!TURN_TYPES.has(type) && (agentRunId !== null || workerAttempt !== null)) {
-        throw new Error(`${type} cannot carry turn fencing fields`);
+    else if (SESSION_TYPES.has(type)) {
+        if (!runtimeSessionId)
+            throw new Error(`${type} requires runtime_session_id`);
+        if (agentRunId !== null || workerAttempt !== null) {
+            throw new Error(`${type} cannot carry turn fencing fields`);
+        }
+        if (type === "session.activate") {
+            if (!activationId)
+                throw new Error("session.activate requires activation_id");
+        }
+        else if (activationId !== null) {
+            throw new Error(`${type} cannot carry activation_id`);
+        }
+    }
+    else if (runtimeSessionId !== null ||
+        agentRunId !== null ||
+        workerAttempt !== null ||
+        activationId !== null) {
+        throw new Error(`${type} cannot carry session or turn scope fields`);
     }
     if (!value.payload || typeof value.payload !== "object" || Array.isArray(value.payload)) {
         throw new Error("frame payload must be an object");
     }
-    for (const key of ["frame_id", "session_id", "sent_at"]) {
+    for (const key of ["frame_id", "sandbox_id", "sent_at"]) {
         if (typeof value[key] !== "string" || !value[key])
             throw new Error(`${key} is required`);
     }
     if (value.frame_id.length > 120)
         throw new Error("frame_id is too long");
-    if (!UUID_PATTERN.test(value.session_id))
-        throw new Error("session_id must be a UUID");
+    if (!UUID_PATTERN.test(value.sandbox_id))
+        throw new Error("sandbox_id must be a UUID");
+    if (runtimeSessionId !== null && !UUID_PATTERN.test(runtimeSessionId)) {
+        throw new Error("runtime_session_id must be a UUID");
+    }
     if (agentRunId !== null && !UUID_PATTERN.test(agentRunId)) {
         throw new Error("agent_run_id must be a UUID");
     }
@@ -100,13 +158,15 @@ export function parseSandboxFrame(raw, maxBytes = 262_144) {
         schema_version: AGENT_SERVICE_WS_SCHEMA,
         type,
         frame_id: value.frame_id,
-        session_id: value.session_id,
-        session_generation: positiveInteger(value.session_generation, "session_generation"),
+        sandbox_id: value.sandbox_id,
+        sandbox_generation: positiveInteger(value.sandbox_generation, "sandbox_generation"),
         connection_epoch: positiveInteger(value.connection_epoch, "connection_epoch"),
         seq: positiveInteger(value.seq, "seq"),
         sent_at: value.sent_at,
+        runtime_session_id: runtimeSessionId,
         agent_run_id: agentRunId,
         worker_attempt: workerAttempt,
+        activation_id: activationId,
         payload: value.payload,
     };
 }
@@ -115,13 +175,15 @@ export function createSandboxFrame(input) {
         schema_version: AGENT_SERVICE_WS_SCHEMA,
         type: input.type,
         frame_id: input.frameId ?? `frm_${randomUUID().replaceAll("-", "")}`,
-        session_id: input.sessionId,
-        session_generation: input.sessionGeneration,
+        sandbox_id: input.sandboxId,
+        sandbox_generation: input.sandboxGeneration,
         connection_epoch: input.connectionEpoch,
         seq: input.seq,
         sent_at: new Date().toISOString(),
+        runtime_session_id: input.runtimeSessionId ?? null,
         agent_run_id: input.agentRunId ?? null,
         worker_attempt: input.workerAttempt ?? null,
+        activation_id: input.activationId ?? null,
         payload: input.payload ?? {},
     };
     return parseSandboxFrame(JSON.stringify(frame));

package/dist/cli.js

@@ -5,7 +5,7 @@ import { hostname } from "node:os";
 import { fileURLToPath } from "node:url";
 import { authFilePath, clearAuth, machineFingerprint, readAuth, writeAuth } from "./auth-store.js";
 import { AgentServiceRunClient } from "./agent-service-client.js";
-import { AgentServiceSessionClient } from "./agent-service-session.js";
+import { AgentServiceSandboxClient } from "./agent-service-sandbox.js";
 import { CourseClient, isAuthFailure, loginCourseDaemon } from "./course-client.js";
 import { runCourseDoctor } from "./doctor.js";
 import { log } from "./log.js";
@@ -16,16 +16,6 @@ import { clearAgentServiceControlEnv } from "./runtime-env.js";
 import { RUNTIME_MODULES, detectAvailableRuntimeIds, fakeRuntimeEnabled, } from "./runtimes/index.js";
 const pkg = createRequire(import.meta.url)("../package.json");
 const SESSION_BOOTSTRAP_MAX_BYTES = 64 * 1024;
-const SESSION_RUNTIME_ENV_KEYS = new Set([
-    "OPENAI_API_KEY",
-    "OPENAI_BASE_URL",
-    "ANTHROPIC_API_KEY",
-    "ANTHROPIC_BASE_URL",
-    "DEEPSEEK_API_KEY",
-    "DEEPSEEK_BASE_URL",
-    "GEMINI_API_KEY",
-    "GEMINI_BASE_URL",
-]);
 const HELP = `botlearn-course-daemon ${pkg.version} — run BotLearn Course tasks on your own machine (BYOA)
 
 Usage:
@@ -57,8 +47,8 @@ Agent Service sandbox environment:
   BOTLEARN_AGENT_SERVICE_RUN_TOKEN
   BOTLEARN_AGENT_SERVICE_WORKER_ID
   BOTLEARN_AGENT_SERVICE_WS_URL
-  BOTLEARN_AGENT_SERVICE_RUNTIME_SESSION_ID
-  BOTLEARN_AGENT_SERVICE_SESSION_TOKEN`;
+  BOTLEARN_AGENT_SERVICE_SANDBOX_ID
+  BOTLEARN_AGENT_SERVICE_SANDBOX_TOKEN`;
 // ---------------------------------------------------------------
 // flag parser（极简：--k v / --k=v / 布尔开关）
 // ---------------------------------------------------------------
@@ -304,56 +294,41 @@ async function cmdAgentServiceRun() {
     }
     return 0;
 }
-async function readSessionBootstrapFromStdin() {
+async function readSandboxBootstrapFromStdin() {
     const chunks = [];
     let size = 0;
     for await (const chunk of process.stdin) {
         const bytes = Buffer.from(chunk);
         size += bytes.length;
         if (size > SESSION_BOOTSTRAP_MAX_BYTES) {
-            throw new Error("Agent Service session bootstrap exceeds size limit");
+            throw new Error("Agent Service sandbox bootstrap exceeds size limit");
         }
         chunks.push(bytes);
     }
     const raw = Buffer.concat(chunks);
     try {
         const parsed = JSON.parse(raw.toString("utf8"));
-        if (parsed.schemaVersion !== "agent-service-session-bootstrap/0.1") {
-            throw new Error("Agent Service session bootstrap schema is unsupported");
+        if (parsed.schema !== "agent-service-sandbox-bootstrap/0.2") {
+            throw new Error("Agent Service sandbox bootstrap schema is unsupported");
         }
-        const runtimeEnv = {};
         if (parsed.runtimeEnv !== undefined) {
-            if (!parsed.runtimeEnv ||
-                typeof parsed.runtimeEnv !== "object" ||
-                Array.isArray(parsed.runtimeEnv)) {
-                throw new Error("Agent Service session bootstrap runtimeEnv is invalid");
-            }
-            for (const [key, value] of Object.entries(parsed.runtimeEnv)) {
-                if (!SESSION_RUNTIME_ENV_KEYS.has(key) ||
-                    typeof value !== "string" ||
-                    value.length < 1 ||
-                    value.length > 8192) {
-                    throw new Error(`Agent Service session bootstrap runtime env is forbidden: ${key}`);
-                }
-                runtimeEnv[key] = value;
-            }
+            throw new Error("Agent Service sandbox bootstrap runtimeEnv is unsupported; use session.activate");
         }
         const wsUrl = parsed.wsUrl;
-        const runtimeSessionId = parsed.runtimeSessionId;
-        const sessionToken = parsed.sessionToken;
+        const sandboxId = parsed.sandboxId;
+        const sandboxToken = parsed.sandboxToken;
         if (typeof wsUrl !== "string" ||
             !/^wss?:\/\//.test(wsUrl) ||
-            typeof runtimeSessionId !== "string" ||
-            !runtimeSessionId ||
-            typeof sessionToken !== "string" ||
-            !sessionToken) {
-            throw new Error("Agent Service session bootstrap is incomplete");
+            typeof sandboxId !== "string" ||
+            !sandboxId ||
+            typeof sandboxToken !== "string" ||
+            !sandboxToken) {
+            throw new Error("Agent Service sandbox bootstrap is incomplete");
         }
         return {
             wsUrl,
-            runtimeSessionId,
-            sessionToken,
-            ...(Object.keys(runtimeEnv).length > 0 ? { runtimeEnv } : {}),
+            sandboxId,
+            sandboxToken,
         };
     }
     finally {
@@ -364,16 +339,15 @@ async function readSessionBootstrapFromStdin() {
 }
 async function cmdAgentServiceSession(args) {
     const bootstrap = args.flags["bootstrap-stdin"] === true
-        ? await readSessionBootstrapFromStdin()
+        ? await readSandboxBootstrapFromStdin()
         : {
             wsUrl: process.env.BOTLEARN_AGENT_SERVICE_WS_URL,
-            runtimeSessionId: process.env.BOTLEARN_AGENT_SERVICE_RUNTIME_SESSION_ID,
-            sessionToken: process.env.BOTLEARN_AGENT_SERVICE_SESSION_TOKEN,
-            runtimeEnv: undefined,
+            sandboxId: process.env.BOTLEARN_AGENT_SERVICE_SANDBOX_ID,
+            sandboxToken: process.env.BOTLEARN_AGENT_SERVICE_SANDBOX_TOKEN,
         };
-    const { wsUrl, runtimeSessionId, sessionToken } = bootstrap;
-    if (!wsUrl || !runtimeSessionId || !sessionToken) {
-        console.error("Agent Service sandbox session environment is incomplete");
+    const { wsUrl, sandboxId, sandboxToken } = bootstrap;
+    if (!wsUrl || !sandboxId || !sandboxToken) {
+        console.error("Agent Service sandbox environment is incomplete");
         return 1;
     }
     augmentProcessPath();
@@ -383,11 +357,10 @@ async function cmdAgentServiceSession(args) {
             continue;
         runtimes.set(mod.id, mod.create());
     }
-    const client = new AgentServiceSessionClient({
+    const client = new AgentServiceSandboxClient({
         wsUrl,
-        sessionId: runtimeSessionId,
-        sessionToken,
-        ...(bootstrap.runtimeEnv ? { runtimeEnv: bootstrap.runtimeEnv } : {}),
+        sandboxId,
+        sandboxToken,
         runtimes,
         daemonVersion: pkg.version,
     });

package/dist/course-client.js

@@ -43,11 +43,11 @@ export class CourseClient {
     setAccessToken(token) {
         this.accessToken = token;
     }
-    // courseApiUrl 可能是 host 根，也可能已带 /api/v1 —— 去重避免拼出 /api/v1/api/v1。
+    // courseApiUrl 可能是 host 根，也可能已带 /course/v1 —— 去重避免拼出 /course/v1/course/v1。
     url(p) {
         const base = this.baseUrl.replace(/\/+$/, "");
-        if (base.endsWith("/api/v1") && p.startsWith("/api/v1/")) {
-            return `${base}${p.slice("/api/v1".length)}`;
+        if (base.endsWith("/course/v1") && p.startsWith("/course/v1/")) {
+            return `${base}${p.slice("/course/v1".length)}`;
         }
         return `${base}${p}`;
     }
@@ -98,18 +98,18 @@ export class CourseClient {
     }
     /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */
     async claimNextRun() {
-        return this.request("GET", "/api/v1/daemon/runs/next");
+        return this.request("GET", "/course/v1/daemon/runs/next");
     }
     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, event.trace_id);
+        await this.request("POST", `/course/v1/daemon/runs/${agentRunId}/events`, sanitized, event.trace_id);
     }
     async postFile(agentRunId, file) {
-        return this.request("POST", `/api/v1/daemon/runs/${agentRunId}/files`, file);
+        return this.request("POST", `/course/v1/daemon/runs/${agentRunId}/files`, file);
     }
     async getRunRuntimeProfile(agentRunId) {
-        return this.request("GET", `/api/v1/daemon/runs/${agentRunId}/runtime-profile`);
+        return this.request("GET", `/course/v1/daemon/runs/${agentRunId}/runtime-profile`);
     }
 }
 function authFromResponse(baseUrl, raw) {
@@ -131,7 +131,7 @@ function authFromResponse(baseUrl, raw) {
 }
 export async function loginCourseDaemon(opts) {
     const client = new CourseClient(opts.courseApiUrl, "");
-    const raw = await client.fetchJson("POST", "/api/v1/daemon/login", {
+    const raw = await client.fetchJson("POST", "/course/v1/daemon/login", {
         code: opts.code,
         label: opts.label ?? "",
         machine_fingerprint: opts.machineFingerprint,
@@ -141,6 +141,6 @@ export async function loginCourseDaemon(opts) {
 }
 export async function refreshCourseDaemonSession(courseApiUrl, refreshToken) {
     const client = new CourseClient(courseApiUrl, "");
-    const raw = await client.fetchJson("POST", "/api/v1/daemon/session", { refresh_token: refreshToken }, null);
+    const raw = await client.fetchJson("POST", "/course/v1/daemon/session", { refresh_token: refreshToken }, null);
     return authFromResponse(courseApiUrl, raw);
 }

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from "./types.js";
 export * from "./auth-store.js";
 export * from "./course-client.js";
 export * from "./agent-service-client.js";
-export * from "./agent-service-session.js";
+export * from "./agent-service-sandbox.js";
 export * from "./agent-service-ws-protocol.js";
 export * from "./run-dispatcher.js";
 export * from "./run-queue.js";

package/dist/index.js

@@ -6,7 +6,7 @@ export * from "./types.js";
 export * from "./auth-store.js";
 export * from "./course-client.js";
 export * from "./agent-service-client.js";
-export * from "./agent-service-session.js";
+export * from "./agent-service-sandbox.js";
 export * from "./agent-service-ws-protocol.js";
 export * from "./run-dispatcher.js";
 export * from "./run-queue.js";

package/dist/run-dispatcher.d.ts

@@ -18,6 +18,7 @@ export interface PreparedPersistentTurn {
 export interface PersistentSessionExecution {
     prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
     persistNativeSession(sessionId: string): void;
+    finishTurn(payload: RunStartPayload): void;
 }
 export interface RunReportingClient {
     postEvent(agentRunId: string, event: RunEvent): Promise<void>;
@@ -52,6 +53,8 @@ export declare class RunDispatcher {
     cancel(agentRunId: string): boolean;
     cancelAll(): void;
     get activeCount(): number;
+    /** Wait until the selected runs have left both the active and queued sets. */
+    waitForRuns(agentRunIds: Iterable<string>, timeoutMs: number): Promise<boolean>;
     /** 等待所有 run（含排队中的）结束；超时返回 false。 */
     drain(timeoutMs: number): Promise<boolean>;
     private execute;