@syengup/friday-channel-next 0.1.30 → 0.1.37

package/dist/src/http/handlers/agent-config.js

@@ -0,0 +1,188 @@
+/**
+ * GET/PUT /friday-next/agents/{id}/config
+ *
+ * Reads and edits a single agent's runtime configuration — the same fields
+ * OpenClaw's ControlUI manages, but written through the plugin's own config
+ * channel (`api.runtime.config.mutateConfigFile`, proven by plugin-upgrade) so
+ * NO OpenClaw core changes are needed. All edits land in `agents.list[]` of the
+ * host config file (`~/.clawrc`), exactly where ControlUI's `config.set` writes.
+ *
+ * Editable fields:
+ *  - model           → agents.list[i].model        (string | {primary,fallbacks})
+ *  - thinkingDefault → agents.list[i].thinkingDefault
+ *  - tools           → agents.list[i].tools        ({profile,allow,alsoAllow,deny})
+ *  - skills          → agents.list[i].skills       (string[]; [] disables all, absent inherits defaults)
+ *
+ * Clearing an override MUST delete the field (not leave a stale value) so the
+ * core's config merge falls back to `agents.defaults` — same hazard documented
+ * for the default-model bug. PUT therefore treats an explicit `null` as "clear".
+ */
+import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
+import { getUpgradeRuntime } from "../../upgrade-runtime.js";
+import { normalizeAgentId } from "../../agent-id.js";
+import { discoverAvailableSkills } from "../../skills-discovery.js";
+import { extractBearerToken } from "../middleware/auth.js";
+import { readJsonBody } from "../middleware/body.js";
+import { createFridayNextLogger } from "../../logging.js";
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(body));
+    return true;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readStringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value
+        .filter((v) => typeof v === "string" && v.trim().length > 0)
+        .map((v) => v.trim());
+    return out;
+}
+function readToolsConfig(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const t = value;
+    const view = {};
+    const profile = readString(t.profile);
+    if (profile)
+        view.profile = profile;
+    const allow = readStringArray(t.allow);
+    if (allow)
+        view.allow = allow;
+    const alsoAllow = readStringArray(t.alsoAllow);
+    if (alsoAllow)
+        view.alsoAllow = alsoAllow;
+    const deny = readStringArray(t.deny);
+    if (deny)
+        view.deny = deny;
+    return view;
+}
+/** Locate the configured `agents.list[]` entry whose normalized id matches `agentId`. */
+function findAgentEntry(cfg, agentId) {
+    const agents = cfg?.agents;
+    const list = agents?.list;
+    if (!Array.isArray(list))
+        return undefined;
+    return list.find((a) => a && typeof a === "object" && normalizeAgentId(a.id) === agentId);
+}
+function buildConfigView(agentId) {
+    const rt = getFridayAgentForwardRuntime();
+    const cfg = rt?.getConfig();
+    const entry = cfg ? findAgentEntry(cfg, agentId) : undefined;
+    return {
+        id: agentId,
+        exists: entry !== undefined,
+        model: entry?.model,
+        thinkingDefault: readString(entry?.thinkingDefault),
+        tools: readToolsConfig(entry?.tools),
+        // undefined = no `skills` field (inherit defaults); [] = field present but empty (all disabled).
+        skills: readStringArray(entry?.skills),
+        availableSkills: discoverAvailableSkills(cfg, agentId),
+    };
+}
+function readPatch(body, key, coerce) {
+    if (!(key in body))
+        return { sent: false, clear: false };
+    const raw = body[key];
+    if (raw === null)
+        return { sent: true, clear: true };
+    const value = coerce(raw);
+    if (value === undefined)
+        return { sent: false, clear: false };
+    return { sent: true, clear: false, value };
+}
+function coerceModel(raw) {
+    if (typeof raw === "string")
+        return raw.trim() || undefined;
+    if (raw && typeof raw === "object") {
+        const primary = readString(raw.primary);
+        if (!primary)
+            return undefined;
+        const fallbacks = readStringArray(raw.fallbacks);
+        return fallbacks && fallbacks.length > 0 ? { primary, fallbacks } : { primary };
+    }
+    return undefined;
+}
+function coerceTools(raw) {
+    return readToolsConfig(raw);
+}
+/** Skills: array (incl. empty = disable all) only; non-arrays are rejected upstream. */
+function coerceSkills(raw) {
+    return Array.isArray(raw) ? (readStringArray(raw) ?? []) : undefined;
+}
+// --- handler -----------------------------------------------------------------
+export async function handleAgentConfig(req, res, rawAgentId) {
+    if (req.method !== "GET" && req.method !== "PUT") {
+        return json(res, 405, { error: "Method Not Allowed" });
+    }
+    if (!extractBearerToken(req)) {
+        return json(res, 401, { error: "Unauthorized: bearer token mismatch" });
+    }
+    const agentId = normalizeAgentId(rawAgentId);
+    if (req.method === "GET") {
+        return json(res, 200, { ok: true, ...buildConfigView(agentId) });
+    }
+    // PUT — partial patch.
+    const body = await readJsonBody(req);
+    if (!body)
+        return json(res, 400, { error: "Invalid or missing JSON body" });
+    const model = readPatch(body, "model", coerceModel);
+    const thinkingDefault = readPatch(body, "thinkingDefault", (r) => readString(r));
+    const tools = readPatch(body, "tools", coerceTools);
+    const skills = readPatch(body, "skills", coerceSkills);
+    if ("skills" in body && body.skills !== null && !Array.isArray(body.skills)) {
+        return json(res, 400, {
+            error: "skills must be an array of skill ids, [] to disable all, or null to inherit defaults",
+        });
+    }
+    if (!model.sent && !thinkingDefault.sent && !tools.sent && !skills.sent) {
+        return json(res, 400, {
+            error: "No editable fields provided (model, thinkingDefault, tools, skills)",
+        });
+    }
+    const upgrade = getUpgradeRuntime();
+    if (!upgrade)
+        return json(res, 503, { error: "Config write runtime unavailable" });
+    const log = createFridayNextLogger("agent-config");
+    try {
+        await upgrade.mutateConfigFile({
+            afterWrite: { mode: "auto" },
+            mutate: (draftRaw) => {
+                const draft = draftRaw;
+                const agents = (draft.agents ??= {});
+                const list = (agents.list ??= []);
+                let entry = list.find((a) => a && typeof a === "object" && normalizeAgentId(a.id) === agentId);
+                if (!entry) {
+                    // Implicit agent (e.g. "main") with no list entry yet — create a bare one.
+                    // Never set `default: true`: that would change default-agent resolution.
+                    entry = { id: agentId };
+                    list.push(entry);
+                }
+                applyField(entry, "model", model);
+                applyField(entry, "thinkingDefault", thinkingDefault);
+                applyField(entry, "tools", tools);
+                applyField(entry, "skills", skills);
+            },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`agent config write failed for "${agentId}": ${msg}`);
+        return json(res, 500, { error: "Failed to write agent config", detail: msg });
+    }
+    log.info(`agent config updated for "${agentId}"`);
+    return json(res, 200, { ok: true, ...buildConfigView(agentId) });
+}
+/** Apply a patch: clear → delete the key; set → assign; not sent → leave as-is. */
+function applyField(entry, key, patch) {
+    if (!patch.sent)
+        return;
+    if (patch.clear) {
+        delete entry[key];
+        return;
+    }
+    entry[key] = patch.value;
+}

package/dist/src/http/handlers/agent-files.d.ts

@@ -0,0 +1,21 @@
+/**
+ * GET/PUT /friday-next/agents/{id}/files[/{name}]
+ *
+ * Reads and edits an agent's core workspace files — the same whitelist ControlUI
+ * exposes (AGENTS/IDENTITY/SOUL/TOOLS/MEMORY/USER/HEARTBEAT/BOOTSTRAP.md). These
+ * are plain workspace files, not config: written directly via Node fs into the
+ * dir resolved by `api.runtime.agent.resolveAgentWorkspaceDir` (the same call
+ * agents-list uses to read IDENTITY.md). No config mutation, no gateway restart —
+ * the agent re-reads them on its next run.
+ *
+ *  - GET  /agents/{id}/files          → status of every whitelist file
+ *  - GET  /agents/{id}/files/{name}   → one file's content
+ *  - PUT  /agents/{id}/files/{name}   → write one file (body: { content })
+ *
+ * Security: the file name MUST be in the whitelist (no path traversal), and the
+ * resolved path is re-checked to stay inside the workspace dir as defense in depth.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Core workspace files an agent edits, mirroring ControlUI's `agents.files` whitelist. */
+export declare const CORE_AGENT_FILES: readonly ["AGENTS.md", "IDENTITY.md", "SOUL.md", "TOOLS.md", "MEMORY.md", "USER.md", "HEARTBEAT.md", "BOOTSTRAP.md"];
+export declare function handleAgentFiles(req: IncomingMessage, res: ServerResponse, rawAgentId: string, fileName: string | undefined): Promise<boolean>;

package/dist/src/http/handlers/agent-files.js

@@ -0,0 +1,137 @@
+/**
+ * GET/PUT /friday-next/agents/{id}/files[/{name}]
+ *
+ * Reads and edits an agent's core workspace files — the same whitelist ControlUI
+ * exposes (AGENTS/IDENTITY/SOUL/TOOLS/MEMORY/USER/HEARTBEAT/BOOTSTRAP.md). These
+ * are plain workspace files, not config: written directly via Node fs into the
+ * dir resolved by `api.runtime.agent.resolveAgentWorkspaceDir` (the same call
+ * agents-list uses to read IDENTITY.md). No config mutation, no gateway restart —
+ * the agent re-reads them on its next run.
+ *
+ *  - GET  /agents/{id}/files          → status of every whitelist file
+ *  - GET  /agents/{id}/files/{name}   → one file's content
+ *  - PUT  /agents/{id}/files/{name}   → write one file (body: { content })
+ *
+ * Security: the file name MUST be in the whitelist (no path traversal), and the
+ * resolved path is re-checked to stay inside the workspace dir as defense in depth.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
+import { normalizeAgentId } from "../../agent-id.js";
+import { extractBearerToken } from "../middleware/auth.js";
+import { readJsonBody } from "../middleware/body.js";
+import { createFridayNextLogger } from "../../logging.js";
+/** Core workspace files an agent edits, mirroring ControlUI's `agents.files` whitelist. */
+export const CORE_AGENT_FILES = [
+    "AGENTS.md",
+    "IDENTITY.md",
+    "SOUL.md",
+    "TOOLS.md",
+    "MEMORY.md",
+    "USER.md",
+    "HEARTBEAT.md",
+    "BOOTSTRAP.md",
+];
+const CORE_FILE_SET = new Set(CORE_AGENT_FILES);
+/** Max core-file size on write (256 KiB) — these are prompts, not data dumps. */
+const MAX_FILE_BYTES = 256 * 1024;
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(body));
+    return true;
+}
+/** Resolve the agent's workspace dir, or undefined if the runtime can't. */
+function resolveWorkspace(agentId) {
+    const rt = getFridayAgentForwardRuntime();
+    if (!rt?.resolveAgentWorkspaceDir)
+        return undefined;
+    try {
+        const dir = rt.resolveAgentWorkspaceDir(rt.getConfig(), agentId);
+        return dir || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whitelisted, traversal-safe absolute path for `name` inside `workspace`, or null. */
+function safeFilePath(workspace, name) {
+    if (!CORE_FILE_SET.has(name))
+        return null;
+    const resolved = path.resolve(workspace, name);
+    // Defense in depth: the resolved path must sit directly inside the workspace.
+    if (path.dirname(resolved) !== path.resolve(workspace))
+        return null;
+    return resolved;
+}
+export async function handleAgentFiles(req, res, rawAgentId, fileName) {
+    const method = req.method;
+    if (method !== "GET" && method !== "PUT") {
+        return json(res, 405, { error: "Method Not Allowed" });
+    }
+    if (!extractBearerToken(req)) {
+        return json(res, 401, { error: "Unauthorized: bearer token mismatch" });
+    }
+    const agentId = normalizeAgentId(rawAgentId);
+    const workspace = resolveWorkspace(agentId);
+    if (!workspace)
+        return json(res, 503, { error: "Agent workspace not resolvable" });
+    // GET /files — list whitelist status.
+    if (method === "GET" && !fileName) {
+        const files = CORE_AGENT_FILES.map((name) => {
+            try {
+                const stat = fs.statSync(path.join(workspace, name));
+                return { name, exists: true, bytes: stat.size };
+            }
+            catch {
+                return { name, exists: false, bytes: 0 };
+            }
+        });
+        return json(res, 200, { ok: true, id: agentId, files });
+    }
+    if (!fileName || !CORE_FILE_SET.has(fileName)) {
+        return json(res, 400, {
+            error: `Unknown core file; allowed: ${CORE_AGENT_FILES.join(", ")}`,
+        });
+    }
+    const filePath = safeFilePath(workspace, fileName);
+    if (!filePath)
+        return json(res, 400, { error: "Invalid file name" });
+    if (method === "GET") {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            return json(res, 200, { ok: true, id: agentId, name: fileName, exists: true, content });
+        }
+        catch {
+            return json(res, 200, { ok: true, id: agentId, name: fileName, exists: false, content: "" });
+        }
+    }
+    // PUT — write content.
+    const body = await readJsonBody(req);
+    if (!body || typeof body.content !== "string") {
+        return json(res, 400, { error: "Missing required field: content (string)" });
+    }
+    const content = body.content;
+    if (Buffer.byteLength(content, "utf-8") > MAX_FILE_BYTES) {
+        return json(res, 413, { error: `content exceeds ${MAX_FILE_BYTES} bytes` });
+    }
+    const log = createFridayNextLogger("agent-files");
+    try {
+        fs.mkdirSync(workspace, { recursive: true });
+        fs.writeFileSync(filePath, content, "utf-8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`write ${fileName} for "${agentId}" failed: ${msg}`);
+        return json(res, 500, { error: "Failed to write file", detail: msg });
+    }
+    log.info(`wrote ${fileName} for "${agentId}" (${Buffer.byteLength(content, "utf-8")} bytes)`);
+    return json(res, 200, {
+        ok: true,
+        id: agentId,
+        name: fileName,
+        exists: true,
+        bytes: Buffer.byteLength(content, "utf-8"),
+    });
+}

package/dist/src/http/handlers/agent-tools-catalog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * GET /friday-next/agents/{id}/tools/catalog
+ *
+ * Returns the agent's full tool catalog (core + plugin tools, grouped by category,
+ * with descriptions, profiles, and per-tool effective `enabled`/`inProfile` state) for
+ * the app's toolbox editor — mirroring ControlUI. Edits are saved via the existing
+ * `PUT /agents/{id}/config` (tools.{profile,allow,alsoAllow,deny}).
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function handleAgentToolsCatalog(req: IncomingMessage, res: ServerResponse, rawAgentId: string): Promise<boolean>;

package/dist/src/http/handlers/agent-tools-catalog.js

@@ -0,0 +1,33 @@
+/**
+ * GET /friday-next/agents/{id}/tools/catalog
+ *
+ * Returns the agent's full tool catalog (core + plugin tools, grouped by category,
+ * with descriptions, profiles, and per-tool effective `enabled`/`inProfile` state) for
+ * the app's toolbox editor — mirroring ControlUI. Edits are saved via the existing
+ * `PUT /agents/{id}/config` (tools.{profile,allow,alsoAllow,deny}).
+ */
+import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
+import { normalizeAgentId } from "../../agent-id.js";
+import { buildAgentToolsCatalog } from "../../tool-catalog.js";
+import { extractBearerToken } from "../middleware/auth.js";
+function json(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(body));
+    return true;
+}
+export async function handleAgentToolsCatalog(req, res, rawAgentId) {
+    if (req.method !== "GET") {
+        return json(res, 405, { error: "Method Not Allowed" });
+    }
+    if (!extractBearerToken(req)) {
+        return json(res, 401, { error: "Unauthorized: bearer token mismatch" });
+    }
+    const agentId = normalizeAgentId(rawAgentId);
+    const cfg = getFridayAgentForwardRuntime()?.getConfig();
+    const catalog = await buildAgentToolsCatalog(cfg, agentId);
+    if (!catalog) {
+        return json(res, 503, { error: "Tool catalog unavailable" });
+    }
+    return json(res, 200, { ok: true, id: agentId, ...catalog });
+}

package/dist/src/http/handlers/agents-list.js

@@ -2,25 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { getFridayAgentForwardRuntime, } from "../../agent-forward-runtime.js";
 import { extractBearerToken } from "../middleware/auth.js";
-const DEFAULT_AGENT_ID = "main";
-/** Agent ids already in path/shell-safe form skip the slug rewrite below. */
-const SAFE_AGENT_ID = /^[a-z0-9][a-z0-9_-]*$/;
-/**
- * Mirror of OpenClaw's `normalizeAgentId` (src/routing/session-key.ts): trim,
- * lowercase, keep path/shell-safe. Empty → "main".
- */
-function normalizeAgentId(value) {
-    const trimmed = typeof value === "string" ? value.trim() : "";
-    if (!trimmed)
-        return DEFAULT_AGENT_ID;
-    const lowered = trimmed.toLowerCase();
-    if (SAFE_AGENT_ID.test(lowered))
-        return lowered;
-    return (lowered
-        .replace(/[^a-z0-9_-]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 64) || DEFAULT_AGENT_ID);
-}
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../agent-id.js";
 /** Extract a primary model ref from the `model` field (string or {primary,...}). */
 function resolvePrimaryModel(model) {
     if (typeof model === "string")

package/dist/src/http/handlers/cancel.js

@@ -1,4 +1,5 @@
-import { abortRun } from "../../agent/abort-run.js";
+import { abortRunForSessionKey } from "../../agent/abort-run.js";
+import { getRunRoute } from "../../run-metadata.js";
 import { sseEmitter } from "../../sse/emitter.js";
 import { readJsonBody } from "../middleware/body.js";
 import { extractBearerToken } from "../middleware/auth.js";
@@ -18,16 +19,23 @@ export async function handleCancel(req, res) {
     }
     const body = await readJsonBody(req);
     const runId = typeof body?.runId === "string" ? body.runId.trim() : "";
-    if (!runId) {
+    // sessionKey is the primary identifier (one active run per session); runId is a
+    // back-compat fallback for older apps — resolve it to a sessionKey via the run route.
+    const sessionKey = (typeof body?.sessionKey === "string" ? body.sessionKey.trim() : "") ||
+        (runId ? (getRunRoute(runId)?.sessionKey?.trim() ?? "") : "");
+    if (!sessionKey && !runId) {
         res.statusCode = 400;
         res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify({ error: "Missing runId" }));
+        res.end(JSON.stringify({ error: "Missing sessionKey or runId" }));
         return true;
     }
-    await abortRun(runId);
-    sseEmitter.untrackRun(runId);
+    const result = sessionKey
+        ? await abortRunForSessionKey(sessionKey)
+        : { aborted: false, drained: false };
+    if (runId)
+        sseEmitter.untrackRun(runId);
     res.statusCode = 200;
     res.setHeader("Content-Type", "application/json");
-    res.end(JSON.stringify({ ok: true, runId, cancelled: true }));
+    res.end(JSON.stringify({ ok: true, sessionKey, runId, cancelled: true, ...result }));
     return true;
 }

package/dist/src/http/handlers/device-approve.js

@@ -92,7 +92,9 @@ export async function handleDeviceApprove(req, res) {
     if (approved.status === "forbidden") {
         res.statusCode = 403;
         res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify({ error: `Device approval forbidden: ${approved.reason ?? "unknown"}` }));
+        res.end(JSON.stringify({
+            error: `Device approval forbidden: ${approved.reason ?? "unknown"}`,
+        }));
         return true;
     }
     res.statusCode = 200;

package/dist/src/http/handlers/files-download.js

@@ -51,7 +51,10 @@ function tryDecodeURIComponent(segment) {
  * Safe Content-Disposition: strip CR/LF/quotes from basename; add RFC 5987 filename* for Unicode.
  */
 function contentDispositionInline(filename) {
-    const base = path.basename(filename).replace(/[\r\n"]/g, "_").replace(/\\/g, "_") || "file";
+    const base = path
+        .basename(filename)
+        .replace(/[\r\n"]/g, "_")
+        .replace(/\\/g, "_") || "file";
     const ascii = /^[\x20-\x7E]*$/.test(base) ? base : "file";
     return `inline; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(base)}`;
 }
@@ -62,9 +65,7 @@ function sendBuffer(req, res, buffer, mimeType, filename) {
     const total = buffer.length;
     const disposition = contentDispositionInline(filename);
     const rangeRaw = req.headers.range;
-    const range = typeof rangeRaw === "string" && /^bytes=/i.test(rangeRaw.trim())
-        ? rangeRaw.trim()
-        : undefined;
+    const range = typeof rangeRaw === "string" && /^bytes=/i.test(rangeRaw.trim()) ? rangeRaw.trim() : undefined;
     res.setHeader("Accept-Ranges", "bytes");
     res.setHeader("Cache-Control", "private, max-age=3600");
     res.setHeader("Content-Type", mimeType);
@@ -178,10 +179,7 @@ export async function handleFilesDownload(req, res) {
         // fileId may include an extension (e.g. "uuid.png") — strip it to get the base id
         const baseId = fileToken.replace(/\.[^.]+$/, "");
         const mediaDir = path.join(os.homedir(), ".openclaw", "media", "inbound");
-        const candidates = [
-            path.join(mediaDir, baseId),
-            path.join(mediaDir, fileToken),
-        ];
+        const candidates = [path.join(mediaDir, baseId), path.join(mediaDir, fileToken)];
         for (const filePath of candidates) {
             if (fs.existsSync(filePath)) {
                 try {

package/dist/src/http/handlers/files.d.ts

@@ -17,6 +17,18 @@ export interface StoredFile {
     path: string;
     createdAt: number;
 }
+/** Clear the in-memory file index. Test-only: simulates a gateway restart. */
+export declare function clearFileIndexForTest(): void;
+/**
+ * Remember the original upload filename for an inbound media file.
+ *
+ * When a user sends an attachment, core's media-store copies it to
+ * `~/.openclaw/media/inbound/<uuid>` — a bare uuid with no extension and no original
+ * name — and the transcript records THAT path. So on history rebuild the original name
+ * is unrecoverable. We stash it here (keyed by the inbound basename, reusing the sidecar
+ * scheme but inside our own attachments dir) at send time, while we still know it.
+ */
+export declare function rememberInboundMediaName(inboundPath: string, filename: string, mimeType: string): void;
 /**
  * Read a file from `attachments/` by URL path token (disk basename).
  * Used when the in-memory index was cleared after a gateway restart.
@@ -24,7 +36,10 @@ export interface StoredFile {
 export declare function readAttachmentFileFromDisk(fileToken: string): {
     buffer: Buffer;
     mimeType: string;
+    /** Original display/download filename (from sidecar; falls back to the on-disk basename). */
     filename: string;
+    /** On-disk basename / urlToken — use this to build `/friday-next/files/{token}` URLs. */
+    diskName: string;
 } | null;
 /**
  * Copy a local file into `attachments/` and register it (no full-buffer read for the copy path).
@@ -54,6 +69,7 @@ export declare function getExternalFileSourceByUrlToken(token: string): string |
 export declare function readFile(id: string): {
     buffer: Buffer | null;
     mimeType: string;
+    filename?: string;
 };
 /**
  * Copy a file from a local filesystem path into the Friday Next channel file store