@poolzin/pool-bot 2026.2.0 → 2026.2.1

package/dist/gateway/server-http.js

@@ -1,12 +1,16 @@
 import { createServer as createHttpServer, } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
-import { handleA2uiHttpRequest } from "../canvas-host/a2ui.js";
+import { A2UI_PATH, CANVAS_HOST_PATH, CANVAS_WS_PATH, handleA2uiHttpRequest, } from "../canvas-host/a2ui.js";
 import { loadConfig } from "../config/config.js";
-import { handleSlackHttpRequest } from "../slack/http/index.js";
 import { resolveAgentAvatar } from "../agents/identity-avatar.js";
-import { handleControlUiAvatarRequest, handleControlUiHttpRequest } from "./control-ui.js";
-import { extractHookToken, getHookChannelError, normalizeAgentPayload, normalizeHookHeaders, normalizeWakePayload, readJsonBody, resolveHookChannel, resolveHookDeliver, } from "./hooks.js";
+import { handleSlackHttpRequest } from "../slack/http/index.js";
+import { authorizeGatewayConnect, isLocalDirectRequest } from "./auth.js";
+import { handleControlUiAvatarRequest, handleControlUiHttpRequest, } from "./control-ui.js";
+import { extractHookToken, getHookAgentPolicyError, getHookChannelError, isHookAgentAllowed, normalizeAgentPayload, normalizeHookHeaders, normalizeWakePayload, readJsonBody, resolveHookTargetAgentId, resolveHookChannel, resolveHookDeliver, } from "./hooks.js";
 import { applyHookMappings } from "./hooks-mapping.js";
+import { sendUnauthorized } from "./http-common.js";
+import { getBearerToken, getHeader } from "./http-utils.js";
+import { resolveGatewayClientIp } from "./net.js";
 import { handleOpenAiHttpRequest } from "./openai-http.js";
 import { handleOpenResponsesHttpRequest } from "./openresponses-http.js";
 import { handleToolsInvokeHttpRequest } from "./tools-invoke-http.js";
@@ -15,6 +19,49 @@ function sendJson(res, status, body) {
     res.setHeader("Content-Type", "application/json; charset=utf-8");
     res.end(JSON.stringify(body));
 }
+function isCanvasPath(pathname) {
+    return (pathname === A2UI_PATH ||
+        pathname.startsWith(`${A2UI_PATH}/`) ||
+        pathname === CANVAS_HOST_PATH ||
+        pathname.startsWith(`${CANVAS_HOST_PATH}/`) ||
+        pathname === CANVAS_WS_PATH);
+}
+function hasAuthorizedWsClientForIp(clients, clientIp) {
+    for (const client of clients) {
+        if (client.clientIp && client.clientIp === clientIp) {
+            return true;
+        }
+    }
+    return false;
+}
+async function authorizeCanvasRequest(params) {
+    const { req, auth, trustedProxies, clients } = params;
+    if (isLocalDirectRequest(req, trustedProxies)) {
+        return true;
+    }
+    const token = getBearerToken(req);
+    if (token) {
+        const authResult = await authorizeGatewayConnect({
+            auth: { ...auth, allowTailscale: false },
+            connectAuth: { token, password: token },
+            req,
+            trustedProxies,
+        });
+        if (authResult.ok) {
+            return true;
+        }
+    }
+    const clientIp = resolveGatewayClientIp({
+        remoteAddr: req.socket?.remoteAddress ?? "",
+        forwardedFor: getHeader(req, "x-forwarded-for"),
+        realIp: getHeader(req, "x-real-ip"),
+        trustedProxies,
+    });
+    if (!clientIp) {
+        return false;
+    }
+    return hasAuthorizedWsClientForIp(clients, clientIp);
+}
 export function createHooksRequestHandler(opts) {
     const { getHooksConfig, bindHost, port, logHooks, dispatchAgentHook, dispatchWakeHook } = opts;
     return async (req, res) => {
@@ -26,6 +73,8 @@ export function createHooksRequestHandler(opts) {
         if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) {
             return false;
         }
+        // pool-bot keeps the deprecation-warning approach for query-param tokens
+        // (upstream hard-rejects; we warn and allow for now)
         const { token, fromQuery } = extractHookToken(req, url);
         if (!token || token !== hooksConfig.token) {
             res.statusCode = 401;
@@ -76,7 +125,14 @@ export function createHooksRequestHandler(opts) {
                 sendJson(res, 400, { ok: false, error: normalized.error });
                 return true;
             }
-            const runId = dispatchAgentHook(normalized.value);
+            if (!isHookAgentAllowed(hooksConfig, normalized.value.agentId)) {
+                sendJson(res, 400, { ok: false, error: getHookAgentPolicyError() });
+                return true;
+            }
+            const runId = dispatchAgentHook({
+                ...normalized.value,
+                agentId: resolveHookTargetAgentId(hooksConfig, normalized.value.agentId),
+            });
             sendJson(res, 202, { ok: true, runId });
             return true;
         }
@@ -111,9 +167,14 @@ export function createHooksRequestHandler(opts) {
                         sendJson(res, 400, { ok: false, error: getHookChannelError() });
                         return true;
                     }
+                    if (!isHookAgentAllowed(hooksConfig, mapped.action.agentId)) {
+                        sendJson(res, 400, { ok: false, error: getHookAgentPolicyError() });
+                        return true;
+                    }
                     const runId = dispatchAgentHook({
                         message: mapped.action.message,
                         name: mapped.action.name ?? "Hook",
+                        agentId: resolveHookTargetAgentId(hooksConfig, mapped.action.agentId),
                         wakeMode: mapped.action.wakeMode,
                         sessionKey: mapped.action.sessionKey ?? "",
                         deliver: resolveHookDeliver(mapped.action.deliver),
@@ -141,7 +202,7 @@ export function createHooksRequestHandler(opts) {
     };
 }
 export function createGatewayHttpServer(opts) {
-    const { canvasHost, controlUiEnabled, controlUiBasePath, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, handleHooksRequest, handlePluginRequest, resolvedAuth, } = opts;
+    const { canvasHost, clients, controlUiEnabled, controlUiBasePath, controlUiRoot, openAiChatCompletionsEnabled, openResponsesEnabled, openResponsesConfig, handleHooksRequest, handlePluginRequest, resolvedAuth, } = opts;
     const httpServer = opts.tlsOptions
         ? createHttpsServer(opts.tlsOptions, (req, res) => {
             void handleRequest(req, res);
@@ -183,6 +244,19 @@ export function createGatewayHttpServer(opts) {
                     return;
             }
             if (canvasHost) {
+                const url = new URL(req.url ?? "/", "http://localhost");
+                if (isCanvasPath(url.pathname)) {
+                    const ok = await authorizeCanvasRequest({
+                        req,
+                        auth: resolvedAuth,
+                        trustedProxies,
+                        clients,
+                    });
+                    if (!ok) {
+                        sendUnauthorized(res);
+                        return;
+                    }
+                }
                 if (await handleA2uiHttpRequest(req, res))
                     return;
                 if (await canvasHost.handleHttpRequest(req, res))
@@ -197,6 +271,7 @@ export function createGatewayHttpServer(opts) {
                 if (handleControlUiHttpRequest(req, res, {
                     basePath: controlUiBasePath,
                     config: configSnapshot,
+                    root: controlUiRoot,
                 }))
                     return;
             }
@@ -213,12 +288,35 @@ export function createGatewayHttpServer(opts) {
     return httpServer;
 }
 export function attachGatewayUpgradeHandler(opts) {
-    const { httpServer, wss, canvasHost } = opts;
+    const { httpServer, wss, canvasHost, clients, resolvedAuth } = opts;
     httpServer.on("upgrade", (req, socket, head) => {
-        if (canvasHost?.handleUpgrade(req, socket, head))
-            return;
-        wss.handleUpgrade(req, socket, head, (ws) => {
-            wss.emit("connection", ws, req);
+        void (async () => {
+            if (canvasHost) {
+                const url = new URL(req.url ?? "/", "http://localhost");
+                if (url.pathname === CANVAS_WS_PATH) {
+                    const configSnapshot = loadConfig();
+                    const trustedProxies = configSnapshot.gateway?.trustedProxies ?? [];
+                    const ok = await authorizeCanvasRequest({
+                        req,
+                        auth: resolvedAuth,
+                        trustedProxies,
+                        clients,
+                    });
+                    if (!ok) {
+                        socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+                        socket.destroy();
+                        return;
+                    }
+                }
+                if (canvasHost.handleUpgrade(req, socket, head)) {
+                    return;
+                }
+            }
+            wss.handleUpgrade(req, socket, head, (ws) => {
+                wss.emit("connection", ws, req);
+            });
+        })().catch(() => {
+            socket.destroy();
         });
     });
 }

package/dist/gateway/server-methods/agent-timestamp.js

@@ -0,0 +1,60 @@
+import { resolveUserTimezone } from "../../agents/date-time.js";
+import { formatZonedTimestamp } from "../../infra/format-time/format-datetime.js";
+/**
+ * Cron jobs inject "Current time: ..." into their messages.
+ * Skip injection for those.
+ */
+const CRON_TIME_PATTERN = /Current time: /;
+/**
+ * Matches a leading `[... YYYY-MM-DD HH:MM ...]` envelope -- either from
+ * channel plugins or from a previous injection. Uses the same YYYY-MM-DD
+ * HH:MM format as {@link formatZonedTimestamp}, so detection stays in sync
+ * with the formatting.
+ */
+const TIMESTAMP_ENVELOPE_PATTERN = /^\[.*\d{4}-\d{2}-\d{2} \d{2}:\d{2}/;
+/**
+ * Injects a compact timestamp prefix into a message if one isn't already
+ * present. Uses the same `YYYY-MM-DD HH:MM TZ` format as channel envelope
+ * timestamps ({@link formatZonedTimestamp}), keeping token cost low (~7
+ * tokens) and format consistent across all agent contexts.
+ *
+ * Used by the gateway `agent` and `chat.send` handlers to give TUI, web,
+ * spawned subagents, `sessions_send`, and heartbeat wake events date/time
+ * awareness -- without modifying the system prompt (which is cached).
+ *
+ * Channel messages (Discord, Telegram, etc.) already have timestamps via
+ * envelope formatting and take a separate code path -- they never reach
+ * these handlers, so there is no double-stamping risk. The detection
+ * pattern is a safety net for edge cases.
+ */
+export function injectTimestamp(message, opts) {
+    if (!message.trim()) {
+        return message;
+    }
+    // Already has an envelope or injected timestamp
+    if (TIMESTAMP_ENVELOPE_PATTERN.test(message)) {
+        return message;
+    }
+    // Already has a cron-injected timestamp
+    if (CRON_TIME_PATTERN.test(message)) {
+        return message;
+    }
+    const now = opts?.now ?? new Date();
+    const timezone = opts?.timezone ?? "UTC";
+    const formatted = formatZonedTimestamp(now, { timeZone: timezone });
+    if (!formatted) {
+        return message;
+    }
+    // 3-letter DOW: small models (8B) can't reliably derive day-of-week from
+    // a date, and may treat a bare "Wed" as a typo. Costs ~1 token.
+    const dow = new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "short" }).format(now);
+    return `[${dow} ${formatted}] ${message}`;
+}
+/**
+ * Build TimestampInjectionOptions from a PoolBotConfig.
+ */
+export function timestampOptsFromConfig(cfg) {
+    return {
+        timezone: resolveUserTimezone(cfg.agents?.defaults?.userTimezone),
+    };
+}

package/dist/gateway/server-methods/agents.js

@@ -1,6 +1,119 @@
-import { loadConfig } from "../../config/config.js";
-import { ErrorCodes, errorShape, formatValidationErrors, validateAgentsListParams, } from "../protocol/index.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { listAgentIds, resolveAgentDir, resolveAgentWorkspaceDir, } from "../../agents/agent-scope.js";
+import { DEFAULT_AGENTS_FILENAME, DEFAULT_BOOTSTRAP_FILENAME, DEFAULT_HEARTBEAT_FILENAME, DEFAULT_IDENTITY_FILENAME, DEFAULT_MEMORY_ALT_FILENAME, DEFAULT_MEMORY_FILENAME, DEFAULT_SOUL_FILENAME, DEFAULT_TOOLS_FILENAME, DEFAULT_USER_FILENAME, ensureAgentWorkspace, } from "../../agents/workspace.js";
+import { movePathToTrash } from "../../browser/trash.js";
+import { applyAgentConfig, findAgentEntryIndex, listAgentEntries, pruneAgentConfig, } from "../../commands/agents.config.js";
+import { loadConfig, writeConfigFile } from "../../config/config.js";
+import { resolveSessionTranscriptsDirForAgent } from "../../config/sessions/paths.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../routing/session-key.js";
+import { resolveUserPath } from "../../utils.js";
+import { ErrorCodes, errorShape, formatValidationErrors, validateAgentsCreateParams, validateAgentsDeleteParams, validateAgentsFilesGetParams, validateAgentsFilesListParams, validateAgentsFilesSetParams, validateAgentsListParams, validateAgentsUpdateParams, } from "../protocol/index.js";
 import { listAgentsForGateway } from "../session-utils.js";
+const BOOTSTRAP_FILE_NAMES = [
+    DEFAULT_AGENTS_FILENAME,
+    DEFAULT_SOUL_FILENAME,
+    DEFAULT_TOOLS_FILENAME,
+    DEFAULT_IDENTITY_FILENAME,
+    DEFAULT_USER_FILENAME,
+    DEFAULT_HEARTBEAT_FILENAME,
+    DEFAULT_BOOTSTRAP_FILENAME,
+];
+const MEMORY_FILE_NAMES = [DEFAULT_MEMORY_FILENAME, DEFAULT_MEMORY_ALT_FILENAME];
+const ALLOWED_FILE_NAMES = new Set([...BOOTSTRAP_FILE_NAMES, ...MEMORY_FILE_NAMES]);
+async function statFile(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        if (!stat.isFile()) {
+            return null;
+        }
+        return {
+            size: stat.size,
+            updatedAtMs: Math.floor(stat.mtimeMs),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function listAgentFiles(workspaceDir) {
+    const files = [];
+    for (const name of BOOTSTRAP_FILE_NAMES) {
+        const filePath = path.join(workspaceDir, name);
+        const meta = await statFile(filePath);
+        if (meta) {
+            files.push({
+                name,
+                path: filePath,
+                missing: false,
+                size: meta.size,
+                updatedAtMs: meta.updatedAtMs,
+            });
+        }
+        else {
+            files.push({ name, path: filePath, missing: true });
+        }
+    }
+    const primaryMemoryPath = path.join(workspaceDir, DEFAULT_MEMORY_FILENAME);
+    const primaryMeta = await statFile(primaryMemoryPath);
+    if (primaryMeta) {
+        files.push({
+            name: DEFAULT_MEMORY_FILENAME,
+            path: primaryMemoryPath,
+            missing: false,
+            size: primaryMeta.size,
+            updatedAtMs: primaryMeta.updatedAtMs,
+        });
+    }
+    else {
+        const altMemoryPath = path.join(workspaceDir, DEFAULT_MEMORY_ALT_FILENAME);
+        const altMeta = await statFile(altMemoryPath);
+        if (altMeta) {
+            files.push({
+                name: DEFAULT_MEMORY_ALT_FILENAME,
+                path: altMemoryPath,
+                missing: false,
+                size: altMeta.size,
+                updatedAtMs: altMeta.updatedAtMs,
+            });
+        }
+        else {
+            files.push({ name: DEFAULT_MEMORY_FILENAME, path: primaryMemoryPath, missing: true });
+        }
+    }
+    return files;
+}
+function resolveAgentIdOrError(agentIdRaw, cfg) {
+    const agentId = normalizeAgentId(agentIdRaw);
+    const allowed = new Set(listAgentIds(cfg));
+    if (!allowed.has(agentId)) {
+        return null;
+    }
+    return agentId;
+}
+function sanitizeIdentityLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function resolveOptionalStringParam(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+async function moveToTrashBestEffort(pathname) {
+    if (!pathname) {
+        return;
+    }
+    try {
+        await fs.access(pathname);
+    }
+    catch {
+        return;
+    }
+    try {
+        await movePathToTrash(pathname);
+    }
+    catch {
+        // Best-effort: path may already be gone or trash unavailable.
+    }
+}
 export const agentsHandlers = {
     "agents.list": ({ params, respond }) => {
         if (!validateAgentsListParams(params)) {
@@ -11,4 +124,210 @@ export const agentsHandlers = {
         const result = listAgentsForGateway(cfg);
         respond(true, result, undefined);
     },
+    "agents.create": async ({ params, respond }) => {
+        if (!validateAgentsCreateParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.create params: ${formatValidationErrors(validateAgentsCreateParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const rawName = String(params.name ?? "").trim();
+        const agentId = normalizeAgentId(rawName);
+        if (agentId === DEFAULT_AGENT_ID) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `"${DEFAULT_AGENT_ID}" is reserved`));
+            return;
+        }
+        if (findAgentEntryIndex(listAgentEntries(cfg), agentId) >= 0) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `agent "${agentId}" already exists`));
+            return;
+        }
+        const workspaceDir = resolveUserPath(String(params.workspace ?? "").trim());
+        // Resolve agentDir against the config we're about to persist (vs the pre-write config),
+        // so subsequent resolutions can't disagree about the agent's directory.
+        let nextConfig = applyAgentConfig(cfg, {
+            agentId,
+            name: rawName,
+            workspace: workspaceDir,
+        });
+        const agentDir = resolveAgentDir(nextConfig, agentId);
+        nextConfig = applyAgentConfig(nextConfig, { agentId, agentDir });
+        // Ensure workspace & transcripts exist BEFORE writing config so a failure
+        // here does not leave a broken config entry behind.
+        const skipBootstrap = Boolean(nextConfig.agents?.defaults?.skipBootstrap);
+        await ensureAgentWorkspace({ dir: workspaceDir, ensureBootstrapFiles: !skipBootstrap });
+        await fs.mkdir(resolveSessionTranscriptsDirForAgent(agentId), { recursive: true });
+        await writeConfigFile(nextConfig);
+        // Always write Name to IDENTITY.md; optionally include emoji/avatar.
+        const safeName = sanitizeIdentityLine(rawName);
+        const emoji = resolveOptionalStringParam(params.emoji);
+        const avatar = resolveOptionalStringParam(params.avatar);
+        const identityPath = path.join(workspaceDir, DEFAULT_IDENTITY_FILENAME);
+        const lines = [
+            "",
+            `- Name: ${safeName}`,
+            ...(emoji ? [`- Emoji: ${sanitizeIdentityLine(emoji)}`] : []),
+            ...(avatar ? [`- Avatar: ${sanitizeIdentityLine(avatar)}`] : []),
+            "",
+        ];
+        await fs.appendFile(identityPath, lines.join("\n"), "utf-8");
+        respond(true, { ok: true, agentId, name: rawName, workspace: workspaceDir }, undefined);
+    },
+    "agents.update": async ({ params, respond }) => {
+        if (!validateAgentsUpdateParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.update params: ${formatValidationErrors(validateAgentsUpdateParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = normalizeAgentId(String(params.agentId ?? ""));
+        if (findAgentEntryIndex(listAgentEntries(cfg), agentId) < 0) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `agent "${agentId}" not found`));
+            return;
+        }
+        const workspaceDir = typeof params.workspace === "string" && params.workspace.trim()
+            ? resolveUserPath(params.workspace.trim())
+            : undefined;
+        const model = resolveOptionalStringParam(params.model);
+        const avatar = resolveOptionalStringParam(params.avatar);
+        const nextConfig = applyAgentConfig(cfg, {
+            agentId,
+            ...(typeof params.name === "string" && params.name.trim()
+                ? { name: params.name.trim() }
+                : {}),
+            ...(workspaceDir ? { workspace: workspaceDir } : {}),
+            ...(model ? { model } : {}),
+        });
+        await writeConfigFile(nextConfig);
+        if (workspaceDir) {
+            const skipBootstrap = Boolean(nextConfig.agents?.defaults?.skipBootstrap);
+            await ensureAgentWorkspace({ dir: workspaceDir, ensureBootstrapFiles: !skipBootstrap });
+        }
+        if (avatar) {
+            const workspace = workspaceDir ?? resolveAgentWorkspaceDir(nextConfig, agentId);
+            await fs.mkdir(workspace, { recursive: true });
+            const identityPath = path.join(workspace, DEFAULT_IDENTITY_FILENAME);
+            await fs.appendFile(identityPath, `\n- Avatar: ${sanitizeIdentityLine(avatar)}\n`, "utf-8");
+        }
+        respond(true, { ok: true, agentId }, undefined);
+    },
+    "agents.delete": async ({ params, respond }) => {
+        if (!validateAgentsDeleteParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.delete params: ${formatValidationErrors(validateAgentsDeleteParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = normalizeAgentId(String(params.agentId ?? ""));
+        if (agentId === DEFAULT_AGENT_ID) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `"${DEFAULT_AGENT_ID}" cannot be deleted`));
+            return;
+        }
+        if (findAgentEntryIndex(listAgentEntries(cfg), agentId) < 0) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `agent "${agentId}" not found`));
+            return;
+        }
+        const deleteFiles = typeof params.deleteFiles === "boolean" ? params.deleteFiles : true;
+        const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+        const agentDir = resolveAgentDir(cfg, agentId);
+        const sessionsDir = resolveSessionTranscriptsDirForAgent(agentId);
+        const result = pruneAgentConfig(cfg, agentId);
+        await writeConfigFile(result.config);
+        if (deleteFiles) {
+            await Promise.all([
+                moveToTrashBestEffort(workspaceDir),
+                moveToTrashBestEffort(agentDir),
+                moveToTrashBestEffort(sessionsDir),
+            ]);
+        }
+        respond(true, { ok: true, agentId, removedBindings: result.removedBindings }, undefined);
+    },
+    "agents.files.list": async ({ params, respond }) => {
+        if (!validateAgentsFilesListParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.files.list params: ${formatValidationErrors(validateAgentsFilesListParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = resolveAgentIdOrError(String(params.agentId ?? ""), cfg);
+        if (!agentId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "unknown agent id"));
+            return;
+        }
+        const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+        const files = await listAgentFiles(workspaceDir);
+        respond(true, { agentId, workspace: workspaceDir, files }, undefined);
+    },
+    "agents.files.get": async ({ params, respond }) => {
+        if (!validateAgentsFilesGetParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.files.get params: ${formatValidationErrors(validateAgentsFilesGetParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = resolveAgentIdOrError(String(params.agentId ?? ""), cfg);
+        if (!agentId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "unknown agent id"));
+            return;
+        }
+        const name = String(params.name ?? "").trim();
+        if (!ALLOWED_FILE_NAMES.has(name)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `unsupported file "${name}"`));
+            return;
+        }
+        const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+        const filePath = path.join(workspaceDir, name);
+        const meta = await statFile(filePath);
+        if (!meta) {
+            respond(true, {
+                agentId,
+                workspace: workspaceDir,
+                file: { name, path: filePath, missing: true },
+            }, undefined);
+            return;
+        }
+        const content = await fs.readFile(filePath, "utf-8");
+        respond(true, {
+            agentId,
+            workspace: workspaceDir,
+            file: {
+                name,
+                path: filePath,
+                missing: false,
+                size: meta.size,
+                updatedAtMs: meta.updatedAtMs,
+                content,
+            },
+        }, undefined);
+    },
+    "agents.files.set": async ({ params, respond }) => {
+        if (!validateAgentsFilesSetParams(params)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `invalid agents.files.set params: ${formatValidationErrors(validateAgentsFilesSetParams.errors)}`));
+            return;
+        }
+        const cfg = loadConfig();
+        const agentId = resolveAgentIdOrError(String(params.agentId ?? ""), cfg);
+        if (!agentId) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "unknown agent id"));
+            return;
+        }
+        const name = String(params.name ?? "").trim();
+        if (!ALLOWED_FILE_NAMES.has(name)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, `unsupported file "${name}"`));
+            return;
+        }
+        const workspaceDir = resolveAgentWorkspaceDir(cfg, agentId);
+        await fs.mkdir(workspaceDir, { recursive: true });
+        const filePath = path.join(workspaceDir, name);
+        const content = String(params.content ?? "");
+        await fs.writeFile(filePath, content, "utf-8");
+        const meta = await statFile(filePath);
+        respond(true, {
+            ok: true,
+            agentId,
+            workspace: workspaceDir,
+            file: {
+                name,
+                path: filePath,
+                missing: false,
+                size: meta?.size,
+                updatedAtMs: meta?.updatedAtMs,
+                content,
+            },
+        }, undefined);
+    },
 };