@botlearn-course/daemon 0.0.17 → 0.0.18-beta.2

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

@@ -64,6 +64,7 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private runtimeLogSuppressedEvents;
     private runtimeLogSuppressedBytes;
     private runtimeLogSendChain;
+    private workspaceFileReadInFlight;
     private readonly removeOperationalLogSink;
     constructor(options: AgentServiceSandboxOptions);
     prepareTurn(payload: RunStartPayload): PreparedPersistentTurn;
@@ -109,9 +110,12 @@ export declare class AgentServiceSandboxClient implements RunReportingClient, Pe
     private replaySpool;
     private sendHeartbeat;
     private sendCommandAck;
+    private handleWorkspaceFileRead;
+    private sendWorkspaceFileResult;
     private sendControlFrame;
     private sendSessionFrame;
     private sendFrame;
+    private sendBinaryFrame;
     private nextOutboundSeq;
     private waitForEventCapacity;
     private waitForPendingEventAcks;

package/dist/agent-service-sandbox.js

@@ -1,14 +1,15 @@
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 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 { AGENT_SERVICE_WS_SCHEMA, AGENT_SERVICE_WS_SUBPROTOCOL, createSandboxFrame, createWorkspaceFileChunk, parseSandboxFrame, UnsupportedSandboxProtocolError, WORKSPACE_FILE_READ_BINARY_CAPABILITY, } from "./agent-service-ws-protocol.js";
 import { log as defaultLog, setOperationalLogSink, } from "./log.js";
 import { availableRunCapabilities, runtimeSupportsCourseSkills, } from "./runtime-capabilities.js";
 import { activationRuntimeEnv, runtimeChildEnv } from "./runtime-env.js";
 import { redactSecretString } from "./redaction.js";
 import { parseRuntimeSkillProviderGrantSet, prepareRuntimeSkillProvider, RuntimeSkillProviderError, } from "./runtime-skills.js";
 import { RunDispatcher, } from "./run-dispatcher.js";
-import { ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, } from "./workspace.js";
+import { ensureRuntimeSessionDirectories, ensureRuntimeSessionWorkspace, exposeRuntimeSessionWorkspace, removeRuntimeSessionWorkspace, revokeRuntimeSessionWorkspace, runtimeSessionWorkspaceDir, } from "./workspace.js";
+import { readWorkspaceFile, WorkspaceFileReadError } from "./workspace-file-read.js";
 import { WebSocketClient, } from "./websocket-client.js";
 const RECONNECT_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 const MAX_SPOOL_FRAMES = 1024;
@@ -19,6 +20,7 @@ const INPUT_ATTACHMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-
 /** 出站 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 WORKSPACE_FILE_TRANSFER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const DISABLED_RUNTIME_LOG_POLICY = {
     enabled: false,
     maxEventBytes: 4096,
@@ -368,6 +370,7 @@ export class AgentServiceSandboxClient {
     runtimeLogSuppressedEvents = 0;
     runtimeLogSuppressedBytes = 0;
     runtimeLogSendChain = Promise.resolve();
+    workspaceFileReadInFlight = false;
     removeOperationalLogSink;
     constructor(options) {
         this.options = options;
@@ -784,6 +787,7 @@ export class AgentServiceSandboxClient {
         this.persist();
         await this.sendControlFrame("sandbox.ready", {
             protocol_versions: [AGENT_SERVICE_WS_SCHEMA],
+            capabilities: [WORKSPACE_FILE_READ_BINARY_CAPABILITY],
             daemon_version: this.options.daemonVersion,
             runtime_versions: {
                 course_daemon: this.options.daemonVersion,
@@ -906,6 +910,15 @@ export class AgentServiceSandboxClient {
                 await this.sendCommandAck(frame, "ok");
                 return;
             }
+            case "workspace.file.read":
+                void this.handleWorkspaceFileRead(frame).catch((error) => {
+                    this.log.warn("Agent Service workspace file read response failed", {
+                        sandboxId: this.options.sandboxId,
+                        runtimeSessionId: frame.runtime_session_id,
+                        error: error instanceof Error ? redactSecretString(error.message) : "unexpected",
+                    });
+                });
+                return;
             case "sandbox.shutdown":
                 this.stop();
                 return;
@@ -1578,6 +1591,78 @@ export class AgentServiceSandboxClient {
             ...(error !== undefined ? { error } : {}),
         });
     }
+    async handleWorkspaceFileRead(frame) {
+        const transferId = frame.payload.transfer_id;
+        const relativePath = frame.payload.path;
+        const maxBytes = frame.payload.max_bytes;
+        const expectedSizeBytes = frame.payload.expected_size_bytes;
+        const expectedSha256 = frame.payload.expected_sha256;
+        const sessionId = frame.runtime_session_id;
+        const reject = async (errorCode) => {
+            await this.sendWorkspaceFileResult(frame, {
+                transfer_id: typeof transferId === "string" ? transferId : "invalid",
+                status: "rejected",
+                error_code: errorCode,
+            });
+        };
+        if (typeof transferId !== "string" ||
+            !WORKSPACE_FILE_TRANSFER_ID.test(transferId) ||
+            typeof relativePath !== "string" ||
+            !Number.isSafeInteger(maxBytes) ||
+            !Number.isSafeInteger(expectedSizeBytes) ||
+            typeof expectedSha256 !== "string") {
+            await reject("workspace_file_invalid_request");
+            return;
+        }
+        if (!this.state.sessions[sessionId]) {
+            await reject("workspace_file_unavailable");
+            return;
+        }
+        if (this.workspaceFileReadInFlight) {
+            await reject("workspace_file_busy");
+            return;
+        }
+        this.workspaceFileReadInFlight = true;
+        try {
+            const result = await readWorkspaceFile(runtimeSessionWorkspaceDir(sessionId, this.sandboxGeneration), relativePath, {
+                maxBytes: maxBytes,
+                expectedSizeBytes: expectedSizeBytes,
+                expectedSha256,
+                onChunk: async (chunkIndex, content) => {
+                    await this.sendBinaryFrame(createWorkspaceFileChunk(transferId, chunkIndex, content), frame);
+                },
+            });
+            await this.sendWorkspaceFileResult(frame, {
+                transfer_id: transferId,
+                status: "ok",
+                size_bytes: result.sizeBytes,
+                sha256: result.sha256,
+                chunk_count: result.chunkCount,
+            });
+        }
+        catch (error) {
+            await reject(error instanceof WorkspaceFileReadError
+                ? error.code
+                : "workspace_file_unavailable");
+        }
+        finally {
+            this.workspaceFileReadInFlight = false;
+        }
+    }
+    async sendWorkspaceFileResult(source, payload) {
+        if (source.sandbox_generation !== this.sandboxGeneration ||
+            source.connection_epoch !== this.connectionEpoch)
+            return;
+        await this.sendFrame(createSandboxFrame({
+            type: "workspace.file.result",
+            sandboxId: this.options.sandboxId,
+            sandboxGeneration: this.sandboxGeneration,
+            connectionEpoch: this.connectionEpoch,
+            seq: this.nextOutboundSeq(),
+            runtimeSessionId: source.runtime_session_id,
+            payload,
+        }));
+    }
     async sendControlFrame(type, payload) {
         await this.sendFrame(createSandboxFrame({
             type,
@@ -1611,6 +1696,19 @@ export class AgentServiceSandboxClient {
             socket.send(JSON.stringify(frame), (error) => (error ? reject(error) : resolve()));
         });
     }
+    async sendBinaryFrame(content, source) {
+        if (source.sandbox_generation !== this.sandboxGeneration ||
+            source.connection_epoch !== this.connectionEpoch) {
+            throw new Error("Agent Service sandbox file transfer was fenced");
+        }
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocketClient.OPEN) {
+            throw new Error("Agent Service sandbox file transport is disconnected");
+        }
+        await new Promise((resolve, reject) => {
+            socket.send(content, (error) => (error ? reject(error) : resolve()));
+        });
+    }
     nextOutboundSeq() {
         this.outboundSeq += 1;
         return this.outboundSeq;

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

@@ -1,6 +1,9 @@
 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" | "sandbox.log" | "pong" | "protocol.error";
+export declare const WORKSPACE_FILE_READ_BINARY_CAPABILITY: "workspace_file_read_binary_v1";
+export declare const WORKSPACE_FILE_CHUNK_BYTES: number;
+export declare const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
+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" | "workspace.file.read" | "ping" | "sandbox.ready" | "sandbox.heartbeat" | "command.ack" | "session.opened" | "session.closed" | "turn.event" | "turn.file.report" | "workspace.file.result" | "sandbox.drained" | "sandbox.log" | "pong" | "protocol.error";
 export declare class UnsupportedSandboxProtocolError extends Error {
     readonly schemaVersion: unknown;
     constructor(schemaVersion: unknown);
@@ -20,6 +23,13 @@ export interface SandboxFrame {
     activation_id: string | null;
     payload: Record<string, unknown>;
 }
+export interface WorkspaceFileChunk {
+    transferId: string;
+    chunkIndex: number;
+    content: Buffer;
+}
+export declare function createWorkspaceFileChunk(transferId: string, chunkIndex: number, content: Buffer): Buffer;
+export declare function parseWorkspaceFileChunk(raw: Buffer): WorkspaceFileChunk;
 export declare function parseSandboxFrame(raw: string, maxBytes?: number): SandboxFrame;
 export declare function createSandboxFrame(input: {
     type: SandboxFrameType;

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

@@ -1,6 +1,10 @@
 import { randomUUID } from "node:crypto";
 export const AGENT_SERVICE_WS_SCHEMA = "botlearn-agent-sandbox-ws/0.2";
 export const AGENT_SERVICE_WS_SUBPROTOCOL = "botlearn-agent-sandbox.v2";
+export const WORKSPACE_FILE_READ_BINARY_CAPABILITY = "workspace_file_read_binary_v1";
+export const WORKSPACE_FILE_CHUNK_BYTES = 64 * 1024;
+export const WORKSPACE_FILE_CHUNK_HEADER_BYTES = 29;
+const WORKSPACE_FILE_CHUNK_MAGIC = Buffer.from("BLWF", "ascii");
 const FRAME_TYPES = new Set([
     "sandbox.hello",
     "sandbox.sync",
@@ -13,6 +17,7 @@ const FRAME_TYPES = new Set([
     "sandbox.shutdown",
     "event.ack",
     "auth.rotate",
+    "workspace.file.read",
     "ping",
     "sandbox.ready",
     "sandbox.heartbeat",
@@ -21,6 +26,7 @@ const FRAME_TYPES = new Set([
     "session.closed",
     "turn.event",
     "turn.file.report",
+    "workspace.file.result",
     "sandbox.drained",
     "sandbox.log",
     "pong",
@@ -33,6 +39,8 @@ const SESSION_TYPES = new Set([
     "session.close",
     "session.opened",
     "session.closed",
+    "workspace.file.read",
+    "workspace.file.result",
 ]);
 /** TURN 帧：必须带 runtime_session_id + agent_run_id + worker_attempt + activation_id 四元组。 */
 const TURN_TYPES = new Set([
@@ -66,6 +74,48 @@ export class UnsupportedSandboxProtocolError extends Error {
         this.name = "UnsupportedSandboxProtocolError";
     }
 }
+function uuidBytes(value) {
+    if (!UUID_PATTERN.test(value))
+        throw new Error("workspace file transfer_id must be a UUID");
+    return Buffer.from(value.replaceAll("-", ""), "hex");
+}
+function bytesUuid(value) {
+    const hex = value.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+export function createWorkspaceFileChunk(transferId, chunkIndex, content) {
+    if (!Number.isSafeInteger(chunkIndex) || chunkIndex < 0 || chunkIndex > 0xffff_ffff) {
+        throw new Error("workspace file chunk_index is invalid");
+    }
+    if (content.length > WORKSPACE_FILE_CHUNK_BYTES) {
+        throw new Error("workspace file chunk exceeds size limit");
+    }
+    const frame = Buffer.allocUnsafe(WORKSPACE_FILE_CHUNK_HEADER_BYTES + content.length);
+    WORKSPACE_FILE_CHUNK_MAGIC.copy(frame, 0);
+    frame[4] = 1;
+    uuidBytes(transferId).copy(frame, 5);
+    frame.writeUInt32BE(chunkIndex, 21);
+    frame.writeUInt32BE(content.length, 25);
+    content.copy(frame, WORKSPACE_FILE_CHUNK_HEADER_BYTES);
+    return frame;
+}
+export function parseWorkspaceFileChunk(raw) {
+    if (raw.length < WORKSPACE_FILE_CHUNK_HEADER_BYTES ||
+        !raw.subarray(0, 4).equals(WORKSPACE_FILE_CHUNK_MAGIC) ||
+        raw[4] !== 1) {
+        throw new Error("invalid workspace file binary frame");
+    }
+    const declaredBytes = raw.readUInt32BE(25);
+    const content = raw.subarray(WORKSPACE_FILE_CHUNK_HEADER_BYTES);
+    if (declaredBytes !== content.length || content.length > WORKSPACE_FILE_CHUNK_BYTES) {
+        throw new Error("invalid workspace file binary frame length");
+    }
+    return {
+        transferId: bytesUuid(raw.subarray(5, 21)),
+        chunkIndex: raw.readUInt32BE(21),
+        content: Buffer.from(content),
+    };
+}
 function positiveInteger(value, label) {
     if (!Number.isInteger(value) || value < 1) {
         throw new Error(`${label} must be a positive integer`);

package/dist/input-attachments.d.ts

@@ -1,4 +1,9 @@
 import type { MaterializedInputAttachment, RunInputAttachment } from "./types.js";
+export type InputAttachmentErrorCode = "attachment_download_failed" | "attachment_download_timeout" | "attachment_read_failed" | "attachment_verification_failed";
+export declare class InputAttachmentMaterializationError extends Error {
+    readonly code: InputAttachmentErrorCode;
+    constructor(message: string, code: InputAttachmentErrorCode, options?: ErrorOptions);
+}
 export interface InputAttachmentGrant {
     downloads: Array<{
         attachmentId: string;

package/dist/input-attachments.js

@@ -10,6 +10,20 @@ const ATTACHMENT_DOWNLOAD_IDLE_TIMEOUT_MS = 60_000;
 const ATTACHMENT_DOWNLOAD_MAX_DURATION_MS = 10 * 60_000;
 const ATTACHMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const SHA256 = /^[0-9a-f]{64}$/i;
+export class InputAttachmentMaterializationError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = "InputAttachmentMaterializationError";
+        this.code = code;
+    }
+}
+function attachmentVerificationError(message) {
+    return new InputAttachmentMaterializationError(message, "attachment_verification_failed");
+}
+function attachmentDownloadError(message) {
+    return new InputAttachmentMaterializationError(message, "attachment_download_failed");
+}
 const CONTENT_TYPE_EXTENSIONS = {
     "image/png": ".png",
     "image/jpeg": ".jpg",
@@ -42,43 +56,44 @@ function normalizedContentType(value) {
 }
 function validateAttachment(attachment) {
     if (!ATTACHMENT_ID.test(attachment.attachment_id)) {
-        throw new Error("invalid input attachment id");
+        throw attachmentVerificationError("invalid input attachment id");
     }
     if (typeof attachment.filename !== "string" ||
         attachment.filename.length < 1 ||
         attachment.filename.length > 255) {
-        throw new Error("invalid input attachment filename");
+        throw attachmentVerificationError("invalid input attachment filename");
     }
     const contentType = normalizedContentType(attachment.content_type);
     const extension = CONTENT_TYPE_EXTENSIONS[contentType];
-    if (!extension)
-        throw new Error(`unsupported input attachment type: ${contentType}`);
+    if (!extension) {
+        throw attachmentVerificationError(`unsupported input attachment type: ${contentType}`);
+    }
     if (!Number.isInteger(attachment.size_bytes) ||
         attachment.size_bytes < 1 ||
         attachment.size_bytes > MAX_ATTACHMENT_BYTES) {
-        throw new Error("invalid input attachment size");
+        throw attachmentVerificationError("invalid input attachment size");
     }
     if (!SHA256.test(attachment.sha256)) {
-        throw new Error("invalid input attachment sha256");
+        throw attachmentVerificationError("invalid input attachment sha256");
     }
     return extension;
 }
 function validateDownloadUrl(value) {
     if (!value || value.length > 4096) {
-        throw new Error("invalid input attachment download URL");
+        throw attachmentDownloadError("invalid input attachment download URL");
     }
     let parsed;
     try {
         parsed = new URL(value);
     }
     catch {
-        throw new Error("invalid input attachment download URL");
+        throw attachmentDownloadError("invalid input attachment download URL");
     }
     if (!["http:", "https:"].includes(parsed.protocol) ||
         parsed.username ||
         parsed.password ||
         parsed.hash) {
-        throw new Error("invalid input attachment download URL");
+        throw attachmentDownloadError("invalid input attachment download URL");
     }
     return value;
 }
@@ -86,12 +101,12 @@ function validateGrant(grant) {
     if (!Array.isArray(grant.downloads) ||
         grant.downloads.length < 1 ||
         grant.downloads.length > MAX_ATTACHMENTS) {
-        throw new Error("invalid input attachment download grant");
+        throw attachmentDownloadError("invalid input attachment download grant");
     }
     const downloads = new Map();
     for (const item of grant.downloads) {
         if (!ATTACHMENT_ID.test(item.attachmentId) || downloads.has(item.attachmentId)) {
-            throw new Error("invalid input attachment download grant");
+            throw attachmentDownloadError("invalid input attachment download grant");
         }
         downloads.set(item.attachmentId, validateDownloadUrl(item.downloadUrl));
     }
@@ -133,15 +148,15 @@ async function verifyExisting(filePath, attachment) {
 }
 async function writeResponseToFile(response, partPath, attachment, signal, onDownloadProgress) {
     if (!response.body)
-        throw new Error("input attachment response has no body");
+        throw attachmentDownloadError("input attachment response has no body");
     const declaredLength = response.headers.get("content-length");
     if (declaredLength !== null && Number(declaredLength) !== attachment.size_bytes) {
-        throw new Error("input attachment response size does not match metadata");
+        throw attachmentVerificationError("input attachment response size does not match metadata");
     }
     const responseType = normalizedContentType(response.headers.get("content-type") ?? "");
     const expectedType = normalizedContentType(attachment.content_type);
     if (responseType !== expectedType) {
-        throw new Error("input attachment response type does not match metadata");
+        throw attachmentVerificationError("input attachment response type does not match metadata");
     }
     const digest = createHash("sha256");
     const signatureChunks = [];
@@ -163,7 +178,7 @@ async function writeResponseToFile(response, partPath, attachment, signal, onDow
             received += chunk.length;
             onDownloadProgress?.();
             if (received > attachment.size_bytes || received > MAX_ATTACHMENT_BYTES) {
-                throw new Error("input attachment response exceeds declared size");
+                throw attachmentVerificationError("input attachment response exceeds declared size");
             }
             digest.update(chunk);
             if (signatureBytes < 16) {
@@ -178,13 +193,13 @@ async function writeResponseToFile(response, partPath, attachment, signal, onDow
             }
         }
         if (received !== attachment.size_bytes) {
-            throw new Error("input attachment response size does not match metadata");
+            throw attachmentVerificationError("input attachment response size does not match metadata");
         }
         if (digest.digest("hex") !== attachment.sha256.toLowerCase()) {
-            throw new Error("input attachment sha256 mismatch");
+            throw attachmentVerificationError("input attachment sha256 mismatch");
         }
         if (!hasExpectedImageSignature(expectedType, Buffer.concat(signatureChunks))) {
-            throw new Error("input attachment file signature does not match content type");
+            throw attachmentVerificationError("input attachment file signature does not match content type");
         }
         await file.sync();
     }
@@ -195,8 +210,8 @@ async function writeResponseToFile(response, partPath, attachment, signal, onDow
 function startAttachmentDownloadBudget(parentSignal) {
     const controller = new AbortController();
     const abortFromParent = () => controller.abort(parentSignal.reason);
-    const abortStalledDownload = () => controller.abort(new Error("input attachment download stalled for 60s"));
-    const abortOverlongDownload = () => controller.abort(new Error("input attachment download exceeded the 600s maximum duration"));
+    const abortStalledDownload = () => controller.abort(new InputAttachmentMaterializationError("input attachment download stalled for 60s", "attachment_download_timeout"));
+    const abortOverlongDownload = () => controller.abort(new InputAttachmentMaterializationError("input attachment download exceeded the 600s maximum duration", "attachment_download_timeout"));
     if (parentSignal.aborted) {
         abortFromParent();
     }
@@ -222,23 +237,23 @@ function startAttachmentDownloadBudget(parentSignal) {
         },
     };
 }
-export async function materializeInputAttachments(workspaceDir, attachments, grant, signal) {
+async function materializeInputAttachmentsImplementation(workspaceDir, attachments, grant, signal) {
     if (attachments.length > MAX_ATTACHMENTS) {
-        throw new Error("too many input attachments");
+        throw attachmentVerificationError("too many input attachments");
     }
     if (new Set(attachments.map((item) => item.attachment_id)).size !== attachments.length) {
-        throw new Error("duplicate input attachment id");
+        throw attachmentVerificationError("duplicate input attachment id");
     }
     const extensions = new Map(attachments.map((attachment) => [attachment.attachment_id, validateAttachment(attachment)]));
     const downloadUrls = validateGrant(grant);
     if (downloadUrls.size !== attachments.length ||
         attachments.some((attachment) => !downloadUrls.has(attachment.attachment_id))) {
-        throw new Error("input attachment download grant does not match run attachments");
+        throw attachmentDownloadError("input attachment download grant does not match run attachments");
     }
     const inputDir = path.resolve(workspaceDir, ".botlearn", "input-attachments");
     const workspaceRoot = path.resolve(workspaceDir);
     if (!inputDir.startsWith(`${workspaceRoot}${path.sep}`)) {
-        throw new Error("input attachment directory escapes workspace");
+        throw attachmentVerificationError("input attachment directory escapes workspace");
     }
     await mkdir(inputDir, { recursive: true, mode: 0o770 });
     await chmod(path.dirname(inputDir), 0o770);
@@ -256,13 +271,22 @@ export async function materializeInputAttachments(workspaceDir, attachments, gra
             const downloadUrl = downloadUrls.get(attachment.attachment_id);
             const budget = startAttachmentDownloadBudget(signal);
             try {
-                const response = await fetch(downloadUrl, {
-                    headers: { "accept-encoding": "identity" },
-                    redirect: "error",
-                    signal: budget.signal,
-                });
+                let response;
+                try {
+                    response = await fetch(downloadUrl, {
+                        headers: { "accept-encoding": "identity" },
+                        redirect: "error",
+                        signal: budget.signal,
+                    });
+                }
+                catch (error) {
+                    if (budget.signal.reason instanceof InputAttachmentMaterializationError) {
+                        throw budget.signal.reason;
+                    }
+                    throw new InputAttachmentMaterializationError("input attachment download request failed", "attachment_download_failed", { cause: error });
+                }
                 if (!response.ok) {
-                    throw new Error(`input attachment download failed with HTTP ${response.status}`);
+                    throw attachmentDownloadError(`input attachment download failed with HTTP ${response.status}`);
                 }
                 await writeResponseToFile(response, partPath, attachment, budget.signal, budget.recordProgress);
                 await rename(partPath, filePath);
@@ -282,3 +306,13 @@ export async function materializeInputAttachments(workspaceDir, attachments, gra
     }
     return results;
 }
+export async function materializeInputAttachments(workspaceDir, attachments, grant, signal) {
+    try {
+        return await materializeInputAttachmentsImplementation(workspaceDir, attachments, grant, signal);
+    }
+    catch (error) {
+        if (error instanceof InputAttachmentMaterializationError)
+            throw error;
+        throw new InputAttachmentMaterializationError("input attachment could not be prepared", "attachment_read_failed", { cause: error });
+    }
+}

package/dist/run-dispatcher.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { CourseClientError, isRunTerminal } from "./course-client.js";
 import { reportFileCandidates } from "./file-candidates.js";
-import { materializeInputAttachments, } from "./input-attachments.js";
+import { InputAttachmentMaterializationError, materializeInputAttachments, } from "./input-attachments.js";
 import { log as defaultLog } from "./log.js";
 import { MAX_PROGRESS_EVENTS_PER_ATTEMPT, tryNormalizeProgressReport, } from "./mcp/report-progress.js";
 import { errorInfo, redactSecretString, sanitizeRuntimeFailureText, truncateText, } from "./redaction.js";
@@ -444,7 +444,7 @@ export class RunDispatcher {
             let inputAttachments = [];
             if (requestedAttachments.length > 0) {
                 if (!persistentTurn?.inputAttachmentGrant) {
-                    throw new Error("input attachment download authorization is unavailable");
+                    throw new InputAttachmentMaterializationError("input attachment download authorization is unavailable", "attachment_download_failed");
                 }
                 inputAttachments = await materializeInputAttachments(workspaceDir, requestedAttachments, persistentTurn.inputAttachmentGrant, controller.signal);
             }
@@ -887,7 +887,13 @@ export class RunDispatcher {
                 }
                 else {
                     const info = errorInfo(err);
-                    const errorType = err instanceof RuntimeExecutionError ? err.errorType : "runtime_error";
+                    const errorType = err instanceof RuntimeProfileApplyError
+                        ? err.code
+                        : err instanceof InputAttachmentMaterializationError
+                            ? err.code
+                            : err instanceof RuntimeExecutionError
+                                ? err.errorType
+                                : "runtime_error";
                     await sendFailure(errorType, info.error_message, err, err instanceof RuntimeProfileApplyError
                         ? { code: err.code, profile_apply_status: "failed" }
                         : {});

package/dist/runtimes/deepseek-tui.js

@@ -259,6 +259,10 @@ export class DeepseekTuiAdapter {
                             if (compacted.error) {
                                 throw new Error(`native compaction failed: ${compacted.error}`);
                             }
+                            // The marker arms exactly one compaction. Disarm it here so later turns
+                            // start work directly; the post-turn threshold check re-arms when the
+                            // compacted thread grows past the limit again.
+                            this.clearCompactionRequired(opts);
                         }
                     }
                     runResult = await this.startTurnAndReadEvents({

package/dist/websocket-client.d.ts

@@ -7,8 +7,8 @@ export interface WebSocketClientOptions {
 /**
  * Narrow RFC 6455 client for the daemon control plane.
  *
- * It intentionally supports only text/control frames, no extensions, and one configured
- * subprotocol. Keeping this transport on Node built-ins preserves the daemon's zero
+ * It intentionally supports only text, binary, and control frames, no extensions, and one
+ * configured subprotocol. Keeping this transport on Node built-ins preserves the daemon's zero
  * production-dependency release invariant.
  */
 export declare class WebSocketClient extends EventEmitter {
@@ -31,7 +31,7 @@ export declare class WebSocketClient extends EventEmitter {
     private closeEmitted;
     private closeSent;
     constructor(rawUrl: string, protocol: string, options?: WebSocketClientOptions);
-    send(data: string, callback?: (error?: Error) => void): void;
+    send(data: string | Buffer, callback?: (error?: Error) => void): void;
     close(code?: number, reason?: string): void;
     private connect;
     private sendHandshake;

package/dist/websocket-client.js

@@ -35,8 +35,8 @@ function framePayload(opcode, payload) {
 /**
  * Narrow RFC 6455 client for the daemon control plane.
  *
- * It intentionally supports only text/control frames, no extensions, and one configured
- * subprotocol. Keeping this transport on Node built-ins preserves the daemon's zero
+ * It intentionally supports only text, binary, and control frames, no extensions, and one
+ * configured subprotocol. Keeping this transport on Node built-ins preserves the daemon's zero
  * production-dependency release invariant.
  */
 export class WebSocketClient extends EventEmitter {
@@ -77,12 +77,15 @@ export class WebSocketClient extends EventEmitter {
             callback?.(new Error("WebSocket is not open"));
             return;
         }
-        const payload = Buffer.from(data, "utf8");
+        const binary = Buffer.isBuffer(data);
+        const payload = binary ? data : Buffer.from(data, "utf8");
         if (payload.length > this.maxPayload) {
             callback?.(new Error("WebSocket payload exceeds configured limit"));
             return;
         }
-        this.socket.write(framePayload(0x1, payload), (error) => callback?.(error ?? undefined));
+        this.socket.write(framePayload(binary ? 0x2 : 0x1, payload), (error) => {
+            callback?.(error ?? undefined);
+        });
     }
     close(code = 1000, reason = "") {
         if (this.readyState === CLOSED)

package/dist/workspace-file-read.d.ts

@@ -0,0 +1,16 @@
+export type WorkspaceFileReadErrorCode = "workspace_file_invalid_request" | "workspace_file_unavailable" | "workspace_file_changed";
+export declare class WorkspaceFileReadError extends Error {
+    readonly code: WorkspaceFileReadErrorCode;
+    constructor(code: WorkspaceFileReadErrorCode);
+}
+export interface WorkspaceFileReadResult {
+    sizeBytes: number;
+    sha256: string;
+    chunkCount: number;
+}
+export declare function readWorkspaceFile(workspaceRoot: string, relativePath: string, options: {
+    maxBytes: number;
+    expectedSizeBytes: number;
+    expectedSha256: string;
+    onChunk(chunkIndex: number, content: Buffer): Promise<void>;
+}): Promise<WorkspaceFileReadResult>;

package/dist/workspace-file-read.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { WORKSPACE_FILE_CHUNK_BYTES } from "./agent-service-ws-protocol.js";
+export class WorkspaceFileReadError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "WorkspaceFileReadError";
+    }
+}
+function relativePathParts(relativePath) {
+    if (!relativePath || path.isAbsolute(relativePath) || relativePath.includes("\\")) {
+        throw new WorkspaceFileReadError("workspace_file_invalid_request");
+    }
+    const parts = relativePath.split("/");
+    if (parts.some((part) => !part || part === "." || part === "..")) {
+        throw new WorkspaceFileReadError("workspace_file_invalid_request");
+    }
+    return parts;
+}
+async function resolveRegularWorkspaceFile(workspaceRoot, relativePath) {
+    const parts = relativePathParts(relativePath);
+    const resolvedRoot = await realpath(workspaceRoot).catch(() => {
+        throw new WorkspaceFileReadError("workspace_file_unavailable");
+    });
+    let candidate = resolvedRoot;
+    for (const part of parts) {
+        candidate = path.join(candidate, part);
+        const metadata = await lstat(candidate).catch(() => {
+            throw new WorkspaceFileReadError("workspace_file_unavailable");
+        });
+        if (metadata.isSymbolicLink()) {
+            throw new WorkspaceFileReadError("workspace_file_unavailable");
+        }
+    }
+    const resolved = await realpath(candidate).catch(() => {
+        throw new WorkspaceFileReadError("workspace_file_unavailable");
+    });
+    if (resolved === resolvedRoot || !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new WorkspaceFileReadError("workspace_file_unavailable");
+    }
+    return resolved;
+}
+export async function readWorkspaceFile(workspaceRoot, relativePath, options) {
+    if (!Number.isSafeInteger(options.maxBytes) ||
+        options.maxBytes < 0 ||
+        !Number.isSafeInteger(options.expectedSizeBytes) ||
+        options.expectedSizeBytes < 0 ||
+        options.expectedSizeBytes > options.maxBytes ||
+        !/^[0-9a-f]{64}$/.test(options.expectedSha256)) {
+        throw new WorkspaceFileReadError("workspace_file_invalid_request");
+    }
+    const resolved = await resolveRegularWorkspaceFile(workspaceRoot, relativePath);
+    let handle;
+    try {
+        handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const metadata = await handle.stat();
+        if (!metadata.isFile())
+            throw new WorkspaceFileReadError("workspace_file_unavailable");
+        if (metadata.size !== options.expectedSizeBytes || metadata.size > options.maxBytes) {
+            throw new WorkspaceFileReadError("workspace_file_changed");
+        }
+        const digest = createHash("sha256");
+        let offset = 0;
+        let chunkCount = 0;
+        while (offset < metadata.size) {
+            const requested = Math.min(WORKSPACE_FILE_CHUNK_BYTES, metadata.size - offset);
+            const buffer = Buffer.allocUnsafe(requested);
+            const { bytesRead } = await handle.read(buffer, 0, requested, offset);
+            if (bytesRead < 1)
+                throw new WorkspaceFileReadError("workspace_file_changed");
+            const content = buffer.subarray(0, bytesRead);
+            digest.update(content);
+            await options.onChunk(chunkCount, content);
+            offset += bytesRead;
+            chunkCount += 1;
+        }
+        const sha256 = digest.digest("hex");
+        if (offset !== options.expectedSizeBytes || sha256 !== options.expectedSha256) {
+            throw new WorkspaceFileReadError("workspace_file_changed");
+        }
+        return { sizeBytes: offset, sha256, chunkCount };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceFileReadError)
+            throw error;
+        throw new WorkspaceFileReadError("workspace_file_unavailable");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}

package/package.json

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