@botlearn-course/daemon 0.0.14 → 0.0.16

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

@@ -1,4 +1,4 @@
-import type { CourseRuntimeProfile, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
+import type { CourseRuntimeProfile, RunEvent, RunEventReceipt, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
 /** Run-scoped client used only inside an Agent Service sandbox. */
 export declare class AgentServiceRunClient {
     private readonly baseUrl;
@@ -10,7 +10,7 @@ export declare class AgentServiceRunClient {
     private url;
     private request;
     getRun(): Promise<RunStartPayload>;
-    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<RunEventReceipt>;
     postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord>;
     getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
     heartbeat(): Promise<void>;

package/dist/agent-service-client.js

@@ -47,7 +47,18 @@ export class AgentServiceRunClient {
         this.assertRunId(agentRunId);
         this.traceId = event.trace_id ?? this.traceId;
         const sanitized = redactSecretsDeep(event, 8, [this.runToken]);
-        await this.request("POST", `/course/v1/agent-service/runs/${agentRunId}/events`, sanitized);
+        const response = await this.request("POST", `/course/v1/agent-service/runs/${agentRunId}/events`, sanitized);
+        return response?.disposition === "retry"
+            ? {
+                disposition: "retry",
+                ...(typeof response.candidate_attempt === "number"
+                    ? { candidate_attempt: response.candidate_attempt }
+                    : {}),
+                ...(typeof response.retry_feedback === "string"
+                    ? { retry_feedback: response.retry_feedback }
+                    : {}),
+            }
+            : { disposition: "accepted" };
     }
     async postFile(agentRunId, file) {
         this.assertRunId(agentRunId);

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

@@ -1,7 +1,7 @@
 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";
+import type { CourseRuntime, CourseRuntimeProfile, RunEvent, RunEventReceipt, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
 export interface AgentServiceSandboxOptions {
     wsUrl: string;
     sandboxId: string;
@@ -56,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;
@@ -64,11 +73,13 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private recoverPendingActivationCleanups;
     run(): Promise<void>;
     stop(): void;
-    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<RunEventReceipt>;
     postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord>;
     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,7 +2,7 @@ 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 { 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";
@@ -17,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;
@@ -277,6 +341,15 @@ 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;
@@ -288,6 +361,9 @@ export class AgentServiceSandboxClient {
         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);
@@ -342,9 +418,8 @@ export class AgentServiceSandboxClient {
         const scope = this.turnScopes.get(payload.agent_run_id);
         if (!scope)
             return;
-        const activation = this.activationContexts.get(scope.sessionId);
         const session = this.state.sessions[scope.sessionId];
-        if (session && activation?.activationId === scope.activationId) {
+        if (session?.activationId === scope.activationId) {
             // Persist the cleanup obligation before attempting chmod. A terminal event has
             // already been durably ACKed at this point, so reconnect/restart must finish this
             // revoke even when the server desired state has already moved to idle.
@@ -448,6 +523,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");
         }
@@ -464,6 +540,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) {
@@ -524,8 +602,7 @@ export class AgentServiceSandboxClient {
             reject: rejectAck,
         });
         await this.sendFrame(frame);
-        if (event.type !== "run.block")
-            await ack;
+        return event.type !== "run.block" ? await ack : { disposition: "accepted" };
     }
     async postFile(agentRunId, file) {
         const scope = this.turnScopes.get(agentRunId);
@@ -639,6 +716,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");
         }
@@ -683,6 +761,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],
@@ -696,6 +775,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 ||
@@ -1088,12 +1234,54 @@ export class AgentServiceSandboxClient {
         });
     }
     async handleTurnCancel(frame) {
-        if (!this.matchesTurnScope(frame, this.turnScopes.get(frame.agent_run_id))) {
+        const sessionId = frame.runtime_session_id;
+        const runId = frame.agent_run_id;
+        const workerAttempt = frame.worker_attempt;
+        const activationId = frame.activation_id;
+        const requestedScope = { sessionId, workerAttempt, activationId };
+        const existingScope = this.turnScopes.get(runId);
+        if (existingScope && !this.sameTurnScope(existingScope, requestedScope)) {
+            await this.sendCommandAck(frame, "rejected", "turn_scope_mismatch");
+            return;
+        }
+        const session = this.state.sessions[sessionId];
+        if (!session) {
+            await this.sendCommandAck(frame, "rejected", "session_not_open");
+            return;
+        }
+        const accepted = Object.values(session.acceptedCommands).find((command) => command.agentRunId === runId);
+        if (accepted && (accepted.workerAttempt !== workerAttempt ||
+            accepted.activationId !== activationId)) {
             await this.sendCommandAck(frame, "rejected", "turn_scope_mismatch");
             return;
         }
-        this.dispatcher.cancel(frame.agent_run_id);
+        this.turnScopes.set(runId, requestedScope);
+        if (this.dispatcher.cancel(runId)) {
+            await this.sendCommandAck(frame, "ok");
+            return;
+        }
+        // ``turn.cancel`` may win the race before ``turn.start`` is delivered, or arrive
+        // after a daemon restart lost the runtime process.  The fenced server command is
+        // authoritative: ACK it and synthesize the durable terminal event without touching
+        // the sandbox generation or deleting the runtime-session workspace.
         await this.sendCommandAck(frame, "ok");
+        await this.postEvent(runId, {
+            type: "run.cancelled",
+            event_id: `cancel-${runId}-${workerAttempt}`,
+            seq: 1,
+            payload: {
+                reason: "cancelled_by_request",
+                runtime: session.runtimeId,
+            },
+        });
+        const commandId = `run:${runId}:${workerAttempt}`;
+        if (!session.completedCommands.includes(commandId)) {
+            session.completedCommands.push(commandId);
+            session.completedCommands = session.completedCommands.slice(-256);
+        }
+        delete session.acceptedCommands[commandId];
+        this.persist();
+        this.finishTurn({ agent_run_id: runId });
     }
     /**
      * 幂等关闭一个 runtime session：终止其 runtime 子进程、删除 workspace/native state、
@@ -1323,7 +1511,17 @@ export class AgentServiceSandboxClient {
         this.persist();
         if (pending) {
             this.pendingAcks.delete(frameId);
-            pending.resolve();
+            pending.resolve(frame.payload.disposition === "retry"
+                ? {
+                    disposition: "retry",
+                    ...(typeof frame.payload.candidate_attempt === "number"
+                        ? { candidate_attempt: frame.payload.candidate_attempt }
+                        : {}),
+                    ...(typeof frame.payload.retry_feedback === "string"
+                        ? { retry_feedback: frame.payload.retry_feedback }
+                        : {}),
+                }
+                : { disposition: "accepted" });
         }
     }
     async replaySpool() {

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/course-client.d.ts

@@ -1,4 +1,4 @@
-import type { CourseRuntimeProfile, DaemonAuth, RunEvent, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
+import type { CourseRuntimeProfile, DaemonAuth, RunEvent, RunEventReceipt, RunFileCandidate, RunFileRecord, RunStartPayload } from "./types.js";
 export declare class CourseClientError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -31,7 +31,7 @@ export declare class CourseClient {
     private request;
     /** 领取下一个分配给本 daemon 的 queued run（无则返回 null）。 */
     claimNextRun(): Promise<RunStartPayload | null>;
-    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<RunEventReceipt>;
     postFile(agentRunId: string, file: RunFileCandidate): Promise<RunFileRecord | void>;
     getRunRuntimeProfile(agentRunId: string): Promise<CourseRuntimeProfile>;
 }

package/dist/course-client.js

@@ -103,7 +103,18 @@ export class CourseClient {
     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", `/course/v1/daemon/runs/${agentRunId}/events`, sanitized, event.trace_id);
+        const response = await this.request("POST", `/course/v1/daemon/runs/${agentRunId}/events`, sanitized, event.trace_id);
+        return response?.disposition === "retry"
+            ? {
+                disposition: "retry",
+                ...(typeof response.candidate_attempt === "number"
+                    ? { candidate_attempt: response.candidate_attempt }
+                    : {}),
+                ...(typeof response.retry_feedback === "string"
+                    ? { retry_feedback: response.retry_feedback }
+                    : {}),
+            }
+            : { disposition: "accepted" };
     }
     async postFile(agentRunId, file) {
         return this.request("POST", `/course/v1/daemon/runs/${agentRunId}/files`, file);

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/run-dispatcher.d.ts

@@ -2,7 +2,7 @@ import { type ScanLimits } from "./file-candidates.js";
 import { type InputAttachmentGrant } from "./input-attachments.js";
 import { type Logger } from "./log.js";
 import type { PreparedRuntimeSkillProvider } from "./runtime-skills.js";
-import { type CourseRuntimeProfile, type CourseRuntime, type RunEvent, type RunStartPayload } from "./types.js";
+import { type CourseRuntimeProfile, type CourseRuntime, type RunEvent, type RunEventReceipt, type RunStartPayload } from "./types.js";
 export interface RunDispatcherOptions {
     defaultRuntimeId?: string;
     log?: Logger;
@@ -26,7 +26,7 @@ export interface PersistentSessionExecution {
     finishTurn(payload: RunStartPayload): void;
 }
 export interface RunReportingClient {
-    postEvent(agentRunId: string, event: RunEvent): Promise<void>;
+    postEvent(agentRunId: string, event: RunEvent): Promise<void | RunEventReceipt>;
     postFile(agentRunId: string, file: import("./types.js").RunFileCandidate): Promise<unknown>;
     getRunRuntimeProfile?(agentRunId: string): Promise<CourseRuntimeProfile>;
 }

package/dist/run-dispatcher.js

@@ -23,6 +23,7 @@ const BLOCK_TEXT_MAX_CHARS = 4000;
 const CONTENT_FLUSH_MAX_CHARS = 512;
 const CONTENT_FLUSH_INTERVAL_MS = 100;
 const AGENT_STREAM_SCHEMA_VERSION = "agent-stream/0.1";
+const MAX_CANDIDATE_GENERATION_ATTEMPTS = 3;
 const SAFE_TOOL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,79}$/;
 const SAFE_FAILURE_CODE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
 const SAFE_FAILURE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/;
@@ -100,6 +101,29 @@ function chunkUnicodeText(value, maxCodePoints) {
     }
     return chunks;
 }
+function candidateRetryPayload(payload, feedback) {
+    const original = typeof payload.input.text === "string" ? payload.input.text : "";
+    const instruction = truncateText(redactSecretString(feedback?.trim() || "Produce a complete learner-facing reply."), 800);
+    return {
+        ...payload,
+        input: {
+            ...payload.input,
+            text: [
+                "[BotLearn internal response retry]",
+                "Replace the previous candidate completely. Do not mention this review or the previous reply.",
+                `Correction required: ${instruction}`,
+                original ? `Original current request:\n${original}` : "",
+            ].filter(Boolean).join("\n\n"),
+        },
+    };
+}
+function replacesLatestConversationTurn(payload) {
+    const regeneration = payload.context.regeneration;
+    return Boolean(regeneration &&
+        typeof regeneration === "object" &&
+        !Array.isArray(regeneration) &&
+        regeneration.mode === "replace_latest");
+}
 /**
  * Run dispatcher：把 Course Service 下发的 run.start 交给 runtime，
  * 并把 runtime 输出归一化成 run.block / run.message / run.completed 回报 Course Service。
@@ -265,8 +289,7 @@ export class RunDispatcher {
             };
             for (let attempt = 0; attempt < 3; attempt += 1) {
                 try {
-                    await this.client.postEvent(runId, outgoing);
-                    return;
+                    return await this.client.postEvent(runId, outgoing);
                 }
                 catch (err) {
                     if (isRunTerminal(err)) {
@@ -274,7 +297,13 @@ export class RunDispatcher {
                         controller.abort();
                         return;
                     }
-                    const retryable = !(err instanceof CourseClientError) || err.status === 429 || err.status >= 500;
+                    const candidateReview = event.type === "run.message"
+                        && typeof event.payload?.candidate_attempt === "number";
+                    // The Course Service already retries the side-effect-free judge once. A known
+                    // 5xx from that boundary must not multiply one review into six provider calls;
+                    // transport errors without a response still reuse this event id normally.
+                    const retryable = !(err instanceof CourseClientError)
+                        || (!candidateReview && (err.status === 429 || err.status >= 500));
                     if (!retryable || attempt === 2)
                         throw err;
                     await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
@@ -441,6 +470,14 @@ export class RunDispatcher {
                 controller.abort();
             }, timeoutSeconds * 1000);
             let finalText = "";
+            let activeNativeSessionId = persistentTurn?.nativeSessionId ?? null;
+            if (activeNativeSessionId && replacesLatestConversationTurn(payload)) {
+                // A user retry is a replacement branch, not a follow-up to the discarded answer.
+                // Clear the provider-native cache before execution; the durable Course transcript
+                // in this payload is sufficient to rebuild the branch in the same turn.
+                activeNativeSessionId = null;
+                this.persistentSession?.persistNativeSession("");
+            }
             // 上一次真正上了 wire 的块 kind：status 只在 kind 切换时上报一次，避免刷屏。
             let lastReportedKind = null;
             let lastReasoningPhase = null;
@@ -730,31 +767,93 @@ export class RunDispatcher {
                     await this.client.postFile(runId, file);
                 },
                 runtimeSession: async (sessionId) => {
+                    activeNativeSessionId = sessionId;
                     this.persistentSession?.persistNativeSession(sessionId);
                 },
             };
             modelStartedAt = this.now();
+            let acceptedOutput = "";
+            let attemptPayload = payload;
+            const resetVisibleCandidate = async () => {
+                await send({
+                    type: "run.block",
+                    payload: {
+                        schema_version: AGENT_STREAM_SCHEMA_VERSION,
+                        kind: "response_reset",
+                        runtime: runtime.id,
+                        status: "retrying",
+                    },
+                });
+            };
             try {
-                await runtime.run({
-                    payload,
-                    workspaceDir,
-                    inputAttachments,
-                    ...(persistentTurn
-                        ? {
-                            ...(persistentTurn.runtimeStateDir
-                                ? { runtimeStateDir: persistentTurn.runtimeStateDir }
-                                : {}),
-                            nativeSessionId: persistentTurn.nativeSessionId,
-                            contextRevision: persistentTurn.contextRevision,
-                            ...(persistentTurn.runtimeEnv
-                                ? { runtimeEnv: persistentTurn.runtimeEnv }
-                                : {}),
-                            ...(persistentTurn.skillProvider
-                                ? { skillProvider: persistentTurn.skillProvider }
-                                : {}),
-                        }
-                        : {}),
-                }, sink, controller.signal);
+                for (let candidateAttempt = 1; candidateAttempt <= MAX_CANDIDATE_GENERATION_ATTEMPTS; candidateAttempt += 1) {
+                    finalText = "";
+                    await runtime.run({
+                        payload: attemptPayload,
+                        workspaceDir,
+                        inputAttachments,
+                        ...(persistentTurn
+                            ? {
+                                ...(persistentTurn.runtimeStateDir
+                                    ? { runtimeStateDir: persistentTurn.runtimeStateDir }
+                                    : {}),
+                                nativeSessionId: activeNativeSessionId,
+                                contextRevision: persistentTurn.contextRevision,
+                                ...(persistentTurn.runtimeEnv
+                                    ? { runtimeEnv: persistentTurn.runtimeEnv }
+                                    : {}),
+                                ...(persistentTurn.skillProvider
+                                    ? { skillProvider: persistentTurn.skillProvider }
+                                    : {}),
+                            }
+                            : {}),
+                    }, sink, controller.signal);
+                    await flushContent();
+                    if (serverTerminal)
+                        return;
+                    if (controller.signal.aborted)
+                        throw new Error("aborted");
+                    const maxOutputChars = typeof payload.limits.max_output_chars === "number" &&
+                        Number.isFinite(payload.limits.max_output_chars) &&
+                        payload.limits.max_output_chars > 0
+                        ? payload.limits.max_output_chars
+                        : DEFAULT_MAX_OUTPUT_CHARS;
+                    const output = redactSecretString(truncateText(finalText, maxOutputChars));
+                    await send({
+                        type: "run.block",
+                        payload: {
+                            schema_version: AGENT_STREAM_SCHEMA_VERSION,
+                            kind: "response_review",
+                            runtime: runtime.id,
+                            status: "in_progress",
+                        },
+                    });
+                    let receipt;
+                    try {
+                        receipt = await send({
+                            type: "run.message",
+                            role: "assistant",
+                            text: output,
+                            payload: { candidate_attempt: candidateAttempt },
+                        });
+                    }
+                    catch (error) {
+                        await resetVisibleCandidate();
+                        throw error;
+                    }
+                    if (receipt?.disposition !== "retry") {
+                        acceptedOutput = output;
+                        break;
+                    }
+                    await resetVisibleCandidate();
+                    if (candidateAttempt >= MAX_CANDIDATE_GENERATION_ATTEMPTS) {
+                        await sendFailure("candidate_rejected", "Agent could not produce a complete reply after two retries", new RuntimeExecutionError("Agent candidate rejected after bounded retries"), { candidate_attempts: candidateAttempt });
+                        return;
+                    }
+                    lastReportedKind = null;
+                    lastReasoningPhase = null;
+                    attemptPayload = candidateRetryPayload(payload, receipt.retry_feedback);
+                }
             }
             finally {
                 modelFinishedAt = this.now();
@@ -764,13 +863,7 @@ export class RunDispatcher {
                 return;
             if (controller.signal.aborted)
                 throw new Error("aborted");
-            const maxOutputChars = typeof payload.limits.max_output_chars === "number" &&
-                Number.isFinite(payload.limits.max_output_chars) &&
-                payload.limits.max_output_chars > 0
-                ? payload.limits.max_output_chars
-                : DEFAULT_MAX_OUTPUT_CHARS;
-            const output = redactSecretString(truncateText(finalText, maxOutputChars));
-            activeTranscript.writeFinal(output);
+            activeTranscript.writeFinal(acceptedOutput);
             fileReportStartedAt = this.now();
             try {
                 await reportFileCandidates(this.client, runId, workspaceDir, this.log, this.scanLimits);
@@ -778,7 +871,6 @@ export class RunDispatcher {
             finally {
                 fileReportFinishedAt = this.now();
             }
-            await send({ type: "run.message", role: "assistant", text: output });
             await sendTerminal({
                 type: "run.completed",
                 payload: { runtime: runtimeId, usage: usage() },

package/dist/types.d.ts

@@ -68,6 +68,11 @@ export interface RunEvent {
     error?: string;
     payload?: Record<string, unknown>;
 }
+export interface RunEventReceipt {
+    disposition: "accepted" | "retry";
+    candidate_attempt?: number;
+    retry_feedback?: string;
+}
 /** `POST /daemon/runs/{id}/files` 的文件候选（与后端 DaemonRunFileIn 一致）。 */
 export interface RunFileCandidate {
     event?: "created" | "modified" | "deleted";

package/package.json

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