@syengup/friday-channel-next 0.1.29 → 0.1.36

package/README.md

@@ -10,15 +10,19 @@
 - **Disk-backed SSE replay** per `deviceId` (JSONL + `Last-Event-ID` / `lastEventId`) for offline gaps and restarts
 - File upload/download (`POST /friday-next/files`, `GET /friday-next/files/:id`)
 - Cancel (`POST /friday-next/cancel`) and status with `activeRuns` (`GET /friday-next/status`)
+- **Agent config editing** (mirrors ControlUI, no core changes): model / core `.md` files / tool permissions / skills, per agent — via `agents.list[]` (`mutateConfigFile`) + workspace fs
+- History sync, link-preview cards, and in-app plugin self-upgrade
 
 ## Endpoints
 
 - `GET /friday-next/events?deviceId=...`
 - `POST /friday-next/messages`
-- `POST /friday-next/files`
-- `GET /friday-next/files/:id`
-- `POST /friday-next/cancel`
-- `GET /friday-next/status`
+- `POST /friday-next/files` · `GET /friday-next/files/:id`
+- `POST /friday-next/cancel` · `GET /friday-next/status` · `GET /friday-next/health`
+- `GET /friday-next/models` · `GET /friday-next/agents` · `GET|PUT /friday-next/sessions/settings`
+- `GET|PUT /friday-next/agents/{id}/config` · `GET|PUT /friday-next/agents/{id}/files[/{name}]` · `GET /friday-next/agents/{id}/tools/catalog`
+- `GET /friday-next/history/sessions` · `GET /friday-next/history/messages` · `GET /friday-next/link-preview`
+- `GET /friday-next/plugin/info` · `POST /friday-next/plugin/upgrade`
 
 See **`API.md`** (English) and **`API.zh-CN.md`** (Chinese) for payloads, event shapes, offline queue paths, and breaking changes.
 

package/dist/src/agent/abort-run.d.ts

@@ -1 +1,12 @@
-export declare function abortRun(runId: string): Promise<void>;
+export type AbortRunResult = {
+    aborted: boolean;
+    drained: boolean;
+};
+/**
+ * Abort the active run for a channel `sessionKey`.
+ *
+ * A session has at most one active run at a time, and the SDK keys active runs by
+ * their internal `sessionId` (not the channel runId). So resolve sessionKey → sessionId
+ * first, then abort-and-drain so the caller learns whether the run actually settled.
+ */
+export declare function abortRunForSessionKey(sessionKey: string): Promise<AbortRunResult>;

package/dist/src/agent/abort-run.js

@@ -1,11 +1,26 @@
-export async function abortRun(runId) {
-    if (process.env.VITEST !== "true") {
-        try {
-            const { abortAgentHarnessRun } = await import("openclaw/plugin-sdk/agent-harness");
-            abortAgentHarnessRun(runId);
-        }
-        catch {
-            // optional at runtime
-        }
+/**
+ * Abort the active run for a channel `sessionKey`.
+ *
+ * A session has at most one active run at a time, and the SDK keys active runs by
+ * their internal `sessionId` (not the channel runId). So resolve sessionKey → sessionId
+ * first, then abort-and-drain so the caller learns whether the run actually settled.
+ */
+export async function abortRunForSessionKey(sessionKey) {
+    if (process.env.VITEST === "true")
+        return { aborted: false, drained: false };
+    const key = sessionKey.trim();
+    if (!key)
+        return { aborted: false, drained: false };
+    try {
+        const { resolveActiveEmbeddedRunSessionId, abortAndDrainAgentHarnessRun } = await import("openclaw/plugin-sdk/agent-harness");
+        const sessionId = resolveActiveEmbeddedRunSessionId(key);
+        if (!sessionId)
+            return { aborted: false, drained: false };
+        const result = await abortAndDrainAgentHarnessRun({ sessionId, sessionKey: key });
+        return { aborted: result.aborted, drained: result.drained };
+    }
+    catch {
+        // optional at runtime
+        return { aborted: false, drained: false };
     }
 }

package/dist/src/agent/media-bridge.d.ts

@@ -1,4 +1,11 @@
-export declare function saveInboundMediaBuffer(buffer: Buffer, mimeType: string): Promise<{
+/**
+ * openclaw's own per-kind byte cap for a mime type (image 6MB / audio·video 16MB /
+ * document 100MB). Unknown mimes fall back to the most permissive ("document") cap.
+ * Returns undefined if the media runtime isn't importable (tests / stripped runtime),
+ * letting `saveMediaBuffer` apply its built-in default.
+ */
+export declare function resolveMediaMaxBytes(mimeType: string): Promise<number | undefined>;
+export declare function saveInboundMediaBuffer(buffer: Buffer, mimeType: string, originalFilename?: string): Promise<{
     id: string;
     path: string;
 }>;

package/dist/src/agent/media-bridge.js

@@ -2,10 +2,31 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
-export async function saveInboundMediaBuffer(buffer, mimeType) {
+/**
+ * openclaw's own per-kind byte cap for a mime type (image 6MB / audio·video 16MB /
+ * document 100MB). Unknown mimes fall back to the most permissive ("document") cap.
+ * Returns undefined if the media runtime isn't importable (tests / stripped runtime),
+ * letting `saveMediaBuffer` apply its built-in default.
+ */
+export async function resolveMediaMaxBytes(mimeType) {
+    try {
+        const { maxBytesForKind, mediaKindFromMime } = await import("openclaw/plugin-sdk/media-runtime");
+        return maxBytesForKind(mediaKindFromMime(mimeType) ?? "document");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function saveInboundMediaBuffer(buffer, mimeType, originalFilename) {
     try {
         const sdk = await import("openclaw/plugin-sdk/media-store");
-        const saved = await sdk.saveMediaBuffer(buffer, mimeType, "inbound");
+        // Accept whatever openclaw itself supports for this media kind instead of
+        // saveMediaBuffer's conservative 5MB default.
+        const maxBytes = await resolveMediaMaxBytes(mimeType);
+        // Pass the original filename (5th arg) so core's media-store preserves the
+        // name+extension instead of saving a bare uuid. Otherwise the agent receives
+        // `[media attached: file://.../inbound/<uuid>]` with no file-format signal.
+        const saved = await sdk.saveMediaBuffer(buffer, mimeType, "inbound", maxBytes, originalFilename);
         if (saved?.id && saved?.path)
             return { id: saved.id, path: saved.path };
     }

package/dist/src/agent-forward-runtime.d.ts

@@ -16,6 +16,21 @@ export type FridayAgentForwardRuntime = {
     }) => Promise<Record<string, unknown> | null>;
     /** Resolves an agent's workspace dir — used to read IDENTITY.md for the name fallback. */
     resolveAgentWorkspaceDir?: (cfg: unknown, agentId: string) => string;
+    /**
+     * Resolves the thinking-level options + default for a provider/model pair, driven by the running
+     * gateway's provider plugins + model catalog (so the option set varies per model). Optional: older
+     * gateways don't expose it, in which case callers fall back to the base five levels.
+     */
+    resolveThinkingPolicy?: (params: {
+        provider?: string | null;
+        model?: string | null;
+    }) => {
+        levels: Array<{
+            id: string;
+            label: string;
+        }>;
+        defaultLevel?: string | null;
+    };
     getConfig: () => unknown;
 };
 /** Called from `registerFull` so terminal lifecycle forwards can read `sessions.json` after persist. */

package/dist/src/agent-forward-runtime.js

@@ -8,6 +8,8 @@ export function setFridayAgentForwardRuntime(api) {
             .updateSessionStoreEntry,
         resolveAgentWorkspaceDir: api.runtime.agent
             .resolveAgentWorkspaceDir,
+        resolveThinkingPolicy: api.runtime.agent
+            .resolveThinkingPolicy,
         getConfig: () => api.runtime.config.current(),
     };
 }

package/dist/src/agent-id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Agent id normalization shared across handlers.
+ *
+ * Mirror of OpenClaw's `normalizeAgentId` (src/routing/session-key.ts): trim,
+ * lowercase, keep path/shell-safe. Empty → "main".
+ */
+export declare const DEFAULT_AGENT_ID = "main";
+export declare function normalizeAgentId(value: unknown): string;

package/dist/src/agent-id.js

@@ -0,0 +1,21 @@
+/**
+ * Agent id normalization shared across handlers.
+ *
+ * Mirror of OpenClaw's `normalizeAgentId` (src/routing/session-key.ts): trim,
+ * lowercase, keep path/shell-safe. Empty → "main".
+ */
+export 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_-]*$/;
+export 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);
+}

package/dist/src/channel-actions.js

@@ -24,6 +24,23 @@ function pickString(params, keys) {
     }
     return "";
 }
+function pickStringArray(params, key) {
+    const v = params[key];
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of v) {
+        if (typeof entry !== "string")
+            continue;
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
 async function readMediaFile(mediaPath, ctx) {
     if (isHttpUrl(mediaPath)) {
         return downloadRemoteMedia(mediaPath);
@@ -78,23 +95,37 @@ async function handleSend(ctx) {
             },
         }, to, true);
     }
-    // Resolve media from an inline base64 buffer or a path/url reference. (`attachments[]` arrays are
-    // normalized by the OpenClaw core and arrive via outbound.sendMedia, so they're not handled here.)
-    let media = null;
-    let originalMediaUrl = "";
-    if (inlineBase64) {
-        media = decodeBase64Media(inlineBase64, mediaMimeHint || (filename ? guessMimeType(filename) : ""));
-        originalMediaUrl = filename || "inline-buffer";
+    // Resolve the media to send. A `message` tool call with a structured `attachments[]` array is
+    // flattened by the OpenClaw core into `params.mediaUrls` (with `media` set to the first entry for
+    // back-compat), so prefer the full list; fall back to a single inline base64 buffer or a
+    // path/url reference for the single-attachment / direct-link / buffer cases.
+    const mediaSources = [];
+    const mediaUrls = pickStringArray(ctx.params, "mediaUrls");
+    if (mediaUrls.length > 0) {
+        for (const ref of mediaUrls) {
+            const loaded = await readMediaFile(ref, ctx);
+            if (loaded)
+                mediaSources.push({ ...loaded, originalMediaUrl: ref });
+        }
+    }
+    else if (inlineBase64) {
+        const loaded = decodeBase64Media(inlineBase64, mediaMimeHint || (filename ? guessMimeType(filename) : ""));
+        if (loaded)
+            mediaSources.push({ ...loaded, originalMediaUrl: filename || "inline-buffer" });
     }
     else if (mediaPath) {
-        media = await readMediaFile(mediaPath, ctx);
-        originalMediaUrl = mediaPath;
+        const loaded = await readMediaFile(mediaPath, ctx);
+        if (loaded)
+            mediaSources.push({ ...loaded, originalMediaUrl: mediaPath });
     }
-    // Send media via SSE outbound
-    if (media) {
+    // Send each media via its own SSE outbound event. They all share this send's `runId` so the app
+    // groups them into a single assistant message (first → attachment, rest → extra attachments).
+    if (mediaSources.length > 0) {
         const { saveMediaBuffer } = await import("openclaw/plugin-sdk/media-store");
-        const saved = await saveMediaBuffer(media.buffer, media.mimeType, "inbound");
-        if (saved.id) {
+        for (const source of mediaSources) {
+            const saved = await saveMediaBuffer(source.buffer, source.mimeType, "inbound");
+            if (!saved.id)
+                continue;
             const publicUrl = `/friday-next/files/${encodeURIComponent(saved.id)}`;
             sseEmitter.broadcast({
                 type: "outbound",
@@ -107,7 +138,7 @@ async function handleSend(ctx) {
                     audioAsVoice: false,
                     caption: caption || text,
                     mediaUrl: publicUrl,
-                    ctx: { to, text: caption || text, originalMediaUrl },
+                    ctx: { to, text: caption || text, originalMediaUrl: source.originalMediaUrl },
                 },
             }, to, true);
         }

package/dist/src/channel.js

@@ -8,12 +8,14 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createChatChannelPlugin } from "openclaw/plugin-sdk/core";
+import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
 import { createFridayNextLogger } from "./logging.js";
 import { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";
 import { sseEmitter } from "./sse/emitter.js";
 import { describeMessageActions, handleMessageAction } from "./channel-actions.js";
 import { guessMimeType, resolveMediaAttachment } from "./http/handlers/files.js";
 import { downloadRemoteMedia, isHttpUrl } from "./media-fetch.js";
+import { resolveMediaMaxBytes } from "./agent/media-bridge.js";
 import { resolveFridayDeviceIdForOutbound, resolveHistorySessionKeyForFridayDevice, } from "./friday-session.js";
 import { getRunRoute } from "./run-metadata.js";
 import { getLastFridayInboundAt } from "./friday-inbound-stats.js";
@@ -83,6 +85,21 @@ const fridayLifecycle = {
         // No-op
     },
 };
+/**
+ * friday-next is a passive HTTP+SSE channel: its routes live on the shared gateway server and
+ * SSE clients connect on demand, so there is no per-account socket or polling loop to maintain.
+ * But the core health-monitor reads the account's lifecycle `running` flag — which the framework
+ * flips to `false` the moment `startAccount` resolves/rejects. Without a long-lived startAccount
+ * the account is permanently seen as "stopped" and restarted every health poll (~5 min). A stopped
+ * account drops out of the deliverable-channel registry, so an agent `message` send landing in that
+ * window fails with `Unknown channel: friday-next`. Hold the account lifecycle open until abort
+ * (reload/shutdown) so the channel stays `running:true` and continuously deliverable.
+ */
+const fridayGateway = {
+    startAccount: async (ctx) => {
+        await waitUntilAbort(ctx.abortSignal);
+    },
+};
 const fridayStatus = {
     buildAccountSnapshot: async (params) => {
         const { account, runtime } = params;
@@ -117,6 +134,7 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
         },
         config: fridayConfigAdapter,
         lifecycle: fridayLifecycle,
+        gateway: fridayGateway,
         status: fridayStatus,
         bindings: {
             compileConfiguredBinding: () => null,
@@ -240,7 +258,10 @@ export const fridayNextChannelPlugin = createChatChannelPlugin({
             }
             if (buffer) {
                 const mimeType = downloadedMimeType ?? guessMimeType(mediaUrl);
-                const saved = await saveMediaBuffer(buffer, mimeType, "inbound");
+                // Match what openclaw itself supports for this media kind rather than
+                // saveMediaBuffer's 5MB default.
+                const maxBytes = await resolveMediaMaxBytes(mimeType);
+                const saved = await saveMediaBuffer(buffer, mimeType, "inbound", maxBytes);
                 if (saved.id) {
                     const fileUrl = `/friday-next/files/${encodeURIComponent(saved.id)}`;
                     const resolved = resolveMediaAttachment(fileUrl);

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

@@ -0,0 +1,27 @@
+/**
+ * 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 type { IncomingMessage, ServerResponse } from "node:http";
+export interface AgentToolsConfig {
+    profile?: string;
+    allow?: string[];
+    alsoAllow?: string[];
+    deny?: string[];
+}
+export declare function handleAgentConfig(req: IncomingMessage, res: ServerResponse, rawAgentId: string): Promise<boolean>;

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

@@ -0,0 +1,182 @@
+/**
+ * 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>;