@botlearn-course/daemon 0.0.1 → 0.0.3

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

@@ -0,0 +1,28 @@
+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 interface SandboxFrame {
+    schema_version: typeof AGENT_SERVICE_WS_SCHEMA;
+    type: SandboxFrameType;
+    frame_id: string;
+    session_id: string;
+    session_generation: number;
+    connection_epoch: number;
+    seq: number;
+    sent_at: string;
+    agent_run_id: string | null;
+    worker_attempt: number | 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;
+    connectionEpoch: number;
+    seq: number;
+    payload?: Record<string, unknown>;
+    agentRunId?: string;
+    workerAttempt?: number;
+    frameId?: string;
+}): SandboxFrame;

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

@@ -0,0 +1,128 @@
+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";
+const FRAME_TYPES = new Set([
+    "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",
+]);
+const TURN_TYPES = new Set([
+    "turn.start",
+    "turn.cancel",
+    "event.ack",
+    "turn.file.upload_grant",
+    "turn.event",
+    "turn.file.prepare",
+    "turn.file.committed",
+]);
+const FRAME_KEYS = new Set([
+    "schema_version",
+    "type",
+    "frame_id",
+    "session_id",
+    "session_generation",
+    "connection_epoch",
+    "seq",
+    "sent_at",
+    "agent_run_id",
+    "worker_attempt",
+    "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;
+function positiveInteger(value, label) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+    return value;
+}
+export function parseSandboxFrame(raw, maxBytes = 262_144) {
+    if (Buffer.byteLength(raw, "utf8") > maxBytes)
+        throw new Error("frame exceeds size limit");
+    const decoded = JSON.parse(raw);
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+        throw new Error("frame must be an object");
+    }
+    const value = decoded;
+    for (const key of Object.keys(value)) {
+        if (!FRAME_KEYS.has(key))
+            throw new Error(`unknown sandbox WebSocket frame field: ${key}`);
+    }
+    if (value.schema_version !== AGENT_SERVICE_WS_SCHEMA) {
+        throw new Error("unsupported sandbox WebSocket schema");
+    }
+    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 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`);
+    }
+    if (!TURN_TYPES.has(type) && (agentRunId !== null || workerAttempt !== null)) {
+        throw new Error(`${type} cannot carry turn fencing 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"]) {
+        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 (agentRunId !== null && !UUID_PATTERN.test(agentRunId)) {
+        throw new Error("agent_run_id must be a UUID");
+    }
+    if (Number.isNaN(Date.parse(value.sent_at)))
+        throw new Error("sent_at is invalid");
+    return {
+        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"),
+        connection_epoch: positiveInteger(value.connection_epoch, "connection_epoch"),
+        seq: positiveInteger(value.seq, "seq"),
+        sent_at: value.sent_at,
+        agent_run_id: agentRunId,
+        worker_attempt: workerAttempt,
+        payload: value.payload,
+    };
+}
+export function createSandboxFrame(input) {
+    const frame = {
+        schema_version: AGENT_SERVICE_WS_SCHEMA,
+        type: input.type,
+        frame_id: input.frameId ?? `frm_${randomUUID().replaceAll("-", "")}`,
+        session_id: input.sessionId,
+        session_generation: input.sessionGeneration,
+        connection_epoch: input.connectionEpoch,
+        seq: input.seq,
+        sent_at: new Date().toISOString(),
+        agent_run_id: input.agentRunId ?? null,
+        worker_attempt: input.workerAttempt ?? null,
+        payload: input.payload ?? {},
+    };
+    return parseSandboxFrame(JSON.stringify(frame));
+}

package/dist/cli.d.ts

@@ -1,8 +1,7 @@
 #!/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 { clearAgentServiceControlEnv } from "./runtime-env.js";
 export interface CliArgs {
     positional: string[];
     flags: Record<string, string | boolean>;

package/dist/cli.js

@@ -5,14 +5,27 @@ 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 { CourseClient, isAuthFailure, loginCourseDaemon } from "./course-client.js";
 import { runCourseDoctor } from "./doctor.js";
 import { log } from "./log.js";
 import { augmentProcessPath } from "./path-env.js";
 import { redactSecretString } from "./redaction.js";
 import { RunDispatcher } from "./run-dispatcher.js";
+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:
@@ -21,6 +34,7 @@ Usage:
   botlearn-course-daemon course logout
   botlearn-course-daemon course doctor
   botlearn-course-daemon agent-service run
+  botlearn-course-daemon agent-service session
   botlearn-course-daemon --help | --version
 
 Commands:
@@ -41,22 +55,15 @@ Agent Service sandbox environment:
   BOTLEARN_COURSE_API_URL
   BOTLEARN_AGENT_SERVICE_RUN_ID
   BOTLEARN_AGENT_SERVICE_RUN_TOKEN
-  BOTLEARN_AGENT_SERVICE_WORKER_ID`;
+  BOTLEARN_AGENT_SERVICE_WORKER_ID
+  BOTLEARN_AGENT_SERVICE_WS_URL
+  BOTLEARN_AGENT_SERVICE_RUNTIME_SESSION_ID
+  BOTLEARN_AGENT_SERVICE_SESSION_TOKEN`;
 // ---------------------------------------------------------------
 // flag parser（极简：--k v / --k=v / 布尔开关）
 // ---------------------------------------------------------------
-const BOOLEAN_FLAGS = new Set(["once", "help", "version"]);
-const AGENT_SERVICE_CONTROL_ENV_KEYS = [
-    "BOTLEARN_COURSE_API_URL",
-    "BOTLEARN_AGENT_SERVICE_RUN_ID",
-    "BOTLEARN_AGENT_SERVICE_RUN_TOKEN",
-    "BOTLEARN_AGENT_SERVICE_WORKER_ID",
-];
-/** Keep the run-scoped Course credential out of runtime subprocess environments. */
-export function clearAgentServiceControlEnv(env = process.env) {
-    for (const key of AGENT_SERVICE_CONTROL_ENV_KEYS)
-        delete env[key];
-}
+const BOOLEAN_FLAGS = new Set(["once", "help", "version", "bootstrap-stdin"]);
+export { clearAgentServiceControlEnv } from "./runtime-env.js";
 export function parseCliArgs(argv) {
     const positional = [];
     const flags = {};
@@ -297,6 +304,97 @@ async function cmdAgentServiceRun() {
     }
     return 0;
 }
+async function readSessionBootstrapFromStdin() {
+    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");
+        }
+        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");
+        }
+        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;
+            }
+        }
+        const wsUrl = parsed.wsUrl;
+        const runtimeSessionId = parsed.runtimeSessionId;
+        const sessionToken = parsed.sessionToken;
+        if (typeof wsUrl !== "string" ||
+            !/^wss?:\/\//.test(wsUrl) ||
+            typeof runtimeSessionId !== "string" ||
+            !runtimeSessionId ||
+            typeof sessionToken !== "string" ||
+            !sessionToken) {
+            throw new Error("Agent Service session bootstrap is incomplete");
+        }
+        return {
+            wsUrl,
+            runtimeSessionId,
+            sessionToken,
+            ...(Object.keys(runtimeEnv).length > 0 ? { runtimeEnv } : {}),
+        };
+    }
+    finally {
+        raw.fill(0);
+        for (const chunk of chunks)
+            chunk.fill(0);
+    }
+}
+async function cmdAgentServiceSession(args) {
+    const bootstrap = args.flags["bootstrap-stdin"] === true
+        ? await readSessionBootstrapFromStdin()
+        : {
+            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,
+        };
+    const { wsUrl, runtimeSessionId, sessionToken } = bootstrap;
+    if (!wsUrl || !runtimeSessionId || !sessionToken) {
+        console.error("Agent Service sandbox session environment is incomplete");
+        return 1;
+    }
+    augmentProcessPath();
+    const runtimes = new Map();
+    for (const mod of RUNTIME_MODULES) {
+        if (mod.hidden && !fakeRuntimeEnabled())
+            continue;
+        runtimes.set(mod.id, mod.create());
+    }
+    const client = new AgentServiceSessionClient({
+        wsUrl,
+        sessionId: runtimeSessionId,
+        sessionToken,
+        ...(bootstrap.runtimeEnv ? { runtimeEnv: bootstrap.runtimeEnv } : {}),
+        runtimes,
+        daemonVersion: pkg.version,
+    });
+    clearAgentServiceControlEnv();
+    await client.run();
+    return 0;
+}
 // ---------------------------------------------------------------
 // 入口
 // ---------------------------------------------------------------
@@ -329,6 +427,9 @@ export async function runCli(argv) {
     if (command === "agent-service" && sub === "run") {
         return cmdAgentServiceRun();
     }
+    if (command === "agent-service" && sub === "session") {
+        return cmdAgentServiceSession(args);
+    }
     console.error(HELP);
     return 1;
 }

package/dist/course-client.js

@@ -1,4 +1,4 @@
-import { redactSecretString } from "./redaction.js";
+import { redactSecretString, redactSecretsDeep } from "./redaction.js";
 export class CourseClientError extends Error {
     status;
     constructor(status, message) {
@@ -100,7 +100,9 @@ export class CourseClient {
         return this.request("GET", "/api/v1/daemon/runs/next");
     }
     async postEvent(agentRunId, event) {
-        await this.request("POST", `/api/v1/daemon/runs/${agentRunId}/events`, 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);
     }
     async postFile(agentRunId, file) {
         return this.request("POST", `/api/v1/daemon/runs/${agentRunId}/files`, file);

package/dist/index.d.ts

@@ -6,6 +6,8 @@ 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-ws-protocol.js";
 export * from "./run-dispatcher.js";
 export * from "./run-queue.js";
 export * from "./workspace.js";
@@ -15,5 +17,7 @@ export * from "./doctor.js";
 export * from "./log.js";
 export * from "./redaction.js";
 export * from "./runtime-profile.js";
+export * from "./runtime-env.js";
+export * from "./mcp/report-progress.js";
 export * from "./runtimes/index.js";
 export * from "./runtimes/engine.js";

package/dist/index.js

@@ -6,6 +6,8 @@ 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-ws-protocol.js";
 export * from "./run-dispatcher.js";
 export * from "./run-queue.js";
 export * from "./workspace.js";
@@ -15,5 +17,7 @@ export * from "./doctor.js";
 export * from "./log.js";
 export * from "./redaction.js";
 export * from "./runtime-profile.js";
+export * from "./runtime-env.js";
+export * from "./mcp/report-progress.js";
 export * from "./runtimes/index.js";
 export * from "./runtimes/engine.js";

package/dist/mcp/report-progress-server.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+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;
+    };
+}
+/** Pure JSON-RPC request handler used by both stdio and deterministic unit tests. */
+export declare function handleReportProgressRequest(request: JsonRpcRequest): JsonRpcResponse | null;
+export declare function runReportProgressStdioServer(): void;
+export {};

package/dist/mcp/report-progress-server.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { normalizeProgressReport, ProgressValidationError, REPORT_PROGRESS_INPUT_SCHEMA, } from "./report-progress.js";
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+const TOOL = {
+    name: "report_progress",
+    description: "Report a concise, learner-visible execution phase update. This does not complete course progress.",
+    inputSchema: REPORT_PROGRESS_INPUT_SCHEMA,
+};
+function responseId(value) {
+    return typeof value === "string" || typeof value === "number" || value === null ? value : null;
+}
+function toolError(code, message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    schemaVersion: "tool-result/0.1",
+                    ok: false,
+                    code,
+                    error: { message },
+                    evidence: [],
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+/** Pure JSON-RPC request handler used by both stdio and deterministic unit tests. */
+export function handleReportProgressRequest(request) {
+    if (request.id === undefined)
+        return null;
+    const id = responseId(request.id);
+    if (request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+        return { jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } };
+    }
+    if (request.method === "initialize") {
+        const requested = request.params && typeof request.params === "object"
+            ? request.params.protocolVersion
+            : undefined;
+        return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+                protocolVersion: typeof requested === "string" && requested.length > 0
+                    ? requested
+                    : DEFAULT_PROTOCOL_VERSION,
+                capabilities: { tools: {} },
+                serverInfo: { name: "botlearn-report-progress", version: "0.1.0" },
+            },
+        };
+    }
+    if (request.method === "tools/list") {
+        return { jsonrpc: "2.0", id, result: { tools: [TOOL] } };
+    }
+    if (request.method === "tools/call") {
+        const params = request.params && typeof request.params === "object"
+            ? request.params
+            : {};
+        if (params.name !== TOOL.name) {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: toolError("unknown_tool", "Unknown tool"),
+            };
+        }
+        try {
+            const progress = normalizeProgressReport(params.arguments);
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                schemaVersion: "tool-result/0.1",
+                                ok: true,
+                                code: "progress_reported",
+                                data: progress,
+                                evidence: [],
+                            }),
+                        },
+                    ],
+                    isError: false,
+                },
+            };
+        }
+        catch (error) {
+            if (!(error instanceof ProgressValidationError))
+                throw error;
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: toolError("invalid_progress", error.message),
+            };
+        }
+    }
+    return { jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } };
+}
+export function runReportProgressStdioServer() {
+    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let response;
+        try {
+            response = handleReportProgressRequest(JSON.parse(line));
+        }
+        catch {
+            response = {
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32700, message: "Parse error" },
+            };
+        }
+        if (response)
+            process.stdout.write(`${JSON.stringify(response)}\n`);
+    });
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule())
+    runReportProgressStdioServer();

package/dist/mcp/report-progress.d.ts

@@ -0,0 +1,29 @@
+export declare const PROGRESS_STATUSES: readonly ["in_progress", "completed"];
+export type ProgressStatus = (typeof PROGRESS_STATUSES)[number];
+export interface ProgressReport {
+    summary: string;
+    status: ProgressStatus;
+}
+export declare const MAX_PROGRESS_EVENTS_PER_ATTEMPT = 64;
+export declare const REPORT_PROGRESS_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["summary", "status"];
+    readonly properties: {
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 240;
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["in_progress", "completed"];
+        };
+    };
+};
+export declare class ProgressValidationError extends Error {
+    constructor(message: string);
+}
+/** Strict shared normalizer: Unicode trim, exact fields/types, then code-point length. */
+export declare function normalizeProgressReport(value: unknown): ProgressReport;
+export declare function tryNormalizeProgressReport(value: unknown): ProgressReport | null;

package/dist/mcp/report-progress.js

@@ -0,0 +1,60 @@
+export const PROGRESS_STATUSES = ["in_progress", "completed"];
+export const MAX_PROGRESS_EVENTS_PER_ATTEMPT = 64;
+export const REPORT_PROGRESS_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["summary", "status"],
+    properties: {
+        summary: {
+            type: "string",
+            minLength: 1,
+            maxLength: 240,
+        },
+        status: {
+            type: "string",
+            enum: PROGRESS_STATUSES,
+        },
+    },
+};
+// Unicode White_Space plus BOM/ZWNBSP, matching the platform's user-facing trim behavior.
+const UNICODE_WHITESPACE_AT_EDGES = /^(?:\p{White_Space}|\uFEFF)+|(?:\p{White_Space}|\uFEFF)+$/gu;
+const MAX_PROGRESS_CODE_POINTS = 240;
+export class ProgressValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProgressValidationError";
+    }
+}
+/** Strict shared normalizer: Unicode trim, exact fields/types, then code-point length. */
+export function normalizeProgressReport(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ProgressValidationError("progress arguments must be an object");
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.length !== 2 || keys[0] !== "status" || keys[1] !== "summary") {
+        throw new ProgressValidationError("progress arguments must contain only summary and status");
+    }
+    if (typeof record.summary !== "string") {
+        throw new ProgressValidationError("progress summary must be a string");
+    }
+    if (record.status !== "in_progress" && record.status !== "completed") {
+        throw new ProgressValidationError("progress status is invalid");
+    }
+    const summary = record.summary.replace(UNICODE_WHITESPACE_AT_EDGES, "");
+    const length = Array.from(summary).length;
+    if (length < 1 || length > MAX_PROGRESS_CODE_POINTS) {
+        throw new ProgressValidationError("progress summary must contain 1 to 240 Unicode code points");
+    }
+    return { summary, status: record.status };
+}
+export function tryNormalizeProgressReport(value) {
+    try {
+        return normalizeProgressReport(value);
+    }
+    catch (error) {
+        if (error instanceof ProgressValidationError)
+            return null;
+        throw error;
+    }
+}

package/dist/run-dispatcher.d.ts

@@ -6,6 +6,18 @@ export interface RunDispatcherOptions {
     log?: Logger;
     scanLimits?: ScanLimits;
     now?: () => number;
+    persistentSession?: PersistentSessionExecution;
+}
+export interface PreparedPersistentTurn {
+    workspaceDir: string;
+    transcriptFile: string;
+    nativeSessionId: string | null;
+    contextRevision: number;
+    runtimeEnv?: NodeJS.ProcessEnv;
+}
+export interface PersistentSessionExecution {
+    prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
+    persistNativeSession(sessionId: string): void;
 }
 export interface RunReportingClient {
     postEvent(agentRunId: string, event: RunEvent): Promise<void>;
@@ -27,10 +39,13 @@ export declare class RunDispatcher {
     private readonly runtimes;
     private readonly queue;
     private readonly inflight;
+    private readonly scheduledRunIds;
+    private readonly pendingCancellations;
     private readonly defaultRuntimeId;
     private readonly log;
     private readonly scanLimits?;
     private readonly now;
+    private readonly persistentSession?;
     constructor(client: RunReportingClient, runtimes: Map<string, CourseRuntime>, opts?: RunDispatcherOptions);
     /** 排队执行一个 run。返回的 Promise 不 reject（失败已归一化回报为 run.failed）。 */
     dispatch(payload: RunStartPayload): Promise<void>;