@syengup/friday-channel-next 0.1.12 → 0.1.14

package/src/history/normalize-message.ts

@@ -0,0 +1,292 @@
+/**
+ * Normalizes raw OpenClaw session transcript messages (as returned by the
+ * gateway `sessions.get` method / `runtime.subagent.getSessionMessages`) into a
+ * stable wire DTO the Friday app can parse without guessing at the upstream
+ * content-block shape.
+ *
+ * Each raw message is one persisted LLM message (UserMessage / AssistantMessage
+ * / ToolResultMessage) with an `__openclaw` metadata envelope attached by the
+ * gateway carrying the stable transcript entry `id`, a positional `seq`, and the
+ * record timestamp. That `id` is the durable, channel-agnostic identity the app
+ * uses as its sync/dedup key — runId is NOT persisted upstream.
+ */
+
+export interface FridayHistoryImage {
+  mimeType?: string;
+  /** Base64 payload for inline ImageContent blocks. */
+  data?: string;
+  /** URL for `[media attached: ...]` markers or resolved `MEDIA:` attachments. */
+  url?: string;
+  /** Display/download filename (set for resolved `MEDIA:` attachments). */
+  filename?: string;
+}
+
+export interface FridayHistoryToolCall {
+  id: string;
+  name: string;
+  arguments?: Record<string, unknown>;
+}
+
+export interface FridayHistoryToolResult {
+  toolCallId?: string;
+  toolName?: string;
+  isError?: boolean;
+  text?: string;
+  images?: FridayHistoryImage[];
+}
+
+export interface FridayHistoryUsage {
+  totalTokens?: number;
+  input?: number;
+  output?: number;
+}
+
+export type FridayHistoryRole = "user" | "assistant" | "toolResult" | "system";
+
+export interface FridayHistoryMessage {
+  /** Stable transcript entry id (sync key). Synthetic when upstream omitted it. */
+  id: string;
+  seq: number;
+  ts?: number;
+  role: FridayHistoryRole;
+  text?: string;
+  thinking?: string;
+  toolCalls?: FridayHistoryToolCall[];
+  toolResult?: FridayHistoryToolResult;
+  images?: FridayHistoryImage[];
+  /** Raw `MEDIA:<path>` server paths stripped from text; the handler resolves
+   *  them to downloadable `/friday-next/files/...` attachment URLs. */
+  mediaPaths?: string[];
+  model?: string;
+  usage?: FridayHistoryUsage;
+  /** Non-message records surfaced for context (e.g. compaction dividers). */
+  kind?: "compaction";
+  /** True when `id` was synthesized because upstream had no stable id. */
+  synthetic?: boolean;
+}
+
+type RawRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): RawRecord | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as RawRecord)
+    : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function readFiniteNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return undefined;
+}
+
+/** `MEDIA:<path>` lines emitted for outbound attachments (e.g. generated images). */
+const MEDIA_LINE_RE = /^[ \t]*MEDIA:[ \t]*(\S.*?)[ \t]*$/gim;
+
+/** Strips `MEDIA:<path>` lines from text, returning the cleaned text + the paths. */
+function splitMediaLines(text: string): { text: string; paths: string[] } {
+  if (!text.includes("MEDIA:")) return { text, paths: [] };
+  const paths: string[] = [];
+  const cleaned = text
+    .replace(MEDIA_LINE_RE, (_m, p: string) => {
+      const v = p.trim();
+      if (v) paths.push(v);
+      return "";
+    })
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  return { text: cleaned, paths };
+}
+
+const MEDIA_MARKER_RE = /\[media attached:\s*([^\]]+)\]/gi;
+
+/** Pull `[media attached: <url>]` markers out of free text into image refs. */
+function extractMediaMarkers(text: string): FridayHistoryImage[] {
+  const images: FridayHistoryImage[] = [];
+  for (const match of text.matchAll(MEDIA_MARKER_RE)) {
+    const url = match[1]?.trim();
+    if (url) images.push({ url });
+  }
+  return images;
+}
+
+interface ParsedContent {
+  text: string;
+  thinking: string;
+  toolCalls: FridayHistoryToolCall[];
+  images: FridayHistoryImage[];
+}
+
+function parseContent(content: unknown): ParsedContent {
+  const out: ParsedContent = { text: "", thinking: "", toolCalls: [], images: [] };
+
+  if (typeof content === "string") {
+    out.text = content;
+    out.images.push(...extractMediaMarkers(content));
+    return out;
+  }
+  if (!Array.isArray(content)) return out;
+
+  const textParts: string[] = [];
+  const thinkingParts: string[] = [];
+  for (const rawBlock of content) {
+    const block = asRecord(rawBlock);
+    if (!block) continue;
+    switch (block.type) {
+      case "text": {
+        const t = readString(block.text);
+        if (t) {
+          textParts.push(t);
+          out.images.push(...extractMediaMarkers(t));
+        }
+        break;
+      }
+      case "thinking": {
+        const t = readString(block.thinking);
+        if (t) thinkingParts.push(t);
+        break;
+      }
+      case "image": {
+        const data = readString(block.data);
+        const url = readString(block.url);
+        // Skip empty image blocks (no payload and no URL) — they'd render as
+        // broken attachment bubbles in the app.
+        if (data || url) {
+          out.images.push({
+            ...(readString(block.mimeType) ? { mimeType: readString(block.mimeType) } : {}),
+            ...(data ? { data } : {}),
+            ...(url ? { url } : {}),
+          });
+        }
+        break;
+      }
+      case "toolCall": {
+        const id = readString(block.id);
+        const name = readString(block.name);
+        if (id && name) {
+          out.toolCalls.push({
+            id,
+            name,
+            ...(asRecord(block.arguments) ? { arguments: asRecord(block.arguments) } : {}),
+          });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  out.text = textParts.join("");
+  out.thinking = thinkingParts.join("");
+  return out;
+}
+
+function parseUsage(raw: unknown): FridayHistoryUsage | undefined {
+  const usage = asRecord(raw);
+  if (!usage) return undefined;
+  const totalTokens = readFiniteNumber(usage.totalTokens) ?? readFiniteNumber(usage.total);
+  const input = readFiniteNumber(usage.input);
+  const output = readFiniteNumber(usage.output);
+  if (totalTokens === undefined && input === undefined && output === undefined) return undefined;
+  return {
+    ...(totalTokens !== undefined ? { totalTokens } : {}),
+    ...(input !== undefined ? { input } : {}),
+    ...(output !== undefined ? { output } : {}),
+  };
+}
+
+function normalizeRole(raw: unknown): FridayHistoryRole {
+  const role = readString(raw)?.toLowerCase();
+  switch (role) {
+    case "user":
+      return "user";
+    case "toolresult":
+      return "toolResult";
+    case "system":
+      return "system";
+    default:
+      return "assistant";
+  }
+}
+
+/**
+ * Normalize one raw transcript message. `index` is the position in the returned
+ * batch, used only to synthesize a stable-ish id when upstream omits one.
+ */
+export function normalizeHistoryMessage(
+  raw: unknown,
+  index: number,
+): FridayHistoryMessage | null {
+  const record = asRecord(raw);
+  if (!record) return null;
+
+  const meta = asRecord(record.__openclaw);
+  const role = normalizeRole(record.role);
+  const parsed = parseContent(record.content);
+
+  const seq = readFiniteNumber(meta?.seq) ?? index + 1;
+  const metaId = readString(meta?.id);
+  const id = metaId ?? `seq:${seq}`;
+  const synthetic = metaId === undefined;
+  const ts = readFiniteNumber(meta?.recordTimestampMs) ?? readFiniteNumber(record.timestamp);
+  const kind = readString(meta?.kind) === "compaction" ? "compaction" : undefined;
+
+  const message: FridayHistoryMessage = {
+    id,
+    seq,
+    role,
+    ...(ts !== undefined ? { ts } : {}),
+    ...(synthetic ? { synthetic: true } : {}),
+    ...(kind ? { kind } : {}),
+  };
+
+  if (kind === "compaction") {
+    message.text = parsed.text || "Compaction";
+    return message;
+  }
+
+  if (role === "toolResult") {
+    const split = splitMediaLines(parsed.text);
+    const toolResult: FridayHistoryToolResult = {
+      ...(readString(record.toolCallId) ? { toolCallId: readString(record.toolCallId) } : {}),
+      ...(readString(record.toolName) ? { toolName: readString(record.toolName) } : {}),
+      ...(record.isError === true ? { isError: true } : {}),
+      ...(split.text ? { text: split.text } : {}),
+      ...(parsed.images.length ? { images: parsed.images } : {}),
+    };
+    message.toolResult = toolResult;
+    if (split.paths.length) message.mediaPaths = split.paths;
+    return message;
+  }
+
+  const split = splitMediaLines(parsed.text);
+  if (split.text) message.text = split.text;
+  if (split.paths.length) message.mediaPaths = split.paths;
+  if (parsed.thinking) message.thinking = parsed.thinking;
+  if (parsed.toolCalls.length) message.toolCalls = parsed.toolCalls;
+  if (parsed.images.length) message.images = parsed.images;
+
+  const model = readString(record.model) ?? readString(record.responseModel);
+  if (model) message.model = model;
+  const usage = parseUsage(record.usage);
+  if (usage) message.usage = usage;
+
+  return message;
+}
+
+/** Normalize a batch of raw transcript messages, dropping unparseable entries. */
+export function normalizeHistoryMessages(rawMessages: unknown[]): FridayHistoryMessage[] {
+  const out: FridayHistoryMessage[] = [];
+  for (let i = 0; i < rawMessages.length; i += 1) {
+    const normalized = normalizeHistoryMessage(rawMessages[i], i);
+    if (normalized) out.push(normalized);
+  }
+  out.sort((a, b) => a.seq - b.seq);
+  return out;
+}

package/src/history/read-transcript.ts

@@ -0,0 +1,136 @@
+/**
+ * Reads a session's transcript directly from disk via the forward runtime's
+ * session store (`sessions.json` → entry.sessionFile → the `.jsonl` transcript).
+ *
+ * We do NOT use `runtime.subagent.getSessionMessages` here: that dispatches the
+ * gateway `sessions.get` method which is only valid inside a gateway request
+ * scope and returns empty when called from a plugin HTTP route. Reading the
+ * transcript file mirrors how `history-sessions.ts` reads `sessions.json`.
+ *
+ * Each transcript line is `{type, id, parentId, timestamp, message:{role,content,...}}`.
+ * We surface message records (in file order) with an `__openclaw` envelope
+ * matching the gateway's own `sessions.get` output, so `normalize-message.ts`
+ * can consume either source identically.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getFridayAgentForwardRuntime } from "../agent-forward-runtime.js";
+import { agentIdFromSessionKey, toSessionStoreKey } from "../session/session-manager.js";
+
+function entryString(entry: unknown, key: string): string | undefined {
+  if (!entry || typeof entry !== "object") return undefined;
+  const v = (entry as Record<string, unknown>)[key];
+  return typeof v === "string" && v.trim() ? v : undefined;
+}
+
+/**
+ * Resolves the store entry for a session key, tolerating case differences
+ * (the app's key carries an upper-case deviceId; `sessions.json` stores it
+ * lower-cased).
+ */
+function resolveEntry(store: Record<string, unknown>, sessionKey: string): unknown {
+  if (store[sessionKey]) return store[sessionKey];
+  const canonical = toSessionStoreKey(sessionKey);
+  if (store[canonical]) return store[canonical];
+  const target = canonical.toLowerCase();
+  for (const [k, v] of Object.entries(store)) {
+    if (k.toLowerCase() === target) return v;
+  }
+  return undefined;
+}
+
+export function resolveTranscriptPath(
+  entry: unknown,
+  storePath: string,
+): string | undefined {
+  const sessionFile = entryString(entry, "sessionFile");
+  if (sessionFile) {
+    return path.isAbsolute(sessionFile)
+      ? sessionFile
+      : path.join(path.dirname(storePath), sessionFile);
+  }
+  const sessionId = entryString(entry, "sessionId");
+  if (sessionId) {
+    return path.join(path.dirname(storePath), `${sessionId}.jsonl`);
+  }
+  return undefined;
+}
+
+/** Resolves the real server-side session id for a session key, or undefined. */
+export function resolveSessionId(sessionKey: string): string | undefined {
+  const rt = getFridayAgentForwardRuntime();
+  if (!rt) return undefined;
+  const agentId = agentIdFromSessionKey(sessionKey);
+  try {
+    const store = rt.loadSessionStore(rt.resolveStorePath(undefined, { agentId })) ?? {};
+    return entryString(resolveEntry(store, sessionKey), "sessionId");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Returns raw transcript message objects (newest tail up to `limit`), each with
+ * an `__openclaw: { id, seq, recordTimestampMs }` envelope. Empty on any failure.
+ */
+export function readSessionTranscriptRawMessages(sessionKey: string, limit: number): unknown[] {
+  const rt = getFridayAgentForwardRuntime();
+  if (!rt) return [];
+
+  const agentId = agentIdFromSessionKey(sessionKey);
+  let storePath: string;
+  let store: Record<string, unknown>;
+  try {
+    storePath = rt.resolveStorePath(undefined, { agentId });
+    store = rt.loadSessionStore(storePath) ?? {};
+  } catch {
+    return [];
+  }
+
+  const entry = resolveEntry(store, sessionKey);
+  if (!entry) return [];
+  const filePath = resolveTranscriptPath(entry, storePath);
+  if (!filePath) return [];
+
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const raw: unknown[] = [];
+  let seq = 0;
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let rec: Record<string, unknown>;
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      rec = parsed as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (rec.type === "session" || !rec.message || typeof rec.message !== "object") continue;
+    seq += 1;
+    const tsRaw = rec.timestamp;
+    const ts =
+      typeof tsRaw === "string"
+        ? Date.parse(tsRaw)
+        : typeof tsRaw === "number"
+          ? tsRaw
+          : Number.NaN;
+    raw.push({
+      ...(rec.message as Record<string, unknown>),
+      __openclaw: {
+        ...(typeof rec.id === "string" ? { id: rec.id } : {}),
+        seq,
+        ...(Number.isFinite(ts) ? { recordTimestampMs: ts } : {}),
+      },
+    });
+  }
+
+  return limit > 0 && raw.length > limit ? raw.slice(raw.length - limit) : raw;
+}

package/src/http/handlers/files.ts

@@ -1,7 +1,7 @@
 /**
  * File manager for Friday Next channel attachments.
  *
- * Files are copied under the plugin root `attachments/` and served at
+ * Files are copied under `~/.openclaw/friday-next/attachments/` and served at
  * GET /friday-next/files/{token} so the app can use stable gateway URLs after restarts.
  */
 
@@ -11,14 +11,30 @@ import os from "node:os";
 import { createFridayNextLogger } from "../../logging.js";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveFridayNextConfig } from "../../config.js";
+import { getHostOpenClawConfigSnapshot } from "../../host-config.js";
+import { getFridayNextRuntime } from "../../runtime.js";
 
-function getPluginRootDir(): string {
-  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+/** Test-only override for the attachments base directory. */
+let testAttachmentsDir: string | null = null;
+
+export function setAttachmentsDirForTest(dir: string | null): void {
+  testAttachmentsDir = dir;
+}
+
+/** Resolve `<historyDir>/../attachments`, mirroring the offline-queue layout. */
+function resolveAttachmentsDir(): string {
+  try {
+    const cfg = resolveFridayNextConfig(getHostOpenClawConfigSnapshot(getFridayNextRuntime().config));
+    return path.join(path.dirname(cfg.historyDir), "attachments");
+  } catch {
+    return path.join(os.homedir(), ".openclaw", "friday-next", "attachments");
+  }
 }
 
-/** Plugin-root `attachments/` directory; created on first use. */
+/** `~/.openclaw/friday-next/attachments/` directory; created on first use. */
 export function getAttachmentsDir(): string {
-  const dir = path.join(getPluginRootDir(), "attachments");
+  const dir = testAttachmentsDir ?? resolveAttachmentsDir();
   try {
     fs.mkdirSync(dir, { recursive: true });
   } catch {

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

@@ -0,0 +1,144 @@
+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 { handleHistoryMessages } from "./history-messages.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(path: string, headers: Record<string, string> = {}, method = "GET"): any {
+  return { method, url: path, headers };
+}
+
+const AUTH = { authorization: "Bearer test-token" };
+const CFG = {
+  channels: { "friday-next": { authToken: "test-token", pathPrefix: "/friday-next" } },
+  gateway: { auth: { token: "test-token" } },
+};
+
+let tmpDir = "";
+
+/** Auth config + optional subagent fallback. */
+function setRuntime(getSessionMessages?: (params: { sessionKey: string; limit?: number }) => Promise<{ messages?: unknown[] }>): void {
+  setFridayNextRuntime({
+    config: { loadConfig: () => CFG },
+    logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },
+    ...(getSessionMessages ? { subagent: { getSessionMessages } } : {}),
+  } as never);
+}
+
+/** Forward runtime: store keyed by full session key → entry with a sessionFile. */
+function setForward(store: Record<string, unknown>): void {
+  setFridayAgentForwardRuntime({
+    runtime: {
+      agent: {
+        session: {
+          resolveStorePath: (_s?: string, opts?: { agentId?: string }) =>
+            path.join(tmpDir, `${opts?.agentId ?? "main"}-sessions.json`),
+          loadSessionStore: () => store,
+        },
+      },
+      config: { current: () => CFG },
+    },
+  } as any);
+}
+
+function writeTranscript(name: string, lines: unknown[]): string {
+  const file = path.join(tmpDir, name);
+  fs.writeFileSync(file, lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf-8");
+  return file;
+}
+
+describe("handleHistoryMessages", () => {
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "friday-hist-"));
+    setRuntime();
+  });
+  afterEach(() => {
+    resetFridayAgentForwardRuntimeForTest();
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it("rejects non-GET with 405", async () => {
+    const res = new MockRes();
+    await handleHistoryMessages(makeReq("/friday-next/history/messages", AUTH, "POST"), res as any);
+    expect(res.statusCode).toBe(405);
+  });
+
+  it("rejects missing token with 401", async () => {
+    const res = new MockRes();
+    await handleHistoryMessages(makeReq("/friday-next/history/messages"), res as any);
+    expect(res.statusCode).toBe(401);
+  });
+
+  it("400s when sessionKey is missing", async () => {
+    const res = new MockRes();
+    await handleHistoryMessages(makeReq("/friday-next/history/messages", AUTH), res as any);
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("reads the transcript file from disk including user + assistant messages", async () => {
+    const file = writeTranscript("sess.jsonl", [
+      { type: "session", version: 1, sessionId: "s" },
+      { type: "message", id: "u1", timestamp: "2026-01-01T00:00:00.000Z", message: { role: "user", content: "hi there" } },
+      { type: "message", id: "a1", timestamp: "2026-01-01T00:00:01.000Z", message: { role: "assistant", content: [{ type: "text", text: "hello" }], model: "openai/gpt-4" } },
+    ]);
+    setForward({ "agent:main:main": { sessionId: "s", sessionFile: file } });
+
+    const res = new MockRes();
+    await handleHistoryMessages(makeReq("/friday-next/history/messages?sessionKey=agent:main:main", AUTH), res as any);
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body.messages.map((m: any) => m.role)).toEqual(["user", "assistant"]);
+    expect(body.messages[0].text).toBe("hi there");
+    expect(body.messages[1].text).toBe("hello");
+  });
+
+  it("resolves the entry case-insensitively (app upper-cases deviceId)", async () => {
+    const file = writeTranscript("fd.jsonl", [
+      { type: "message", id: "u1", message: { role: "user", content: "from app" } },
+    ]);
+    // Store keyed lower-case (as sessions.json persists it).
+    setForward({ "agent:main:friday:direct:abcd-1234:9": { sessionId: "x", sessionFile: file } });
+
+    const res = new MockRes();
+    await handleHistoryMessages(
+      makeReq("/friday-next/history/messages?sessionKey=agent:main:friday:direct:ABCD-1234:9", AUTH),
+      res as any,
+    );
+    const body = JSON.parse(res.body);
+    expect(body.messages.map((m: any) => m.role)).toEqual(["user"]);
+    expect(body.messages[0].text).toBe("from app");
+  });
+
+  it("falls back to getSessionMessages when the transcript is not on disk", async () => {
+    setForward({}); // no entry → disk read yields nothing
+    setRuntime(async () => ({
+      messages: [{ role: "assistant", content: "fallback", __openclaw: { id: "a1", seq: 1 } }],
+    }));
+    const res = new MockRes();
+    await handleHistoryMessages(makeReq("/friday-next/history/messages?sessionKey=agent:main:main", AUTH), res as any);
+    const body = JSON.parse(res.body);
+    expect(body.messages.map((m: any) => m.id)).toEqual(["a1"]);
+  });
+});