@syengup/friday-channel-next 0.1.13 → 0.1.15

package/src/http/handlers/history-messages.ts

@@ -0,0 +1,123 @@
+/**
+ * GET /friday-next/history/messages?sessionKey=&agentId=&limit=
+ *
+ * Returns a session's transcript history as a flat, normalized message stream.
+ * The Friday app groups these into rounds itself (by role transitions) and uses
+ * each message's stable `id` (the upstream transcript entry id) as its sync key.
+ *
+ * Reads via the gateway `sessions.get` method (exposed to plugins as
+ * `runtime.subagent.getSessionMessages`), which already resolves the active
+ * branch and compaction, then normalizes each raw message into a stable DTO.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { getFridayNextRuntime } from "../../runtime.js";
+import { extractBearerToken } from "../middleware/auth.js";
+import { normalizeHistoryMessages } from "../../history/normalize-message.js";
+import { readSessionTranscriptRawMessages, resolveSessionId } from "../../history/read-transcript.js";
+import { resolveMediaAttachment } from "./files.js";
+
+const DEFAULT_LIMIT = 200;
+const MAX_LIMIT = 1000;
+
+type SubagentSessionApi = {
+  getSessionMessages?: (params: {
+    sessionKey: string;
+    limit?: number;
+  }) => Promise<{ messages?: unknown[] }>;
+};
+
+function resolveSubagentApi(): SubagentSessionApi | undefined {
+  try {
+    const runtime = getFridayNextRuntime();
+    return (runtime as unknown as { subagent?: SubagentSessionApi }).subagent;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function handleHistoryMessages(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+
+  const token = extractBearerToken(req);
+  if (!token) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const sessionKey = url.searchParams.get("sessionKey")?.trim();
+  if (!sessionKey) {
+    res.statusCode = 400;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Missing required query param: sessionKey" }));
+    return true;
+  }
+  const agentId = url.searchParams.get("agentId")?.trim() || undefined;
+  const limitParam = Number(url.searchParams.get("limit"));
+  const limit =
+    Number.isFinite(limitParam) && limitParam > 0
+      ? Math.min(Math.floor(limitParam), MAX_LIMIT)
+      : DEFAULT_LIMIT;
+
+  // Primary path: read the transcript file directly (works from an HTTP route).
+  let rawMessages: unknown[] = readSessionTranscriptRawMessages(sessionKey, limit);
+
+  // Fallback: the request-scoped gateway method (only works in some contexts).
+  if (rawMessages.length === 0) {
+    const sessionApi = resolveSubagentApi();
+    if (sessionApi?.getSessionMessages) {
+      try {
+        const response = await sessionApi.getSessionMessages({ sessionKey, limit });
+        rawMessages = Array.isArray(response?.messages) ? response.messages : [];
+      } catch {
+        // Best-effort: an unreadable/unknown session yields an empty history
+        // rather than an error, so the app degrades gracefully.
+        rawMessages = [];
+      }
+    }
+  }
+
+  const messages = normalizeHistoryMessages(rawMessages);
+
+  // Resolve `MEDIA:<server-path>` references into downloadable attachment URLs
+  // (copies the file into the plugin's attachments/ dir — the same mechanism the
+  // live deliver path uses), then drop the raw paths from the wire.
+  for (const message of messages) {
+    if (!message.mediaPaths?.length) continue;
+    const resolved = message.mediaPaths
+      .map((p) => resolveMediaAttachment(p))
+      .filter((r): r is NonNullable<typeof r> => Boolean(r))
+      .map((r) => ({ url: r.url, filename: r.fileName }));
+    if (resolved.length) {
+      message.images = [...(message.images ?? []), ...resolved];
+    }
+    delete message.mediaPaths;
+  }
+
+  const sessionId = resolveSessionId(sessionKey);
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(
+    JSON.stringify({
+      ok: true,
+      sessionKey,
+      ...(agentId ? { agentId } : {}),
+      ...(sessionId ? { sessionId } : {}),
+      totalMessages: messages.length,
+      messages,
+    }),
+  );
+  return true;
+}

package/src/http/handlers/history-sessions.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { handleHistorySessions } from "./history-sessions.js";
+import { setMockRuntime } from "../../test-support/mock-runtime.js";
+import {
+  setFridayAgentForwardRuntime,
+  resetFridayAgentForwardRuntimeForTest,
+} from "../../agent-forward-runtime.js";
+
+class MockRes extends EventEmitter {
+  statusCode = 0;
+  headers: Record<string, string> = {};
+  body = "";
+  setHeader(name: string, value: string): void {
+    this.headers[name.toLowerCase()] = value;
+  }
+  end(body?: string): void {
+    if (body) this.body += body;
+  }
+}
+
+function makeReq(headers: Record<string, string> = {}, method = "GET"): any {
+  return { method, url: "/friday-next/history/sessions", headers };
+}
+
+const AUTH = { authorization: "Bearer test-token" };
+
+let tmpDir = "";
+
+/** Write a non-empty transcript file and return its absolute path. */
+function transcript(name: string): string {
+  const file = path.join(tmpDir, name);
+  fs.writeFileSync(file, `${JSON.stringify({ type: "message", id: "m", message: { role: "user", content: "hi" } })}\n`, "utf-8");
+  return file;
+}
+
+function setForward(config: unknown, storesByAgent: Record<string, Record<string, unknown>>): void {
+  setFridayAgentForwardRuntime({
+    runtime: {
+      agent: {
+        session: {
+          resolveStorePath: (_s?: string, opts?: { agentId?: string }) =>
+            path.join(tmpDir, `${opts?.agentId ?? "main"}.json`),
+          loadSessionStore: (p: string) => {
+            const agentId = path.basename(p, ".json");
+            return storesByAgent[agentId] ?? {};
+          },
+        },
+      },
+      config: { current: () => config },
+    },
+  } as any);
+}
+
+describe("handleHistorySessions", () => {
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "friday-hs-"));
+    setMockRuntime();
+  });
+  afterEach(() => {
+    resetFridayAgentForwardRuntimeForTest();
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it("rejects non-GET with 405", async () => {
+    const res = new MockRes();
+    await handleHistorySessions(makeReq(AUTH, "POST"), res as any);
+    expect(res.statusCode).toBe(405);
+  });
+
+  it("rejects missing token with 401", async () => {
+    const res = new MockRes();
+    await handleHistorySessions(makeReq(), res as any);
+    expect(res.statusCode).toBe(401);
+  });
+
+  it("lists live sessions with sessionId + server title, sorted by updatedAt", async () => {
+    setForward(
+      { agents: { list: [{ id: "main" }] } },
+      {
+        main: {
+          "agent:main:main": { sessionId: "s-main", updatedAt: 100, sessionFile: transcript("main.jsonl") },
+          "agent:main:friday:direct:dev:1": {
+            sessionId: "s-fd",
+            updatedAt: 300,
+            displayName: "我的会话",
+            sessionFile: transcript("fd.jsonl"),
+          },
+        },
+      },
+    );
+    const res = new MockRes();
+    await handleHistorySessions(makeReq(AUTH), res as any);
+    const body = JSON.parse(res.body);
+    expect(body.sessions.map((s: any) => s.sessionKey)).toEqual([
+      "agent:main:friday:direct:dev:1",
+      "agent:main:main",
+    ]);
+    const fd = body.sessions[0];
+    expect(fd).toMatchObject({ sessionId: "s-fd", title: "我的会话" });
+  });
+
+  it("filters out archived sessions (transcript file missing)", async () => {
+    setForward(
+      { agents: { list: [{ id: "main" }] } },
+      {
+        main: {
+          "agent:main:live": { sessionId: "a", updatedAt: 1, sessionFile: transcript("live.jsonl") },
+          "agent:main:archived": { sessionId: "b", updatedAt: 2, sessionFile: path.join(tmpDir, "gone.jsonl") },
+        },
+      },
+    );
+    const res = new MockRes();
+    await handleHistorySessions(makeReq(AUTH), res as any);
+    const keys = JSON.parse(res.body).sessions.map((s: any) => s.sessionKey);
+    expect(keys).toEqual(["agent:main:live"]);
+  });
+
+  it("filters out internal/system + subagent sessions", async () => {
+    setForward(
+      { agents: { list: [{ id: "main" }] } },
+      {
+        main: {
+          "agent:main:main": { sessionId: "ok", updatedAt: 5, sessionFile: transcript("ok.jsonl") },
+          "agent:main:main:heartbeat": { sessionId: "hb", updatedAt: 4, sessionFile: transcript("hb.jsonl") },
+          "agent:main:cron:abc": { sessionId: "c", updatedAt: 3, sessionFile: transcript("c.jsonl") },
+          "agent:main:subagent:xyz": { sessionId: "sa", updatedAt: 2, sessionFile: transcript("sa.jsonl") },
+          "agent:main:dreaming-narrative-rem-1": { sessionId: "d", updatedAt: 1, sessionFile: transcript("d.jsonl") },
+          "agent:main:child": { sessionId: "ch", updatedAt: 6, spawnedBy: "agent:main:main", sessionFile: transcript("ch.jsonl") },
+          global: { sessionId: "g", updatedAt: 7, sessionFile: transcript("g.jsonl") },
+        },
+      },
+    );
+    const res = new MockRes();
+    await handleHistorySessions(makeReq(AUTH), res as any);
+    const keys = JSON.parse(res.body).sessions.map((s: any) => s.sessionKey);
+    expect(keys).toEqual(["agent:main:main"]);
+  });
+});

package/src/http/handlers/history-sessions.ts

@@ -0,0 +1,184 @@
+/**
+ * GET /friday-next/history/sessions
+ *
+ * Lists every session across every configured agent (lightweight metadata only).
+ * The Friday app uses this to surface sessions created on other platforms /
+ * channels in its sidebar before lazily fetching each session's history.
+ *
+ * Session message bodies are intentionally NOT read here — that is the job of the
+ * per-session history endpoint. We only read each agent's `sessions.json` via the
+ * forward runtime (`loadSessionStore`), matching the read path already used for
+ * terminal lifecycle forwards.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import fs from "node:fs";
+import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
+import { extractBearerToken } from "../middleware/auth.js";
+import { resolveTranscriptPath } from "../../history/read-transcript.js";
+
+const DEFAULT_AGENT_ID = "main";
+const SAFE_AGENT_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+export interface FridayHistorySessionSummary {
+  /** Canonical app session key, e.g. "agent:main:main". */
+  sessionKey: string;
+  agentId: string;
+  sessionId?: string;
+  updatedAt?: number;
+  model?: string;
+  title?: string;
+}
+
+/** Mirror of OpenClaw's `normalizeAgentId` (also used in agents-list.ts). */
+function normalizeAgentId(value: unknown): string {
+  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
+  );
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/** Configured agent ids (deduped). Falls back to the implicit "main" agent. */
+function resolveConfiguredAgentIds(config: Record<string, unknown> | undefined): string[] {
+  const agents = config?.agents as Record<string, unknown> | undefined;
+  const list = agents?.list as Array<Record<string, unknown>> | undefined;
+  if (!Array.isArray(list) || list.length === 0) return [DEFAULT_AGENT_ID];
+  const ids = new Set<string>();
+  for (const agent of list) {
+    if (agent && typeof agent === "object") ids.add(normalizeAgentId(agent.id));
+  }
+  if (ids.size === 0) ids.add(DEFAULT_AGENT_ID);
+  return [...ids];
+}
+
+/** Build the canonical app session key from an agent + a raw sessions.json key. */
+function toCanonicalSessionKey(agentId: string, storeKey: string): string {
+  const key = storeKey.trim();
+  if (key.toLowerCase().startsWith("agent:")) return key;
+  return `agent:${agentId}:${key}`;
+}
+
+/** Session-id portion (everything after `agent:<id>:`). */
+function sessionRest(canonicalKey: string): string {
+  const m = canonicalKey.match(/^agent:[^:]+:(.+)$/);
+  return (m?.[1] ?? canonicalKey).toLowerCase();
+}
+
+/**
+ * Internal/system sessions that aren't user-facing conversations — mirrors what
+ * OpenClaw's own `sessions.list` filters (cron/global/unknown/phantom) plus
+ * heartbeat / subagent / memory-dreaming runs.
+ */
+function isInternalSessionKey(canonicalKey: string, storeKey: string): boolean {
+  const k = storeKey.toLowerCase();
+  if (k === "global" || k === "unknown") return true;
+  const rest = sessionRest(canonicalKey);
+  return (
+    rest === "sessions" || // phantom agent-store entry
+    rest.startsWith("subagent:") ||
+    rest.startsWith("cron:") ||
+    rest.startsWith("dreaming-narrative") ||
+    rest === "heartbeat" ||
+    rest.endsWith(":heartbeat")
+  );
+}
+
+/** A session counts as archived/empty when its transcript file is gone or empty. */
+function hasLiveTranscript(entry: Record<string, unknown>, storePath: string): boolean {
+  const filePath = resolveTranscriptPath(entry, storePath);
+  if (!filePath) return false;
+  try {
+    return fs.statSync(filePath).size > 0;
+  } catch {
+    return false; // archived (moved to .deleted/.bak) or never written
+  }
+}
+
+function readAgentSessions(agentId: string): FridayHistorySessionSummary[] {
+  const rt = getFridayAgentForwardRuntime();
+  if (!rt) return [];
+  let storePath: string;
+  let store: Record<string, unknown>;
+  try {
+    storePath = rt.resolveStorePath(undefined, { agentId });
+    store = rt.loadSessionStore(storePath) ?? {};
+  } catch {
+    return [];
+  }
+  const summaries: FridayHistorySessionSummary[] = [];
+  for (const [storeKey, rawEntry] of Object.entries(store)) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as Record<string, unknown>;
+    const canonicalKey = toCanonicalSessionKey(agentId, storeKey);
+
+    // Drop internal/system sessions and subagent links.
+    if (isInternalSessionKey(canonicalKey, storeKey)) continue;
+    if (entry.spawnedBy || entry.subagentRole || entry.parentSessionKey) continue;
+    // Drop archived/empty sessions (transcript moved away or never written).
+    if (!hasLiveTranscript(entry, storePath)) continue;
+
+    summaries.push({
+      sessionKey: canonicalKey,
+      agentId,
+      ...(readString(entry.sessionId) ? { sessionId: readString(entry.sessionId) } : {}),
+      ...(readNumber(entry.updatedAt) !== undefined ? { updatedAt: readNumber(entry.updatedAt) } : {}),
+      ...(readString(entry.model) ?? readString(entry.modelOverride)
+        ? { model: readString(entry.model) ?? readString(entry.modelOverride) }
+        : {}),
+      // Server-side session display name (matches OpenClaw's resolution order).
+      ...(readString(entry.displayName) ?? readString(entry.label)
+        ? { title: readString(entry.displayName) ?? readString(entry.label) }
+        : {}),
+    });
+  }
+  return summaries;
+}
+
+export async function handleHistorySessions(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  if (req.method !== "GET") {
+    res.statusCode = 405;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Method Not Allowed" }));
+    return true;
+  }
+
+  const token = extractBearerToken(req);
+  if (!token) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Unauthorized: bearer token mismatch" }));
+    return true;
+  }
+
+  const rt = getFridayAgentForwardRuntime();
+  const config = rt?.getConfig() as Record<string, unknown> | undefined;
+  const agentIds = resolveConfiguredAgentIds(config);
+
+  const sessions: FridayHistorySessionSummary[] = [];
+  for (const agentId of agentIds) {
+    sessions.push(...readAgentSessions(agentId));
+  }
+  sessions.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify({ ok: true, sessions }));
+  return true;
+}

package/src/http/handlers/history-set-title.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
+import { handleHistorySetTitle } from "./history-set-title.js";
+import { setFridayNextRuntime } from "../../runtime.js";
+import {
+  setFridayAgentForwardRuntime,
+  resetFridayAgentForwardRuntimeForTest,
+} from "../../agent-forward-runtime.js";
+
+class MockRes extends EventEmitter {
+  statusCode = 0;
+  headers: Record<string, string> = {};
+  body = "";
+  setHeader(name: string, value: string): void {
+    this.headers[name.toLowerCase()] = value;
+  }
+  end(body?: string): void {
+    if (body) this.body += body;
+  }
+}
+
+function makeReq(bodyObj: unknown, headers: Record<string, string> = {}, method = "PUT"): any {
+  const req = Readable.from([Buffer.from(JSON.stringify(bodyObj))]) as any;
+  req.method = method;
+  req.url = "/friday-next/sessions/title";
+  req.headers = headers;
+  return req;
+}
+
+const AUTH = { authorization: "Bearer test-token" };
+const CFG = {
+  channels: { "friday-next": { authToken: "test-token", pathPrefix: "/friday-next" } },
+  gateway: { auth: { token: "test-token" } },
+};
+
+let captured: { storePath: string; sessionKey: string; patch: unknown } | null = null;
+
+function setForward(store: Record<string, unknown>, withWriter = true): void {
+  captured = null;
+  setFridayAgentForwardRuntime({
+    runtime: {
+      agent: {
+        session: {
+          resolveStorePath: (_s?: string, opts?: { agentId?: string }) => `/store/${opts?.agentId ?? "main"}.json`,
+          loadSessionStore: () => store,
+          ...(withWriter
+            ? {
+                updateSessionStoreEntry: async (params: any) => {
+                  const patch = await params.update({ sessionId: "sess-1" });
+                  captured = { storePath: params.storePath, sessionKey: params.sessionKey, patch };
+                  return { sessionId: "sess-1", ...patch };
+                },
+              }
+            : {}),
+        },
+      },
+      config: { current: () => CFG },
+    },
+  } as any);
+}
+
+describe("handleHistorySetTitle", () => {
+  beforeEach(() => setFridayNextRuntime({ config: { loadConfig: () => CFG }, logger: {} } as never));
+  afterEach(() => resetFridayAgentForwardRuntimeForTest());
+
+  it("rejects GET with 405", async () => {
+    setForward({});
+    const res = new MockRes();
+    await handleHistorySetTitle(makeReq({}, AUTH, "GET"), res as any);
+    expect(res.statusCode).toBe(405);
+  });
+
+  it("rejects missing token with 401", async () => {
+    setForward({});
+    const res = new MockRes();
+    await handleHistorySetTitle(makeReq({ sessionKey: "agent:main:main", title: "x" }), res as any);
+    expect(res.statusCode).toBe(401);
+  });
+
+  it("400s without sessionKey", async () => {
+    setForward({});
+    const res = new MockRes();
+    await handleHistorySetTitle(makeReq({ title: "x" }, AUTH), res as any);
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("writes displayName for the resolved (case-insensitive) store key", async () => {
+    setForward({ "agent:main:friday:direct:abcd:9": { sessionId: "sess-1" } });
+    const res = new MockRes();
+    await handleHistorySetTitle(
+      makeReq({ sessionKey: "agent:main:friday:direct:ABCD:9", title: "My Chat" }, AUTH),
+      res as any,
+    );
+    expect(res.statusCode).toBe(200);
+    expect(captured?.sessionKey).toBe("agent:main:friday:direct:abcd:9");
+    expect(captured?.patch).toEqual({ displayName: "My Chat" });
+    const body = JSON.parse(res.body);
+    expect(body).toMatchObject({ ok: true, sessionId: "sess-1", title: "My Chat" });
+  });
+
+  it("404s when the session is unknown", async () => {
+    setForward({});
+    const res = new MockRes();
+    await handleHistorySetTitle(makeReq({ sessionKey: "agent:main:nope", title: "x" }, AUTH), res as any);
+    expect(res.statusCode).toBe(404);
+  });
+
+  it("503s when the store writer is unavailable", async () => {
+    setForward({ "agent:main:main": { sessionId: "s" } }, false);
+    const res = new MockRes();
+    await handleHistorySetTitle(makeReq({ sessionKey: "agent:main:main", title: "x" }, AUTH), res as any);
+    expect(res.statusCode).toBe(503);
+  });
+})

package/src/http/handlers/history-set-title.ts

@@ -0,0 +1,86 @@
+/**
+ * PUT /friday-next/sessions/title  body: { sessionKey, title }
+ *
+ * Syncs the app-set session name to the server session's `displayName` (the
+ * field OpenClaw resolves first for a session's display title, ahead of `label`).
+ * Writes via `updateSessionStoreEntry` (cache-owning, not request-scoped), so the
+ * change is also visible to webui and other clients.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { getFridayAgentForwardRuntime } from "../../agent-forward-runtime.js";
+import { extractBearerToken } from "../middleware/auth.js";
+import { readJsonBody } from "../middleware/body.js";
+import { agentIdFromSessionKey, toSessionStoreKey } from "../../session/session-manager.js";
+
+function json(res: ServerResponse, status: number, body: unknown): true {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(body));
+  return true;
+}
+
+/** Real store key matching `sessionKey`, tolerating deviceId case differences. */
+function resolveStoreKey(store: Record<string, unknown>, sessionKey: string): string | undefined {
+  if (store[sessionKey]) return sessionKey;
+  const canonical = toSessionStoreKey(sessionKey);
+  if (store[canonical]) return canonical;
+  const target = canonical.toLowerCase();
+  for (const k of Object.keys(store)) {
+    if (k.toLowerCase() === target) return k;
+  }
+  return undefined;
+}
+
+export async function handleHistorySetTitle(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  if (req.method !== "PUT" && req.method !== "POST") {
+    return json(res, 405, { error: "Method Not Allowed" });
+  }
+  if (!extractBearerToken(req)) {
+    return json(res, 401, { error: "Unauthorized: bearer token mismatch" });
+  }
+
+  const body = (await readJsonBody(req)) as { sessionKey?: unknown; title?: unknown } | null;
+  const sessionKey = typeof body?.sessionKey === "string" ? body.sessionKey.trim() : "";
+  const title = typeof body?.title === "string" ? body.title.trim() : "";
+  if (!sessionKey) {
+    return json(res, 400, { error: "Missing required field: sessionKey" });
+  }
+
+  const rt = getFridayAgentForwardRuntime();
+  if (!rt?.updateSessionStoreEntry) {
+    return json(res, 503, { error: "Session store write not available" });
+  }
+
+  const agentId = agentIdFromSessionKey(sessionKey);
+  let storePath: string;
+  let store: Record<string, unknown>;
+  try {
+    storePath = rt.resolveStorePath(undefined, { agentId });
+    store = rt.loadSessionStore(storePath) ?? {};
+  } catch {
+    return json(res, 500, { error: "Failed to load session store" });
+  }
+
+  const storeKey = resolveStoreKey(store, sessionKey);
+  if (!storeKey) {
+    return json(res, 404, { error: `Session not found: ${sessionKey}` });
+  }
+
+  try {
+    const updated = await rt.updateSessionStoreEntry({
+      storePath,
+      sessionKey: storeKey,
+      // Empty title clears the override so the server can derive its own again.
+      update: () => ({ displayName: title || undefined }),
+    });
+    const sessionId =
+      updated && typeof updated.sessionId === "string" ? updated.sessionId : undefined;
+    return json(res, 200, { ok: true, sessionKey, ...(sessionId ? { sessionId } : {}), title });
+  } catch {
+    return json(res, 500, { error: "Failed to update session title" });
+  }
+}